Animation in HOOPS Publish
HOOPS Publish is able to export key frame animation in 3D PDF documents. This feature allows you to use JavaScript to direct the animation using familiar controls. Attributes of the geometric model which can be animated are appearance, transform, and camera. If you are already familiar with building 3D PDF documents programmatically, you should be able to get running quickly as animation is built into the Artwork Publish object.
In order to organize complex animations efficiently, the animation interface is broken into a hierarchy:
Note the objects with the [array] tag. This indicates these objects are inserted as arrays of multiple objects in order to support complex, multi-layered animations.
Overview
At the lowest level, the animation interface is built around one main data structure, A3DPDFAnimKeyFrameData. This structure represents the state of the model at a specific key frame. The idea is to build multiple A3DPDFAnimKeyFrameData structures and order them sequentially, which allows HOOPS Publish to interpolate the animated object between key frames. You should adjust the parameters of each key frame data structure so it describes the model at that frame. You can combine the attributes of appearance, transform, and camera into the same key frame.
Key frames are collected to form a key frame array. The array is then used as a component of a motion data object. The motion object, A3DPDFAnimMotion, defines movement on a set of target objects. If you have a scene with multiple animated objects, you need to create a corresponding motion object for each of them.
All motion objects are then collected to form an animation object. Animation objects also encapsulate other high-level parameters such as number of frames per second. Finally, the animation object is bound to the Publish Artwork object.
JavaScript
Although the HOOPS Publish interface language is C++, all generated documents are able to store embedded JavaScript. The purpose of JavaScript in this context is to interact with the model and control the animation. The procedure is roughly as follows:
- User begins creating a 3D PDF, possibly containing JavaScript logic for interactive widgets such as buttons
- As part of the Artwork, user creates an animation for the PDF using C++
- Upon generating the document, HOOPS Publish automatically translates the C++ instructions and embeds them in the document as additional JavaScript
- User may inspect or edit the JavaScript before the 3D PDF is finalized (see reference manual entry for A3DPDF3DArtworkEditAnimationJavascript)
Further details about using JavaScript are provided after the first example.
Building an animation
Perhaps the best way to learn about the implementation details of the Publish animation API is to inspect a few examples. There are three examples in this guide:
In the first example, we will demonstrate how to move the camera around a model in order to create an orbiting effect. As noted earlier, Publish animations are hierarchical and are typically built from the bottom up. Therefore, in step 1, we will start by building the key frames.
Example 1 - Moving the camera
This example will create an animation based on two key frames. There are two parts to each key frame - the key frame object itself, as well as its associated data (in this case, camera position). The data for each key frame is stored in an object of the type A3DPDFAnimKeyFrameData while the encapsulating object is of type A3DPDFAnimKeyFrame.
Step 1: Create the basic structures
Step 2: Set up the data for the first key frame
In order for the animation API to work, you must define the properties for each key frame. The following code snippet sets up the starting position and orientation of the camera.
Now that all data for the first key frame is created, we need to bind it to the animation framework. This is done by calling A3DPDFAnimKeyFrameCreate. Notice that we are binding it to the 0th element of the key frame array. Change this as needed for additional key frames.
Step 3: Set up the data for the second key frame
In the second key frame, the camera position and zoom changes, but the target remains the same. The objects used here are identical to the previous step, but the field values are changed to reflect the desired key frame.
Step 4: Set up the motion parameters
Now that the key frames are created, you must next assign the motion parameters. These parameters control things like the number of key frames to expect, whether or not there is a starting delay, or whether the animation will repeat. This example uses two key frames, loops, and will start immediately.
NOTE: The motion target is the object that will be animated. In this case, we are animating only the camera. The camera is not part of the model file, so it is not addressable. Therefore, the number of targets is zero. The target field is used in the other animation types. See this subsection for more information.
Step 5: Build the animation object
The animation object, A3DPDFAnimation, is the final encapsulating object of an animation. This object controls number of frames per second and contains any motion objects from the previous step.
Step 6: Add the completed object to the Artwork
The animation object becomes part of the normal Artwork object used when exporting HOOPS Publish PDF documents.
Note on interpolations
The interpolation mask, sKeyFrameData.m_iInterpolationMask, lets HOOPS Publish know what type of interpolation your animation should use. In the last example, we set this field to kA3DPDFInterpolateCamera to indicate we were animating the camera. Other values allow you to interpolate the appearance or matrix (see examples 2 and 3, below).
If you do not want smooth interpolation, set the interpolation mask field to 0. This will force an abrupt transition at the next key frame.
Interacting with animations
Before continuing with further examples, we will spend some time discussing how to interact with the animation. The animations generated by HOOPS Publish can be controlled with JavaScript embedded within the PDF document. In most cases, the PDF page defines buttons to play and pause the animation. Other buttons may play a minimal portion of the animation, or just a subset of animations.
The primary functions that can be called externally are as follows:
| Parameters: | start - The time, relative to the animation, from which you would like the animation to begin playing. A value of 0 indicates the beginning of the animation. |
| end - The time, relative to the animation, from which you would like the animation to end. | |
| fncallbackStart - A callback function that is called at the beginning of the sequence. | |
| fncallbackStop - A callback function that is called at the end of the sequence. |
Returns: none
Parameters: none<br>
Returns: none
| Parameters: | start - The animation from which you would like to begin playing. A value of 0 indicates the first animation. |
| end - The animation at which you would like to end. | |
| fncallbackStart - A callback function that is called at the beginning of the sequence. | |
| fncallbackStop - A callback function that is called at the end of the sequence. |
Parameters: none<br>
Returns: none
These interactions are demonstrated in the package sample area - samples\publish\publishsource\AnimWorkinstruction.
Example 2 - Transformation
This example shows how to build the key frames for an animation which makes a cube turn on its z-axis. The process for building the animation is almost the same as the previous example. The main difference is setting up the key frame data - since we are dealing with a transformation instead of adjusting the camera position, we will adjust the model matrix.
First key frame
Second keyframe: rotation of 90 degrees around z
Third keyframe: rotation of 90 degrees around z again, the result is a rotation of 180 degrees
Fourth keyframe: rotation of 90 degrees around z again, the result is a rotation of 270 degrees
Fifth keyframe: rotation of 90 degrees around z again, the result is a rotation of 360 degrees, back to the first position
Motion object
Lastly, when building the motion object, be sure to account for all five key frames:
For this type of animation, it is also necessary to specify which object will be animated. This object is called the target object, and it is specified by a PRC entity and its father product occurrence. If you don't already have a reference to these target data, you can use the function A3DPDFGetEntitiesFromName to traverse your model in order to find it. The target is specifed in the motion object.
Example 3 - Adjusting appearance over time
In this example, we are going to create an animation which changes the color and transparency of the model.
Like the previous transformation example, you also need to specify the animation target in the motion object.