Animation Options Panel for the COLLADA DAE File Exporter

This panel controls the export "animation conversion engine". This engine allows any form of source animation data to be exported cleanly and properly to COLLADA.

Object Animation

If this option is enabled (checkmarked) then object animation data which is currently contained within the internal database will be exported.

Preferred Interpolation method: Constant, Linear, Bezier

This combo box determines which type of keyframe interpolation method should be used for the exported COLLADA file. At the moment the possible choices are constant and linear. In almost all cases you will want to use Bezier.

Keep Original Interpolation Method When Possible

If this checkbox is enabled then the animation resampling process will attempt to preserve the interpolation method used in the original source animation data. This can often be accomplished, but not in all cases. When it can be accomplished, then the animation data sent to the COLLADA file will preserve the same interpolation type as the original source animation data. Otherwise, the animation output to COLLADA will use the "Preferred Interpolation Method" you have specified above. You will typically want to keep this checkbox enabled, unless you have specific reasons for wanting all your COLLADA animation controllers to use the same interpolation type.

NOTE: When this checkbox is enabled, keyframe resampling might still occur. However, the interpolation type of the resampled keyframes will have the same interpolation method as the original source animation data, when possible (or the "Preferred Interpolation Method" when the original source animation data's interpolation method cannot be used.)

If this checkbox is disabled then the resampling process will use the "Preferred Interpolation Method" you have specified above. If the original animation source data has a different interpolation type, then resampling must occur. If the original source data has the same interpolation type as the "Preferred Interpolation Method" you have specified above, then resampling will only occur if otherwise mandated.

Preferred Rotation Type (Quaternion, XYZ, XZY, YXZ, YZX, ZXY, ZYX)

When we refer to the "rotation controller type" (or just rotation type), we are indicating whether a rotation animation is expressed in terms of Quaternions or in terms of Euler Angles. When rotation data is expressed in terms of Euler Angles, it is expressed in terms of some specific rotation axis order (such as XYZ or YZX). The rotation controller type of the original source animation data will have been chosen by the format-specific plugin which brought the source data into PolyTrans. Generally, the rotation controller type of the original source animation data could vary from object to object, from camera to camera, and from light to light.

If and when animation resampling occurs on a rotation channel, the resampling process must select a target rotation type. Since repetitive-order Euler rotations (XYX, ZXZ, etc) of the source animation data are not entirely compatible with COLLADA's repetitive-order Euler rotations, it is sometimes necessary to pick an arbitrary rotation type as output for the resampling process. This arbitrary choice is left in your hands and is selected via this drop-down box.

Whenever the original rotation type can be replicated into COLLADA, you have a choice between keeping the original rotation type or always using one specific rotation type. That choice is controlled by the "Keep Original Rotation Controller Type When Possible" option below. If you disable that checkbox, then all rotation animation exported to COLLADA will be forced to use the rotation type selected in the "Preferred Rotation Type" list box.

Keep Original Rotation Controller Type When Possible

If this checkbox is enabled then the resampling process will attempt to preserve the rotation controller type used in the original source animation data. This can often be accomplished, but not in all cases. When it can be accomplished, then the rotation animation exported to COLLADA will use the same rotation controller type as the original source animation data. Otherwise, the rotation animation exported to COLLADA will use the "Preferred Rotation Type" as specified above. You will typically want to keep this checkbox enabled, unless you have specific reasons for wanting all your COLLADA rotation animations to use the same rotation type.

NOTE: When this checkbox is enabled, rotation keyframe resampling might still occur. However, the resampled rotation keyframes will have the same rotation type as the original source animation data, when possible (or the "Preferred Rotation Type" when the original source animation data's rotation type is not compatible with COLLADA).

NOTE: The rotation type is not to be confused with the interpolation type. The selection of rotation type determines which rotation data channels are created for COLLADA (either a single Quaternion channel or 3 independent Euler Angle channels), as well as which Euler Angle order to use (when the rotation type is not Quaternion). Each rotation channel created for COLLADA must then be assigned an interpolation type, which is determined according to the relevant options above ("Preferred Interpolation Type" and "Keep Original Interpolation Type When Possible").

If this checkbox is disabled then the resampling process will use the "Preferred Rotation Method" you have specified above. If the original animation source data has a different rotation type, then resampling must occur. If the original source data has the same interpolation type as the "Preferred Rotation Method" you have specified above, then resampling will only occur if otherwise mandated.

Fix up -180/180 Degree Euler Flips (Maintain Euler Continuity)

This option fixes exported Euler rotation channels which flip back and forth between values close to 180 degrees and -180.0 degrees, from key to key. Normally this flipping will not pose a problem unless COLLADA "slows down" an animation for previewing in slow motion, and does sub-key interpolation (in such cases the objects may appear to randomly spin in the wrong direction at specific keys).

This option can only take effect when rotation curves are explicitly resampled during the import process.

NOTE: This option will not take effect if the 'Preferred Rotation Type' is set to Quaternion and the 'Keep Original Rotation Controller Type When Possible' is disabled.

Background Info:

There are several cases where the exported rotation animation needs to be "resampled" from one mathematical format to another, such as if the Euler order has to be changed, or when quaternion animation needs to be cross converted to Euler animation curves for COLLADA.

The resampling process first converts the rotation value(s) at each keyframe to a 4x4 rotation matrix, and then the matrix is decomposed into explicit (X, Y, Z) Euler rotation angles, of the desired Euler order. The Euler angles will always be in the range -180 to 180 degrees.

The primary disadvantage of the traditional Euler decomposition method comes about when the target program tries to view the animation in a "slow motion" mode. Since two adjacent frames might have values of, say, -179.9 and 179.9 (or vice versa) on one of the Euler angles, the sub-frame interpolation between these values will result in a quick spin through 359.8(!) degrees, rather than the intended 0.2 degree change. When a "slow motion" mode is not in effect, the user will traditionally never see the sub-frame interpolated values because the -179.9 and 179.9 rotations are absolute and correct values (needing no further interpolation between them).

Problem example: if the imported source rotations are 150.0 deg, 179.0, deg, 185.0 deg, 190.0 deg then after resampling the rotations will be 150.0 deg, 179.0 def, -175.0 deg, -170.0 deg. These are correct. However, some 3D viewers, during slow-motion playback where sub-frame interpolation is performed, will look at the 179.0 to -175.0 degree interval and create new interpolated values through a 354 degree rotation interval and not the shorter 6 degree rotation.

What This Option Does:

Enabling this option will allow an additional algorithm to be used which detects cases of "-180/180 degree Euler Flips" and attempts to fix them. This alternative algorithm will take the previous frame of animation into account when performing rotation resampling. It will attempt to decompose the rotation into a equivalent set of Euler angles which represents the smallest Euler-space change of values. This makes the algorithm very good for preventing -180/180 discontinuities in the Euler animation curves. This allows "slow motion" sub-frame interpolation to function as ideally expected.

One possible down-side to this alternative algorithm is that Euler angles are free to "drift" away from the normal -180/180 range. Let us suppose you have an animation of a spinning top. Under the traditional algorithm, the top might spin from 0 to 180, then a discontinuity effect occurs, causing the next frames to go from -180 to 0 to 180, and so forth. With this option enabled, the top would spin from 0 to 180, then from 180 to 360 to 540, and so forth. There are hypothetical scenarios where users might not want that to happen. If that is the case, disable this option to ensure that all angles are clamped to the -180/180 range.

Resampling and Reduction Options

Pressing this button will show the animation resampling and reduction options dialog box. This, in general, controls the precision and reduction options used globally during animation resampling (for both import and export). If you find that your imported animation data looks jittery or does not hit target translations/rotations, then reduce the tolerance values.

If you disable keyframe reduction, then resampled animation data will have a key at every frame. You might have a specific reason to desire that output. Leaving keyframe reduction enabled, but setting the tolerance values to zero, will result in a curve which perfectly fits the original curve at all frames, but has all redundant keys eliminated. For example, if a channel is actually non-animated, then leaving keyframe reduction enabled with a zero tolerance will result in far fewer keys than entirely disabling keyframe reduction.