Anchor, Skew and Auto-Orient - Node.js

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.

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.

import CreativeEngine from '@cesdk/node';
import { writeFileSync, mkdirSync } from 'fs';
import { config } from 'dotenv';

// Load environment variables
config();

/**
 * CE.SDK Server Guide: Anchor, Skew and Auto-Orient Guide
 *
 * Demonstrates the transform properties of graphic, text and caption blocks:
 * - The anchor that rotation, scale and skew pivot on
 * - A static and an animated skew
 * - Auto-orient along a motion path
 * - The errors for blocks without these properties
 */
async function main() {
  // Initialize the headless Creative Engine
  const engine = await CreativeEngine.init({
    baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
    // license: process.env.CESDK_LICENSE
  });

  try {
    // Create a scene with a 5 second page
    const scene = engine.scene.create('DepthStack');
    const page = engine.block.create('page');
    engine.block.setWidth(page, 1920);
    engine.block.setHeight(page, 1080);
    engine.block.appendChild(scene, page);
    engine.block.setDuration(page, 5);

    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

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

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

    // 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 } }
    ]);

    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

    try {
      // A page has no anchor and no skew
      engine.block.setFloat(page, 'transform/anchor/x', 10);
    } catch (error) {
      // Engine errors carry a stable catalog id in `code`
      const { code } = error as { code?: string };
      console.log(code); // 'BLOCK.TYPE_CANNOT_HAVE_ANCHOR_OR_SKEW'
    }
    try {
      engine.block.setBool(page, 'transform/autoOrient', true);
    } catch (error) {
      const { code } = error as { code?: string };
      console.log(code); // 'BLOCK.TYPE_CANNOT_AUTO_ORIENT'
    }

    // Export the frame at 1.5 seconds, while the arrow climbs its path
    engine.block.setPlaybackTime(page, 1.5);
    mkdirSync('output', { recursive: true });
    const blob = await engine.block.export(page, { mimeType: 'image/png' });
    writeFileSync(
      'output/anchor-skew-auto-orient.png',
      Buffer.from(await blob.arrayBuffer())
    );
    console.log('Frame saved to output/anchor-skew-auto-orient.png');
  } finally {
    // Always dispose of the engine to free resources
    engine.dispose();
  }
}

/** 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;
}

main().catch(console.error);

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. It ends with a frame export.

Creating the Scene#

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

// Initialize the headless Creative Engine
const engine = await CreativeEngine.init({
  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
  // license: process.env.CESDK_LICENSE
});

try {
  // Create a scene with a 5 second page
  const scene = engine.scene.create('DepthStack');
  const page = engine.block.create('page');
  engine.block.setWidth(page, 1920);
  engine.block.setHeight(page, 1080);
  engine.block.appendChild(scene, page);
  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) {
  // Engine errors carry a stable catalog id in `code`
  const { code } = error as { code?: string };
  console.log(code); // 'BLOCK.TYPE_CANNOT_HAVE_ANCHOR_OR_SKEW'
}
try {
  engine.block.setBool(page, 'transform/autoOrient', true);
} catch (error) {
  const { code } = error as { code?: string };
  console.log(code); // 'BLOCK.TYPE_CANNOT_AUTO_ORIENT'
}

Exporting a Frame#

We export the page as PNG at 1.5 seconds. The frame shows both squares part way through their turn, the leaning sign, the swaying blade and the arrow pointing up along its path.

// Export the frame at 1.5 seconds, while the arrow climbs its path
engine.block.setPlaybackTime(page, 1.5);
mkdirSync('output', { recursive: true });
const blob = await engine.block.export(page, { mimeType: 'image/png' });
writeFileSync(
  'output/anchor-skew-auto-orient.png',
  Buffer.from(await blob.arrayBuffer())
);
console.log('Frame saved to output/anchor-skew-auto-orient.png');

Cleaning Up#

We dispose of the engine in a finally block, so it frees its resources also after an error.

// Always dispose of the engine to free resources
engine.dispose();

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
`block.export(block, options)`	Export the frame as PNG

Next Steps#

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