19.1 Introduction

19.1.1 Name

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

19.1.2 Overview

This subclause describes the Interpolation component of this part of ISO/IEC 19775. Table 19.1 provides links to the major topics in this subclause.

19.2 Concepts

This clause includes six Interpolator nodes all of which provide keyframe-based animation capability.

19.2.1 Interpolators

The Interpolator nodes provide linear interpolation between animation key frame values. The following node types are Interpolator nodes, each based on the type of value that is interpolated:

• ColorInterpolator
• CoordinateInterpolator
• CoordinateInterpolator2D
• NormalInterpolator
• OrientationInterpolator
• PositionInterpolator
• PositionInterpolator2D
• ScalarInterpolator

All Interpolator nodes are based on the abstract type X3DInterpolatorNode.

19.2.2 Linear interpolation

The X3D Interpolator nodes specified in this clause are designed for linear key framed animation. Each of these nodes defines a piecewise-linear function, f(t), on the interval (−∞,∞). The piecewise-linear function is defined by n values of t, called key, and the n corresponding values of f(t), called keyValue. The keys shall be monotonically non-decreasing, otherwise the results are undefined.

An interpolator node evaluates f(t) given any value of t (via the fraction field) as follows: Let the n keys t₀, t₁, t₂, ..., t_n−1 partition the domain (−∞,∞) into the n+1 subintervals given by (-∞, t₀), [t₀, t₁), [t₁, t₂), ... , [t_n−1, +∞). Also, let the n values v₀, v₁, v₂, ..., v_n-1 be the values of f(t) at the associated key values. The piecewise-linear interpolating function, f(t), is defined to be:

    f(t) = v0,    if t ≤ t0,
         = vn−1,   if t ≥ tn−1,
         = linterp(t, vi, vi+1),    if ti ≤ t ≤ ti+1,

     where linterp(t,x,y) is the linear interpolant, 
           i belongs to {0,1,..., n−2}.

The third conditional value of f(t) allows the defining of multiple values for a single key, (i.e., limits from both the left and right at a discontinuity in f(t)). The first specified value is used as the limit of f(t) from the left, and the last specified value is used as the limit of f(t) from the right. The value of f(t) at a multiply defined key is indeterminate, but should be one of the associated limit values.

19.3 Abstract types

19.3.1 X3DInterpolatorNode

X3DInterpolatorNode : X3DChildNode { 
  SFFloat      [in]     set_fraction       (-∞,∞)
  MFFloat      [in,out] key           []   (-∞,∞)
  MF<type>     [in,out] keyValue      []
  SFNode       [in,out] metadata      NULL [X3DMetadataObject]
  [S|M]F<type> [out]    value_changed
}

The abstract node X3DInterpolatorNode forms the basis for all types of interpolators specified in this clause.

The key field contains the list of key times, which could appear as:

    key [0 0.25 0.65 0.75 1]

The set_fraction inputOnly field receives an SFFloat event and causes the interpolator node function to evaluate, resulting in a value_changed output event of the specified type with the same timestamp as the set_fraction event.

The contents of the keyValue and value_changed fields are dependent on the type of the node (e.g., the PositionInterpolator fields use MFVec3f values). Each value or set of values in the keyValue field corresponds in order to the parameter value in the key field.

For interpolator nodes that produce a single value, results are undefined if the number of values in the key field is not the same as the number of values in the keyValue field.

For Interpolator nodes that produce multiple values, the keyValue field is an nxm array of values, where n is the number of values in the key field and m is the number of values at each key frame. Each m values in the keyValue field correspond, in order, to a parameter value in the key field. Each value_changed event shall contain m interpolated values. Results are undefined if the number of values in the keyValue field is not a positive integer multiple of the number of values in the key field.

If an X3DInterpolatorNode value_changed outputOnly field is read before it receives any inputs, keyValue[0] is returned if keyValue is not empty. If keyValue is empty (i.e., [ ]), the initial value for the respective field type is returned (EXAMPLE  (0, 0, 0) for SFVec3f); see 5 Field type reference for initial event values.

The location of an X3DInterpolatorNode in the transformation hierarchy has no effect on its operation. For example, if a parent of an interpolator node is a Switch node with whichChoice set to −1 (i.e., ignore its children), the interpolator continues to operate as specified (receives and sends events).

A typical simplified structure for a key frame animation implementation involves a TimeSensor, ROUTEs, and the target node.

  Transform { 
    Shape 
       IndexedFaceSet { coordIndex='... −1 ... >
           Coordinate DEF='Moved' point [ x y z, ... ] # t0Geometry
       }                  
    } 
  } 

  CoordinateInterpolator DEF='Mover' 
      key [t0 t1 t2 ]            #   list of key times, 0 to 1
      keyValue ' x y z, ... '    #   one geometry per key time 

  TimeSensor DEF='Timer' cycleInterval 5 loop TRUE 

  ROUTE Timer.fraction_changed TO Mover.set_value  
  ROUTE Mover.value_changed TO Moved.point 

In typical operation, the key frame set_fraction event arrives from a TimeSensor to signal that the time value has advanced. This value varies from 0 to 1 depending upon where the TimeSensor is in its cycle time. For example, if the TimeSensor has a cycleTime of 10 seconds, and 5 seconds has elapsed in its cycle, the set_fraction value will be 0.5.

In this example structure, the IndexedFaceSet contains a Coordinate field named Moved. This defines the time equals zero geometry for the node. The CoordinateInterpolator node named Mover contains the list of key frame times and the corresponding sets of Coordinates in the keyValue field. When the set_fraction event arrives for key, the corresponding interpolated keyValue is sent to the target Coordinate node for rendering.

19.4 Node reference

19.4.1 ColorInterpolator

ColorInterpolator : X3DInterpolatorNode {
  SFFloat [in]     set_fraction       (-∞,∞)
  MFFloat [in,out] key           []   (-∞,∞)
  MFColor [in,out] keyValue      []   [0,1]
  SFNode  [in,out] metadata      NULL [X3DMetadataObject]
  SFColor [out]    value_changed
}

This node interpolates among a list of MFColor key values to produce an SFColor (RGB) value_changed event. The number of colours in the keyValue field shall be equal to the number of key frames in the key field. The keyValue field and value_changed events are defined in RGB colour space. A linear interpolation using the value of set_fraction as input is performed in HSV space (see [FOLEY] for description of RGB and HSV colour spaces). The results are undefined when interpolating between two consecutive keys with complementary hues.

19.4.2 CoordinateInterpolator

CoordinateInterpolator : X3DInterpolatorNode {
  SFFloat [in]     set_fraction       (-∞,∞)
  MFFloat [in,out] key           []   (-∞,∞)
  MFVec3f [in,out] keyValue      []   (-∞,∞)
  SFNode  [in,out] metadata      NULL [X3DMetadataObject]
  MFVec3f [out]    value_changed
}

This node linearly interpolates among a list of MFVec3f values to produce an MFVec3f value_changed event. The number of coordinates in the keyValue field shall be an integer multiple of the number of key frames in the key field. That integer multiple defines how many coordinates will be contained in the value_changed events.

19.4.3 CoordinateInterpolator2D

CoordinateInterpolator2D : X3DInterpolatorNode {
  SFFloat [in]     set_fraction       (-∞,∞)
  MFFloat [in,out] key           []   (-∞,∞)
  MFVec2f [in,out] keyValue      []   (-∞,∞)
  SFNode  [in,out] metadata      NULL [X3DMetadataObject]
  MFVec2f [out]    value_changed
}

This node linearly interpolates among a list of MFVec2f values to produce an MFVec2f value_changed event. The number of coordinates in the keyValue field shall be an integer multiple of the number of key frames in the key field. That integer multiple defines how many coordinates will be contained in the value_changed events.

19.4.4 NormalInterpolator

NormalInterpolator : X3DInterpolatorNode {
  SFFloat [in]     set_fraction       (-∞,∞)
  MFFloat [in,out] key           []   (-∞,∞)
  MFVec3f [in,out] keyValue      []   (-∞,∞)
  SFNode  [in,out] metadata      NULL [X3DMetadataObject]
  MFVec3f [out]    value_changed
}

The NormalInterpolator node interpolates among a list of normal vector sets specified by the keyValue field to produce an MFVec3f value_changed event. The output vector, value_changed, shall be a set of normalized vectors.

Values in the keyValue field shall be of unit length. The number of normals in the keyValue field shall be an integer multiple of the number of key frames in the key field. That integer multiple defines how many normals will be contained in the value_changed events.

Normal interpolation shall be performed on the surface of the unit sphere. That is, the output values for a linear interpolation from a point P on the unit sphere to a point Q also on the unit sphere shall lie along the shortest arc (on the unit sphere) connecting points P and Q. Also, equally spaced input fractions shall result in arcs of equal length. The results are undefined if P and Q are diagonally opposite.

19.4.5 OrientationInterpolator

OrientationInterpolator : X3DInterpolatorNode {
  SFFloat    [in]     set_fraction       (-∞,∞)
  MFFloat    [in,out] key           []   (-∞,∞)
  MFRotation [in,out] keyValue      []   [-1,1] or (-∞,∞)
  SFNode     [in,out] metadata      NULL [X3DMetadataObject]
  SFRotation [out]    value_changed
}

The OrientationInterpolator node interpolates among a list of rotation values specified in the keyValue field to produce an SFRotation value_changed event. These rotations are absolute in object space and therefore are not cumulative. The keyValue field shall contain exactly as many rotations as there are key frames in the key field.

An orientation represents the final position of an object after a rotation has been applied. An OrientationInterpolator interpolates between two orientations by computing the shortest path on the unit sphere between the two orientations. The interpolation is linear in arc length along this path. The results are undefined if the two orientations are diagonally opposite.

If two consecutive keyValue values exist such that the arc length between them is greater than π, the interpolation will take place on the arc complement. For example, the interpolation between the orientations

(0, 1, 0, 0) and (0, 1, 0, 5.0)

is equivalent to the rotation between the orientations

(0, 1, 0, 2π) and (0, 1, 0, 5.0).

19.4.6 PositionInterpolator

PositionInterpolator : X3DInterpolatorNode {
  SFFloat [in]     set_fraction       (-∞,∞)
  MFFloat [in,out] key           []   (-∞,∞)
  MFVec3f [in,out] keyValue      []   (-∞,∞)
  SFNode  [in,out] metadata      NULL [X3DMetadataObject]
  SFVec3f [out]    value_changed
}

The PositionInterpolator node linearly interpolates among a list of 3D vectors to produce an SFVec3f value_changed event. The keyValue field shall contain exactly as many values as in the key field.

19.4.7 PositionInterpolator2D

PositionInterpolator2D : X3DInterpolatorNode {
  SFFloat [in]     set_fraction       (-∞,∞)
  MFFloat [in,out] key           []   (-∞,∞)
  MFVec2f [in,out] keyValue      []   (-∞,∞)
  SFNode  [in,out] metadata      NULL [X3DMetadataObject]
  SFVec2f [out]    value_changed
}

The PositionInterpolator node linearly interpolates among a list of 2D vectors to produce an SFVec2f value_changed event. The keyValue field shall contain exactly as many values as in the key field.

19.4.8 ScalarInterpolator

ScalarInterpolator : X3DInterpolatorNode {
  SFFloat [in]     set_fraction       (-∞,∞)
  MFFloat [in,out] key           []   (-∞,∞)
  MFFloat [in,out] keyValue      []   (-∞,∞)
  SFNode  [in,out] metadata      NULL [X3DMetadataObject]
  SFFloat [out]    value_changed
}

This node linearly interpolates among a list of SFFloat values to produce an SFFloat value_changed event. This interpolator is appropriate for any parameter defined using a single floating point value. Examples include width, radius, and intensity fields. The keyValue field shall contain exactly as many numbers as there are key frames in the key field.

19.5 Support levels

The Interpolation component provides three levels of support as specified in Table 19.2.