Search Docs
Loading...
Skip to content

Anchor, Skew and Auto-Orient

Set the point that a block turns, scales and skews about, shear a block with a skew, and turn a block along its motion path.

Two turning squares, a leaning sign, a swaying blade of grass and an arrow on a curved path, at 1.5 seconds

6 mins
estimated time
Download
StackBlitz
GitHub

Anchor, skew and auto-orient are transform properties of graphic, text and caption blocks. The anchor is the pivot of rotation, scale and skew, the skew shears a block, and auto-orient turns a block along the direction of its position keyframes. The editor has no controls for them, so you set them with the block API.

This guide covers how to set the anchor, how to skew a block and animate the skew, how to turn a block along its motion path, the errors to expect, and how the properties behave with other block operations.

Creating the Scene#

We create a video scene with a page of 5 seconds, so the blocks can animate. The properties also work in a design scene.

await cesdk.actions.run('scene.create', {
  mode: 'Video',
  layout: 'DepthStack',
  page: { width: 1920, height: 1080, unit: 'Pixel' }
});


const engine = cesdk.engine;
const page = engine.block.findByType('page')[0]!;
engine.block.setDuration(page, 5);

Creating the Blocks#

The example draws its blocks as rectangles with a color fill. A small helper creates each one on the page with a duration of 5 seconds.

/** Creates a rect graphic with a color fill on the page. */
function createRect(
  engine: CreativeEngine,
  page: number,
  x: number,
  y: number,
  width: number,
  height: number,
  color: { r: number; g: number; b: number; a: number }
): number {
  const block = engine.block.create('graphic');
  engine.block.setShape(block, engine.block.createShape('rect'));
  const fill = engine.block.createFill('color');
  engine.block.setColor(fill, 'fill/color/value', color);
  engine.block.setFill(block, fill);
  engine.block.setWidth(block, width);
  engine.block.setHeight(block, height);
  engine.block.setPositionX(block, x);
  engine.block.setPositionY(block, y);
  engine.block.appendChild(page, block);
  engine.block.setDuration(block, 5);
  return block;
}

Setting the Anchor#

transform/anchor/x and transform/anchor/y set the point that rotation, scale and skew pivot on, in design units from the top-left corner of the block’s frame. A block without an anchor turns about its center under a rotation track, as setRotation() turns it. Its skew and scale pivot on its top-left corner. Both squares get the same quarter turn over 5 seconds. The left square sets its anchor to (0, 0) and swings about its corner, while the right square has its anchor at its center and turns in place. setFloat() sets the anchor and getFloat() reads it back.

const cornerSquare = createRect(engine, page, 300, 200, 160, 160, {
  r: 0.2,
  g: 0.4,
  b: 0.9,
  a: 1
});
const centerSquare = createRect(engine, page, 700, 200, 160, 160, {
  r: 0.9,
  g: 0.3,
  b: 0.4,
  a: 1
});
// Without an anchor, a rotation track turns a block about its center, so
// the left square sets its anchor to its top-left corner
engine.block.setFloat(cornerSquare, 'transform/anchor/x', 0);
engine.block.setFloat(cornerSquare, 'transform/anchor/y', 0);
engine.block.setFloat(centerSquare, 'transform/anchor/x', 80);
engine.block.setFloat(centerSquare, 'transform/anchor/y', 80);
for (const square of [cornerSquare, centerSquare]) {
  engine.block.setKeyframes(square, 'rotation', [
    { time: 0, value: { type: 'Float', value: 0 } },
    { time: 1, value: { type: 'Float', value: Math.PI / 2 } }
  ]);
}
console.log(engine.block.getFloat(centerSquare, 'transform/anchor/x')); // 80

Setting transform/anchor/x or transform/anchor/y, even to 0, or giving one of them keyframes, gives a block an anchor. getFloat() reads 0 for a block without an anchor too, so hasTransformAnchor() tells whether a block has one.

// An anchor set to 0 is still an anchor
console.log(engine.block.hasTransformAnchor(cornerSquare)); // true

Skewing a Block#

transform/skew shears a block by an angle in degrees. transform/skewAxis sets the direction of the shear in degrees, where 0 shears along the block’s x-axis. The rendered shear is limited to the range from -85° to 85°. The skew pivots on the anchor, or on the top-left corner of a block without one. The sign has no anchor, so it keeps its top edge in place and leans by 20 degrees.

const sign = createRect(engine, page, 1150, 200, 240, 160, {
  r: 0.95,
  g: 0.7,
  b: 0.1,
  a: 1
});
engine.block.setFloat(sign, 'transform/skew', 20);
engine.block.setFloat(sign, 'transform/skewAxis', 0);

Animating the Skew#

All four anchor and skew properties are numbers, so 'Float' keyframes animate them with setKeyframes(). The blade of grass has its anchor at its bottom center, so its base stays in place while the skew track sways it from -20 to 20 degrees and back. For keyframes, see Keyframes.

// The anchor sits at the bottom center, so the base of the blade stays put
const blade = createRect(engine, page, 1600, 600, 40, 300, {
  r: 0.2,
  g: 0.7,
  b: 0.3,
  a: 1
});
engine.block.setFloat(blade, 'transform/anchor/x', 20);
engine.block.setFloat(blade, 'transform/anchor/y', 300);
engine.block.setKeyframes(blade, 'transform/skew', [
  { time: 0, value: { type: 'Float', value: -20 } },
  { time: 0.5, value: { type: 'Float', value: 20 } },
  { time: 1, value: { type: 'Float', value: -20 } }
]);

Turning Along the Motion Path#

When the bool property transform/autoOrient is on, a block turns to follow the direction of its position keyframes. The engine adds the direction of the path at the current playback time to the block’s rotation, so a static rotation or a rotation track stays as an offset. The direction comes from a position track or from position/x and position/y tracks, absolute or relative. A hold segment adds no turn. The arrow turns about its anchor at its center, so it points up while it climbs the curve and down while it falls.

const arrow = createRect(engine, page, 300, 800, 160, 40, {
  r: 0.5,
  g: 0.2,
  b: 0.8,
  a: 1
});
engine.block.setFloat(arrow, 'transform/anchor/x', 80);
engine.block.setFloat(arrow, 'transform/anchor/y', 20);
engine.block.setVec2(arrow, 'position', { x: 300, y: 800 });
engine.block.setKeyframes(arrow, 'position', [
  {
    time: 0,
    value: { type: 'Vec2', value: { x: 300, y: 800 } },
    spatialOut: { x: 300, y: -300 },
    spatialIn: { x: -300, y: -300 }
  },
  { time: 1, value: { type: 'Vec2', value: { x: 1300, y: 800 } } }
]);
engine.block.setBool(arrow, 'transform/autoOrient', true);
console.log(engine.block.getBool(arrow, 'transform/autoOrient')); // true

transform/autoOrient is off by default and does not take keyframes. setBool() turns it on and getBool() reads it back.

Handling Errors#

Graphic, text and caption blocks have an anchor, a skew and auto-orient. Any other block, such as a page or a group, is refused and nothing changes. The call throws an error with a code.

try {
  // A page has no anchor and no skew
  engine.block.setFloat(page, 'transform/anchor/x', 10);
} catch (error) {
  if (isEngineError(error)) {
    console.log(error.code); // 'BLOCK.TYPE_CANNOT_HAVE_ANCHOR_OR_SKEW'
  }
}
try {
  engine.block.setBool(page, 'transform/autoOrient', true);
} catch (error) {
  if (isEngineError(error)) {
    console.log(error.code); // 'BLOCK.TYPE_CANNOT_AUTO_ORIENT'
  }
}

Anchor, Skew and Other Block Operations#

  • setRotation() keeps the center of an anchored block in place.
  • Scaling a block scales its anchor and keeps the fixed corner. A flip mirrors an anchored or skewed block in place. Filling the parent removes the skew.
  • Saving and loading and undo keep the properties. Changing the design unit converts the anchor.
  • A block that follows a transform parent auto-orients in the space of that parent.
  • When the engine enforces scopes, changing the anchor needs the layer/move scope, and changing the skew or auto-orient needs layer/rotate. Check a block with isAllowedByScope before you offer the edit.

Troubleshooting#

  • The block type has no anchor or skew (BLOCK.TYPE_CANNOT_HAVE_ANCHOR_OR_SKEW): pass a graphic, text or caption block.
  • The block type cannot auto-orient (BLOCK.TYPE_CANNOT_AUTO_ORIENT): pass a graphic, text or caption block.
  • The anchor or the skew cannot change (BLOCK.TRANSFORM_LOCKED_ANCHOR_OR_SKEW): the transform of the block is locked. Unlock it first.
  • Auto-orient cannot change (BLOCK.TRANSFORM_LOCKED_ROTATE): the transform of the block is locked. Unlock it first.
  • The value is not a number (EDITOR.VALUE_NOT_FINITE): pass a finite anchor, skew or skew axis.
  • The block turns about its corner: it has an anchor at (0, 0), which hasTransformAnchor() reports. A block with a rotation track in a scene saved by an earlier version loads with this anchor. Set the anchor to half the width and height to turn the block about its center.
  • The block does not turn along its path: it has no position keyframes, or the current segment is a hold.

API Reference#

Method Description
block.setFloat(block, property, value) Set transform/anchor/x, transform/anchor/y, transform/skew or transform/skewAxis
block.getFloat(block, property) Read an anchor or skew property
block.hasTransformAnchor(block) Check whether a block has an anchor, even one at (0, 0)
block.setBool(block, 'transform/autoOrient', value) Turn auto-orient on or off
block.getBool(block, 'transform/autoOrient') Check whether a block auto-orients
block.setKeyframes(block, property, keyframes) Animate the rotation, the skew or the position
block.setVec2(block, 'position', value) Set the static position at the start of the path
block.setPlaybackTime(block, time) Show a frame at a playback time

Next Steps#

  • Keyframes: animate block properties with keyframe tracks.
  • Create Animations: add preset animations, which turn and scale about the anchor.