Extensible 3D (X3D)
Part 1: Architecture and base components

26 Humanoid Animation (HAnim) component

# 26.1 Introduction

## 26.1.1 Name

The name of this component is " HAnim". This name shall be used when referring to this component in the COMPONENT statement (see 7.2.5.4 Component statement).

## 26.1.2 Overview

This clause describes the Humanoid Animation (HAnim) component of this document. Table 26.1 provides links to the major topics in this clause. The HAnim component of X3D defines the node bindings and other specifics for implementing ISO/IEC 19774 (see [I19774]) within X3D.

Table 26.1 — Topics

26.1 Introduction 26.1.1 Name 26.1.2 Overview 26.2 Concepts 26.3 Node reference 26.3.1 HAnimDisplacer 26.3.2 HAnimHumanoid 26.3.3 HAnimJoint 26.3.4 HAnimMotion 26.3.5 HAnimSegment 26.3.6 HAnimSite 26.4 Support levels Table 26.1 — Topics Table 26.2 — Humanoid animation (HAnim) component support levels

# 26.2 Concepts

This component maps the functionality defined in ISO/IEC 19774 to a set of X3D nodes. The semantics for these nodes are as specified therein.

# 26.3 Node reference

## 26.3.1 HAnimDisplacer

    HAnimDisplacer : X3DGeometricPropertyNode {
      MFInt32  [in,out] coordIndex    []   [0,∞)
      SFString [in,out] description   ""
      MFVec3f  [in,out] displacements []
      SFNode   [in,out] metadata      NULL [X3DMetadataObject]
      SFString [in,out] name          ""
      SFFloat  [in,out] weight        0.0  (-∞,∞)
    }

Applications may need to alter the shape of individual segments. At the most basic level, this is done by writing to the point field of the node found in the coord field of the HAnimSegment node.

In some cases, the application may need to be able to identify specific groups of vertices within an HAnimSegment.

EXAMPLE The application may need to know which vertices within the skull HAnimSegment comprise the left eyebrow.

It may also require "hints" as to the direction in which each vertex should move. That information is stored in a node called an HAnimDisplacer. The HAnimDisplacers for a particular HAnimSegment are stored in the displacers field of that HAnimSegment.

Each field is described in ISO/IEC 19774.

### 26.3.2 HAnimHumanoid

    HAnimHumanoid : X3DChildNode, X3DBoundedObject {
      SFVec3f    [in,out] center                0 0 0    (-∞,∞)
      SFString   [in,out] description           ""
      SFBool     [in,out] bboxDisplay           FALSE
      MFString   [in,out] info                  []
      MFVec3f    [in,out] jointBindingPositions []       (-∞,∞)
      MFRotation [in,out] jointBindingRotations []       [-1,1] or (-∞,∞)
      MFVec3f    [in,out] jointBindingScales    []       (0,∞)
      MFNode     [in,out] joints                []       [HAnimJoint]
      SFInt32    [in,out] loa                   -1       [-1,4]
      SFNode     [in,out] metadata              NULL     [X3DMetadataObject]
      MFNode     [in,out] motions               []       [HAnimMotion]
      MFBool     [in,out] motionsEnabled        []
      SFString   [in,out] name                  ""
      SFRotation [in,out] rotation              0 0 1 0  [-1,1] or (-∞,∞)
      SFVec3f    [in,out] scale                 1 1 1    (0,∞)
      SFRotation [in,out] scaleOrientation      0 0 1 0  [-1,1] or (-∞,∞)
      MFNode     [in,out] segments              []       [HAnimSegment]
      MFNode     [in,out] sites                 []       [HAnimSite]
      SFString   [in,out] skeletalConfiguration "BASIC"
      MFNode     [in,out] skeleton              []       [HAnimJoint, HAnimSite]
      MFNode     [in,out] skin                  []       [Group, LOD, Shape, Switch, Transform, IndexedFaceSet, IndexedFanSet, IndexedLineSet, IndexedQuadSet, IndexedTriangleSet, IndexedTriangleStripSet]
      SFNode     [in,out] skinBindingCoords     NULL     [Coordinate|CoordinateDouble]
      SFNode     [in,out] skinBindingNormals    NULL     [X3DNormalNode]
      SFNode     [in,out] skinCoord             NULL     [Coordinate|CoordinateDouble]
      SFNode     [in,out] skinNormal            NULL     [X3DNormalNode]
      SFVec3f    [in,out] translation           0 0 0    (-∞,∞)
      SFString   [in,out] version               "2.0"    ["2.0"]
      MFNode     [in,out] viewpoints            []       [HAnimSite]
      SFBool     [in,out] visible               TRUE
      SFVec3f    []       bboxCenter            0 0 0    (-∞,∞)
      SFVec3f    []       bboxSize              -1 -1 -1 [0,∞) or −1 −1 −1
    }

The HAnimHumanoid node is used to store human-readable data such as author and copyright information, as well as to store references to the HAnimJoint, HAnimMotion, HAnimSegment, and HAnimSite nodes in addition to serving as a container for the entire humanoid. Thus, it serves as an essential node for moving the humanoid through its environment.

Each field is described in ISO/IEC 19774.

Metadata values from the info field can be equivalently encoded via MetadataSet containing related X3DMetadataObject nodes.

## 26.3.3 HAnimJoint

    HAnimJoint : X3DGroupingNode {
      MFNode     [in]     addChildren               [HAnimJoint,HAnimSegment]
      MFNode     [in]     removeChildren            [HAnimJoint,HAnimSegment]
      SFVec3f    [in,out] center           0 0 0    (-∞,∞)`
      MFNode     [in,out] children         []       [HAnimJoint,HAnimSegment]
      SFString   [in,out] description      ""
      MFNode     [in,out] displacers       []       [HAnimDisplacer]
      SFBool     [in,out] bboxDisplay      FALSE
      SFRotation [in,out] limitOrientation 0 0 1 0  [-1,1] or (-∞,∞)
      MFFloat    [in,out] llimit           [0 0 0]  (-∞,∞)
      SFNode     [in,out] metadata         NULL     [X3DMetadataObject]
      SFString   [in,out] name             ""
      SFRotation [in,out] rotation         0 0 1 0  [-1,1] or (-∞,∞)
      SFVec3f    [in,out] scale            1 1 1    (0,∞)
      SFRotation [in,out] scaleOrientation 0 0 1 0  [-1,1] or (-∞,∞)
      MFInt32    [in,out] skinCoordIndex   []       [0,∞)
      MFFloat    [in,out] skinCoordWeight  []       [0,1]
      MFFloat    [in,out] stiffness        [0 0 0]  [0,1]
      SFVec3f    [in,out] translation      0 0 0    (-∞,∞)
      MFFloat    [in,out] ulimit           [0 0 0]  (-∞,∞)
      SFBool     [in,out] visible          TRUE
      SFVec3f    []       bboxCenter       0 0 0    (-∞,∞)
      SFVec3f    []       bboxSize         -1 -1 -1 [0,∞) or −1 −1 −1
    }

Each joint in the body is represented by an HAnimJoint node, which is used to define the relationship of each body segment to its immediate parent. A child HAnimSegment node provides a visual representation of the skeleton segment.

An HAnimJoint may only be a child of another HAnimJoint node or a child within the skeleton field in the case of the HAnimJoint used as a humanoid root ( i.e., an HAnimJoint may not be a child of an HAnimSegment).

The HAnimJoint node is also used to store other joint-specific information. In particular, a joint name is provided so that applications can identify each HAnimJoint node at run-time. The HAnimJoint node may contain hints for inverse-kinematics systems that wish to control the HAnim figure. These hints include the upper and lower joint limits, the orientation of the joint limits, and a stiffness (resistance) value.

The llimit, ulimit, and stiffness fields shall contain three values or else be an empty array. An empty llimit, ulimit, or stiffness array is equivalent to 0 0 0. Behavior is undefined when array length is 1, 2, or greater than 3.

NOTE These limits are not enforced by any mechanism within the scene graph of the humanoid, and are provided for information purposes only. Use of this information and enforcement of the joint limits is up to the application.

Humanoid authors and tools are free to implement the HAnimJoint node however they choose. In particular, they may choose to use a single polygonal mesh to represent a humanoid, rather than having a separate IndexedFaceSet for each body segment. In such a case, an HAnimJoint would be responsible for moving the vertices that correspond to a particular body segment and all the segments descended from it.

Each field is described in ISO/IEC 19774.

## 26.3.4 HAnimMotion

    HAnimMotion : X3DChildNode {
      SFBool   [in]     next
      SFBool   [in]     previous
      SFString [in,out] channels         ""
      MFBool   [in,out] channelsEnabled  []
      SFString [in,out] description      ""
      SFBool   [in,out] enabled          TRUE
      SFInt32  [in,out] endFrame         0      [0,∞)
      SFTime   [in,out] frameDuration    0.1    (0,∞)
      SFInt32  [in,out] frameIncrement   1      (-∞,∞)
      SFInt32  [in,out] frameIndex       0      [0,∞)
      SFString [in,out] joints           ""
      SFInt32  [in,out] loa              -1     [-1,4]
      SFBool   [in,out] loop             FALSE
      SFNode   [in,out] metadata         NULL   [X3DMetadataObject]
      SFString [in,out] name             ""
      SFInt32  [in,out] startFrame       0      [0,∞)
      MFFloat  [in,out] values           []     (-∞,∞)
      SFTime   [out]    cycleTime               [0,∞)
      SFTime   [out]    elapsedTime             (0,∞)
      SFInt32  [out]    frameCount              [0,∞)
    }

HAnimMotion is used for motion animation of Humanoid characters. Raw motion data, for example, motion capture data, details the number of frames, the frame display time, and the parameter values for the motion from each channel at each frame.

Each field is described in ISO/IEC 19774.

## 26.3.5 HAnimSegment

    HAnimSegment : X3DGroupingNode {
      MFNode   [in]     addChildren                          [X3DChildNode]
      MFNode   [in]     removeChildren                       [X3DChildNode]
      SFBool   [in,out] bboxDisplay      FALSE
      SFVec3f  [in,out] centerOfMass     0 0 0               (-∞,∞)
      MFNode   [in,out] children         []                  [X3DChildNode]
      SFNode   [in,out] coord            NULL                [Coordinate|CoordinateDouble]
      SFString [in,out] description      ""
      MFNode   [in,out] displacers       []                  [HAnimDisplacer]
      SFFloat  [in,out] mass             0                   [0,∞)
      SFNode   [in,out] metadata         NULL                [X3DMetadataObject]
      MFFloat  [in,out] momentsOfInertia [0 0 0 0 0 0 0 0 0] [0,∞)
      SFString [in,out] name             ""
      SFBool   [in,out] visible          TRUE
      SFVec3f  []       bboxCenter       0 0 0               (-∞,∞)
      SFVec3f  []       bboxSize         -1 -1 -1            [0,∞) or −1 −1 −1
    }

Each body segment is stored in an HAnimSegment node, providing a visual representation of the skeleton segment. Parent/child translation and rotation relationships are defined in parent/child HAnimSegment nodes.

The HAnimSegment node is a grouping node that will typically contain either a number of Shape nodes or perhaps Transform nodes that position the body part within its coordinate system as defined in ISO/IEC 19774. The use of LOD nodes is recommended if the geometry of the HAnimSegment is complex.

Each field is described in ISO/IEC 19774.

## 26.3.6 HAnimSite

    HAnimSite : X3DGroupingNode {
      MFNode     [in]     addChildren               [X3DChildNode]
      MFNode     [in]     removeChildren            [X3DChildNode]
      SFVec3f    [in,out] center           0 0 0    (-∞,∞)
      MFNode     [in,out] children         []       [X3DChildNode]
      SFString   [in,out] description      ""
      SFBool     [in,out] bboxDisplay      FALSE
      SFBool     [in,out] visible          TRUE
      SFNode     [in,out] metadata         NULL     [X3DMetadataObject]
      SFString   [in,out] name             ""
      SFRotation [in,out] rotation         0 0 1 0  [-1,1] or (-∞,∞)
      SFVec3f    [in,out] scale            1 1 1    (0,∞)
      SFRotation [in,out] scaleOrientation 0 0 1 0  [-1,1] or (-∞,∞)
      SFVec3f    [in,out] translation      0 0 0    [-1,1] or (-∞,∞)
      SFVec3f    []       bboxCenter       0 0 0    (-∞,∞)
      SFVec3f    []       bboxSize         -1 -1 -1 [0,∞) or −1 −1 −1
    }

An HAnimSite node serves three purposes. The first is to define an "end effecter" location that can be used by an inverse kinematics system. The second is to define an attachment point for accessories such as jewelry and clothing. The third is to define a location for a virtual camera in the reference frame of an HAnimSegment (such as a view "through the eyes" of the humanoid for use in multi-user worlds).

Each field is described in ISO/IEC 19774.

# 26.4 Support levels

The HAnim component provides 3 levels of support as specified in Table 26.2.

Table 26.2 — Humanoid animation (HAnim) component support levels

Level | Prerequisites | Nodes/Features | Support
--- | --- | --- | ---
1 | Core 1 Grouping 1 Geometry3D 2 Shape 1 Texturing 1 Navigation 2 | HAnimHumanoid skeleton support |
|  | HAnimDisplacer | All fields fully supported.
|  | HAnimHumanoid | All fields fully supported except skin, skinCoord, skinNormal, skinBindingCoord, skinBindingNormal, motions and motionsEnabled fields optional.
|  | HAnimJoint | All fields fully supported except skinCoordIndex and skinCoordWeight fields optional.
|  | HAnimSegment | All fields fully supported.
|  | HAnimSite | All fields fully supported.
2 | Core 1 Grouping 1 Geometry3D 2 Shape 1 Texturing 1 Navigation 2 | HAnimHumanoid skin support |
|  | HAnimDisplacer | All fields fully supported.
|  | HAnimHumanoid | All fields fully supported except motions and motionsEnabled fields optional.
|  | HAnimJoint | All fields fully supported.
|  | HAnimSegment | All fields fully supported.
|  | HAnimSite | All fields fully supported.
3 | Core 1 Grouping 1 Geometry3D 2 Shape 1 Texturing 1 Navigation 2 | Motion animation support |
|  | HAnimDisplacer | All fields fully supported.
|  | HAnimHumanoid | All fields fully supported.
|  | HAnimJoint | All fields fully supported.
|  | HAnimMotion | All fields fully supported.
|  | HAnimSegment | All fields fully supported.
|  | HAnimSite | All fields fully supported.