Introduction
A collection of layers describes an animation or a composition (see compositions for more information).
They are the building blocks of an animation. The order of layers represents (in most cases) the order in which they should be rendered. The first element in the list should be rendered above all the other elements on the stack.
Some exceptions to this rule are camera layers that don’t have a visual representation on the canvas. Others, that are not yet part of the specification, are Light layers, and Adjustment layers.
Layers are categorized by the type of content, and each should be rendered according to their unique specification.
Layer Types
| Layer | Value |
|---|---|
| Pre Comp | 0 |
| Null | 1 |
| Image | 2 |
| Solid | 3 |
| Shape | 4 |
| Text | 5 |
Common Layer Properties
| Definition | Name | Type | Required | Default |
|---|---|---|---|---|
| Index | ind | Number | ✅ | |
| Transform | ks | Object | ✅ | |
| Parent | parent | Number | ➖ | |
| In Point | ip | Number | ➖ | |
| Out Point | op | Number | ➖ | |
| Start Point | st | Number | ➖ | |
| Time stretch | sr | Number | ➖ | 1 |
| Masks | masksProperties | Array[Mask Elements] | ➖ | |
| Track Matte Masked Layer | tt | Matte Mask types | ➖ | |
| Track Matte Masking Layer | td | Number | ➖ | |
| Track Matte Masking Layer Index | tp | Number | ➖ | |
| Blend Mode | bm | Blend Mode types | ➖ |
Layers have common properties and unique properties related to their content. In this section common properties will be covered.
Transform
Details
Property names: ks
Property type: object
Required
The transform property is a container for a set of properties that are traditionally related to GPU operations on textures. They represent affine operations and opacity.
| Definition | Name | Type | Required | Default |
|---|---|---|---|---|
| Anchor Point | a | Array | Spatial Animated Property | ✅ | |
| Position | p | Array | Spatial Animated Property | ✅ | |
| Scale | s | Array | Multi Dimensional Animated Property | ✅ | |
| 2d Rotation | r | Number | Multi Dimensional Animated Property | ➖ | |
| 3d X Rotation | rx | Number | Multi Dimensional Animated Property | ➖ | |
| 3d Y Rotation | ry | Number | Multi Dimensional Animated Property | ➖ | |
| 3d Z Rotation | rz | Number | Multi Dimensional Animated Property | ➖ | |
| 3d Orientation | or | Array | Spatial Animated Property | ➖ | |
| Opacity | o | Number | Multi Dimensional Animated Property | ✅ | |
| Skew | sk | Number | Multi Dimensional Animated Property | ➖ | |
| Skew Axis | sa | Number | Multi Dimensional Animated Property | ➖ |
Anchor Point
The Anchor point is a two-dimensional (or three if layer is 3d) array that represents the origin from which other transformations should be applied.
Position
The position can be expressed in two different ways, and it will be indicated by a property called "s". If s is true, dimensions are separate. If s is false, it behaves as an Array.
Position Separate Dimensions
Details
Property names: *x, y, z *
Property types: Non-Animated Number | Multi Dimensional Animated Property
Required
If dimensions are separate, the position will be a container for 2 (or 3 if the layer is 3d) one-dimensional independent properties. Those properties are "x", “y”, and “z” and they can be animated separately.
Scale
The scale is a two dimensional (or three if layer is 3d) array that represents the scaling percentage of the layer. If its value is 100%, no scaling is applied.
Rotation for 2d layers
This property is the rotation expressed in degrees applied to the layer.
X Rotation for 3d layers
This property is the x rotation expressed in degrees applied to the layer.
Y Rotation for 3d layers
This property is the y rotation expressed in degrees applied to the layer.
Z Rotation for 3d layers
This property is the z rotation expressed in degrees applied to the layer.
Orientation for 3d layers
3d layers have an extra property called orientation represented by an array of 3 floating point values expressed in degrees. It indicates the pitch, roll and yaw of the layer.
Opacity
Opacity is a percentage based value. It defaults to 100 which means the layer is fully opaque. Value 0 means the layer is fully transparent.
This property ranges from 0 to 100.
Skew
Skew indicates the slant of the element.
Skew Axis
Skew axis specifies the axis along which the character is skewed.
Index
The index refers to a unique id that each layer has within a stack. It is used for parenting and also for certain expressions.
Parenting
Optional
If present, it points to the ind property of the target layer whose transform data should be included in the transform operations that affect the layer. When a layer has this attribute set, in order to draw the content, first all the parenting hierarchy needs to be looked up iteratively. Once the parenting chain is complete (the top layer doesn’t have a parent property set to look up), transforms have to be applied from the top layer down to the transforms of the current layer.
Note: Parenting should never target the original layer as part of the chain or it would create an endless loop.
In Point
The in point is a frame based Number that indicates the inital frame of the layer
Out Point
The out point is a frame based Number that indicates the final frame of the layer
Start Point
The start point is a frame based Number that indicates when the layer should be visible on screen
Time Stretch
This is a factor by which time should be stretched on keyframe information. A value of 1 means that no stretching is needed.
Masks
Masks define a list of bezier curve shapes that act as clipping paths or composite operations on layers. Multiple masks with different properties can be applied to the same layer where, depending on the mask mode, different rules of stacking apply.
Mask elements
A mask can be considered as a clipping shape or a composite operation depending on their specific properties and types.
Mask modes
Mask types describe how the shape should affect the underlying layer.
Inverted property
The inverted property will take the opacity values of the output of the mask (with its corresponding higher stack of masks if it applies) and perform a boolean filter to invert the result.
Path property
The path property describes the bezier path that the mask will use to apply the mask
Opacity property
The opacity property defines how clipped pixels will transfer to the final output. When opacity is set to 0.5, the resulting output will multiply the alpha.
Expansion property
Expansion affects the path property of the mask by shrinking or growing it by the specified number of pixels. The path should be transformed by the center of the shape itself.
Since offsetting bezier curves is not a trivial task, this effect might be hard to copy.
Lottie-web makes use of the feMorphology filter and applies an erode operator to shrink the mask. For growing it, it adds a stroke to the mask which is used as part of the masking itself.
Matte Masks
Matte masks are pairs of layers where one acts as a mask for the other. Those layers are indicated by a tt property on the masked layer and a td on the masking one. They are always stacked one after to the other on the stacking order.
Masked Layer
Details
Property name: tt
Property type: Matte Mask types
Optional (Required if previous layer has a td property)
This property only accepts four values and describes the type of mask that should be applied. If "tp" is not defined, the masking layer should be the layer immediately before it in the layer stack.
Masking Layer
Details
Property name: td
Property type: Number
Property value: 1
Optional
This property only accepts one value that indicates it should be used as a masking layer
Masking Layer Index
Details
Property name: tp
Property type: Number
Optional
If present, it points to the ind property of the target layer that should be used as the masking layer. If not present, but the "tt" property is present, the layer immediately before it in the layer stack should be used as the masking layer.
Blend Mode
Supported blend modes.