Skip to main content

Transforms

Every node has a transform that places it relative to its parent. In 2D, a node's transform is a NodeTransform2D by default, which stores position, rotation, scale and anchor (PRSA), the representation we discussed in lecture. Its corresponding matrix is calculated as

Matrix = Translate(position) * Rotate(rotation) * Scale(scale) * Translate(-anchor)

so the anchor is the point in the node's own coordinates that ends up at position, and that it rotates and scales around when rotation or scale changes. In HierarchyAndAnimation's ArmLinkModel, for example, each link's anchor is its joint (in the link's own coordinates) and its position is the parent link's tip (in the parent's coordinates), so setting rotation swings the link about its joint.

Changing a transform​

node.prsa is the node's transform, as position, rotation, scale and anchor. Change it, and the view redraws on its own:

const transform = node.prsa;
transform.position = V2(2, 1);
transform.rotation = Math.PI * 0.25; // radians
transform.scale = 2; // a number sets both x and y; or use V2(2, 1)
transform.anchor = V2(0, -1);

The example scenes also call node.signalTransformUpdate() after changing a transform. That is harmless in most cases, but will cause another update of the view. When you actually want to use signalTransformUpdate() is if you turn automatic updates off (see below).

Signal geometry and particle changes

While changing a transform redraws a view by default, other changes (e.g., to a model's geometry) need to be signaled manually. setVerts(...) signals the change for you, but after editing a node's existing vertices in place (for example this.verts.FillColor(color)), call signalGeometryUpdate(). For a particle system, call signalParticlesUpdated() when you finish updating particle properties. Forgetting this is the most common reason a shape "doesn't change".

More generally, you should pay attention to what signals and updates are being used in each scene, and optionally define your own (see Events and subscriptions).

Many transform changes in one frame​

By default (autoTransformUpdate is true), every change to a node's transform redraws its views right away. If you change one node's transform many times in a single frame, for example in a loop of small physics steps, that's wasted work: only the last value will actually appear on screen. Instead, turn automatic updates off for that node, make all the changes, and signal once:

node.autoTransformUpdate = false;   // once, e.g. in the constructor

// later, each frame:
for (let step = 0; step < 20; step++) {
const transform = node.prsa;
transform.position = transform.position.plus(velocity.times(dt / 20));
}
node.signalTransformUpdate(); // the views redraw once

node.flushTransformUpdate() does the same as signalTransformUpdate() when automatic updates are off, and nothing when they are on, so it's safe to call at the end of the batch either way.

Using a Mat3​

If you'd rather work with a matrix, as in A1 and A2, you can pass one to setTransform:

node.setTransform(Mat3.Translation2D(V2(1, 0)).times(Mat3.Rotation(Math.PI/4)));

setTransform maintains the type of the node's current transform when possible. A node's transform starts as a NodeTransform2D by default, so setting it with a matrix will convert it into a position, rotation and scale that give the same matrix, letting the node keep its anchor. You can go on editing node.prsa afterwards. The one exception is a matrix with shear, which no position, rotation and scale can produce: then the node's transform becomes that Mat3, and AniGraph prints a warning.

To make a node's transform a Mat3 on purpose, construct the node with a Mat3, or call node.convertTransformToMatrix(). Whichever kind it is, node.transform.getMatrix() gives you its matrix form. Note two things:

  • A Mat3 has no position, rotation, scale or anchor to edit, so node.prsa throws an error on a node whose transform is a Mat3. Call node.convertTransformToPRSA() to switch it back to PRSA. (node.transformIsPRSA tells you which kind a node has.)
  • A matrix can't tell a translation by position from a translation by the anchor. So converting a NodeTransform2D with a non-zero anchor to a Mat3 loses the anchor, and AniGraph prints a warning.
Try it in the tutorial

World transforms​

node.getWorldTransform() returns the Mat3 from the node's coordinates to world coordinates: its own transform multiplied by all of its ancestors'. Its inverse takes a world point (say, the mouse) into the node's coordinates:

const localPoint = node.getWorldTransform().getInverse().times(worldPoint);
Abe's note on "PRSA"

"PRSA" is not a common term. If you google it, you will find essentially nothing about transformations or animation. In fact, I'm pretty sure I made up the term "PRSA" for this class... So how can it be a standard? What does appear in plenty of APIs is "TRS", which stands for "translation, rotation, scale". Technically, any PRSA transform can be mapped to an equivalent TRS transform, so from an engineer's perspective the P and A may seem redundant. But the advantage of PRSA is for designing animations, especially in an interactive tool, and it comes from creative tools for animation, where it is just referred to as four separate properties. To make matters worse, the name "anchor point" is not standardized; some software uses "origin" or "pivot point" instead. However, the corresponding order of matrix operations has become quite standard, probably because if you set the anchor to zero it reduces to TRS.

Try it in the tutorial