Motion

CubicVR.Motion

The Motion class represents a group of Envelope objects that are used for ID-based motion control of objects. It's primary use is as the .motion property of a SceneObject, Light or Camera in a Scene to provide animation but can be applied to nearly anything.

Motion( obj_init )

Invoke with an object initializer representing the motion or referencing an external json or xml via CubicVR.get. Please note this functionality is experimental.

// A simple Motion representing a translation on X, Y that repeats forever
// and an X, Z rotation that continues on an offset forever
mySceneObject.motion = new CubicVR.Motion({
    position: {                         // Controller ID
        0.0: { x: 0, y: 1 },            // Time: { MotionID: value, MotionID: value },
        1.0: { x: 1 },
        2.0: { x: -1, y: 0 },
        3.0: { x: -0.5 },
        4.0: { x: 0, y: 1 },
    },
    rotation: {                         // Controller ID
        0.0: { x: 0, z: 0 },            // Time: { MotionID: value, MotionID: value },
        1.0: { x: 90, z: 45 },
        envelope: {                     // Envelope behavior specific to 'rotation' controller
            behavior: "offset"
        }
    },
    envelope: {
        behavior: "repeat"              // Default envelope behavior for other envelopes
    }
});

// This motion will be evaluated for an object in a Scene when scene.evaluate(time); has been called.

Motion( env_init, key_init )

Invoke with the env_init and key_init constructors which will be used for defaults for subsequent envelopes and keys that are created for this motion.

Parameters:

• env_init : A default behavior constructor object for any Envelope channels created. (optional)
• key_init : An object constructor representing the default Envelope key structure/options. Used when not provided otherwise. (optional)

Object Constructor(s):

var env_init = {
  in_behavior: "constant",  // Input behavior (before envelope start) for curves
  out_behavior: "constant"  // Output behavior (after envelope end) for curves
};

var key_init = {
  shape: "tcb",    // One of the shape enumerators.
  tension: 0.0,    // If "tcb", tension value.
  continuity: 0.0, // If "tcb", continuity value.
  bias: 0.0,       // If "tcb", bias value.
  param: null      // If "herm"/"bez2" relative X/Y tangent pairs: [inTime, inValue, outTime, outValue].
};

Behaviors:

Enumerators for the behavior of envelopes (controllers). Each controller may contain an independent behavior for what to do when it's envelope is being evaluated before or after it's timeline. Each controller has it's own begin/end time based on the keys set and are not dependent on the motion as a whole.

• "constant" : repeat the first or last value.
• "reset" : return 0.
• "repeat" : cycle back to the first or last value.
• "oscillate" : cycle back and forth between the first and last value.
• "offset" : cycle back to the first or last value and offset subsequent cycles.
• "linear" : continue forever at the incoming or outgoing tangent.

Shapes:

The shape of an envelope determines what function is used to evaluate it. Some shape types require additional parameters so the default is to use "tcb" or tension-continuity-bias as it requires no additional parameters to provide smooth animation but can be easily tuned per key.

• "tcb" : tension-continuity-bias based interpolation. You can set the .tension, .continuity and .bias of any key, default for all 3 is 0.
• "line" : linear interpolation, values move linearly.
• "step" : step interpolation, values remain constant between keys.
• "herm" : Hermite based interpolation. Use the key .param to set tangents: [inTime, inValue, outTime, outValue].
• "bezi" : 1-dimensional bezier curve interpolation.
• "bez2" : Bezier based interpolation. Use the key .param to set tangents: [inTime, inValue, outTime, outValue].

Motions:

Several classes in CubicVR already support having an obj.motion property representing a Motion object that can be applied at the Scene level using the scene.evaluate(index) method. Here are the standard control, motion pairs that are supported:

• Position - supported by SceneObject, Camera and Light

  • Controller ID "pos" or "position" : Object position
  • Motion IDs "x", "y" or "z" : X, Y or Z position

• Rotation - supported by SceneObject, Un-targeted Camera and Un-targeted Light

  • Controller ID "rot" or "rotation" : Object rotation
  • Motion IDs "x", "y" or "z" : X, Y, or Z rotation in euler degrees.

• Scale - supported by SceneObject

  • Controller ID "scl" or "scale" : Object scale
  • Motion IDs "x", "y" or "z" : X, Y or Z scale value

• Camera-specific

  • Controller IDs
    • "fov" : Field of view
    • "lens" : Lens focal length
    • "nearclip" : Near clip plane
    • "farclip" : Far clip plane
  • Motion IDs
    • "v" : Value for controller

• Light-specific

  • Controller IDs
    • "intensity" : Light Intensity
  • Motion IDs
    • "v" : Value for controller

Methods:

setKey( controllerId, motionId, time, value, key_init ) or setKey( controllerId, motionId, key_init )

Add a new key frame to the Motion at the given envelope controller/motion id.

Parameters:

• controllerId : One of the standard motion pairs (described above) or your own controllerId, any positive integer value is allowed
• motionId : One of the standard motion pairs (described above) or your own motionId, any positive integer value is allowed
• time : Time of keyframe to insert.
• value : Value of key.
• key_init (optional) - An object constructor representing the new key structure/options. Same as constructor plus time and value.

var key_init = {
  time: 0.0,       // Time for this key (required)
  value: 0.0,      // Value for this key (required)
  shape: "tcb",    // One of the shape enumerators.
  tension: 0.0,    // If "tcb", tension value.
  continuity: 0.0, // If "tcb", continuity value.
  bias: 0.0,       // If "tcb", bias value.
  param: null      // If "herm"/"bez2" relative X/Y tangent pairs: [inTime, inValue, outTime, outValue].
};

Returns:

The inserted Envelope key, structure matches key_init for setting properties.

setArray( controllerId, time, value, key_init )

Add an array of new motion keys to the Motion at the given envelope controller id. Provides a simple way to avoid having to call setKey for individual motion channels since they are designed to align with their data types, i.e. [0: X, 1: Y, 2: Z]

Parameters:

• controllerId : One of the standard motion pairs (described above) or your own controllerId, any positive integer value is allowed
• time : Time of keyframe to insert.
• value : An array of values in the format: [#motionId: value, #motionId: value, ... ].
• key_init (optional) - see setKey for reference.

Returns:

An array of the inserted Envelope keys, structure matches key_init for setting properties (see setKey).

envelope( controllerId, motionId )

Fetch (or create and fetch) the envelope given by controllerId and motionId channels.

Parameters:

• controllerId : One of the standard motion pairs (described above) or your own controllerId, any positive integer value is allowed
• motionId : One of the standard motion pairs (described above) or your own motionId, any positive integer value is allowed

Returns:

A pre-existing Envelope with the given id's or a new Envelope initialized to env_init provided during construction.

apply( time, target )

Evaluate all envelopes, interpolate and apply the values at the given time index to the object target via a function callback.

Parameters:

• time : Time (or X value) to evaluate.
• target : An object with a function in the format: obj.control( controllerId, motionId, value ) relevant values in all envelopes will be called independently.

Returns:

none

evaluate( time )

Evaluate all envelopes, interpolate and return the values at the given time index.

Parameters:

• time : Time (or X value) to evaluate.

Returns:

Values of all envelope at given time, indexed array format: [ #controllerId#: [ #motionId#: value, #motionId#: value, ... ], #controllerId#: [ ... ], ... ].

setBehavior( controllerId, motionId, in_behavior, out_behavior )

Set the incoming/outgoing (pre/post) behavior of individual envelopes.

Parameters:

• controllerId : One of the standard motion pairs (described above) or your own controllerId, any positive integer value is allowed
• motionId : One of the standard motion pairs (described above) or your own motionId, any positive integer value is allowed
• in_behavior : Input behavior (before envelope start). See Motion Behaviors constructor for options.
• out_behavior : Output behavior (after envelope end). See Motion Behaviors constructor for options.

Returns:

none

setBehaviorArray( controllerId, in_behavior, out_behavior )

Set the incoming/outgoing (pre/post) behavior for an array of motion envelopes.

Parameters:

• controllerId : One of the standard motion pairs (described above) or your own controllerId, any positive integer value is allowed.
• in_behavior : Input behavior array keyed by motionId format: [ #motionId#: behavior_in, #motionId#: behavior_in, .. ]. See Motion constructor for options.
• out_behavior : Output behavior array keyed by motionId format: [ #motionId#: behavior_out, #motionId#: behavior_out, .. ]. See Motion constructor for options.

Returns:

none