AnimJ

From Neos Wiki
Jump to navigation Jump to search
Other languages:
English • ‎日本語

AnimJ is a custom import format for Animation asset files in Neos. It allows you to build arbitrary animation tracks as external JSON files and import them as Neos native Animation assets. Those can be used to drive values with Animator or samples with LogiX nodes.

Schema

Each animation can have one or more animation tracks. Neos supports different animation track types for different purposes. Each animation track can also use any Neos Primitive as its element. Each animation track has one or more keyframes that represent a sequence of values.

The typical structure of animation track is following:


{
   "name": "My Animation",
   "globalDuration": 0,
   "tracks": [
       {
           "trackType": "Discrete",
           "valueType": "float",
           "data": {
               "node": "Test",
               "property": "Test",
               "keyframes": [
                   {
                       "time": 0,
                       "value": 1
                   },
                   {
                       "time": 1,
                       "value": 42
                   },
                   {
                       "time": 5,
                       "value": 20
                   }
               ]
           }
       }
   ]
}


follows is a example track with a float3 type:

{
   "name": "Test Animation Data 1",
   "globalDuration": 0,
   "tracks": [
       {
           "trackType": "Discrete",
           "valueType": "float3",
           "data": {
               "node": "TestData",
               "property": "TestData",
               "keyframes": [
                   {
                       "time": 0,
                       "value": {
                           "x": 1.0,
                           "y": 2.0,
                           "z": 3.0
                       }
                   }
               ]
           }
       }
   ]
}

Animation Track

Animation track is a single timeline of values. You can have as many animation tracks in an Animation as you like. Each track can be uniquely identified by Node and Property.

Node indicates which object in the hierarchy given track controls, while Property specifies which of its fields will be controlled when the animation is bound to a scene objects. For example Node "Fan Blade" and Property "Rotation" for track of type floatQ can control rotation animation.

However both are just names and do not need to correspond to anything in the scene. You can ignore the names and refer to the animation track by its index or use the names for a dynamic lookup with LogiX.

Animation Track Types

Neos currently supports following animation track types. Each type is optimized for different use-case. Animation can mix tracks of different types.

Raw Animation Track

This is the simplest form of animation. It is a raw sequence of values, with a global Interval (length of the animation). The keyframes are uniformly distributed in this track. This can be ideal representation for baked animations with a regular framerate.


Here's example of such track:

{
           "trackType": "Raw",
           "valueType": "float",
           "data": {
               "node": "Test",
               "property": "Test",
               "keyframes": [
                  0.5,
                  0.7,
                  0.8,
                  0.9
               ]
           }
}

Discrete Animation Track

This track is useful for keyframes that are irregular and do not need interpolation. Each value is held for the entire duration of the keyframe, until the next one comes in. This is the type of animation track that Neos imports subtitles as, but it can be used for any value. It can be useful also in cases you do your own custom interpolation (e.g. with Smooth Lerp) and just need to change the "master" value.

{
           "trackType": "Discrete",
           "valueType": "float",
           "data": {
               "keyframes": [
                   {
                       "time": 0,
                       "value": 2
                   },
                   {
                       "time": 1,
                       "value": 8
                   },
                   {
                       "time": 5,
                       "value": 20
                   }
               ],
               "node": "Test",
               "property": "Test"
           }
}

Curve Animation Track

This is the most versatile (and typical) type of animation track, used for values that are interpolated between. Each keyframe can use different types of interpolation (Hold, Linear and Tangent). The Tangent interpolation keyframes specify the Left and Right tangents, which indicate how the keyframe's base value changes over time as it transitions to the next keyframe.

When importing 3D Model files, this type of animation track is used.

The following example shows the Curve animation track with linear interpolation between keyframes. It also has additional Discrete animation track.

{
   "name": "Universe Timing (Czech)",
   "tracks": [
       {
           "trackType": "Curve",
           "valueType": "float",
           "data": {
               "node": "Scale",
               "property": "",
               "keyframes": [
                   {
                       "time": 0,
                       "value": -17,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 49.97,
                       "value": -17,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 97,
                       "value": -5,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 128,
                       "value": 0,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 134,
                       "value": 0,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 152,
                       "value": 5.5,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 175,
                       "value": 7,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 184,
                       "value": 7.5,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 207,
                       "value": 12,
                       "interpolation" : "Linear"
                   },
                   {
                       "time": 247,
                       "value": 27,
                       "interpolation" : "Linear"
                   }
               ]
           }
       },
       {
           "trackType": "Discrete",
           "valueType": "int",
           "data": {
               "node": "Phase",
               "property": "",
               "keyframes": [
                   {
                       "time": 0,
                       "value": 0
                   },
                   {
                       "time": 45,
                       "value": 1
                   },
                   {
                       "time": 49.97,
                       "value": 2
                   },
                   {
                       "time": 247,
                       "value": 3
                   }
               ]
           }
       }
   ]
}

The schema for keyframes with tangents (these define a bezier curve) is following:

{
   "time": 10,
   "value": 0,
   "leftTangent" : -10,
   "rightTangent" : 5,
   "interpolation" : "Tangent"
}