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 Curve 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) |