Shapes

The graphical elements are divided in 4 categories:

• Shapes that define the actual curves but have no styling information
• Grouping, used to organize collections of graphic elements
• Styles, that define the visual appearance of shapes
• Modifiers alter the curves of the shapes

Shape Rendering Model

Grouping and Ordering Rules

• Shapes are rendered in reverse order, bottom->top. Shapes at the beginning of the array are rendered on top of shapes with larger indices.
• Groups offer a scoping mechanism for transforms, styles, modifiers, and shapes. All group children, including sub-groups and their children, are considered part of the group's scope.
• Transforms adjust the coordinate system for all elements within their group, and transitively for all other group-nested elements.
• Styles and modifiers apply to all preceding shapes within the current scope, including subgroup-nested shapes.
• When multiple styles apply to the same shape, the shape is rendered repeatedly for each style, in reverse order.
• When multiple modifiers apply to the same shape, they are composed in reverse order (e.g. $Trim(Trim(shape))$).
• When multiple transforms apply to the same shape due to scope nesting, they compose in group nesting order (transforms are additive).
• Group opacity (property of the group transform) applies atomically to all elements in scope - i.e. opacity applies to the result of compositing all group content, and not to individual elements.

More formally:

• for each $(shape,style)$ tuple, where $Index(shape)<Index(style)$ and $shape\in Scope(style)$:
• for each $modifier$, in increasing index order, where $Index(shape)<Index(modifier)$ and $shape\in Scope(modifier)$:
  • $shape=modifier(shape)$
• compute the total shape transformation by composing all transforms within the shape scope chain:

• compute the total style transformation by composing all transforms within the style scope chain:

• $Render(shape\times T_{shape},style\times T_{style})$

Notes

1. Certain modifier operations (e.g. sequential $Trim$) may require information about shapes from different groups, thus $Render()$ calls cannot always be issued based on single-pass local knowledge.

2. Transforms can affect both shapes and styles (e.g. stroke width). For a given $(shape,style)$, the shape and style transforms are not necessarily equal.

3. Shapes without an applicable style are not rendered.

4. This rendering model is based on AfterEffects' Shape Layer semantics.

Rendering Convention

Shapes defined in this section contain rendering instructions. These instructions are used to generate the path as a bezier curve.

Implementations MAY use different algorithms or primitives to render the shapes but the result MUST be equivalent to the paths defined here.

Some instructions define named values for clarity and illustrative purposes, implementations are not required to have them explicitly defined in their rendering process.

When referencing animated properties, the rendering instruction will use the same name as in the JSON but it's assumed they refer to their value at a given point in time rather than the property itself. For Vector values, $value.x$ and $value.y$ in the instructions are equivalent to value[0] and value[1] respectively.

All paths MUST be closed unless specified otherwise in the rendering instructions.

When instructions call for an equality comparison between two values, implementations MAY consider similar values to be equal to overcome numerical instability.

Drawing Commands

Drawing instructions will contain the following commands:

• add vertex: Adds a vertex to the bezier shape in global coordinates
• set in tangent: Sets the cubic tangent to the last added vertex, with coordinates relative to it. If omitted, tangents MUST be $(0,0)$.
• set out tangent: Sets the cubic tangent from the last added vertex, with coordinates relative to it. If omitted, tangents MUST be $(0,0)$.
• lerp: Linearly interpolates two points or scalars by a given amount.

Approximating Ellipses with Cubic Bezier

An elliptical quadrant can be approximated by a cubic bezier segment with tangents of length $radius \cdot E_t.

Where

See this article for the math behind it.

When implementations render elliptical arcs using bezier curves, they SHOULD use this constant, a similar approximation, or elliptical arc drawing primitives.

Graphic Element

Element used to display vector data in a shape layer

The ty property defines the specific element type based on the following values:

Hidden shapes (hd: True) are ignored, and do not contribute to rendering nor modifier operations.

Shapes

Drawable shape, defines the actual shape but not the style

Ellipse

Ellipse shape

Example

An ellipse is drawn from the top quandrant point going clockwise:

1. Add vertex $(x,y-radius.y)$
2. Set in tangent $(-tangent.x,0)$
3. Set out tangent $(tangent.x,0)$
4. Add vertex $(x+radius.x,y)$
5. Set in tangent $(0,-tangent.y)$
6. Set out tangent $(0,tangent.y)$
7. Add vertex $(x,y+radius.y)$
8. Set in tangent $(tangent.x,0)$
9. Set out tangent $(-tangent.x,0)$
10. Add vertex $(x-radius.x,y)$
11. Set in tangent $(0,tangent.y)$
12. Set out tangent $(0,-tangent.y)$

Implementations MAY use elliptical arcs to render an ellipse.

Rectangle

A simple rectangle shape

Example

Definitions:

If $r=0$, then the rectangle is rendered from the top-right going clockwise:

1. Add vertex $(right,top)$
2. Add vertex $(right,bottom)$
3. Add vertex $(left,bottom)$
4. Add vertex $(left,top)$

If $r>0$, the rounded corners must be taken into account.

1. Add vertex $(right,top+rounded)$
2. Set in tangent $(0,-tangent)$
3. Add vertex $(right,bottom-rounded)$
4. Set out tangent $(0,tangent)$
5. Add vertex $(right-rounded,bottom)$
6. Set in tangent $(tangent,0)$
7. Add vertex $(left+rounded,bottom)$
8. Set out tangent $(-tangent,0)$
9. Add vertex $(left,bottom-rounded)$
10. Set in tangent $(0,tangent)$
11. Add vertex $(left,top+rounded)$
12. Set out tangent $(0,-tangent)$
13. Add vertex $(left+rounded,top)$
14. Set in tangent $(-tangent,0)$
15. Add vertex $(right-rounded,top)$
16. Set out tangent $(tangent,0)$

Path

Custom Bezier shape

Example

PolyStar

Star or regular polygon

Example

Definitions:

1. For $i$ in $[0,points)$
   1. Let $\beta =-\frac{\pi }{2}+\alpha +i·2\dot{\theta }$
   2. Let $V_{out}=(or·\cos (\beta ),or·\sin (\beta ))$
   3. Add vertex $p+V_{out}$
   4. If $or\ne 0$, we need to add bezier tangent
      1. Let $T_{out}=(V_{out}·\frac{ta{n}_{out}}{or})$
      2. Set in tangent $V_{out}$
      3. Set out tangent $-V_{out}$
   5. If $sy=1$, we need to add a vertex towards the inner radius to make a star
      1. Let $V_{in}=(ir·\cos (\beta +\theta ),or·\sin (\beta +\theta ))$
      2. Add vertex $p+V_{in}$
      3. If $ir\ne 0$, we need to add bezier tangent
         1. Let $T_{in}=(V_{in}·\frac{ta{n}_{in}}{or})$
         2. Set in tangent $V_{in}$
         3. Set out tangent $-V_{in}$

Grouping

Group

Shape Element that can contain other shapes

A group defines a render stack, elements within a group MUST be rendered in reverse order (the first object in the list will appear on top of elements further down).

1. Apply the transform
2. Render Styles and child groups in the transformed coordinate system.

Transform

Group transform

Transform shapes MUST always be present in the group and they MUST be the last item in the it array.

They modify the group's coordinate system the same way as Layer Transform.

Style

Describes the visual appearance (like fill and stroke) of neighbouring shapes

Shapes styles MUST apply their style to the collected shapes that come before them in stacking order.

Fill

Solid fill color

Example

Stroke

Solid stroke

Example

Stroke Dashes

An item used to described the dash pattern in a stroked path

Example

Gradient Fill

Gradient fill color

Example

Gradient Stroke

Gradient stroke

Example

Modifiers

Modifiers change the bezier curves of neighbouring shapes

Modifiers replace shapes in the render stack by applying operating on the bezier path of to the collected shapes that come before it in stacking order.

Trim Path

Trims shapes into a segment

When rendering trim path, the order of bezier points MUST be the same as rendering instructions given for each shape in this section.

Rendering trim path can be rather complex.

Given

If $s$ and $e$ are equal, implementations MUST NOT render any shapes.

If $s=0$ and $e=1$, the input shape MUST be rendered as-is.

To render trim path, implementations MUST consider the actual length of each shape (they MAY use approximations). Once the shapes are collected, the segment to render is given by the percentages $start$ and $end$.

When trim path is applied to multiple shapes, the m property MUST be considered when applying the modifier:

• When m has a value of 1 (Parallel), each shape MUST considered separately, $start$ and $end$ being applied to each shape.

• When m has a value of 2 (Sequential), all the shapes MUST be considered as following each other in render order. $start$ and $end$ refer to the whole length created by concatenating each shape.