Roto serialisation format¶

Curve tree¶

The curve tree consists of a hierarchy of one or more layers, each containing zero or more curvegroups. Here we give a general description of the format, using AUgmented Backhaus Naur Form.

It disregards some fine lexer details, and is not necessarily suitable for turning directly into a parser. In particular, it has not been checked for ambiguity in the definition, and begin and end can be followed and preceded by whitespace.

begin                          = "{"

end                            = "}"

float                          = "0x" 8HEXDIG
float                          =/ ["-"] (1*DIGIT "." 1*DIGIT) / 1*DIGIT

  ; Floating point numbers can, in addition to being written out as normal
  ; decimals literals, be written out as hexadecimal literals (represented
  ; under IEEE 754).  For endianness considerations, see serialisation code
  ; further down.

int                            = ["-"] 1*DIGIT

unquoted-char                  = "!" / %x23-26 / %x28-5B / %x5D-7B / %x7C / %x7E

  ; everything ASCII except space, " ' \ { }

escaped-char                   = %x7D DQUOTE   ; "
escaped-char                   =/ %x7D %x27    ; '
escaped-char                   =/ %x7D %x5C    ; \
escaped-char                   =/ %x7D %x7B    ; {
escaped-char                   =/ %x7D %x7D    ; }

printable-char                 = unquoted-char / escaped-char

string                         = 1*unquoted-char
string                         =/ DQUOTE 0*printable-char DQUOTE

  ; the effect of this is that a string with space, " ' \ { } within it must be
  ; quoted

flag                           = int

  ; Flags are a bitmask.  See below for the significance of the bits.

wsp                            = 1*SP

view-name                      = string

attribute-name                 = string

  ; the view name "-" means the default view.

anim-curve-key-time            = float

anim-curve-key-value           = float

anim-curve-key-left-tangent    = wsp float wsp float

anim-curve-key-right-tangent   = wsp float wsp float

anim-curve-key-interpolation   = wsp int

  ; This is a bitmask.  The interpolation type can be found when masked
  ; with 255; the extrapolation can be found when shifted right 8 bits and
  ; masked with 255.
  ;
  ; The defined interpolation types are:
  ;   0 - step
  ;   1 - linear
  ;   2 - cubic
  ;
  ; The default value for this is "256" - i.e. linear extrapolation
  ; and step interpolation.

anim-curve-key-extra           = wsp "-"
anim-curve-key-extra           =/ anim-curve-key-left-tangent [anim-curve-key-right-tangent [anim-curve-key-interpolation]]

anim-curve-key                 = begin anim-curve-key-time wsp anim-curve-key-value [anim-curve-key-extra] end
anim-curve-key                 =/ begin anim-curve-key-time end

  ; Together these mean that a basic anim curve key consists of a group with
  ; time and value, separated by spaces, and then a list of optional
  ; elements that are in order the left tangents (2 floats), the right
  ; tangents (2 floats) and then the the interpolation type (which is a
  ; bitmask)
  ;
  ; If any of these are not provided the tangents default to 0 and the
  ; interpolation defaults to 256.  Instead of the optional elements, the
  ; literal "-" can be provided, which defaults both tangents to (0, 1) and
  ; the interpolation to 256.
  ;
  ; If this consists of only one element, then this represents the time
  ; alone, and can only appear as a medial or final element in the key-list.
  ; The other fields are copied from the immediately previous curve key.

anim-curve-expression          = "=" string
anim-curve-key-list            = anim-curve-key 0*(wsp anim-curve-key)

anim-curve-constant-value      = float

anim-curve-rle-key-count       = int

anim-curve-rle-key-entry       = begin anim-curve-key anim-curve-rle-key-count end

  ; The anim-curve-key is repeated anim-curve-key-count numbers of times,
  ; with each key's time being incremented by one from the base.

anim-curve-rle-key-list        = anim-curve-rle-key-entry 0*(wsp anim-curve-rle-key-entry)

anim-curve-data                = anim-curve-constant-value
anim-curve-data                =/ begin anim-curve-key-list end
anim-curve-data                =/ begin "r" begin anim-curve-rle-key-list end end

anim-curve-flag-entry          = begin "f" wsp flag end

  ; Flag entry consists of a group with "f" followed by the actual flag value
  ;
  ; There are no interesting flags on curves.  Ignore this.  Do not write it
  ; out.

anim-curve                     = anim-curve-data
anim-curve                     =/ begin [anim-curve-expression wsp] [anim-curve-flag-entry wsp] anim-curve-data end

  ; If there is no animation, an anim-curve can be represented as a single
  ; value, with no futher grouping at this level.
  ;
  ; Alternatively, it will be represented as a keylist, or possibly as an
  ; RLE keylist.
  ;
  ; If these is a flag and/or an expression then this will itself be wrapped
  ; in a group, with the expression or flag.

anim-curve-timeless-key        = anim-curve-key-value / ( begin anim-curve-key-value anim-curve-key-extra end )

  ; Similar to anim-curve-key but without time, which is fed in at a higher
  ; level and shared between multiple curves.  As an additional compaction
  ; step, if the tangents and interpolation are default values (i.e. 0 and
  ; 56), then it will be a single value outside a group, without the braces.

anim-curve-timeless-data-count = int

anim-curve-timeless-data-entry = anim-curve-timeless-key
anim-curve-timeless-data-entry =/ begin "x" wsp anim-curve-timeless-data-count wsp anim-curve-timeless end

anim-curve-timeless-data       = anim-curve-timeless-data-entry [wsp anim-curve-timeless-data-entry]

  ; Keylists for timeless data consists of elements which are either a
  ; timeless key in themselves (which might be a float literal if the
  ; tangents and interpolation is to be copied from the previous key), or a
  ; group which contains "x", a count, and then the actual key, for repeats
  ; of the same values.
  ;
  ; The time is fed in from outside

anim-curve-timeless            = anim-curve-key-value
anim-curve-timeless            =/ anim-curve-timeless-data
anim-curve-timeless            =/ begin [anim-curve-expression wsp] [anim-curve-flag-entry wsp] anim-curve-timeless-data end

anim-curve-views-entry         = view-name wsp anim-curve

anim-curve-views-list          = anim-curve-views-entry [wsp anim-curve-views-entry]

  ; This consists of the view as a string followed by the anim-curve.

anim-curve-views               = anim-curve
anim-curve-views               =/ begin "v" anim-curve-views-list end

  ; An anim-curve-views can be a regular anim-curve.  If so, then this is
  ; the "default" curve, and no others are split.  If it is split then it
  ; will be a group with "v" as its first element, followed by a number of
  ; view-curve entries (not themselves groups).

anim-attribute-entry           = attribute-name wsp anim-curve-views

anim-attribute-list            = anim-attribute-entry 0*(wsp anim-attribute-entry)

anim-attributes                = begin "a" anim-attribute-list end

  ; An AnimAttributes block is made up of a group containing "a", to
  ; indicate a set of attributes, then the name and curve for each
  ; attribute in turn.  Omitted attributes are set to the default,
  ; which will depend upon the type of object these attributes
  ; are for.
  ;
  ; Shape points have 2 dimensions.  Strokes have a third dimension,
  ; used for storing pressure.

anim-control-point             = begin [anim-attributes] 1*4(wsp anim-curve) end

  ; An AnimControlPoint consists of a group containing optionally, a list
  ; of attributes, and then up to four AnimCurves, one for each
  ; dimension.

anim-control-point-timeless    = begin [anim-attributes] 1*4(wsp anim-curve-timeless) end

  ; The timeless version of an AnimControlPoint uses anim-curve-timeless
  ; objects instead of AnimCurves.

anim-cubic-curve-flag-entry    = begin "f" wsp flag end

anim-cubic-curve-tension       = float

anim-cubic-curve-tension-entry = begin "tens" wsp anim-cubic-curve-tension end

key-times-list                 = begin float 1*(wsp float) end

anim-cubic-curve-points-list   = begin "p" wsp anim-control-point 0*(wsp anim-control-point) end
anim-cubic-curve-points-list   =/ begin "px" wsp key-times-list wsp anim-control-point-timeless 0*(wsp anim-control-point-timeless) end

  ; There are two versions of the cubic curve points list.  If all
  ; the AnimCurves within it use the same keyframes, then these are
  ; extracted outwards and a "px" group is made, with that keylist as
  ; the next element in the group - this is then followed by all the
  ; control point data.  This means it doesn't need to keep repeating
  ; common keyframes.
  ;
  ; However, it is not structurally built into the cubic curve that
  ; all control points or dimensions within must be keyed on the
  ; same sets of frames, they may be individually controled.  So a
  ; simpler format exists, which will write out all the control points
  ; in full.
  ;
  ; Note that the attributes are independent of this.

anim-cubic-curve               = begin "cc" wsp anim-cubic-curve-flag-entry [wsp anim-cubic-curve-tension-entry] wsp anim-cubic-curve-points-list end

  ; A cubic curve is a group containing the declaration "cc", the
  ; flags for the curve, an optional tension entry if the tension is
  ; non-default (the default being 0.5) followed by a point-list
  ; in either full or compact format.

anim-curve-group               = begin anim-cubic-curve wsp "idem" end
anim-curve-group               = begin anim-cubic-curve wsp anim-cubic-curve end

  ; An AnimCurveGroup is a group containing exactly two cubic curves.
  ; The first of these is always specified in full, and is the main
  ; curve.  The second of these is the feather, which is specified as
  ; an offset to the main curve (or rather, the 'absolute' points on the main
  ; become offsets to the corresponding ones, whereas the tangents,
  ; which were offsets from those absolute points on the main curve, become
  ; offsets from the absolute points on the feather.
  ;
  ; The feather curve can be replaced simply with "idem", which means
  ; that the feather is identical to the main curve: all the absolute offsets
  ; are zero, and the tangents are the same.

anim-curve-group-views-entry   = view-name wsp anim-curve-group

anim-curve-group-views         = anim-curve-group
anim-curve-group-views         =/ begin "v" anim-curve-group-views-entry 0*(wsp anim-curve-group-views-entry) end

anim-node-curve-type           = "bezier" / "bspline" / "catmullrom"

anim-node-name                 = string

anim-node-flag                 = int

anim-transform                 = begin "t" wsp anim-curve-views 1*(wsp anim-curve-views) end
anim-transform                 =/ begin "tx" wsp key-times-list anim-curve-timeless 1*(wsp anim-curve-timeless) end

 ; An AnimTransform consists of a bunch of animations for each transform curve
 ; these are in order - the pivot point (xyz), the translation (xyz), the scale (xyz),
 ; the rotation (xyz), the skew (xyz), the extra translation (xyz), the skew order;
 ; and then a 4x4 extra matrix.  These default to 0, except for the scale, which
 ; defaults to (1, 1, 1), and the matrix, which defaults to the identity matrix.
 ; any fields not present are the default.
 ;
 ; Transform and rotation orders are fixed, as there is no way of adjusting them
 ; in the UI, and therefore do not appear in the file format.  skew order is
 ; 0 = xy, 1 = yx

anim-curve-group-node          = begin "curvegroup" wsp anim-node-name wsp anim-node-flag wsp anim-node-curve-type wsp anim-curve-group-views wsp anim-transform wsp anim-attributes end

  ; An AnimCurveGroupNode is a group containing a declaration of its
  ; type, a node name, a flag, a curve type, a curve groups list (which
  ; might contain one curve group or one for several diffferent view),
  ; and then a transform and an attributes.
  ;
  ; The default attributes are as follows
  ;    0   : ro go bo ao bm inv mbo mbsot mbso fx fy ft src stx sy str sr sskx
  ;          ssky sso stot sto sv sb ltt tt pt
  ;    1   : vis r g b a opc mb fo ff ssx ssy sf nv view1 ltn ltm
  ;    0.5 : mbs
  ;    240 : spy
  ;    320 : spx

anim-curve-node                = begin "cubiccurve" wsp anim-node-name wsp anim-node-flag wsp anim-node-curve-type wsp anim-cubic-curve wsp anim-transform wsp anim-attributes end

  ; An AnimCurveNode is similar to the AnimCurveGroupNode, except that it only
  ; contains one curve, and that this cannot be split. (the attributes and transforms
  ; can be split)
  ;
  ; The default attributes are as follows
  ;    0    : bu bm ds dh bt inv src stx sty str sr sskx ssky sso sb
  ;           stot sto sv ltt tt ws ep1 ep2 ep3 nv1 view1
  ;    0.05 : bsp
  ;    0.2  : h
  ;    1    : vis r g b a ro go bo ao opc dt ssx ssy sf ltn ltm we
  ;           cookie hard_boundary boundary ab
  ;    25   : bs
  ;    240  : spy
  ;    320  : spx

anim-node                      = anim-curve-group-node / anim-curve-node / anim-layer-node

  ; An AnimNode can be either a CurveGroup, a CubicCurve or a Layer.
  ;
  ; Which is distinguished by the first keyword inside the group.

anim-node-list                 = [anim-node 1*(wsp anim-node)]

anim-layer-node                = begin "layer" wsp anim-node-name wsp begin "f" wsp anim-node-flag end wsp anim-transform wsp anim-node-list end

  ; A Layer node.  This contains a name, some flags, a transform, and then some more nodes.
  ;
  ; The default attributes are as follows
  ;   0     : fx fy pt
  ;   0.5   : mbs
  ;   1     : vis opc mbo mb fo ff warp

anim-tree-version              = float

anim-tree-version-entry        = begin "v" wsp anim-tree-version end

anim-tree-flag-entry           = begin "f" wsp flag end

anim-tree-root-entry           = begin "n" anim-layer-node end

anim-tree                      = begin anim-tree-version-entry wsp anim-tree-flag-entry wsp anim-tree-root-entry end

Floating point format¶

Floating point values are stored in binary encoded format (‘x01234567’), you can use the following code to convert between the two:

Values of 0.0f and 1.0f (zero and one) are special cased and stored just as ‘0’ or ‘1’.

From floating point to binary encoded:

std::string toString(float fltValue)
{
  static const char* hexDigits = "0123456789abcdef";

  unsigned int value = *reinterpret_cast<unsigned int*>(&fltValue);

  char buf[10];

  buf[9] = '\0';
  buf[8] = hexDigits[(value & 0xf)];
  value >>= 4;
  buf[7] = hexDigits[(value & 0xf)];
  value >>= 4;
  buf[6] = hexDigits[(value & 0xf)];
  value >>= 4;
  buf[5] = hexDigits[(value & 0xf)];
  value >>= 4;
  buf[4] = hexDigits[(value & 0xf)];
  value >>= 4;
  buf[3] = hexDigits[(value & 0xf)];
  value >>= 4;
  buf[2] = hexDigits[(value & 0xf)];
  value >>= 4;
  buf[1] = hexDigits[(value & 0xf)];
  buf[0] = 'x';

  return std::string(buf);
}

From binary encoding to floating point:

float toFloat(const char* str) {
  int value = 0;
  sscanf(str, "x%x", &value);
  return *reinterpret_cast<float*>(&value);
}

Layers¶

Layers can contain other layers or curve groups

Curve Groups¶

Curve groups specify the actual curve data for both Bezier and B-Spline curves.

There’s normally two curves in a curve group; the main curve and a feather curve (which can be the same as the main curve, unless the feather has been dragged out.)

SplineWarp curves only contain a main curve.

Keyframes and Animation¶

Keyframes are defined within a curvegroup in a {px …} block

{px {key0_time key1_time ...}
  {
    {a attribute_name {attribute_value_at_key0}}
    {control_point_position_at_key0}
  }
  {
    {a attribute_name {attribute_value_at_key1}}
    {control_point_positions_at_key1}
  }

  #...
}

Flags¶

Flag	Binary	Bit shift
eBreakFlag	000000000000000000000001	(1<<0)
eTangentLengthLockFlag	000000000000000000000010	(1<<1)
eKeySelectedFlag	000000000000000000000100	(1<<2)
eLeftTangentSelectedFlag	000000000000000000001000	(1<<3)
eRightTangentSelectedFlag	000000000000000000010000	(1<<4)
eOpenFlag	000000000000000000100000	(1<<5)
eSelectedFlag	000000000000000001000000	(1<<6)
eActiveFlag	000000000000000010000000	(1<<7)
eVisibleFlag	000000000000000100000000	(1<<8)
eRenderableFlag	000000000000001000000000	(1<<9)
eLockedFlag	000000000000010000000000	(1<<10)
ePressureInZFlag	000000000000100000000000	(1<<11)
eNukeAnimCurveEvalFlag	000000000001000000000000	(1<<12)
eRelativeTangentFlag	000000000010000000000000	(1<<13)

Attribute Names¶

Attribute name	script key	Notes
kRedAttribute	r	Colour
kGreenAttribute	g
kBlueAttribute	b
kAlphaAttribute	a
kFeatherOnAttribute	fo	Feather on/off
kFeatherXAttribute	fx	Relative X coordinate
kFeatherYAttribute	fy	Relative Y coordinate
kFeatherFallOffAttribute	ff
kFeatherTypeAttribute	ft
kBrushSizeAttribute	bs	RotoPaint: Brush size
kBrushSpacingAttribute	bsp	RotoPaint: Brush spacing
kOpacityAttribute	opc	Opacity
kHardnessAttribute	h
kSourceAttribute	src
kBlendingModeAttribute	bm
kBrushTypeAttribute	bt	RotoPaint: Brush type
kBuildUpAttribute	bu	RotoPaint
kDynamicTransparencyAttribute	dt
kDynamicSizeAttribute	ds
kDynamicHardnessAttribute	dh
kViewAttribute	view
kNumberOfViewsAttribute	nv
kInvertedAttribute	inv
kMotionBlurOnAttribute	mbo	Motion blur
kMotionBlurAttribute	mb
kMotionBlurShutterAttribute	mbs
kMotionBlurShutterOffsetTypeAttribute	mbsot
kMotionBlurShutterOffsetAttribute	mbso
kSourceTranslateXAttribute	stx
kSourceTranslateYAttribute	sty
kSourceTranslateRoundAttribute	str
kSourceRotateAttribute	sr
kSourceScaleXAttribute	ssx
kSourceScaleYAttribute	ssy
kSourceSkewXAttribute	sskx
kSourceSkewYAttribute	ssky
kSourceSkewOrderAttribute	sso
kSourcePivotPointXAttribute	spx
kSourcePivotPointYAttribute	spy
kSourceTimeOffsetTypeAttribute	stot
kSourceTimeOffsetAttribute	sto
kSourceFilterAttribute	sf
kSourceBlackOutsideAttribute	sb
kSourceViewAttribute	sv
kLifeTimeNAttribute	ltn	Life time start
kLifeTimeMAttribute	ltm	Life time end
kLifeTimeTypeAttribute	ltt
kWriteOnStartAttribute	ws
kWriteOnEndAttribute	we
kRedOverlayAttribute	ro
kGreenOverlayAttribute	go
kBlueOverlayAttribute	bo
kAlphaOverlayAttribute	ao
kEffectParameter1Attribute	ep1
kEffectParameter2Attribute	ep2
kEffectParameter3Attribute	ep3
kToolTypeAttribute	tt
kPlanarTrackLayerAttribute	pt
kVisibleAttribute	vis
kTensionAttribute	t
kRepeatAttribute	rp
kTensionExponentAttribute	te
kCutoutAttribute	hard_boundary	SplineWarp only
kBoundaryAttribute	boundary	SplineWarp only
kWarpAttribute	warp	SplineWarp only
kMixAttribute	mix	SplineWarp only
kABAttribute	ab	SplineWarp only - whether the curve is in A or B
kCookieCutAttribute	cookie	SplineWarp only
kAnimCurveKeyframeRLE	r	Run-length encoding for key frames (as value, length pairs)