H-Anim logo

Humanoid animation (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 a 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     field_1_range_limits
          ...             ...              ...                       ...
        datatype     field_n_name     field_n_default_value     field_n_range_limits
    }

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

For fields accepting numerical values, range limits are specified as lower and upper values, enclosed in either parentheses of square brackets. A parenthesis specifies that a limit is exclusive, and a square bracket specifies that the limit is inclusive. For fields that have multiple values the limits apply to each value.

EXAMPLE If a range is specified as [0,∞) then the field may take any value from, and including, 0, up to, but not including, infinity.

For fields that are Object data types, acceptable object types are listed in square brackets. Objects of any of these listed data types may be used in any quantity, and in any order, unless otherwise specified for that particular field.

For fields that are string data types, acceptable values (if any are specified) are listed in square brackets. Each individual acceptable value is listed in double quotation marks, with values separated by vertical bars (|) to indicate that any one of these values is acceptable. If no acceptable values are specified then any value may be used, provided it meets the requirements specified in this International Standard for that particular field.

6.1.4 Extensibility

Any fields that are not listed in this part of ISO/IEC 19774 shall be ignored. Fields may be added in subsequent parts of ISO/IEC 19774, in which case those fields become part of the object definition and shall be supported if those parts of ISO/IEC 19774 are supported by the implementation.

cube 6.2 Humanoid

The Humanoid object is a container for the components that define the skeleton, geometry and landmarks of the H-Anim figure. These components, which include the Joint, Segment, Site and Displacer objects, specify the majority of the details of the H-Anim 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     [0,∞) or -1
        float[3]           center                0 0 0        (-∞,∞)
        sequence<string>   info                  []
        sequence<float[3]> jointBindingPositions [0 0 0]      (-∞,∞)
        sequence<float[4]> jointBindingRotations [0 0 1 0]    (-∞,∞)
        sequence<float[3]> jointBindingScales    [1 1 1]      (0,∞)
        sequence<Object>   joints                []           [Joint]
        string             name                  required name
        float[4]           rotation              0 0 1 0      (-∞,∞)
        float[3]           scale                 1 1 1        (0,∞)
        float[4]           scaleOrientation      0 0 1 0      (-∞,∞)
        sequence<Object>   segments              []           [Segment]
        sequence<Object>   sites                 []           [Site]
        string             skeletalConfiguration ["BASIC"]
        sequence<Object>   skeleton              []           [Joint, Site]
        sequence<Object>   skin                  []           [indexed mesh objects as defined by the representation]
        sequence<float[3]> skinBindingCoords     []           (-∞,∞)
        sequence<float[4]> skinBindingNormals    []           (-∞,∞)
        sequence<float[3]> skinCoord             []           (-∞,∞)
        sequence<float[3]> skinNormal            []           (-∞,∞)
        float[3]           translation           0 0 0        (-∞,∞)
        string             version               "2.0"        ["2.0"]
        sequence<Object>   viewpoints            []           [Site]
    }

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 term=value. The following terms are defined in this International Standard:

   authorName
   authorEmail
   copyright
   creationDate
   usageRestrictions
   humanoidVersion
   age
   gender
   height
   weight

The gender term typically has a value of female, male or neuter. The humanoidVersion term 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 term=value pairs may be included as needed for specific applications.

The name field, which shall be present, and which shall not have the empty string value, stores the name of the humanoid defined by the Humanoid object. Of the other fields, only the skeleton and version fields are required. The remaining fields are optional.

The skeleton field contains the humanoid_root Joint object. The Humanoid object is considered the parent object of the humanoid_root Joint object and defines a coordinate space for the humanoid_root 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 can also contain zero or more Site objects which allow landmarks to be established with respect to the overall humanoid figure, but which are not 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 references to contained Joint, Segment and Site objects may be used to support inverse kinematics (IK) and other motion tools animating nodes found within the skeleton field.

The skeletalConfiguration field identifies the skeletal configuration of this model. Any models that share the same skeletalConfiguration value can also share skeletal animation data. The only specific skeletal configuration defined in this International Standard is the "BASIC" skeletal configuration specified in 4.8.1 Overview. Since the default value of the skeletal configuration is "BASIC", a humanoid model that specifies a skeletalConfiguration value of "BASIC" shall conform to the restrictive skeletal model specified in 4.8.1 Overview. If skeletalConfiguration is set to any value other than "BASIC", the model shall also contain one or more of the five fields that are required for models that are not "BASIC" as described below.

The skin field contains one or more indexed mesh definitions. Those indexed mesh 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 generic 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 mesh 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 mesh definitions within the skin field, which contains the actual surface geometry that is rendered.

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 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).

Since the translations and rotations of all the joints is zero at the binding pose, there is no transformation required to calculate the positions and normals of the vertices in the local coordinate system of the Joint objects. Models that contain non-zero values for the translations and rotations of the Joint objects at the binding pose shall also provide the additional fields necessary for the implementation to calculate the positions and normals of the vertices in the local coordinate system of the Joint objects.

The following five fields provide information needed for each binding pose of a humanoid or non-human model, as specified in 4.8.3 Modelling of non-human H-Anim figures.

None of these five fields shall be used in a model that has a skeletalConfiguration value of "BASIC".

The jointBindingPositions, jointBindingRotations, and jointBindingScales fields specify arrays of positions, rotations, and scale values, respectively. These sets of attributes are associated with the array of Joint objects contained in the joints field. If only one value is provided (such as the default value) then it is applied to all listed Joint objects equivalently. Applying each set of these translation, rotation, and scale values, in order, to the corresponding Joint objects maps a skeleton to the binding pose.

The skinBindingCoords field specifies an array of vertex locations that define the mesh in the binding pose. For each set of values corresponding to a given pose, the same vertex indexing system that is used for the skinCoord field also applies to this field.

The skinBindingNormals field specifies an array of normal vectors that define the mesh normal vectors in the binding pose. For each set of values corresponding to a given pose, the same normal indexing system used for the skinNormal field also applies to this field.

These five fields specify the necessary information so that both the skin and the skeleton can be in the same binding pose. Thus, implementations can calculate the location and normal of each vertex in the local coordinate system of each Joint object, a step required in the skin deformation process.

Support for additional fields used for Motion Data Animation is specified in ISO/IEC 19774-2.

cube 6.3 Joint

The Joint object is the fundamental building block that represents articulated 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      [0,∞) or -1
       float[3]           center           0 0 0         (-∞,∞)
       sequence<Object>   children         []            [Joint, Segment]
       sequence<Object>   displacers       []            [Displacer]
       float[3]           llimit           0 0 0         (-∞,∞)
       float[4]           limitOrientation 0 0 1 0       (-∞,∞)
       string             name             required name
       float[4]           rotation         0 0 1 0       (-∞,∞)
       float[3]           scale            1 1 1         (0,∞)
       float[4]           scaleOrientation 0 0 1 0       (-∞,∞)
       sequence<integer>  skinCoordIndex   []            [0,∞)
       sequence<float>    skinCoordWeight  []            [0,1]
       float[3]           stiffness        0 0 0         [0,1]
       float[3]           translation      0 0 0         (-∞,∞)
       float[3]           ulimit           0 0 0         (-∞,∞)
    }

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. Since all of the 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 centre and the child's Joint object centre. The exception is segments at the ends of the fingers and toes, for which the end effector Site objects within the Segment object shall be used.

The children field specifies the child objects of a Joint object in a humanoid hierarchy. It is dependent on the levels of articulation and their hierarchies. Any number, including zero, of Joint objects, may be used. The children field may also contain a single Segment object.

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

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 sequences 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. A sequence containing zero elements indicates that the joint is unconstrained. A non-empty sequence can only consist of a single three-value element. If ulimit and llimit values are provided, both must be defined together. If llimit and ulimit are equal, no constraints are applied to Joint object rotations.

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 ulimit and llimit fields in the local coordinate frame, relative to the Joint object centre position described by the center field.

The stiffness field, if present, contains values that specify to an inverse kinematics (IK) system how much each degree of freedom should scale the calculated joint rotation at each step of the IK 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.

A scale factor of (1 - stiffness) is applied around the corresponding axis (X, Y, or Z for entries 0, 1 and 2 of the stiffness field). Thus a stiffness value of zero means that no rotation scaling occurs, while a stiffness value of one means that no rotation occurs regardless of any provided rotation.

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

Each Joint object shall have a name field, which shall not have the empty string value, 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".

The name field is the only field which shall 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.8 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 examples.

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          [0,∞) or -1
       float[3]           centerOfMass     0 0 0             (-∞,∞)
       sequence<Object>   children         []                [Site, indexed mesh objects as defined by the representation]
       sequence<float[3]> coord            []                (-∞,∞)
       sequence<Object>   displacers       []                [Displacer]
       float              mass             0                 [0,∞) or -1
       float[9]           momentsOfInertia 0 0 0 0 0 0 0 0 0 (-∞,∞)
       string             name             required name
    }

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.

Each Segment object shall have a name field, which shall not have the empty string value, that is used for identifying the object. Within the local scope of a Humanoid object, each Segment object can be referenced by its name alone (e.g., r_upperarm, l_thigh, or skull). However, when referring to 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".

The name field is the only field which shall 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 Segment objects define values for those fields.

The mass field is the total mass of the segment. A value of -1 for mass specifies that no mass value is available.

The centerOfMass field is the location within the segment of its centre of mass.

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 indexed mesh 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.

Any Segment object can also contain zero or more Site objects in the children field, which allow landmarks to be established with respect to the specific Segment. These Site objects are moved with the parent Segment but are not affected by skin deformation or displacer animations.

In addition to any Site objects the children field also specifies any indexed mesh geometry that is to be used in accordance with the skeletal body geometry specification detailed at 4.3.2 Skeletal body geometry specification.

cube 6.5 Site

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

    interface Site {
      float[3]         bboxCenter       0 0 0          (-∞,∞)
      float[3]         bboxSize         -1 -1 -1       [0,∞) or -1
      float[3]         center           0 0 0          (-∞,∞)
      sequence<Object> children         []             [any object defined by the representation]
      string           name             required name
      float[4]         rotation         0 0 1 0        (-∞,∞)
      float[3]         scale            1 1 1          (0,∞)
      float[4]         scaleOrientation 0 0 1 0        (-∞,∞)
      float[3]         translation      0 0 0          (-∞,∞)
    }

The name field is the only field which shall be defined, and which shall not have the empty string value. 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 Site objects define values for those fields.

Each Site object shall have a name field that is used for identifying the object. Within the local scope of a Humanoid object, each Site object can be referenced by its name alone (e.g., r_neck_base, l_femoral_lateral_epicn, sellion, etc.). 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"".

Depending on the intended purpose, 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 an "_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.

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. 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 translation field specifies a translation to the coordinate system of the Site object.

The children field is an generic container for any appropriate object defined by the representation system.

cube 6.6 Displacer

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

    interface Displacer {
       sequence<integer>  coordIndex    []                [0,∞);
       sequence<float[3]> displacements []                (-∞,∞)
       string             name          required name
       float              weight        0                 (-∞,∞)
    }

Each Displacer object shall have a name field required for identifying the object. This field shall not have the empty string value. 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".

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.

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.

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"
    }

means 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 uniformly 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.

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.

--- H-Anim separator bar ---