disfigure

Disfigure: User Guide

Figures · Motions · Postures · Customizations · Worlds · Others

Disfigure is a library for animating human figures by modifying a matrix field of the space around them. Here is an absurdly minimal demo – see it live.

import * as Happy from 'disfigure'
	
new Happy.World
new Happy.Man

Figure shapes

new Man( height )
new Woman( height )
new Child( height )

Disfigure defines figures as instances of classes Man, Woman and Child – see it. The optional parameter height defines the height of a figure in meters – see it. By default a man is 1.80m, a woman is 1.70m and a child is 1.35m.

var man = new Happy.Man( 1.90 );
var woman = new Happy.Woman( );

All types of figures have the exact same structure with names corresponding to body parts, like head and chest. Left and right body parts are always in respect to the figure. Their names have prefixes l_··· for left and r_··· for right, so there is l_knee and r_knee – see it:

Whole body – torso
Central parts – head, chest, waist
Upper limbs – arm, elbow, forearm, wrist
Lower limbs – leg, thigh, knee, shin, ankle, foot

Figure motions

Central parts

The motion of a figure is done by manipulating properties of body parts. Motions are just rotations measured in degrees.

figure.torso
figure.head
figure.chest
figure.waist

The torso is the root body part and its rotation affects the whole body. Torso has properties bend, turn and tilt – see it. The central body parts are head, chest and waist. They have the same set of properties as the torso – see it.

bend – bends foreward or backward
turn – turns to the left or right
tilt – tilts sideways to the left or right

figure.torso.bend = 40;
figure.head.bend = 40;
figure.chest.turn = -20;
figure.waist.tilt = 35;

Upper limbs

figure.l_arm
figure.r_arm

The upper limbs are symmetrical body parts with multiple joints and rotation properties that recreate a complex and flexible motion – see it. Arms have foreward, turn and straddle – see it.

foreward – moves an arm foreward (or backward)
turn – turns an arm inwards (or outwards)
straddle – moves an arm sideways to the body (or away from the body)

figure.r_arm.foreward = 70;
figure.r_arm.straddle = -30;
figure.r_arm.turn = 5;

figure.l_elbow
figure.r_elbow

Elbows l_elbow and r_elbow have limited motions. Elbows have only bend – see it.

bend – bends an elbow towards the body (or away from the body)

figure.r_elbow.bend = 45;

figure.l_forearm
figure.r_forearm

Forearms l_forearm and r_forearm have limited motions. Forearms have only turn – see it.

turn – turns a forearm inwards (or outwards)

figure.r_forearm.turn = -20;

figure.l_wrist
figure.r_wrist

Wrists l_wrist and r_wrist support bend and tilt – see it. Wrist have no turns, as turning is done in the forearm or the arm.

Motions of l_wrist and r_wrist:

bend – bends a wrist down or up
turn – turns a wrist foreward or backward

man.r_wrist.bend = -60;
man.r_wrist.tilt = 10;

Lower limbs

figure.l_leg
figure.r_leg

The lower limbs are symmetrical body parts with multiple joints and rotation properties that recreate a complex and flexible motion – see it. Legs have foreward, straddle and turn – see it.

foreward – moves a leg foreward (or backward)
straddle – moves a leg sideways away from the body (or to the body)
turn – turns a leg inward (or outward)

figure.r_leg.foreward = -10;
figure.r_leg.straddle = 50;
figure.r_leg.turn = 20;

figure.l_thigh
figure.r_thigh

Thighs l_thigh and r_thigh have limited motions. Thighs have only turn – see it.

turn – turns a thigh outwards (or inwards)

figure.r_thigh.turn = 20;

figure.l_knee
figure.r_knee

Knees l_knee and r_knee support bend and tilt – see it. Knee have no turns, as turning is done in the thigh or the shin. However, their tilting is used to model bowlegs and knock knees.

Motions of l_knee and r_knee:

bend – bends a knee backward
tilt – tilts a knee sideways

man.r_knee.bend = 40;
man.r_knee.tilt = 0;

figure.l_shin
figure.r_shin

Shins l_shin and r_shin have limited motions, just like thighs. Shins have only turn – see it.

turn – turns a shin outwards (or inwards)

figure.r_shin.turn = 20;

figure.l_ankle
figure.r_ankle

Ankles l_ankle and r_ankle support bend and tilt – see it. Ankle have no turns, as turning is done in the shin.

Motions of l_ankle and r_ankle:

bend – bends an ankle foreward or backward
tilt – tilts a ankle outward or inward

man.r_ankle.bend = 40;
man.r_ankle.tilt = -10;

figure.l_foot
figure.r_foot

Feet l_foot and r_foot have limited motions. Feet have only bend – see it.

bend – bends a foot downward (or upward)

figure.r_foot.bend = 20;

Figure postures

The posture of a figure is defined by the rotation properties of its body parts. By default, when a figure is created, it is set to a default posture.

Figure setup

When a posture is defined programmatically, it might be easier to define it step by step. To recreate a Tai Chi Chuan posture – see it, first the whole body position is defined:

figure.torso.bend = 10;
figure.torso.tilt = -5;
:

Then the orientations of the legs are set:

figure.l_leg.straddle = 25;
figure.l_knee.bend = 50;
:

Finally, the arms are fixed:

figure.l_arm.straddle = 12;
figure.l_elbow.bend = 140;
:

Figure animation

A dynamic posture is when is changes over time. If a predefined world is used, it manages posture animation in two ways – via animation loop function or via timer events. In both ways the user program should provide angles at a given time.

The function setAnimationLoop registers a user-defind function that is called automatically each frame. This user function accepts a parameter time with the current time in miliseconds – see it. The alternative approach is to let the window object listen to the animate events via the addEventListener method. The event.time holds the current time in miliseconds – see it.

setAnimationLoop( animate );

function animate( time ) {
   
   // executed once per frame
   
}

window.addEventListener( 'animate', animate );

function animate ( event ) {

   // executed once per frame
   
   var time = event.time;

}

The animate event is triggered to each figure. In this case the activating figure is stored in the property event.target. This allows the same animation to be applied to several figures – see it.

figure.addEventListener( 'animate', animate );

function animate ( event ) {
		
   // executed once per frame
   
   var time = event.time;
   var figure = event.target;

}

Figure postures

figure.posture
figure.postureString

A posture could be extracted from a figure with the posture property. The posture object contains properties version of the posture data format, positio for the coordinates of the figure, rotation for its orientation and data with joint angles. The posture property can be used to push a posture to a figure – see it.

figure.posture = {
   version:  8,
   position: [0,-0.29,0.5],
   rotation: [0,0,0,"XYZ"],
   angles:   [8,0,0,-4,4,-6,3,-34,0,-5,-60,...]
};

A read-only property postureString retrieves the posture as a string.

var str = figure.postureString;

figure.blend( postureA, postureB, k )

A posture could be defined as a blend of other postures. The method blend mixes the initial postureA and the final postureB with a coefficient k∈[0,1]. When k=0 the result is postureA, when k=1 the result is postureB, when k is between 0 and 1 the result is a posture between postureA and postureB – see it.

var A = manA.posture;
var B = manB.posture;

manZ.blend(A,B,0.5);

Figure customizations

Apart for moving body parts, Disfigure provides basic functionality for additional modification of a figure – adding accessories or changing colors.

Accessories

figure.bodypart.attach( accessory, x, y, z )
figure.bodypart.attach( accessory )

Accessories are Three.js objects attached to a specific body part. They do not deform, but move as if attached to the body. The position of accessory is defined by the optional parameters x, y and z. The position is in respect to the origin point of the body part – see it. Alternatively, the position of an accessory could be set via its Three.js position property.

figure.l_arm.attach(spike);

figure.bodypart.point( x, y, z )

When just the final coordinates are needed it is faster to use point, which calculates the position and ignores the orientation – see it.

v = figure.l_arm.point(0,0.1,0);

figure.bodypart.lockTo( localX, localY, localZ, globalX, globalY, globalZ )

The function lockTo moves the whole figure so that the local point (localX, localY, localZ) of bodypart is mapped to the global point (globalX, globalY, globalZ). This can be used to keep a figure standing on the ground (by locking its feet to level 0). The following examples shows two floating figures touching the same spot with their fingers – see it.

figure.l_wrist.lockTo(0.2,-0.01,0.01, 0, 1.5, 0 );

Custom colors

Disfigure supports a painting interface to draw simple shapes directly onto the skin of a figure.

figure.dress( clothing )

This function defines the dressing of a figure. The description of the clothing is an array of range and material functions. The range function selects a portion of the body skin, called slice, and the material function applies a material to it. The structure of the clothing is:

[
   material,            // default material
   
   slice_1, material_1, // optional materials
   slice_2, material_2,
   ...
   slice_N, material_N
]

The material is the mandatory default material for the whole figure. The next optional slice-material pairs define slices and materials for each slice – see it.

figure.dress([

   Happy.velour( 'black' ),

   Happy.slice( 1.1, 2, {angle: -20} ),
   Happy.velour( 'red' ),

   Happy.slice( 1.15, 2, {angle: 35} ),
   Happy.velour( 'red' ),
   ...
];

velour( color )
latex( color )

The functions velour and latex define matte material – see it and shiny material – see it The color is either a Three.js color or a HTML/CSS color name.

velour( 'green' )
latex( 'red' )

bands( material_1, material_2, width, options )

The bands function makes a composite material of alternating horizontal bands of material_1 and material_2. The width of each band is defined in meters. The optional options parameter provides additional properties for the band – see it. Adequate bluring the bands may improve the visual appearance of the bands, especially when they are too close or too far.

Polar bands revolve around a vertical axis. They are more suitable for vertical bands that go around a body part – see it.

balance – the relative weight of the two materials from -1 to 1; 0 means they are equally balanced
blur – the blurness of the bands’ edges from 0 to 1; 0 is no blur, 1 is maximal blur
angle – the rotation of bands in degrees, from -360 to 360; 0 is horizontal bands, 90 is vertical bands
polar – bands are around a central vertical axis, angle is not used and width represents portions of a full circle of one band, i.e. 1/10 is 10 bands
x – the x-coordinate of a central vertical axis, used only for polar bands
z – the z-coordinate of a central vertical axis, used only for polar bands

Happy.bands(
   Happy.latex( 'crimson' ),
   Happy.velour( 'azure' ),
   0.015, { balance: 0.9, blur: 0.2, angle: 90 }
)

slice( from, to, options )

The slice function defines a slice of a figure – this is a part of the figure that is dressed in given material. Parameters from and to define the start and the end of the slice, measure in meters. By default a slice is horizontal, thus from and to denote distance from the ground. The optional options parameter provides additional properties for the slice like their orientation – see it, their rotation – see it.

side – if true, the slice is vertical across the front-back of a figure
front – if true, the slice is vertical across the left-right of a figure
angle – the rotation of the slice in degrees around one axis, from -360 to 360
sideAngle – the rotation of the slice in degrees around another axis, from -360 to 360
symmetry – if true, the slice is symmetrical, i.e. [-to,-from] and [from,to]

Happy.slice( -0.07, 0.03, {front: true} )
Happy.slice( 0.70, 1.40, {angle:55} )

Additionally, slices could be curved as a wave when a non-zero wave option is provided – see it

wave – height of the weight in meters
width – width of a single wave in meters, this defines how sparse or dense is the wave
sharpness – defines how sharp are the edges of the wave, 0 is for sharp, 1 is for sinusoidal, intermediate values, as well as less than 0 or greater than 1 are also accepted

Happy.slice( 1.3, 2, {wave:0.15, width:0.1, sharpness:1} )

slice(…).and( slice )
slice(…).or( slice )

Slices can be combined into more complex shapes by intersecting or uniting them. The function and intersects two slices, e.g. slice_1.and(slice_2) generates a slice containing all points both in slide_1 and in slide_2, while or unites two slices, e.g. slice_1.or(slice_2) generates a slice containing all points either in slide_1 or in slide_2 – see it

Happy.slice( -0.1, 1.1, {angle:45, wave: 0.3, width:0.02} )
   .and( Happy.slice( -0.3, 0.9, {angle:-45, wave: 0.3, width:0.02} ) )
   .or( Happy.slice( -0.2, 0.2 ) ),

TSL textures

Disfigure is compatible with most TSL Textures – real-time textures generated via TSL. However, textures are currently not compatible with figure dressing. To use a TSL Texture it must be imported. As textures use Three.js color objects, Three.js should also be imported.

Each texture is activated with a function, assigned to the figure’s material.colorNode property – see it. Different figures may have individual TSL textures – see it.

import * as Three from "three";
import * as TSLTexture from "https://cdn.jsdelivr.net/npm/tsl-textures@2.1.2/dist/tsl-textures.min.js";
:
figure.material.colorNode = TSLTexture.camouflage ( {
	scale: 3,
	colorA: new Three.Color(12762792),
	colorB: new Three.Color(10258782),
	colorC: new Three.Color(9610101),
	colorD: new Three.Color(7435617),
} );

Predefined world

new World( )
new World( features )

Creates a predefined default 3D world with all basic attributes, like camera, lights, ground, user navigations and so on. The optional parameter features defines what attribute to create. It is a set of the following options:

lights – boolean; if true, lights are created
controls – boolean, if true, orbit controls is created
ground – boolean, if true, ground is created
shadows – boolean, if true, shadows are created
stats – boolean, if true, stats panel is created
antialias – boolean, if false, antialias is turned off (this may speed up animations in slow GPUs)

new World( {ground: false, stats: true} );

userAnimationLoop( animate )

Sets the user-defined function animate to be called from the main animation loop at every frame. This function has one parameter of the elapsed time, measured in milliseconds (one second is 1000 milliseconds).

function animate( ms ) {...}

setAnimationLoop( animate );

renderer
scene
camera
light
cameraLight

These are core rendering variables that are created only for a default world. The light is a static light casting shadows, while cameraLight is attached to the camera. These variables are instances of the following Three.js classes: THREE.Scene,THREE.PerspectiveCamera and THREE.DirectionalLight. They are used to modify the predefined world – see it:

ground

This variable is the ground for the default world. It creates the illusion of a solid surface and hosts bodies’ shadows. It is an instance of THREE.Mesh shaped by PlaneGeometry.

controls

The navigation controls for the default world. It allows the user to rotate and move the camera within the world. It is an instance of OrbitControls.

stats

A statistics panel used to show the current the performance of rendering the default world. It is an instance of Stats.

Others

random( )
random( min, max )

Generates uniformly distributed random numbers in the interval [min,max) – see it. By default min=-1 and max=1. Internally uses a pseudo-random function.

figure.head.turn = random( -60, 60 );

regular( time )
regular( time, offset )
regular( time, offset, min, max )

Generates an oscilating sequence of numbers in the interval [min,max] – see it. By default offset=0, min=-1 and max=1. Internally uses the sine function. Parameter offset shifts the oscillation foreward or backward in time.

figure.head.turn = regular( time, 0, -60, 60 );

chaotic( time )
chaotic( time, offset )
chaotic( time, offset, min, max )

Generates a chaotic (random, but gradually changing) sequence of numbers in the interval [min,max] – see it. By default offset=0, min=-1 and max=1. Internally uses a simplex noise function. Parameter offset shifts the sequence across the time, i.e. two generators with different offsets produce different sequences.

figure.head.turn = chaotic( time, 0, -60, 60 );

everybody

An array of all created bodies. Usually used to traverse them and do some operation on all bodies.

Home · GitHub · NPM

This site is open source. Improve this page.

disfigure

Disfigure: User Guide

Figures · Motions · Postures · Customizations · Worlds · Others

Figure shapes

new Man( height )new Woman( height )new Child( height )

Figure motions

Central parts

figure.torsofigure.headfigure.chestfigure.waist

Upper limbs

figure.l_armfigure.r_arm

figure.l_elbowfigure.r_elbow

figure.l_forearmfigure.r_forearm

figure.l_wristfigure.r_wrist

Lower limbs

figure.l_legfigure.r_leg

figure.l_thighfigure.r_thigh

figure.l_kneefigure.r_knee

figure.l_shinfigure.r_shin

figure.l_anklefigure.r_ankle

figure.l_footfigure.r_foot

Figure postures

Figure setup

Figure animation

Figure postures

figure.posture figure.postureString

figure.blend( postureA, postureB, k )

Figure customizations

Accessories

figure.bodypart.attach( accessory, x, y, z )figure.bodypart.attach( accessory )

figure.bodypart.point( x, y, z )

figure.bodypart.lockTo( localX, localY, localZ, globalX, globalY, globalZ )

Custom colors

figure.dress( clothing )

velour( color )latex( color )

bands( material_1, material_2, width, options )

slice( from, to, options )

slice(…).and( slice )slice(…).or( slice )

TSL textures

Predefined world

new World( )new World( features )

userAnimationLoop( animate )

rendererscenecameralightcameraLight

ground

controls

stats

Others

random( )random( min, max )

regular( time )regular( time, offset )regular( time, offset, min, max )

chaotic( time )chaotic( time, offset )chaotic( time, offset, min, max )

everybody

new Man( height )
new Woman( height )
new Child( height )

figure.torso
figure.head
figure.chest
figure.waist

figure.l_arm
figure.r_arm

figure.l_elbow
figure.r_elbow

figure.l_forearm
figure.r_forearm

figure.l_wrist
figure.r_wrist

figure.l_leg
figure.r_leg

figure.l_thigh
figure.r_thigh

figure.l_knee
figure.r_knee

figure.l_shin
figure.r_shin

figure.l_ankle
figure.r_ankle

figure.l_foot
figure.r_foot

figure.posture
figure.postureString

figure.bodypart.attach( accessory, x, y, z )
figure.bodypart.attach( accessory )

velour( color )
latex( color )

slice(…).and( slice )
slice(…).or( slice )

new World( )
new World( features )

renderer
scene
camera
light
cameraLight

random( )
random( min, max )

regular( time )
regular( time, offset )
regular( time, offset, min, max )

chaotic( time )
chaotic( time, offset )
chaotic( time, offset, min, max )