Motion Tracking

Caddis tracks motion with an analyze pass: you set up a tracker node, press Track, the engine analyzes the frame range once (with a progress bar), and the result is baked — it scrubs instantly, saves with the project, and never silently re-runs. User corrections layer on top of the bake as ordinary keyframes, so a drifting track is fixed by nudging, not re-tracking.

Two trackers cover the two workflows:

• PlanarTrack — one flat surface (a phone screen, a sign), tracked with sub-pixel perspective. Drives CornerPin for screen replacement.
• TrackPoints — tens to hundreds of points (feature or blob tracking) emitted as Points geometry for stylized design work.

Screen replacement, end to end

1. Footage layer: drop your clip (VideoSource), add Track > Planar Track, and connect VideoSource → PlanarTrack.in.
2. Define the region: with the PlanarTrack node selected, a lime quad appears in the viewer. Drag its corners over the surface to track. Corner order (1–4 labels) is TL, TR, BR, BL — it determines the pin orientation.
3. Track: in Properties, press Track ▶ (playhead to end of range), ◀ Track (backward — the region is read at the playhead), or All. The range follows the preview range if set, else the layer clip. Progress streams in the Properties panel and status console; rendering pauses while the engine tracks.
4. Review: scrub. The quad now follows the surface; a faint polyline shows the tracked path. Outside the tracked range the quad dims and holds.
5. Correct: see drift at a frame? Drag a corner. That writes a keyframed offset at that frame (always keyed, regardless of auto-key) — the bake is untouched, and the offsets interpolate between your fixes. The dope sheet shows them on offset0–3.
6. Pin Setup: prepare your insert content as its own layer (it can be disabled). On the PlanarTrack's Properties, pick the layer in Pin Setup and press Create. This builds LayerSource(insert) → CornerPin, wires the tracked corners, and merges the pin over the footage — one undo step.
7. The CornerPin gizmo's pins are draggable too; when track-driven, drags write corrections to the tracker.

Changing the region or tracker settings after baking lights an amber "Edited since track" dot — retrack to refresh. Clear discards the bake but keeps corrections.

Blob / point tracking for design

1. Footage → Track > Track Points. Pick a mode:
   • Features tracks corners and texture. Good on real-world footage.
   • Blobs tracks bright (or dark) regions by centroid. Push the footage through Threshold/Levels upstream to isolate what you want; the tracker analyzes its input, not the raw file.
2. Track (same buttons as planar). The bake is written to the project's cache/track/ folder.
3. Wire points into the existing Points pipeline: PointTrail for trails, CloneToPoints to stamp geometry on every track, DrawPoints for dots, PointAttributes/AttributeToField to map the per-point velocity / age / confidence / area attributes onto scale, opacity, or color.

Point IDs are stable for a track's lifetime and never reused, so trails and clones stay attached to "their" point.

Notes

• Tracking blocks the engine (the IPC loop is serial): playback, RAM preview, and rendering wait until the pass finishes. There's no cancel in v1 — track shorter ranges when iterating.
• Tracks are deterministic: re-running on identical input produces an identical bake.
• Planar bakes live inside the project file; point bakes are sidecar files under cache/track/ (collect the cache folder when moving projects, or retrack).