p5.tree/track

Animating objects and the camera along keyframes

Keyframe animation for a WEBGL sketch. createPoseTrack animates an object: add position, rotation and scale keyframes, play, and read the interpolated pose each frame to place whatever you draw. createCameraTrack animates a camera the same way from eye and center keyframes, and the camera follows on its own with nothing to do in draw(). Both tracks play automatically each frame, and { handles: true } adds draggable keyframe dots (TrackHandles).

Reach for p5.Camera.capturePose and p5.Camera.applyPose to read the current camera into a keyframe or set a camera from one, and for applyPose and rotateQuat to place an object from a pose or a quaternion. getCamera returns the current camera.

p5

getCamera()

Return the current Camera, the one drawing the canvas right now.

Returns null if called before createCanvas().

Returns p5.Camera|null

The current camera read back: its eye, live, as you orbit

createPoseTrack([opts])

Animate an object along keyframes: add poses, play, and read the interpolated pose each frame with eval to place whatever you draw. Position, rotation and scale each have their own interpolation mode, and { handles: true } adds draggable keyframe dots with an optional rotation ring (see the keyframe handles example). Needs a WEBGL canvas.

ParameterTypeDefaultDescription
opts optional { handles?: boolean|Object }

Returns PoseTrack

Position, rotation and scale keyframes; Hermite, slerp and linear by default
Interpolation modes: linear position, stepped rotation
Keyframe handles: drag the dots, turn the rings about Y

createCameraTrack([cam], [opts])

Animate the camera along keyframes: add lookats, play, and the camera follows with nothing to do in draw(). Pass a camera to fly a second one while the default stays free to orbit, and add { handles: true } to drag keyframe eyes and centers (see the keyframe handles example). Needs a WEBGL canvas; keyframe handles need a second camera to fly, viewed from the default one.

ParameterTypeDefaultDescription
cam optional p5.Camera Camera to drive. Defaults to the current camera. Use createCamera() for a dedicated camera.
opts optional { handles?: boolean|Object }

Returns CameraTrack

Fly the default camera; any key stops and restarts, and the orbit is free while stopped
A dedicated camera: the observer stays free and watches the flight
Author by capture: a adds the current camera as a keyframe, p plays, s stops
Keyframe handles on a dedicated camera: drag eyes and centers, the frustum reflows

rotateQuat(q, [opts])

Rotate the current transform by a unit quaternion [x,y,z,w].

ParameterTypeDefaultDescription
q Float32Array|ArrayLike Unit quaternion [x,y,z,w].
opts optional { eps?:number }
opts.eps optional number 1e-8 Below this sine of the half-angle the rotation is skipped.

Returns p5 this

Accumulate a quaternion each frame and apply it

applyPose(pose)

Apply a { pos, rot, scl } pose (translate, rotate, scale) to the current transform.

ParameterTypeDefaultDescription
pose { pos?:ArrayLike, rot?:ArrayLike, scl?:ArrayLike }

Returns p5 this

A { pos, rot, scl } pose animated by hand and applied to the stack

TrackHandles

update()

Drive the keyframe handles for this frame and report whether one is being dragged. Call it first in draw() and orbit only when it returns false, so a press on a dot grabs it while one that misses orbits (see the orbit gate example). Needs a WEBGL canvas and a track created with handles.

Returns boolean true while any keyframe handle is grabbed.

The orbit gate: a press on a dot grabs it, one that misses orbits

grabbed()

Tell whether any keyframe handle is being dragged right now (see the magenta path example).

Returns boolean true while any keyframe handle is grabbed.

The path turns magenta while any keyframe is held

hovered()

Give the index of the keyframe whose handle is under the pointer or being dragged, or null when there is none (see the bulls-eye example).

Returns number|null keyframe index under the pointer (or grabbed).

A bulls-eye on the keyframe under the pointer

sync()

Refresh the handle dots after editing keyframes from code in the same frame, so they draw where the keyframes are (see the bobbing keyframe example). Chainable.

Returns TrackHandles this

An edit after update() in the same frame: sync() re-seeds the dot before it draws

dispose()

Remove the keyframe handles from the track: the dots disappear and the orbit runs unconditionally (see the key-press example).

Any key disposes the handles: the dots go and the orbit is unconditional

draw([opts])

Draw the keyframe handle dots with the sketch's current fill and stroke; a hovered or grabbed dot grows. Pass size for the dot radius and emphasis for the hover growth (see the standalone draw example). Normally trackPath with the HANDLES bit draws them for you.

ParameterTypeDefaultDescription
opts optional { size?: number, emphasis?: number }
opts.size optional number grabPx Base dot radius in px.
opts.emphasis optional number 1.4 Hover / grab scale factor.

Returns TrackHandles this

Standalone draw with a larger dot and stronger hover emphasis

p5.Camera

capturePose([out])

Read this camera's eye, center, up and lens into a pose you can add to a camera track or draw as a frustum. Pass your own out object to reuse it every frame (see the second camera example). Works on any Camera, live or not.

ParameterTypeDefaultDescription
out optional { eye:number[], center:number[], up:number[], fov:number|null, halfHeight:number|null, near:number, far:number }

Returns { eye:number[], center:number[], up:number[], fov:number|null, halfHeight:number|null, near:number, far:number } fov:number|null, halfHeight:number|null, near:number, far:number }}

A second camera captured into a preallocated out: drawn as a pose spec, and read out

applyPose(pose)

Set this camera from a pose: eye, center and up, plus the lens when a fov or halfHeight is given. Also accepts a { pos, rot, scl } pose from a PoseTrack, so a camera can ride an object's animation.

ParameterTypeDefaultDescription
pose { eye:number[], center:number[], up:number[], fov?:number|null, halfHeight?:number|null, near?:number, far?:number } | { pos:number[], rot:number[], scl?:number[] }

Returns p5.Camera this

A lookat pose written each frame to a second camera
The TRS form: a PoseTrack sample drives the camera like an object