.. _advanced-rotoformat:

Roto serialisation format
============

Roto serialisation format has changed for NUKE 7.0. The new format is not backwards compatible but NUKE 7 will read older scripts.

See also :ref:`advanced-curveformat`

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.

.. code-block:: abnf

  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:

.. code-block:: c

  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:

.. code-block:: c

  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

.. code-block:: tcl

  {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
-----

.. tabularcolumns:: |l|l|l
=========================== ======================== =========
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)
=========================================== =================== =============================================================

