ATOM format description

The .atom file format is similar to the .anim format and uses the same schema for saving animation curves. However it also contains additional data such as non-animated static values, baked values, animation layers, and embedded export edit files which contain information for reconstructing constraints and set driven keys. (See also ATOM file format.)

Once you export an .atom file (Export .atom animation), you can view and edit the file in any text editor of your choice. For the purposes of describing the format, this topic breaks the file down into the following parts:

To view a complete .atom file without descriptions, see Example .atom file.

Other introductory notes on the .atom syntax:

# is a valid comment character. Note that unlike .anim files, // is not a valid comment character.
```
#Atom File Format Description
```
Any line in the file that does not contain curly braces { or }, must end with a semi-colon (;). After the semi-colon (;) start a new line.
Keywords and data are whitespace delimited.

Header section

The header section of the .atom file can include the following.

atomVersion 1.0;
mayaVersion 2013 x64;
mayaSceneFile string
timeUnit [game|film|pal|ntsc|show|palf|ntscf|hour|min|sec|millisec]
linearUnit [mm|cm|m|km|in|ft|yd|mi]
angularUnit [rad|deg|min|sec]
startTime [float] 
endTime [float]
startUnitless [float] 
endUnitless [float]
offlineFile [string:optional]

For example:

atomVersion 1.0;
mayaVersion 2013 x64;
mayaSceneFile C:/Users/user/Documents/maya/projects/default/scenes/test.ma;
timeUnit film;
linearUnit cm;
angularUnit deg;
startTime 1;
endTime 8;
offlineFile ;

atomVersion	The version number of the file format. This is a required line.
mayaVersion	The Maya version. This string is the value of MGlobal::mayaVersion() mayaVersion string.
mayaSceneFile	(Optional) The name of the scene file that the .atom file was saved from.
timeUnit	These keywords are used to set the units for the file. Each animation curve, static value, and baked value can have its own units, but these are the default units if the anim curve units are not given (see animData). If the units are not given, then the UI units are used. Can be included only in the header section of the file.
linearUnit
angularUnit
startTime	The starting frame for the clipboard, and the ending frame for the clipboard. These are used by animation curves that have time inputs and by baked values. These lines are optional if there are no baked values in the file. If they are not included, the clipboard is set to the range defined by the animation curves contained in the clipboard. Note If there are baked values in the file, then these values are mandatory since they determine the start and end time of the baked values.
endTime
startUnitless	The starting value for the clipboard and the value for the clipboard. These are used by animation curves that do not have time inputs.
endUnitless
offlineFile	This keyword is optional, and is specified if the file contains export edits. The default behavior is to then embed the export edits at the end of the .atom file. If you specify a filename after the offlineFile keyword, that file is used as the offline edit file. The .atom format uses offline edits to store constraint and set driven key animation. Can be included only in the header section of the file. See also Embedded offline edit files.

Animation Layers section (Optional)

The animation layers section starts with a line that contains the names of all animation layers present on objects in this file.

animLayers {string string ...}

This line is followed by a list of the attributes for each animation layer.

This information is used on import to check whether any named animation layers are missing in the target scene, and creates them if they are.

For example:

animLayers {   BaseAnimation  AnimLayer1 }
animLayer {
  BaseAnimation 0 0;
  static mute mute 0;
  { 0 }
  static lock lock 1;
  { 0 }
  static solo solo 2;
  { 0 }
  static override override 3;
  { 1 }
  static passthrough passthrough 4;
  { 1 }
  static preferred preferred 5;
  { 0 }
  static weight weight 6;
  { 1 }
  static rotationAccumulationMode rotationAccumulationMode 7;
  { 0 }
  static scaleAccumulationMode scaleAccumulationMode 8;
  { 1 }
}
animLayer {
  AnimLayer1 0 0;
  static mute mute 0;

Main body (Objects) section

The main body of the file lists each node that has been saved in the .atom file. Supported node types include DAG nodes (dagNode keyword) and shape nodes (shape keyword). For other types of nodes, depend nodes (node keyword) are listed.

ImportantUnlike .anim files, the DAG and shape nodes in an .atom file are sorted in a particular order to match how they existed in the Maya scene. For example, the child shape nodes for a DAG node are listed immediately after the parent DAG node in the .atom file. Note that editing an .atom file to change this ordering can result in certain operations not working as expected.

The first line for each object included in the file specifies the node name, depth and child count.

dagNode {
pSphere1 1 1;

NoteFor all nodes except for DAG nodes, both of these values will be zero. For DAG nodes, the depth is the number of parents it has, including the root (so default is one), and child count identifies its sibling order number (default is one). These values are used when performing hierarchy matching on import.

Each node identifier is followed by a begin and closing parenthesis pair { }, which contains information for each attribute. ATOM files support static values (single, non-animated values), baked values (a list of per-frame values), or animation curve values.

This is one of the main differences between .anim and .atom files. While .anim files contain a simple list of attributes (with the associated object as part of the attribute listing), the .atom file lists each attribute under the object that it belongs to, making .atom files easier to read and improving the matching done on import.

dagNode {
pSphere1 1 1;
}
static string string int string|optional
cached int|float|double int|float|double int|float|double ... 
anim string string int string|optional

For example:

dagNode {
  pSphere1 1 1;
  anim translate.translateY translateY 0;
  animData {
    input time;
    output linear;
    weighted 0;
    preInfinity constant;
    postInfinity constant;
    keys {
      1 0 auto auto 1 1 0;
      10 -0.48952813 auto auto 1 1 0;
    }

Each attribute is exported the same way, with a static, cached (for baked), or anim (for animation curve) identifier, followed by the long name of the attribute, the short name, the attribute number, and an optional animation layer name.

dagNode {
  pSphere1 1 1;
  anim translate.translateY translateY 0;
  animData {
    input time;
    output linear;
    weighted 0;
    preInfinity constant;
    postInfinity constant;
    keys {
      1 0 auto auto 1 1 0;
      10 -0.48952813 auto auto 1 1 0;
    }
  }
  cached translate.translateX translateX 0;
  { -5.2988979 -4.7870473 -3.4152877 -1.4293071 0.92520503 3.4025622 5.4610407 0.70032059  }
}
dagNode {
  pPlane1 1 2;
  static rotate.rotateX rotateX 0;
  { 0 }
  static rotate.rotateY rotateY 1;
  { 0 }
  static rotate.rotateZ rotateZ 2;
  { 0 }
  static scale.scaleX scaleX 3;
  { 1 }
  static scale.scaleY scaleY 4;
  { 1 }
  static scale.scaleZ scaleZ 5;
  { 1 }
  static visibility visibility 9;
  { 1 }
}

NoteIf the animation layer name is present, the data specified is found on that node and attribute for that specified animation layer, so the attribute name will appear multiple times, once for each animation layer it is a part of.

static

After static identifier, a single value that specifies the value of the non-animated attribute is listed inside a parentheses pair.

This value can be an integer, float, double, string, or enumeration.

cached

Baked values are similar to static values but represent a value per frame over the time range specified by the start and end times. Values get baked when the Baked Animation option is turned on during export.

If the exported attribute is not driven by a simple animation curve and is not exported as an animation layer, constraint, or set driven key.

So for baked values we have a begin and end parenthesis pair followed by a set of values, equal to the number of frames between the specified start and end times.

anim

The saved attribute can be driven by an animation curve, just like in .anim files.

As noted earlier, the anim keyword is followed by the long name, short name, and attribute number of the string.

WarningThis is different than .anim files where before the attribute number the row (depth) and child numbers are also saved, so be careful if integrating .anim data into an .atom file, since these redundant numbers need to be removed.

(See the following.)

If an attribute is driven by an animation curve, the anim line is followed by an animData block that specifies the key data.

animData  {
  input [time|unitless]
  output [time|linear|angular|unitless]
  weighted [1|0]
  inputUnit [game|film|pal|ntsc|show|palf|ntscf|hour|min|sec|millisec]
	 outputUnit [game|film|pal|ntsc|show|palf|ntscf|hour|min|sec|millisec]
  outputUnit [mm|cm|m|km|in|ft|yd|mi]
  outputUnit [rad|deg|min|sec]
  tangentAngleUnit [rad|deg|min|sec]
  preInfinity [constant|linear|cycle|cycleRelative|oscillate]
  postInfinity [constant|linear|cycle|cycleRelative|oscillate]

For example:

anim rotate.rotateY rotateY 5 AnimLayer1;
  animData {
    input time;
    output angular;
    weighted 0;
    preInfinity constant;
    postInfinity constant;
    keys {
      1 0 auto auto 1 1 0;
      8 0 flat auto 1 1 0;

animData	Indicates the start of the key data for the animation curve including the following definitions:
input	The input type of the anim curve. Defaults to time.
output	The output type of the anim curve. Defaults to linear.
weighted	Specifies whether the curve has weighted tangents. Defaults to false.
inputUnit	The unit of the anim curve input, if it is a time input. Defaults to the time units specified in the file header section.
outputUnit	The unit of the anim curve output. The output unit should match the output type of the curve. Defaults to the units specified in the header.
tangentAngleUnit	The unit of the tangent angles, if there are any fixed tangents. Defaults to the angular units specified in the file header.
preInfinity	The pre-infinity type. Defaults to constant.
postInfinity	The post-infinity type. Defaults to constant.
keys	(See the following.)

The final lines in each block contain the actual keyframe data. Each key is a row in the braced section.

 keys {
 [float] [float] [in tan] [out tan] [tan locked] [weight locked][breakdown]

float

These first two values are the input and output values in the units defined by the inputUnit and outputUnit keywords.

in tan

out tan

The in and out tangent types. Should be valid tangent types.

tan locked

weight locked

breakdown

Int values for tangent locking, weight locking, and the breakdown flag. If they are 0, the values are unlocked, or not a breakdown, otherwise they are locked.

If either, or both, or the tangents are fixed, then additional information is needed: a tangent angle and weight.

These two values, per fixed tangent, are added at the end of the line.

For example, 62.345 is the tangent angle for the first tangent and the tangent weights are 0.04:

1.0 2.0 fixed linear 1 1 0 62.345
0.04;

An example with two fixed tangents:

1.0 2.0 fixed fixed 1 1 0 62.345
0.04 45.3 0.023;

Embedded offline edit files (.editMA)

An .atom file can contain an embedded offline edit file (.editMA file) if the offlineFile identifier is present in the header.

For example:

offlineFileData //Maya ASCII 2013ff03 scene
//Name: test.editMA

After the offlineFileData identifier, there will be a stream of data that contains the embedded .editMA file. This data must come at the end of the file.

WarningDo not modify this data.