Motion Paths - macOS | IMG.LY Docs

import Foundation
import IMGLYEngine

struct MotionPathsGuideResult {
  let ballPosition: SIMD2<Float>
  let keyframeCount: Int
  let firstSpatialOut: SIMD2<Float>?
  let valueKindErrorCode: EngineErrorCode?
  let tangentErrorCode: EngineErrorCode?
  let pngData: Data
}

@MainActor
func motionPaths(engine: Engine) async throws -> MotionPathsGuideResult {
  let scene = try engine.scene.create()
  let page = try engine.block.create(.page)
  try engine.block.setWidth(page, value: 1920)
  try engine.block.setHeight(page, value: 1080)
  try engine.block.appendChild(to: scene, child: page)
  try engine.block.setDuration(page, duration: 5)

  // Creates a circle graphic of the given size and color on the page
  func createCircle(size: Float, color: Color) throws -> DesignBlockID {
    let block = try engine.block.create(.graphic)
    try engine.block.setShape(block, shape: engine.block.createShape(.ellipse))
    let fill = try engine.block.createFill(.color)
    try engine.block.setColor(fill, property: "fill/color/value", color: color)
    try engine.block.setFill(block, fill: fill)
    try engine.block.setWidth(block, value: size)
    try engine.block.setHeight(block, value: size)
    try engine.block.appendChild(to: page, child: block)
    try engine.block.setDuration(block, duration: 5)
    return block
  }

  // Both tangents of a segment sit on its first keyframe. `spatialOut` is
  // relative to this keyframe's value, `spatialIn` to the next one's.
  let ball = try createCircle(size: 80, color: .rgba(r: 0.2, g: 0.4, b: 0.9, a: 1))
  try engine.block.setVec2(ball, property: "position", value: [200, 800])
  try engine.block.setKeyframes(ball, property: "position", keyframes: [
    Keyframe(time: 0, value: .vec2([200, 800]), spatialOut: [0, -400], spatialIn: [-400, 0]),
    Keyframe(time: 0.5, value: .vec2([920, 300]), spatialOut: [400, 0], spatialIn: [0, -400]),
    Keyframe(time: 1, value: .vec2([1640, 800])),
  ])
  let ballPosition = try engine.block.getVec2(ball, property: "position")
  print(ballPosition) // SIMD2<Float>(200.0, 800.0)

  let dot = try createCircle(size: 40, color: .rgba(r: 0.9, g: 0.3, b: 0.4, a: 1))
  try engine.block.setVec2(dot, property: "position", value: [200, 980])
  try engine.block.setKeyframes(dot, property: "position", keyframes: [
    Keyframe(time: 0, value: .vec2([200, 980])),
    Keyframe(time: 1, value: .vec2([1680, 980])),
  ])

  let keyframes = try engine.block.getKeyframes(ball, property: "position")
  print(keyframes.count, keyframes[0].spatialOut as Any) // 3 Optional(SIMD2<Float>(0.0, -400.0))

  // The `position/y` track replaces the y-axis of the `position` track
  let hopper = try createCircle(size: 60, color: .rgba(r: 0.2, g: 0.7, b: 0.3, a: 1))
  try engine.block.setKeyframes(hopper, property: "position", keyframes: [
    Keyframe(time: 0, value: .vec2([200, 100])),
    Keyframe(time: 1, value: .vec2([1660, 100])),
  ])
  try engine.block.setKeyframes(hopper, property: "position/y", keyframes: [
    Keyframe(time: 0, value: .float(160)),
    Keyframe(time: 0.25, value: .float(40)),
    Keyframe(time: 0.5, value: .float(160)),
    Keyframe(time: 0.75, value: .float(40)),
    Keyframe(time: 1, value: .float(160)),
  ])

  var valueKindErrorCode: EngineErrorCode?
  do {
    // A motion path takes vec2 values only
    try engine.block.setKeyframes(ball, property: "position", keyframes: [Keyframe(time: 0, value: .float(0))])
  } catch let error as EngineError {
    valueKindErrorCode = error.catalogCode
    print(valueKindErrorCode == .blockKeyframesValueKindMismatch) // true
  }
  var tangentErrorCode: EngineErrorCode?
  do {
    // A single axis takes no spatial tangents
    try engine.block.setKeyframes(ball, property: "position/x", keyframes: [
      Keyframe(time: 0, value: .float(0), spatialOut: [10, 0]),
    ])
  } catch let error as EngineError {
    tangentErrorCode = error.catalogCode
    print(tangentErrorCode == .blockKeyframesSpatialTangentUnsupported) // true
  }

  // Export the frame at 1.25 seconds, while the ball climbs its path
  try engine.block.setPlaybackTime(page, time: 1.25)
  let pngData = try await engine.block.export(page, mimeType: .png)
  print(!pngData.isEmpty) // true

  try await engine.captureGuide(data: pngData, label: "hero", mimeType: .png)

  return MotionPathsGuideResult(
    ballPosition: ballPosition,
    keyframeCount: keyframes.count,
    firstSpatialOut: keyframes[0].spatialOut,
    valueKindErrorCode: valueKindErrorCode,
    tangentErrorCode: tangentErrorCode,
    pngData: pngData,
  )
}

Move a block along a straight or curved path with vec2 position keyframes and spatial tangents.

A blue ball partway along its curve, a red dot partway across, and a green ball at the top of a hop, at 1.25 seconds

6 mins

estimated time

GitHub

position is a vec2 property. One .vec2 keyframe track moves the /x and /y properties of a block together, and spatial tangents curve the path between two keyframes. The editor has no motion path controls, so you set them with the block API.

This guide covers how to curve a path with spatial tangents, how to move in a straight line, how to read a path back, how a single-axis track changes one axis, and the errors to expect. It ends with a frame export.

Creating the Blocks#

The example draws its blocks as circles. A small local function creates each one on the page with a duration of 5 seconds.

// Creates a circle graphic of the given size and color on the page
func createCircle(size: Float, color: Color) throws -> DesignBlockID {
  let block = try engine.block.create(.graphic)
  try engine.block.setShape(block, shape: engine.block.createShape(.ellipse))
  let fill = try engine.block.createFill(.color)
  try engine.block.setColor(fill, property: "fill/color/value", color: color)
  try engine.block.setFill(block, fill: fill)
  try engine.block.setWidth(block, value: size)
  try engine.block.setHeight(block, value: size)
  try engine.block.appendChild(to: page, child: block)
  try engine.block.setDuration(block, duration: 5)
  return block
}

Curving a Path#

setKeyframes(_:property:keyframes:mode:) with .vec2 keyframes sets the path of a block. Both tangents of a segment sit on its first keyframe. spatialOut leaves that keyframe’s value and is relative to it. spatialIn enters the next keyframe’s value and is relative to that value. The last keyframe uses neither. The ball leaves its start straight up, enters the top of its arc from the left, leaves it to the right, and enters its end from above.

setVec2(_:property:value:) sets the static position, here at the start of the path, and getVec2(_:property:) reads it back. The keyframes replace the static position at every playback time.

// Both tangents of a segment sit on its first keyframe. `spatialOut` is
// relative to this keyframe's value, `spatialIn` to the next one's.
let ball = try createCircle(size: 80, color: .rgba(r: 0.2, g: 0.4, b: 0.9, a: 1))
try engine.block.setVec2(ball, property: "position", value: [200, 800])
try engine.block.setKeyframes(ball, property: "position", keyframes: [
  Keyframe(time: 0, value: .vec2([200, 800]), spatialOut: [0, -400], spatialIn: [-400, 0]),
  Keyframe(time: 0.5, value: .vec2([920, 300]), spatialOut: [400, 0], spatialIn: [0, -400]),
  Keyframe(time: 1, value: .vec2([1640, 800])),
])
let ballPosition = try engine.block.getVec2(ball, property: "position")
print(ballPosition) // SIMD2<Float>(200.0, 800.0)

Moving in a Straight Line#

Keyframes without tangents move a block in a straight line between their values. The dot slides along the bottom of the page.

let dot = try createCircle(size: 40, color: .rgba(r: 0.9, g: 0.3, b: 0.4, a: 1))
try engine.block.setVec2(dot, property: "position", value: [200, 980])
try engine.block.setKeyframes(dot, property: "position", keyframes: [
  Keyframe(time: 0, value: .vec2([200, 980])),
  Keyframe(time: 1, value: .vec2([1680, 980])),
])

Reading the Path Back#

getKeyframes(_:property:) returns the keyframes of a property, sorted by time, with their tangents.

let keyframes = try engine.block.getKeyframes(ball, property: "position")
print(keyframes.count, keyframes[0].spatialOut as Any) // 3 Optional(SIMD2<Float>(0.0, -400.0))

Changing One Axis#

A position/x or position/y track with .float keyframes overrides that axis of a position track. The green ball moves right with its position track, while its position/y track makes it hop twice.

// The `position/y` track replaces the y-axis of the `position` track
let hopper = try createCircle(size: 60, color: .rgba(r: 0.2, g: 0.7, b: 0.3, a: 1))
try engine.block.setKeyframes(hopper, property: "position", keyframes: [
  Keyframe(time: 0, value: .vec2([200, 100])),
  Keyframe(time: 1, value: .vec2([1660, 100])),
])
try engine.block.setKeyframes(hopper, property: "position/y", keyframes: [
  Keyframe(time: 0, value: .float(160)),
  Keyframe(time: 0.25, value: .float(40)),
  Keyframe(time: 0.5, value: .float(160)),
  Keyframe(time: 0.75, value: .float(40)),
  Keyframe(time: 1, value: .float(160)),
])

Handling Errors#

A failed setKeyframes(_:property:keyframes:mode:) throws an EngineError whose catalogCode names the cause. The track stays unchanged. A position track takes vec2 values only, and only a vec2 keyframe takes spatial tangents.

var valueKindErrorCode: EngineErrorCode?
do {
  // A motion path takes vec2 values only
  try engine.block.setKeyframes(ball, property: "position", keyframes: [Keyframe(time: 0, value: .float(0))])
} catch let error as EngineError {
  valueKindErrorCode = error.catalogCode
  print(valueKindErrorCode == .blockKeyframesValueKindMismatch) // true
}
var tangentErrorCode: EngineErrorCode?
do {
  // A single axis takes no spatial tangents
  try engine.block.setKeyframes(ball, property: "position/x", keyframes: [
    Keyframe(time: 0, value: .float(0), spatialOut: [10, 0]),
  ])
} catch let error as EngineError {
  tangentErrorCode = error.catalogCode
  print(tangentErrorCode == .blockKeyframesSpatialTangentUnsupported) // true
}

Exporting a Frame#

We export the page as PNG at 1.25 seconds. The frame shows the blue ball on the rising part of its arc, the red dot a quarter of the way along the bottom, and the green ball at the top of its first hop.

// Export the frame at 1.25 seconds, while the ball climbs its path
try engine.block.setPlaybackTime(page, time: 1.25)
let pngData = try await engine.block.export(page, mimeType: .png)
print(!pngData.isEmpty) // true

Motion Paths and Other Block Operations#

Position keyframes are in design units, also when the position mode of the block is .percent.
Scaling the block or changing the design unit also converts its position keyframes.
A .relative position track adds its offsets to the static position, so the path moves with the block. For relative tracks and easing, see Keyframes.
shape/position places a subshape with the same vec2 keyframes and tangents.
When the engine enforces scopes, setting keyframes needs the appearance/animation scope. A position, position/x or position/y track also needs layer/move, and a shape/position track needs shape/change.

Troubleshooting#

The path does not take the values (EngineErrorCode.blockKeyframesValueKindMismatch): pass vec2 keyframes for position and shape/position.
The tangents are refused (EngineErrorCode.blockKeyframesSpatialTangentUnsupported): set spatialOut and spatialIn only on vec2 keyframes, not on position/x or position/y.
The block does not follow the curve: put both tangents of a segment on its first keyframe. A spatialIn on the last keyframe has no effect.
One axis ignores the path: a position/x or position/y track overrides that axis. Remove it to use the path on both axes.

API Reference#

Methods#

Method	Description
`engine.block.create(_:)`	Create a graphic block
`engine.block.createShape(_:)`	Create the ellipse shape
`engine.block.setShape(_:shape:)`	Give a graphic its shape
`engine.block.createFill(_:)`	Create a color fill
`engine.block.setColor(_:property:color:)`	Set the fill color
`engine.block.setFill(_:fill:)`	Give a graphic its fill
`engine.block.setWidth(_:value:)`	Set the width of a block
`engine.block.setHeight(_:value:)`	Set the height of a block
`engine.block.appendChild(to:child:)`	Add a block to the page
`engine.block.setDuration(_:duration:)`	Set the duration that keyframe times refer to
`engine.block.setKeyframes(_:property:keyframes:mode:)`	Set the path or a single-axis track
`engine.block.getKeyframes(_:property:)`	Read the keyframes and tangents of a property
`engine.block.setVec2(_:property:value:)`	Set the static position
`engine.block.getVec2(_:property:)`	Read the static position
`engine.block.setPlaybackTime(_:time:)`	Seek before you export a frame
`engine.block.export(_:mimeType:options:onPreExport:uriResolver:onProgress:)`	Export the frame as PNG

Keyframe Fields#

Field	Type	Description
`spatialOut`	`SIMD2<Float>?`	Tangent that leaves this keyframe’s value, relative to it
`spatialIn`	`SIMD2<Float>?`	Tangent that enters the next keyframe’s value, relative to that value. It sits on this keyframe

Next Steps#

Keyframes: easing, relative tracks and the other keyframe value kinds.
Create Animations: add preset animations to blocks.