H-Anim logo

Humanoid animiation (H-Anim)
Part 1: Architecture

6 Object interfaces

--- H-Anim separator bar ---

cube 6.1 General

6.1.1 Introduction

This clause specifies the abstract definitions for the five objects specified by this International Standard. Actual usage of these interfaces requires a binding to an actual representation system. Two such systems are specified in Annex C VRML binding and Annex D X3D binding. Use of this International Standard in VRML worlds (see ISO/IEC 14772-1) shall use the binding and encoding specified in Annex C VRML binding. Use of this International Standard in an X3D world shall use the binding specified in 26 Humanoid animation (H-Anim) component of ISO/IEC 19775-1 and shall be encoded as specified in ISO/IEC 19776. Other bindings are allowed but are not specified in this International Standard.

6.1.2 Topics

Table 6.1 lists the topics of this clause.

Table 6.1 — Topics

6.1.3 Definition presentation

Each object interface defined below is presented as follows:

interface ObjectName {
    datatype           field_1_name     field_1_default_value
     ...                 ...             ...
    datatype           field_n_name     field_n_default_value
}

Empty string data types are represented by two consecutive double qoutation marks (""). Empty sequences are represented by open and closing brackets with no intervening values ([]).

cube 6.2 Humanoid

The Humanoid object is a container for the components that define the skeleton, geometry and landmarks of the H-Anim humanoid figure.  These components, which include the JointSegmentSite and Displacer objects, specify the majority of the details of the H-Anim humanoid figure, while the other fields of the Humanoid object specify information about the author, copyright, and usage restrictions of the model.

This section describes the interface of the Humanoid object and the fields which allow the functionality of the object to be defined and accessed.
interface Humanoid {
   float[3]           bboxCenter       0 0 0
   float[3]           bboxSize         -1 -1 -1
   float[3]           center           0 0 0
   sequence<string>   info             []
   sequence<Object>   joints           []
   string             name             ""
   float[4]           rotation         0 0 1 0
   float[3]           scale            1 1 1
   float[4]           scaleOrientation 0 0 1 0 
   sequence<Object>   segments         []
   sequence<Object>   sites            []
   sequence<Object>   skeleton         []
   sequence<Object>   skin             []
   sequence<float[3]> skinCoord        []
   sequence<float[3]> skinNormal       []
   float[3]           translation      0 0 0
   string             version          ""
   sequence<Object>   viewpoints       []
}

The bboxCenter and bboxSize fields specify a bounding box that encloses the children of the Humanoid object. These fields are hints and if defined may be used for optimization purposes. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, shall be calculated by the browser.

The center field specifies a translation offset from the origin of the local coordinate system (0,0,0). The rotation field specifies a rotation of the coordinate system of the humanoid figure. The scale field specifies a non-uniform scale of the humanoid figure coordinate system and the scale values shall be greater than zero. The scaleOrientation specifies a rotation of the coordinate system of the humanoid figure before the scale (to specify scales in arbitrary orientations). The scaleOrientation applies only to the scale operation.  The translation field specifies a translation to the coordinate system of the entire humanoid figure..

The info field consists of a sequence of strings, each of which is of the form item=value. The following tags are currently defined by the H-Anim Specification:

authorName
authorEmail
copyright
creationDate
usageRestrictions
humanoidVersion
age
gender
height
weight
The gender item typically has a value of female, male or neuter.  The humanoidVersion item refers to the version of the humanoid being used, in order to track revisions to the data. It is not the same as the version field of the Humanoid object, which refers to the version of the H-Anim specification that was used when building the humanoid. Additional item=value pairs can be included as needed for specific applications and can be proposed as additions to future versions of this International Standard.

The version field stores the version of this International Standard to which the Humanoid object conforms. The version value for this International Standard is “2.0”.

The name field, which shall be present, stores the name of the humanoid defined by the Humanoid object.

The skeleton field contains the HumanoidRoot Joint object.  The Humanoid object is considered the parent object of the HumanoidRoot Joint object and defines a coordinate space for the HumanoidRoot Joint object.  Thus, the Humanoid object's transformation affects the Joint object hierarchy in the skeleton field.  A hierarchy of Joint objects is defined for each H-Anim humanoid figure within the skeleton field of the Humanoid object and a hierarchical definition of joints is present even when the geometry of the humanoid figure is not defined within the skeleton field. The skeleton field contain can also contain zero or more Site objects which allow landmarks to be established with respect to the overall humanoid figure, but which will not be affected by the movement of any of the Joint objects.

The joints field contains a list of references, one for each Joint object defined within the skeleton field hierarchy of the Humanoid object. The order in which the joints are listed is irrelevant since the names of the joints are stored in the Joint objects themselves.

The segments field contains a list of references, one for each Segment object defined within the skeleton field hierarchy of the Humanoid object.  The order in which the segments are listed is irrelevant since the names of the segments are stored in the Segment objects themselves.

The sites field contains a list of references, one for each Site object defined within the skeleton field hierarchy of the Humanoid object. The order in which the sites are listed is irrelevant since the names of the sites are stored in the Site objects themselves.

The viewpoints field has a different functionality and behaviour than the joints, segments and sites fields. The viewpoints field can contain zero or more Site object definitions. The Site objects defined within this field are affected by the transformations applied to the Humanoid object, but are not affected by any of the transformations performed on the skeletal hierarchy defined within the skeleton field. The purpose of these Site objects is to define locations for virtual cameras in the reference frame of the Humanoid object. Site objects that are defined in this manner are intended to be used as attachment points from which a certain viewing perspective can be seen (such as viewing the face or profile of the human figure).

The skin field contains one or more indexed face set definitions. Those indexed face set definitions utilize the point and normal data that is defined within the skinCoord and skinNormal fields, respectively, of the Humanoid object. This field is defined as an opaque type for which the specific representation is defined by each binding to a presentation system. Annex C VRML binding contains a binding for VRML. Annex D X3D binding describes the Humanoid animation component of X3D specified in ISO/IEC 19775-1.

The skinCoord field contains a single sequence of points which are used by the internal mechanisms of the Humanoid object to create the appropriate surface deformations as well as by the indexed face set definitions within the skin field which do the actual rendering of the surface geometry.

The skinNormal field contains the normal data definition which is used by the internal mechanisms of the Humanoid object to create the appropriate surface deformations as well as the indexed face set definitions within the skin field, which contains the actual surface geometry that is rendered.

cube 6.3 Joint

The Joint object is the fundamental building block that represents body parts.

This section describes the interface of the Joint object and the fields that allow the functionality of the object to be defined and accessed.

interface Joint {
   float[3]           bboxCenter       0 0 0
   float[3]           bboxSize         -1 -1 -1
   float[3]           center           0 0 0
   sequence<Object>   children []
   sequence<Object>   displacers []
   sequence<float[3]> llimit []
   float[4]           limitOrientation 0 0 1 0
   string             name ""
   float[4]           rotation 0 0 1 0
   float[3]           scale 1 1 1
   float[4]           scaleOrientation 0 0 1 0
   sequence<integer>  skinCoordIndex []
   sequence<float>    skinCoordWeight []
   sequence<float[3]> stiffness [0 0 0]
   float[3]           translation 0 0 0
   sequence<float[3]> ulimit [] int[2] ChannelsNumber
sequence<string> Channels
bool Sensor }

The bboxCenter and bboxSize fields specify a bounding box that encloses the children of the Joint object. These fields are hints and if defined may be used for optimization purposes. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, shall be calculated by the browser.

The center field specifies a translation offset from the root of the overall humanoid body description and is not intended to receive events in most cases. Since all of the Joint objects have their centre values defined in the same coordinate frame, the length of any segment can be determined by calculating the distance between the parent’s joint centre and the child’s Joint object centre. The exception will be segments at the ends of the fingers and toes, for which the end effector Site objects within the Segment object shall be used.

The rotation field specifies a rotation of the coordinate system of the Joint object as a quaternion. The scale field specifies a non-uniform scale of the humanoid figure coordinate system and the scale values shall be greater than zero. The scaleOrientation specifies a rotation of the coordinate system of the humanoid figure before the scale. The scaleOrientation applies only to the scale operation. The translation field specifies a translation to the coordinate system of the entire humanoid figure.

The skinCoordWeight field contains a list of floating point values between 0.0 and 1.0 that describe an amount of weighting that should be used to affect a particular vertex from the skinCoord field of the Humanoid object.  Each item in this list has a corresponding index value in the skinCoordIndex field of the Joint object indicating exactly which coordinate is to be influenced.

The ulimit and llimit fields of the Joint object specify the upper and lower joint rotation limits. Both fields are three-element float sequence containing separate values for the X, Y and Z rotation limits. The ulimit field stores the upper (i.e. maximum) values for rotation around the X, Y and Z axes. The llimit field stores the lower (i.e., minimum) values for rotation around those axes. The default values for each of these fields is the null set indicating that the joint is unconstrained.

The limitOrientation field gives the orientation of the coordinate frame in which the ulimit and llimit values are to be interpreted. The limitOrientation describes the orientation of a local coordinate frame, relative to the Joint object centre position described by the center field.

The stiffness field, if present, contains values ranging between 0.0 and 1.0 that provide an inverse kinematics system how much each degree of freedom should scale the calculated joint rotation at each step of the inverse kinematics solver. 

EXAMPLE  A Joint object's stiffness can be used in an arm joint chain to give preference to moving the left wrist and left elbow over moving the left shoulder, or it can be used within a single Joint object with multiple degrees of freedom to give preference to individual degrees of freedom.

The value in the stiffness field is used as a scaling factor around the corresponding axis (X, Y, or Z for entries 0, 1 and 2 of the stiffness field).

The Joint object includes three additional attribute fields beyond those specified in ISO/IEC 19774 Humanoid Animation V1.0: ChannelsNumber, Channels, and Sensor. The additional fields allow a Joint object to have motion capture channels for receiving motion capture parameter values from a motion capture sensor. These define the number of channels, the types of channels based on transformation parameters, and a sensor to detect if the joint is able to receive motion capture parameter values, respectively. If motion capture data provides the joint with parameter values, the Sensor field is set to true. If not, the Sensor field is set to false.

EXAMPLE  If a joint has a stiffness value of 0.5 for the X DOF, then the joint will move half as much as it would of if the scaling value were not present (see [BADLER]).

Each Joint object shall have a name field that is used for identifying the object.  Within the local scope of a Humanoid object, each Joint object can be referenced by its name alone (e.g., r_shoulder, l_hip, or skullbase). However, when referring to a Joint object within a larger or global scope, the name of the Humanoid object shall be added as a distinguishing prefix.

EXAMPLE  If a Humanoid object’s name field contains the value “joe”, the l_hip Joint object of that Humanoid object is referred to globally as “joe_l_hip”.

If only a single humanoid is defined within a global scope, that Humanoid object’s name field shall contain the prefix of “hanim_”. In such a case, the l_hip Joint object of that Humanoid object shall be referred to globally as “hanim_l_hip”.

The name field is the only field which must be defined, all the other fields are optional.  However, it should be noted that those fields are still required to be part of the interface, even if none of the actual Joint objects define values for those fields.

The displacers field contains a list of Displacer objects that are used to morph the deformable mesh using the morph targets defined in the Displacer objects. See the Displacer object reference for more information.

The person creating a humanoid may wish to add additional joints to the body. The body remains humanoid in form, and is still generally expected to have the basic joints described in 4.9 Structure of a humanoid. The basic joints are known as the basic Joint object set to which additional Joint objects may be added (such as a prehensile tail). See 4.9.6 Additional Joint and Segment objects for more information. 

If necessary, some of the joints (such as the many vertebrae) may be omitted. See Annex A Nominal body dimensions and levels of articulation for details.

cube 6.4 Segment

The Segment object is a container for information about a segment of the body.

interface Segment {
   float[3]           bboxCenter       0 0 0
   float[3]           bboxSize         -1 -1 -1
   float[3]           centerOfMass     0 0 0
   sequence<Object>   children         []
   sequence<float[3]> coord            []
   sequence<Object>   displacers       []
   float              mass             0
   float[9]           momentsOfInertia 0 0 0 0 0 0 0 0 0
   string             name             ""
   sequence<Object>   addChildren      []
   sequence<Object>   removeChildren   []
}

The bboxCenter and bboxSize fields specify a bounding box that encloses the children of the Segment object. This is a hint that may be used for optimization purposes. A default bboxSize value of (-1, -1, -1) indicates that the bounding box is not specified and, if needed, shall be calculated by the implementing environment.

The name field shall be present, so that the Segment can be distinguished from other Segment objects.  Within the local scope of a Humanoid object, each Segment can be referenced by its name alone (e.g., r_upperarm, l_thigh, or skull). However, when referencing a Segment object within a larger or global scope, the name of the Humanoid object shall be added as a distinguishing prefix.

EXAMPLE  If a Humanoid object’s name field contains the value “joe”, the l_thigh Segment object of that Humanoid would be referred to globally as “joe_l_thigh”.

If only a single humanoid is defined within a global scope, it is a common practice for that Humanoid object’s namefield to contains the value of “hanim”. In such a case, the l_thigh Segment object of that humanoid would be referred to globally as "hanim_l_thigh".

The name field is the only field is required; all the other fields are optional.  However, those fields are part of the interface even if none of the actual Segment objects define values for those fields.

The mass field is the total mass of the segment.

The centerOfMass field is the location within the segment of its centre of mass. A value of -1 for centerOfMass specifies that no mass value is available.

The momentsOfInertia field contains the moment of inertia matrix. The first three elements are the first row of the 3×3 matrix, the next three elements are the second row, and the final three elements are the third row.

The coord field is used for Segment objects that have deformable meshes and shall contain coordinates referenced from the IndexedFaceSet for the Segment object. The coordinates are given the same name as the Segment object, but with a "_coords" appended (e.g., "skull_coords"). 

The displacers field stores the Displacer objects for a particular Segment object.

cube 6.5 Site

The Site object identifies locations that serve as landmarks for attaching semantics.

interface Site {
  float[3]         bboxCenter       0 0 0
  float[3]         bboxSize         -1 -1 -1
  float[3]         center           0 0 0
  sequence<Object> children         []
  string           name             ""
  float[4]         rotation         0 0 1 0
  float[3]         scale            1 1 1
  float[4]         scaleOrientation 0 0 1 0
  float[3]         translation      0 0 0
  sequence<Object> addChildren      []
  sequence<Object> removeChildren   []
}

The name field shall be present so that the Site can be distinguished from other Site objects.  Within the local scope of a Humanoid object, each Site can be referred to by its name alone (e.g., r_arm, l_hip, or skullbase). However, when referring to a Site object within a larger or global scope, the name of the Humanoid object shall be added as a distinguishing prefix.

EXAMPLE If a Humanoid object's name field contains the value joe, the l_index_distal_tip Site object of that Humanoid is referred to globally as "joe_l_index_distal_tip".

If only a single humanoid is defined within a global scope, the Humanoid object’s name field to contain the value of “hanim”. In such a case, the l_index_distal_tip Segment object of that humanoid shall be referred to globally as hanim_l_index_distal_tip.

Depending on the intended purpose, the prefix of the Site object’s name field shall be altered to appropriately describe its function.  If used as an end effector, the Site object shall have a name consisting of the name of the Segment to which it is attached with a “_tip” suffix appended.

EXAMPLE  The end effector Site on the right index finger shall be named r_index_distal_tip, and the Site object shall be a child of the r_index_distal Segment.

Site objects that are used to define viewpoint locations shall have a “_view” suffix appended. Site objects that are not end effectors and not camera locations shall have an “_pt” suffix. 

When a Site object is created, only the name field shall be specified. The other fields are optional.

The bboxCenter and bboxSize fields specify a bounding box that encloses the children of the Site object. These fields are hints and if defined may be used for optimization purposes. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and, if needed, shall be calculated by the browser.

The center field specifies a translation offset from the root of the overall humanoid body description and is not intended to receive events in most cases. Since all of the Site and Joint objects have their center values defined in the same coordinate frame, the length of any segment can be determined by calculating the distance between the parent’s Joint object center value and the child’s Joint object center value or in the case of segments at the ends of the fingers and toes, the end effector Site objects within the Segment object shall be used.

The rotation field specifies a rotation of the coordinate system of the Site object.

The scale field specifies a non-uniform scale of the Site object coordinate system and the scale values shall be greater than zero.

The scaleOrientation specifies a rotation of the coordinate system of the Site object before the scale. The scaleOrientation applies only to the scale operation. The orientation is specified as a quaternion.

The translation field specifies a translation to the coordinate system of the Site object.

cube 6.6 Displacer

The Displacer object is a container for information that specifies the allowable displacements of portions of an H-Anim figure.

interface Displacer {
   sequence<integer> coordIndex    []
   sequence<float>   displacements []
   string            name          ""
   float             weight        0
}

Each Displacer object shall have a name field required for identifying the object. All the other fields are optional. Within the local scope of a Humanoid object, each Displacer object can be referred to by its name alone (e.g., l_eyebrow_feature or l_eyebrow_raiser_action). However, when referring to a Displacer object within a larger or global scope, the name of the Humanoid object shall be added as a distinguishing prefix.

EXAMPLE  If a Humanoid object’s name field contains the value “joe”, the l_eyebrow_feature Displacer object of that humanoid is referred to globally as “joe_l_eyebrow_feature”.

If only a single humanoid is defined within a global scope, that Humanoid object’s name field to contains the value of “hanim”. In such a case, the l_eyebrow_feature Displacer object of that humanoid would be referred to globally as "hanim_l_eyebrow_feature".

Displacer objects that are used to identify features shall have a name with a “_feature” suffix. Displacer objects that are used to move a feature shall be given a name with an “_action” suffix, usually with an additional pre-suffix to indicate the kind of motion (such as “l_eyebrow_raiser_action”). Displacer objects that correspond to a particular configuration of the vertices should have a “_config” suffix.

The coordIndex field contains the indices into the coordinate array for the mesh of the vertices that are affected by the Displacer.

EXAMPLE

Displacer {
    coordIndex [ 7, 12, 21, 18 ]
    name "l_eyebrow_feature"
}

would mean that vertices 7, 12, 21, and 18 of the mesh are from the left eyebrow.

The displacements field, if present, provides a set of 3D values that are added to the neutral or resting position of each of the vertices referenced in the coordIndex field of the associated mesh. These values correspond one-to-one with the values in the coordIndex array of the mesh. The values shall be maximum displacements, and the application shall scale them using the value of the weight field before adding them to the neutral vertex positions.

EXAMPLE

Displacer {
    coordIndex [ 7, 12, 21, 18 ]
    displacements [ 0 0.0025 0, 0 0.005 0, 0 0.0025 0, 0 0.001 0 ]
    name "l_eyebrow_raiser_action"
}

would raise the four vertices of the left eyebrow in a vertical direction. Vertex 7 would be displaced up to 2.5 millimetres in the vertical (Y) direction, vertex 12 would be displaced up to 5 millimetres, vertex 21 would be displaced up to 2.5 millimetres, and vertex 18 would be displaced by just one millimetre.

The application shall uniformly scale the displacements by the value of the weight field.

By dynamically modifying the value of the weight fields of the Displacer objects, an application can morph the mesh object using a linear combination of the morph targets defined in the Displacer objects. For the Displacer objects that are contained in the displacers field of the Segment objects, the displacements are defined and applied in the Segment coordinate system. The base mesh for the morphed Segment is the original mesh defined in the Segment. For the Displacer objects that are contained in the displacers field of the Joint objects, the displacements are applied to the deformable mesh specified in the skinCoord field of the Humanoid object. The displacements are defined in the local coordinate system of the Joint object that contains the Displacer. The weighted displacements shall be applied to the skinCoord array in the coordinate system of the Humanoid object. Therefore, the displacements shall be transformed from the Joint object space into the Humanoid object space. The base mesh for the morphed skin is the deformed mesh that results from the bone based skin deformation.

--- H-Anim separator bar ---