Animation XML tags for HSF

Proposed by:

Tech Soft 3D

Initial release date: January 14th, 2003

Acceptance date: February 17th, 2003

Last modification: February 17th, 2003

This document describes how to encode behavioral information as XML tags. The syntax/naming-scheme and functional descriptions are still preliminary and should serve as a base for discussion.

General Concepts

It is our intention to separate model geometry definitions and behavioral information. This implies that the animation data is stored separately from the model data and in particular is NOT part of the segment tree structure. In a lot of cases the XML tags might still be embedded inside the HSF file (as user data) but they can also be stored in a separate file. As discussed below in some cases the animation data can also reference multiple HSF files.

One goal of the design is to keep the definition simple, functional and easy to grasp with a high degree of reusability for the individual elements to cut down on size. For the first iteration the functionality will also be somewhat limited to let the feature implementation keep up with the XML definition.

This paper does not discuss implementation related issues. It is up to the developer to find a solid class based representation of the various tags for his application. TSA however will provide a fully featured implementation as part of its MVO class library.

Below is a rough overview of the various Tags described in this document and their hierarchical relationship:

Quick Overview

A typical behavior definition will consist of the following components:

• “Timeline” - tags that provide a list of time values expressed in ticks. These are used for key-framing.

• “Interpolator” - tags that represent changing values over a time period. These could be positional values, rotation, color, etc. Some of these values will have additional “Modifiers” attached to them which control how the interpolation is performed (linear, bezier, etc).

• “Animation” - tags which connect a timeline with one or more interpolators and applies various attributes to the animation (delay period, initial acceleration, on/off, etc…)

• “Sensor” - tags which define simple (usually mouse based) user interaction with objects on the screen and can trigger/stop animations or other sensors and perform other tasks.

XML Tags

<Animdef>

Parameters:

Name = string (optional) Identifier of the animation data

Version = string Version number of the format specification Vendor = string (optional, default = "") Vendor information TicksPerSecond = integer (optional, default = 4800) Number of individual "time-slices" per second that can be used to specify key frames (tps). All time related values are expressed in ticks. FramesPerSecond = float (optional, default = 30) Number of frames displayed for every second of real time. This value does not influence the overall playback speed of the animation which is defined by the TicksPerSecond Parameter (see above).

Delay = int (optional, default = 0) Initial Execution delay for this animation block (in ticks)

File = string (optional., default = "") Path/URL of file that serves as stage for this animation block

**Description:** This tag encloses all animation specific data. The "File" parameter can be used to load a default environment for the viewer/container. Using this approach the user can use a HSF to define the initial attribute settings within the scene. This could include color settings for geometry within the scene and the initial positioning of lights.

**Example:** A set of animation tags is enclosed by this tag. It also specifies a default scene definition loaded from the file "defaultscene.hsf":

  ...
...

**Parameters:**

Modifiers = string Global Modifier list for this timeline Valid options are currently: (l)inear, (t)cb, (b)ezier (d)iscrete <> Array of time values (in ticks) along the timeline

**Description:** This tag defines a series of time values (expressed in ticks) used in conjunction with one or more interpolators. The actual time for one frame is determined by the "TicksPerSecond" parameter in the Animdef tag that encloses all animation data. The timeline array can be seen as linear interpolation of time over distance. By using modifiers on an individual timeline element it is possible to change this "velocity curve" and give it non-linear behavior. While it is common in animation to specify "acceleration and deceleration" as part of the "space-curve" definition this approach provides an alternative and more direct control over the "speed" of the animation. See the "Interpolator" description for a more in-depth discussion of modifiers. **Example 1:** Timeline consisting of four elements:

 0 10 20 30

**Example 2:** Timeline consisting of 4 elements. The default modifier is changed to bezier. Element 3 has a linear modifier attached which overrides the default one:

0 10 [[l]20] 30

Using Interpolator Tags

The following tags provide the key-frame values for the various interpolation types. Additionally each element can have one or more "modifiers" attached to it, which further specifies the interpolation method and other parameters. Syntactically every key-frame value is enclosed into square brackets (which can be omitted only for singular components). Additional modifiers appear inside these brackets. Modifiers can be abbreviated usually by their first few letters (as indicated). Currently the following "Modifiers" are supported:

• **Linear (l):** Linear interpolation between keyframes
• **Discrete (d): **"Abrupt" switching between this keyframe and the following with no interpolation between them.
• ** Bezier (b):** Bezier spline interpolation, if no tangent vectors are specified a smooth ease in/ease out between keyframes is assumed
• **Cardinal Spline (ca):** Cardinal spline interpolation, if no curve tightness is specified catmull rom spline is asumed
• **Tcb (t):** Interpolation based on tcb-splines. Tension, continuity, bias, ease-in and-ease-out parameters need to be specified
• **Absolute (a): **Interpolation values are expressed in absolute terms in relation to the last keyframe (default)
• **Relative (r):** Interpolation values are expressed in relative terms in relation to the last keyframe
• **Constant Acceleration (co):** Keeps the interpolation speed constant between two keyframes (applicable to spline modifiers)
• ** Channels (c):** Specifies to which of the output channels the keyframe values correspond to. This allows for very compact definitions of 1 or 2-Dimensional Animation values as well as animating channels separately.
• ** Extra Rotation (er):** Take the "long" path instead of the shortest rotation between two quaternions.
• ** (*):** Hold the value from the last keyframe constant to the current keyframe value. This is NOT the same as simply repeating the last value especially for non-linear interpolation.
• ** Rotation Vector (v): **Rotation vector for use with AxisRotInterpolator type.

All unrecognized modifiers must be quietly disregarded by any standard parser. The user is free to create his own modifier types however we recommend prefixing them with a "$" symbol to avoid any clashes with future extensions of the format. For most interpolation types "*" can be used instead of defining specific values for the output channels. This holds the value of the channels constant from the last keyframe to the current keyframe. If "*" is used in the first item of the interpolation list this indicates that the interpolation should proceed from the currently set value of the target. Here is an example of a positional value with various modifier combinations: [0.4 0.1 0.2] Position only, default modifiers specified by "Modifiers" attribute are used. [d 0.4 0.1 0.2] Discrete switching (no interpolation) occurs at this keyframe. "D" does not need a separate bracket as it is a singular value [[b 0.2 1.0 0.5 0.3 1.7 2.2] 0.4 0.1 0.2] Bezier interpolation is used for this keyframe. Two tangents are defined together with the bezier token. [l [c 13] 0.4 0.1] Two Modifiers are used here, the first forces linear interpolation and the second limits the animation channels to the first and the third (x and z) [l r 1.2 2.4 3.6] Two Modifiers are used here, the first forces linear interpolation and the indicates that the interpolation from the last to this keyframe should occur in a relative fashion. [1 2 3] * [4 5 6] The channel values 1,2 and 3 are held constant until the second keyframe value has been reached by the animation. * [4 5 6] [7 8 9] The Interpolation starts from the original values of the target object (e.g. as defined by a modeling matrix)

**Parameters: **

Name = string (optional) Identifier of the Interpolator object

FollowPath = (1 or 0), (optional, default = "0") Adjusts the rotation of the object to follow the path of the keyframe values PathVector = [x y z], (optional, default = [1 0 0]) Directional vector if FollowPath=1

Modifiers = string, (optional, default = [l a]) Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: linear, tcb, bezier, discrete, absolute, relative, channels, "*"

<> Array of positional values

**Description:** Positional values expressed either linear or spline based movement.

**Example:**


[0 0 0] [0.2 0.6 0.8] [0.1 0.6 0.3] [0.0 0.1 0.2]

**Parameters: **

Name = string (optional) Identifier of the Interpolator object Color = string, (optional, default = "white") Color of the trail geometry

Weight = x, (optional, default = 1) Thickness of the trail Style = string, (optional, default = "----" ) Style of trail (see HOOPS documentation for available line styles) Type = string ("forward", "backward", "full"), (optional, default = "forward" ) Path will either extend from target position to last keyframe (forward), from first keyframe to target position (backward) or from first keyframe to last keyframe (full)

Modifiers = string, (optional, default = [l a]) Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: linear, tcb, bezier, discrete, absolute, relative, channels, "*"

<> Array of positional values

 

**Description:** Positional values defining a trail drawn as line segments. The trail is created in a special subsegment (called "trail") of the segment pointed to by the target object of the parent animation.

**Example:**


[0 0 0] [0.2 0.6 0.8] [0.1 0.6 0.3] [0.0 0.1 0.2]

**Parameters: **

Name = string (optional) Identifier of the Interpolator object

Modifiers = string, (optional, default = [l a]) Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: linear, discrete, absolute, relative,channels, "*" <> Array of scaling values (1.0 = no scaling), only positive values are allowed

**Description:** Linear or non-linear scaling of objects **Example:**

[1 1 1] [2.0 2.0 2.0]

**Parameters: **

Name = string (optional) Identifier of the Interpolator object

Modifiers = string, (optional, default = [l r]) Default Modifiers that are implicitly applied to all keyframes Valid modifiers include linear, tcb, discrete, absolute, relative, "*", extra rotation

<> Array of quaternions ([x y z w])

**Description:** Rotational Values expressed as quaternions (x, y, z, w). SLERP interpolation is used between the keyframes. **Example:**

[0 0 -0.5070 0.823] [0 0 -0.3070 0.823] [0 0 -0.5070 0.223] [0 0 -0.5470 0.823]

**Parameters: **

Name = string (optional) Identifier of the Interpolator object

Modifiers = string, (optional, default = [l a]) Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: linear, discrete, absolute, relative,"*", rotation vector

<> Array of rotation angles (in degree)

**Description:** Rotational Values expressed as rotations around a common axis (in degrees). Swinging door, pendulum, etc...

**Example:**


0 45 [[v 1 0 0]90] 180

 

**Parameters: **

Name = string (optional) Identifier of the Interpolator object

Type = string (optional, default = "diffuse") Further specifies the color component(diffuse, specular, transmission)

GeomType = string (optional, default = "everything") Further specifies the geometry type that the color applies to (faces, edges, lines, etc...) Modifiers = string, (optional, default = [l a]) Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: linear, tcb, bezier, discrete, absolute, relative,channels, "*"

<> Array of color values (expressed as rgb-triplets)

**Description:** Color values expressed as rgb triplets.

**Example:**

[0 0 0] [1.0 1.0 1.0]

**Parameters: **

Name = string (optional) Identifier of the Interpolator object

Modifiers = string Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: discrete, "*" <> Array of segment identifiers

**Description:** Transition between attribute settings. All attributes of the segments referenced in the keyframe list will be applied to the target segment. Useful for switching rendering modes, visibility, etc.

**Example:**


"target1" "target2" "target3" "target4"

**Parameters: **

Name = string (optional) Identifier of the Interpolator object

Modifiers = string Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: discrete, "*" <> Array of segment identifiers Can be of the following types (see Appendix A for more information): TOB, TID, HKEY

**Description:** Transition between segments by turning visibility on/off. Simple but fast form of animation. **Example:**

"target1" "target2" "target3" "target4"

**Parameters:**

Name = string (optional) Identifier of the Interpolator object

Modifiers = string, (optional, default = [l]) Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: linear, discrete, "*"

<> Array of shell identifiers

**Description** Transition between facetted objects with the same number of vertices. Linearly interpolates between vertex coordinates. Useful for non-rigid body animation. Note that object descriptor can currently only be a tag-id or a key. (TOB, TID, HKEY),

**Example:**



"object descriptor1" "object descriptor2" "object      descriptor3" "object
descriptor4"
&
lt;/VertexMorphInterpolator>

**Parameters: **

Name = string (optional) Identifier of the Interpolator object

Modifiers = string, (optional, default = [l]) Default Modifiers that are implicitly applied to all keyframes Valid modifiers include: linear, discrete, "*"

<> Array of color array identifiers

**Description:** Transition between per vertex color attributes to model for example heat or stress proliferation on an object. The object descriptor must point to an array of color values that match the target object.

**Example:**

"object descriptor1" "object descriptor2" "object      descriptor3" "object descriptor4"

**Parameters: **

Name = string (optional) Identifier of the Animation object Target = string (optional) Identifier of target object for this animation (see below) The target can be of the following types (see Appendix A for more information): TOB, TID, HKEY, SPATH, FILE

Active = 0/1 (optional, default = 1) Animation active 1=yes 0 = no Delay = int (optional, default = 0) Initial delay before animation starts (in ticks)

Loop = integer (optional, default = 1) number of loops for the animation. -1 indicates infinite RLoop = 0/1 (optional, default = 0) go backwards after complete timeline, useful for swinging doors, etc... Accelerate = 0/1 (optional, default = 0) Accelerate on start of animation

Decelerate = 0/1 (optional, default = 0) Decelerate on end of animation CurrentTick= int (optional, default = 0) currently elapsed tick for the animation. This can be used to start the animation at a particular stage (in ticks)

InstanceOf = string (optional, default = "") The name of an animation or animation block that will be instanciated by this animation. (See below for more information)

**Description: **By combining a timeline with one or more interpolators and a target the Animation tag defines a single animation. If the timeline contains more values than the interpolator the remaining timeline values are disregarded. If the timeline contains less values than the interpolator than the number of interpolator values must be a multiple of the timeline values. Timeline values (s): 0, 0.2, 0.8, 1.2 Rotation Values (degree): 0, 90, 180 The animation will rotate from 0 to 180 degrees in 0.8 seconds and then stop or restart (according to the loop setting) Timeline values (s): 0, 0.2, 0.8, 1.2 Rotation Values (degree): 0,20,40,60,80,100,120,140 The animation will go from 0 to 180 degrees in 1.2 seconds. It will be at 40 degrees in 0.2 seconds and at 20 degrees in 0.1 seconds. Timeline values (s) : 0, 0.2, 0.8, 1.2 Rotation Values (degree): 0,20,40,60,80,100 Invalid!! An animation can be declared either active or inactive at startup. If inactive it can later be activated by a sensor tag, through scripting or programmatically. An active animation will execute immediately after program initialization with the defined delay time With the Loop parameter it is possible to allow an animation to be performed once or any number of times. Alternatively it can also go backwards after going through the complete timeline by setting RLoop to 1. This is useful for a swinging door or any kind of repetitive animation. Apart from the delay time that is only executed once it is also possible to define an acceleration time and deceleration time which allows for a smooth acceleration when going from the first to the second (or second last to last) value of the interpolators. This is based on a simple predefined acceleration/deceleration curves. This tag can also be nested allowing for sets of animations that logically belong together. All tags that appear inside an "Animation" tag are defined relative to that block. Sensor tags can access nested animation data by using a hierarchical naming scheme similar to the one used to access elements in the HOOPS segment structure. The same is true for target specifications. All parameters of the enclosing animation block will be inherited by the child animations. it is possible to define an animation "instance" by specifying another animation with the "InstanceOf" Parameter. This facilitates the reuse of animations for different target objects. An example would be an animation block that defines various complex animations which should be applied to multiple objects simultaneously. An "instanced" animation can itself not instantiate another animation. The "Target" Paremter for instanced animations will be ignored and replaced by the Target of the instanciating animation. Also the "CurrentTick" and "Active" Parameter do not apply for instanced animations. **Example 1:** This animation uses one timeline and two interpolators on the segment "MODEL/car/wheel". It is not active on startup:

   0 10 20


   [0 0 0] [10 10 10] [20 20 20]

     
        [0 0 0] [1 1 1] [0 0 0]

**Example 2:** This example demonstrates the use of two nested animation blocks:

        0 10 20 30

...
...

        ...
        ...

**Example 3:** This example demonstrates the use of two nested animation blocks which are instanciated by another animation:

        0 10 20 30

...
...

        ...
        ...













**Parameters: **

Name = string (optional, default = "") Identifier of target object

Path = string (required) Segment path to target object It can be of the following types (see Appendix A for more information): TOB, TID, HKEY, SPATH, FILE

Pivot = [x y z], (optional, default = [ 0 0 0 ]) Pivot point

Rotation = [x y z x y z x y z] Rotational Components of modelling Matrix

Scale = [x y z] Scale Components along the three axis

**Description:** This tags defines an alias for a given animation target. It can either enclose one or multiple animation tags or be defined for later use. **Example:** **Example 1:** In this example the TargetObject tag encloses two animations which do not need to specify a target separately. The Animations instanciate two other animations.

        0 10


        [10 20 30] [40 50 60]

**Example 2:** Here the alias "object1" is simply defined and can later be used by an animation tag.

**Parameters:**

Name = string Identifier of the subtarget object

Type = string String can be any one of the following : GEOMETRY, FACES, VERTICES, EDGES.

<> Array of subtarget values List of faces, vertices etc. that this animation applies to (for changing individual face colors, move vertices, etc)

**Description:** The subtarget tag can be part of the TargetObject tag and further specifies targets for the animation. Those could be individual faces/edges/vertices in a shell or individual shells inside a segment . **Example:**

        0 5 6 7 22 44 

**Parameters: **

Name = string (required) Identifier of the sensor object.

Active = (1 or 0) (optional, default = 1)

Delay = int (optional, default = 0) Delay time (in ticks) before sensor is active

**Description:** see below **Example:** see below

**Parameters:**

Target = string Identifier of target object for this sensor (see below). Could be either an object or an animation (for ONANIMFINISHED), if no target is provided sensor can still be executed by other sensor

Event = event associated with the target (optional, default = ONLCLICK). Valid options include: ONTICK, ONLCLICK, ONRCLICK, ONMOUSEOVER, ONCOLLISION, ONANIMFINISHED, ONSENSOR

Idle = (0,1) optional, default = "1") Event is only executed if target object is idle (not in any animation)

**Description:** see below **Example:** see below

**Parameters:**

Target = string (optional, default = "") Animation Identifier, Object Identifier or Sensor identifier

Type = string Action associated with the target.Valid options include ACTIVATE, DEACTIVATE, RESET, RESTART, LOADFILE.

Value = string Additional parameters for the defined action, (optional , default = "")

Delay = int (optional, default = 0) Delay time (in ticks) before action is activated

**Description:** The different action type strings have the following meaning:

ACTIVATE continues an animation from it's current position DEACTIVATE stops an animation at its current position INFOTEXT displays text information (e.g. tooltip) at mouse position RESET stops an animation at it's current position and rewinds it RESTART restarts an animation LOADFILE loads a new (hsf) file and places it in the directory defined by the value parameter LOADURL loads a specific URL by opening a separate browser window

This collection of tags provide a simple means of triggering animation based on user input or other sensors. It is usually associated with visible geometry that the user can interact with. In a lot of cases this will be the same geometry that the animation is performed on. To chain multiple animations together ONANIMFINISHED with an animation as the target can be used. Users can define their own action types/value combinations. All action types that are not recognized will have to be quietly disregarded by any parser. We recommend developers to prefix all user defined types with a "$". **Example:** In this example the animation a2 is activated and a3 is deactivated if the geometry contained in the model/car2 segment has been clicked. Also a new file is loaded into the model directory:

In this example the sensor gets triggered if the animation a2 has been finished. It then activates animation a3

Complete Examples

Example1:

        0 10 20 30


        + [r 0.2 0.6 0.8] [r 0.1 0.6 0.3] [r 0.0 0.1 0.2]

        0 1.0


        [0 0 0] [1 1 1]

        0 10 20 30


        [0 0 -0.5070 0.823] [0 0 -0.3070 0.823] [0 0 -0.5070 0.223]
        [0 0 -0.5470 0.823]


        + [r 0.2 0.6 0.8] [r 0.1 0.6 0.3] [r 0.0 0.1 0.2]

**Example2:** A simple example with just one animation:

        0 10 20 30


        [0 0 -0.5070 0.823] [0 0 -0.3070 0.823] [0 0 -0.5070 0.223]
        [0 0 -0.547 0.823]

**Example3:** A simple example with one animation definition that is instanciated for two targets with the second reusing the timeline and interpolator from the first.

   

        0 10 20 30


          [0 0 -0.5070 0.823] [0 0 -0.3070 0.823] [0 0 -0.5070 0.223] [0 0 -0.547 0.823]

**Example4:** In this "realworld" example an objects visibility is first turned on, it then rotates 360 degrees around it's center in 8 seconds. After that it fades to invisibility and back to fully opaque in ten seconds total. After that the animation can be triggered again by clicking on the object.

        
                  0 40 80 120 160
        

                   
        
                 "MODEL/object1"
        

                   
                  + 90 180 270 360
        

          
        
                  0 100
        
        

                   
                        [1.0 1.0 1.0] [0 0 0]
        

This sensors condition is met afterAnimation A3 has finished for the first time. It then turns on the sensor S2 and disables itself

This sensor is initially inactive and gets activated by sensor s1 after the animation A3 executed for the first time. Once active it is triggered by a left mouseclick on the target object and restarts animation a2 and a3

Appendix A:

Object Type Identifiers:

"TOB:" : The name of a previously declared "TargetObject" tag Example: Target = "TOB: object1" "TID:" : A tag identifier which can be obtained from the streaming toolkit while processing the hsf file. Example: Target = "TID: 123"

"HKEY: " : A unique key identifying the object Example: Target = "HKEY: 123"

"SPATH:" : A segment path corresponding to the HSF segment structure. SCENE and MODEL are reserved keywords (they refer to the model segment and scene segment as defined in MVO). Specifying SCENE as the segment name can be useful to make global color changes or to do camera movement. "CAMERAPOS" and "CAMERATARGET" are reserved keywords that refer to the camera of the scene. Translation and quaternion rotation will be applied to the camera position/orientation. Camera manipulation will usually require separate animations performed in conjunction. One for the camera movement (using the POS interpolator), one for the camera orientation (using QUAT or EULER) and one for zooming in/out (using the scale interpolator). For "orbit" types of camera animation it is usually preferable to animate the cameratarget, while for walkthroughs the camera position should be used. The camera keywords can appear at the end of a target statement. This is useful if multiple cameras in the scene need to be manipulated. Examples: Target = "SPATH: MODEL/car/wheel1" Target = "SPATH: SCENE/CAMERATARGET"

"FILE:" : The name of an HSF or file who's contents will be treated as the object. The object will be loaded into the current scene into a separate segment. Example: Target = "FILE: teapot.hsf" "ANIM:" The name of an animation tag Example: Target = "ANIM: a1"

"SSR:" The name of a Sensor tag Example: Target = "SSR: s1"