disfigure

Disfigure: User Guide

Figures (creating · anatomy · posture) Motions (figure · animation · generators )

Figures

Disfigure is a simple library for animating human figures.

Creating a figure

A figure is created as an instance of Man, Woman and Child with an optional parameter for height in meters. The default heights are 1.80 for men, 1.70 for women and 1.35 for children.

var man = new Man( );
var woman = new Woman( 1.75 );
var child = new Child( 1 );

Live examples: figure types and custom heights:

Anatomy of a figure

All figures have the same body structure with names for each body part that can be manipulated.

The central body parts are torso, head, chest and waist. Arms are arm, elbow,forearm and wrist. Legs are leg, thigh, knee, shin, ankle and foot. Hand fingers are thumb, index, middle, ring and pinky.

The names of symmetrical body parts have prefixes l_ for left and r_ for right. Leftness and rightness is always in respect to the figure itself. Fingers phalanges are named after the fingers but with suffixes _mid and _tip (note: thumbs have no middle phalanges).

figure.head        // head
figure.r_knee      // knee of right leg
figure.l_index     // index finger of left hand
figure.l_index_tip // tip phalange of index finger of left hand

Live examples: body parts and fingers with phalanges:

Figure posture

The posture property of a figure describes the rotations of all body parts. It contains version number of an array of rotation angles. The posture property can be used to push a posture to a figure. A read-only property postureString retrieves the posture as a string.

figure.posture = {version:9, angles:[[-15,44,10],[5,82,-24],...]};
figure.posture = anotherFigure.posture;

var str = figure.postureString;

A posture could be defined as a blend of other postures. Method blend mixes two postures with a blending coefficient. When the coefficient is 0 the result is the first posture, when it is 1 the result is the second and when it is between 0 and 1 the result is a posture between both postures.

figure.blend( initialPosture, finalPosture, 0.5 );

Live examples: posture data and posture blending:

Motions

The motion of a figure is done by manipulating properties of the figure or its body parts.

Figure position

The position of the figure within the 3D is controlled by its .position property with subproperties .x, .y and .z. Technically, the position is Vector3 object.

figure.position.set( 1, 0, 0.5 );
figure.position.y = -0.1;

Live examples: figure position and figure motion:

Figure motion

Each figure has three main axes:

Body parts have properties .x, .y and .z which define the rotation around the corresponding axes. Angles of rotations are in degrees.

Central body

The central body contains body parts in the middle of the figure – head, chest, waist and the torso. They have no left and right variants. The motions of central body parts follow the same axes of rotations.

figure.head.x = 40;
figure.chest.z = 10;
figure.waist.z = -30;

Live examples: axes of rotations and motion of head, chest and waist:

Legs and arms

A leg is made of leg, thigh, knee, shin, ankle and foot. An arm is made of arm, elbow, forearm and wrist. These body parts are left and right and the rotation around Y and Z axes is symmetrical and horizontally flipped as if mirrored. Note that some motions might look counterintuitive when two or three rotation are applied on the same body part. This is due to rotations being non-commutative.

figure.l_knee.x = 40;
figure.r_ankle.x = 10;
figure.l_elbow.y = 45;
figure.r_wrist.z = -20;

Live examples: motion of legs and motion of arms:

Fingers

Only hand fingers are presented as individual body parts. Fingers are thumb, index, middle, ring and pinky. They are always used with prefixes l_ or r_. Fingers have phalanges which are identified with sufix _mid (for middle) and _tip (for end) phalange. Note that the thumb has no middle phalange.

figure.l_thumb.x = 20;
figure.r_index.z = 45;
figure.r_index_mid.z = 30;
figure.r_index_tip.z = 15;

Live examples: motion of fingers and motion of phalanges:

Figure animation

A default Disfigure world manages figure animation in two ways – via animation loop or animation event. The function setAnimationLoop registers a user-defined function that is called automatically each frame. The function accepts a parameter time with the current time in milliseconds.

setAnimationLoop( animate );

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

Alternatively the window object may listen to animate events that are generated every frame with property event.time holds the current time in milliseconds. The animate event is also sent to individual figures and in this case the figure itself is in event.target.

window.addEventListener( 'animate', animate );

function animate ( event ) {

   var time = event.time;

   // executed once per frame
   
}

figure.addEventListener( 'animate', animate );

function animate ( event ) {

   var time = event.time,
       figure = event.target;

   // executed once per frame
   
}

Live examples: animation loop and animation event:

Number generators

Disfiure provide three number generators – these are functions that generate sequences of numbers used in animations. The random generator creates uniformly distributed random numbers within interval. The regular generator creates oscillation of values within interval. The chaotic generator combines randomness and smoothness – it creates smoothe sequence of numbers that gradually oscillate between randomly selected values in interval.

Random generator needs only interval, while regular and chaotic generators need time, offset and interval.

figure1.head.y = random( -30, 30 );
figure2.head.y = regular( time, 0, -30, 30 );
figure3.head.y = chaotic( time, 0, -30, 30 );

Live examples: generators graphs and generators animations:

Home · GitHub · Legacy NPM
This site is open source. Improve this page.