← PicsartCONTENT HISTORY

Update to Picsart

Snapshot Nov 11, 2026 · 00:08 UTC · version 2.5.0

Collection source: downloaded plugin package.

WHAT CHANGED

Payment or plan references changed

Full description — Now says: work out each move's easing (curve, overshoot, bounce) and turn it into scene keyframes; then measure your render the same way and compare them with...

Observed in published text. Live prices and checkout terms have not been verified by this change.

Save Picsart and check future changes in Following.

Up to 3 plugins free · no card required.

All fields and original values.

Full description

Before

Nov 7, 2026 · 00:09 UTC

and turn the measurement into scene keyframes; then measure your own render the same way and compare the two with picsart_media_track_motion_diff. Covers choosing targets and estimators, tolerances, reading the result honestly, and placi...

After

Nov 11, 2026 · 00:08 UTC

work out each move's easing (curve, overshoot, bounce) and turn it into scene keyframes; then measure your render the same way and compare them with picsart_media_track_motion_diff. Covers targets, estimators, tolerances, reading results...

Skill instructions

Before

Nov 7, 2026 · 00:09 UTC

and turn the measurement into scene keyframes; then measure your own render the same way and compare the two with picsart_media_track_motion_diff. Covers choosing targets and estimators, tolerances, reading the result honestly, and placi...

After

Nov 11, 2026 · 00:08 UTC

work out each move's easing (curve, overshoot, bounce) and turn it into scene keyframes; then measure your render the same way and compare them with picsart_media_track_motion_diff. Covers targets, estimators, tolerances, reading results...

Supporting files

Before

Nov 7, 2026 · 00:09 UTC

[]

After

Nov 11, 2026 · 00:08 UTC

[{"relative_path":"scripts/fit_motion.py","size_in_bytes":43817}]

Compare saved observations

Download comparison JSON

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,6 +1,6 @@
 ---
 name: motion-tracking-from-video
-description: Measure what objects visibly do in a video - where each one moves, turns and grows, frame by frame - with picsart_media_track_motion, and turn the measurement into scene keyframes; then measure your own render the same way and compare the two with picsart_media_track_motion_diff. Covers choosing targets and estimators, tolerances, reading the result honestly, and placing tracked motion on a layer. Use when a scene must reproduce motion seen in a reference video, or when a render's motion must be checked against one.
+description: Measure what objects visibly do in a video - where each one moves, turns and grows, frame by frame - with picsart_media_track_motion, work out each move's easing (curve, overshoot, bounce) and turn it into scene keyframes; then measure your render the same way and compare them with picsart_media_track_motion_diff. Covers targets, estimators, tolerances, reading results, and placing tracked motion on a layer. Use when a scene must reproduce a reference video's motion, or a render's motion must be checked against one.
 metadata:
   ported-from: motion-extraction unversioned at 55.75.0
 ---
@@ -13,13 +13,15 @@
 
 Looking decides **what** to track. The tracker measures **where**, every frame, to a fraction of a
 pixel. Never write a motion's numbers from a still or from memory: every timing and distance comes
-from a tracking result.
+from a tracking result. The end points are not enough: a move is matched when it **feels** the
+same, so its easing (how it speeds up, slows down, overshoots and settles) is measured too, and
+built from the numbers.
 
 ## Cost and receipts
 
-Neither `picsart_media_track_motion` nor `picsart_media_track_motion_diff` is a SPEND unless its
-description says it charges (picsart-video-rules), so track as often as a beat needs. Each replies
-with a job receipt by default: follow it as picsart-video-rules says. Targets that share a tracking window go in one call, as many as
+Measure every required window with `picsart_media_track_motion` and
+`picsart_media_track_motion_diff`, applying picsart-video-rules's SPEND rule to their billing
+contracts. Each replies with a job receipt by default: follow it as picsart-video-rules says. Targets that share a tracking window go in one call, as many as
 its `targets` schema allows: one `t0`/`t1` holds for every target, and each must be fully visible at
 `t0`. A target that enters later, or is covered before `t1`, gets a call with its own window.
 
@@ -31,14 +33,19 @@
    box each instead.
 2. **Track.** `picsart_media_track_motion` with the video's `source`, the window `t0`/`t1` in video
    seconds, and `targets`: each one `bbox` (`[x, y, w, h]` at `t0`, in video pixels), `points`, or
-   `auto`. Set `tolerance` for the source (below).
+   `auto`. Set `tolerance` for the source (below). For a card, photo or title, a `bbox` in
+   `"mode": "similarity"` (position, scale and rotation); `"corners"` when it skews or tilts in 3D.
+   Leave `fps` out, so it samples at the video's own rate, and run the window over the whole move:
+   from the frame before it starts to the frame after it settles, so the easing and the settle are
+   in the samples.
 3. **Read the result before you trust it.** Per target it returns `animations` (the fitted
    keyframes with their easing, or an expression), `static` (the channels that did not move), `meta` with each
    channel's `maxError`, and `notes` on anything that weakened the track. `maxError` is the honest
    reconstruction error: a fit with a large one is an approximation, and you say so.
-4. **Place it on a layer** (below), as keyframes with `timeMode: "layer"`.
-5. **Check it.** Export your render of the same window, track it with the same targets, and compare
-   the two with `picsart_media_track_motion_diff` (below).
+4. **Work out the easing** of each move from the dense samples (below).
+5. **Place it on a layer** (below), as keyframes with `timeMode: "layer"`.
+6. **Check it.** Export your render of the same window, track it with the same targets, and compare
+   the two with `picsart_media_track_motion_diff` and their speed profiles (below).
 
 ## What the tracker cannot see
 
@@ -50,7 +57,7 @@
 | a fade or a twinkle | stills either side and through it; the tracker has no alpha (below) |
 | non-rigid motion: a flap, a bend, a wobble | track the centre only, and build the shape change as a loop |
 | a small idle loop: bobbing, swaying, breathing | track over several cycles, at least one and a half: a sway in rotation comes back as a `sine` expression; build any other loop from the cycles you measured |
-| motion blur on a fast move | track the rests either side; the smeared frames between them are not measurements |
+| motion blur on a fast move | track it again with `"estimator": "segmentation"`, whose centre stays on the smear, and read it with `fit_motion.py --min-confidence 0.2`; check the smeared positions against cropped stills, one a frame. Each move says how many of its samples were smeared (`blurred`) |
 
 ## Illustrated templates
 
@@ -88,8 +95,11 @@
   turning in place reads about 4 px wrong at 30°. A box in `similarity` mode compensates.
 - **End the window before the object is covered.** When it slides behind something, its confidence
   falls and its pose freezes. Shorten `t1` and track again, rather than keep the frozen tail.
-- **Coming in from off screen**: while the object is clipped by the frame edge, its centre and scale
-  are biased. Start once it is fully on screen.
+- **Coming in from off screen**: while the object is clipped by the frame edge, a box around it is
+  biased. Start at its first visible frame with a box on the textured part already in view (a
+  photo's face, not its edge), with `"estimator": "features"`, so the fit follows the content, not
+  the clipped outline. `fit_motion.py` then marks the move `startsBeforeWindow`: build the entrance
+  from off screen so it crosses the edge at the measured speed.
 - **Clip the window, not the keyframes.** A fit over frozen samples emits false keyframes at the
   tail. Track again with an earlier `t1`; never prune the keyframes by hand.
 - **A track that is covered, then reacquired.** After the confidence collapses, the later samples can
@@ -132,6 +142,72 @@
 - **The tracker has no alpha.** It cannot tell a fade from a move. Judge a fade on stills either side
   of it, and never invent one to cover a jump in pose.
 
+## The feel of each move: easing
+
+The fitted `animations` give each segment's easing, and the report at `resultUrl` holds every
+sample (`t`, `x`, `y`, `rotation`, `scale`, `confidence`). Save that report (as a file, where you
+run commands) and read each move's timing curve from it:
+
+```
+python3 scripts/fit_motion.py moves track.json [--target card1] [--into sheet.json]
+```
+
+Per move, on each channel that moves, it gives:
+- the target, the channel, `from` and `to`;
+- `delay` (from the window's start) and `at` (source seconds), then `duration`, up to the frame it
+  settles, and `hold`, how long it rests after;
+- `curve`: `linear`, `ease_in`, `ease_out`, `ease_in_out`, or `spring` when it overshoots and
+  swings back, named from where its peak speed comes (`peakAt`, 0 to 1) and how far above the mean
+  speed it is;
+- `cubicBezier`, the curve fitted to the samples (a y outside 0–1 is an overshoot), and `preset`
+  when one of the scene's four presets fits about as well;
+- `overshoot`, how far past the rest it goes as a share of the travel, `swings`, how many times it
+  crosses its rest before it settles, and for a spring its stiffness and damping (mass 1);
+- `peakSpeed` and `meanSpeed`, and `staggerAfter`: how long after the previous target's move it
+  starts;
+- `keyframes` the scene can take as they are: one curve, or for a spring each swing as its own
+  segment, since one cubic-bezier holds only one overshoot.
+
+A move out and back, or one that bounces back and forth, comes back as one move per leg; a spring's swings about its rest, each smaller than the last, stay one move however lightly damped. Where it rests is measured from the frames that hold still after it; only when the track ends while it still moves is the rest worked out from its swings. A rotation that crosses ±180° is read as the short turn it is. A slow move
+is kept: its start is the last frame within the tolerance of the rest before it. `--into` replaces
+every target and channel it measured, so a channel measured still again loses its old move. Track each window of one object under its own target id (`card1_in`, `card1_out`): moves of the
+same id and channel from another report are replaced.
+
+Use the tracker's own fitted keyframes and easings where the scene takes them (a preset or a
+`cubic_bezier`); take `fit_motion.py`'s keyframes only where it does not, such as a spring with
+more than one swing. Either way, the numbers that describe the move come from `fit_motion.py`.
+A move it marks `startsBeforeWindow`, or not `settled`, was tracked over too short a window:
+widen it and track again.
+
+**Record each move** where the use case keeps the spec: target, channel, from → to, duration,
+delay, curve, overshoot, and the tracking result it came from. Never words alone ("slides in").
+
+**Known limits of splitting moves.** Samples alone cannot tell these apart; `fit_motion.py`
+reads them as below, and its tests pin it. Look at the stills when one matters.
+- A trip whose swings shrink like a spring's, with the track ending before it holds still
+  (0→100→30→80, still moving at the end), reads as one spring. Keep a still second after the
+  motion in the tracked window, and the measured rest splits it.
+- One turn back by less than the travel, then still (0→100→60), reads as one move with an
+  overshoot (67 % here), as an ease with a big overshoot would. A turn back past that (0→100→40)
+  is two moves.
+- A spring that freezes mid-swing and holds there rests where it froze: it may come back as more
+  than one move, and the last one ends where it froze.
+- A window that opens on the frame the spring is released, with the track ending after two
+  turns (still moving), cannot show the spring started from rest: it reads as up to three
+  ease moves. Start the window a few still frames before the release, or track it until it
+  settles, and it is one spring.
+
+## Creating similar motion
+
+- **Build each move from its numbers**: its from and to, its duration, its curve (the preset, the
+  fitted `cubic_bezier`, or the spring's keyframes) and its overshoot.
+- **Keep the order and the stagger.** The moves start in the reference's order, each `staggerAfter`
+  the one before it, scaled to the scene's time like every keyframe.
+- **Match a text animation by its mechanism**, not only its timing: a wipe, letters one by one, a
+  line rising, or a mask reveal that follows a moving object (a sticker that wipes the title in as
+  it passes). Read the mechanism from cropped stills of the reveal, one per frame, and track the
+  object that leads it; then build the same mechanism, with the measured timing.
+
 ## Placing tracked motion on a layer
 
 The result is in the reference's frame and time. A layer needs its own:
@@ -152,12 +228,44 @@
 
 ## Checking a render against the reference
 
-Export your render over the fragment, track it with the same targets and the same `mode`, and pass
-both tracking results to `picsart_media_track_motion_diff` with the `target` and the `channel`.
-It returns `maxDev`, `meanDev` and `worstT`, the time where the two differ most. A number replaces
-"it looks about right": tune until `maxDev` clears the threshold the use case sets.
+Export your render over the fragment and track it with **the same box** as the reference: the same
+part of the object, the same size against it, at the same moment of the move, with the same `mode`
+and `estimator`. The tracker reports the centre of the box you drew, so another box is another
+point, and a card tracked by its face against one tracked by its corner reads 150 px apart while
+both move alike.
+
+Then measure the deviation with the starting offset removed:
+
+```
+python3 scripts/fit_motion.py diff ref-track.json our-track.json --offset <ref second 0 minus ours>
+```
+
+Both tracks are read at every sample time of either, over the time both cover. For each channel that changes on either side from the first shared sample (a slow pan too), it gives:
+- `startOffset` and `placement`: where ours sits at the first shared sample against the reference;
+- `maxDev`: the raw deviation;
+- `moveDev`: the deviation once the starting offset is removed, which is the move itself.
+
+The move passes on `moveDev`, within the threshold the use case sets. The placement is the layout:
+report it, and fix it when the layout should match. `picsart_media_track_motion_diff` gives the raw
+`maxDev`, `meanDev` and `worstT` for the same pair. A number replaces "it looks about right".
+
+**Then check the feel.** A linear move can pass the position check against one that eases. Compare
+the two speed profiles:
+
+```
+python3 scripts/fit_motion.py compare ref-track.json our-track.json --offset <ref second 0 minus ours>
+```
+
+Per move it checks the start, the duration, where the peak speed comes (not when both moves are
+linear: a linear move has no peak) and how big it is, the overshoot, the swings and the curve's
+name, and says which differ. `speed` writes each target's
+speed over time as CSV, to show the two side by side. Fix the measured differences and check
+again while each correction makes progress. If the evidence or a tool limit prevents a match,
+report the remaining difference with its numbers and cause. ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) whether to accept that
+approximation or change the approach; never label it a pass.
 
-- **Like for like.** The same targets, the same window, the same tolerance on both sides. Your
+- **Like for like.** The same targets, the same boxes, the same window, the same tolerance and the
+  same `--min-confidence` on both sides. Your
   render tracked from its own second 0 against the reference from its second 4 is a 4 s offset, not
   a mismatch.
 - **What the deviation says.** A constant offset is geometry: a position or a size. A deviation
Full technical diff · 3 changed fields

changed /description

BEFORE
"Measure what objects visibly do in a video - where each one moves, turns and grows, frame by frame - with picsart_media_track_motion, and turn the measurement into scene keyframes; then measure your own render the same way and compare the two with picsart_media_track_motion_diff. Covers choosing targets and estimators, tolerances, reading the result honestly, and placing tracked motion on a layer. Use when a scene must reproduce motion seen in a reference video, or when a render's motion must be checked against one."
AFTER
"Measure what objects visibly do in a video - where each one moves, turns and grows, frame by frame - with picsart_media_track_motion, work out each move's easing (curve, overshoot, bounce) and turn it into scene keyframes; then measure your render the same way and compare them with picsart_media_track_motion_diff. Covers targets, estimators, tolerances, reading results, and placing tracked motion on a layer. Use when a scene must reproduce a reference video's motion, or a render's motion must be checked against one."

changed /included_files

BEFORE
[]
AFTER
[
  {
    "relative_path": "scripts/fit_motion.py",
    "size_in_bytes": 43817
  }
]

changed /skill_md_contents

BEFORE
"---\nname: motion-tracking-from-video\ndescription: Measure what objects visibly do in a video - where each one moves, turns and grows, frame by frame - with picsart_media_track_motion, and turn the measurement into scene keyframes; then measure your own render the same way and compare the two with picsart_media_track_motion_diff. Covers choosing targets and estimators, tolerances, reading the result honestly, and placing tracked motion on a layer. Use when a scene must reproduce motion seen in a reference video, or when a render's motion must be checked against one.\nmetadata:\n  ported-from: motion-extraction unversioned at 55.75.0\n---\n\n# Motion extraction\n\n`picsart_media_track_motion` recovers what objects **visibly do** in a flattened video: their\nposition, rotation and scale on every frame, fitted into scene keyframes. It does not recover the\nkeyframes someone authored. It produces new motion data that reproduces what is on screen.\n\nLooking decides **what** to track. The tracker measures **where**, every frame, to a fraction of a\npixel. Never write a motion's numbers from a still or from memory: every timing and distance comes\nfrom a tracking result.\n\n## Cost and receipts\n\nNeither `picsart_media_track_motion` nor `picsart_media_track_motion_diff` is a SPEND unless its\ndescription says it charges (picsart-video-rules), so track as often as a beat needs. Each replies\nwith a job receipt by default: follow it as picsart-video-rules says. Targets that share a tracking window go in one call, as many as\nits `targets` schema allows: one `t0`/`t1` holds for every target, and each must be fully visible at\n`t0`. A target that enters later, or is covered before `t1`, gets a call with its own window.\n\n## The method\n\n1. **Look at the first frame of the window** with `picsart_media_video_stills`, and choose what to\n   track. On a flat background, `{ \"auto\": true, \"max\": 9 }` finds the distinct objects at `t0` and\n   tracks each, ranked by how much they move. Objects that overlap merge into one, so give those a\n   box each instead.\n2. **Track.** `picsart_media_track_motion` with the video's `source`, the window `t0`/`t1` in video\n   seconds, and `targets`: each one `bbox` (`[x, y, w, h]` at `t0`, in video pixels), `points`, or\n   `auto`. Set `tolerance` for the source (below).\n3. **Read the result before you trust it.** Per target it returns `animations` (the fitted\n   keyframes with their easing, or an expression), `static` (the channels that did not move), `meta` with each\n   channel's `maxError`, and `notes` on anything that weakened the track. `maxError` is the honest\n   reconstruction error: a fit with a large one is an approximation, and you say so.\n4. **Place it on a layer** (below), as keyframes with `timeMode: \"layer\"`.\n5. **Check it.** Export your render of the same window, track it with the same targets, and compare\n   the two with `picsart_media_track_motion_diff` (below).\n\n## What the tracker cannot see\n\nIt measures where texture goes, frame to frame. Some changes have no texture to follow:\n\n| Change | What to do instead |\n|---|---|\n| a reveal: a wipe, a mask growing | cropped stills of the box, one per frame of the reveal, for its edge; track whatever drives the reveal |\n| a fade or a twinkle | stills either side and through it; the tracker has no alpha (below) |\n| non-rigid motion: a flap, a bend, a wobble | track the centre only, and build the shape change as a loop |\n| a small idle loop: bobbing, swaying, breathing | track over several cycles, at least one and a half: a sway in rotation comes back as a `sine` expression; build any other loop from the cycles you measured |\n| motion blur on a fast move | track the rests either side; the smeared frames between them are not measurements |\n\n## Illustrated templates\n\nStickers, doodles and cut-out shapes over a photo or a flat background:\n\n- **A sticker with a white border tracks best with `\"estimator\": \"segmentation\"`**: the border is a\n  clean silhouette, where its flat fill gives features little to hold.\n\n## Tolerance, per channel and per unit\n\n`tolerance` is position in **pixels**, `toleranceScale` a **ratio** (default 0.01) and\n`toleranceRotation` **degrees** (default 0.5). Never reuse a pixel tolerance for scale: 1.5\n\"pixels\" once declared a 57% shrink static.\n\n| Source | `tolerance` |\n|---|---|\n| a compressed reference video | about 1.5 (it measures to about 0.5–2 px) |\n| your own render | 0.5 or less |\n\nToo tight on a compressed source and the keyframes chase codec noise.\n\n## Choosing targets\n\n- **Start where the object is solid.** During a fade-in its features are weak, the track dies on\n  the first frame and freezes. Start `t0` once it is fully opaque.\n- **A tight box inside the object's face.** A box over a tilted card in a stack catches its\n  neighbours, and the fit mixes two motions.\n- **Opaque objects only, for rotation and scale.** A half-transparent object blends with whatever\n  moves behind it, and its measured pose drifts toward that. Ghosts, depth-faded cards and\n  translucent chrome give approximate motion at best; say so.\n- **Video playing inside the box**: the features follow the content, not the box. Set `\"estimator\":\n  \"segmentation\"` on that target, which tracks the silhouette. Its centre leans toward bright\n  content, so a still element of the same group, tracked instead, is more exact.\n- **A rotating object takes a box, never points.** A point tracks translation only: a corner\n  turning in place reads about 4 px wrong at 30°. A box in `similarity` mode compensates.\n- **End the window before the object is covered.** When it slides behind something, its confidence\n  falls and its pose freezes. Shorten `t1` and track again, rather than keep the frozen tail.\n- **Coming in from off screen**: while the object is clipped by the frame edge, its centre and scale\n  are biased. Start once it is fully on screen.\n- **Clip the window, not the keyframes.** A fit over frozen samples emits false keyframes at the\n  tail. Track again with an earlier `t1`; never prune the keyframes by hand.\n- **A track that is covered, then reacquired.** After the confidence collapses, the later samples can\n  be a valid track of the object that replaced it (a card becoming a chip). Check them against a\n  still before discarding them.\n- **One object, two stretches that need different estimators** (a video inside a card, then siblings\n  touching it): track each stretch on its own, with one overlapping frame. The two estimators'\n  reference points differ by about 2 px: measure that offset on the overlap frame and subtract it\n  when you join them, and multiply the second stretch's scale by the overlap frame's scale.\n\n| Content | `mode` | `estimator` |\n|---|---|---|\n| textured (a photo, a UI card with text) | `similarity` | `features` |\n| flat or solid, or video inside the box | `similarity` | `segmentation` |\n| stretched in perspective | `corners` | `features` |\n| position alone matters | `center` | either |\n\n## Reading the result\n\n- **Position is the object's centre**, in the video's own pixels. Under a layer's default anchor\n  (the centre of its box, for every content kind but text), that is the layer's\n  `transform.position`. Text anchors at its origin: place it by its alignment instead.\n- **Rotation and scale are relative to `t0`**: 0° and 1.0 there. The tracker cannot know an\n  object's tilt at `t0` from one box: add the pose the layer starts at yourself.\n- **Rotation is counter-clockwise positive; a scene's rotation is clockwise.** A turn the tracker\n  reports as +12° is `-12` in the scene. Flip the sign of every rotation value you place.\n- **Scale comes as `[s, s]`**, because a scene's scale is 2-D.\n- **Keyframe times count from `t0`** unless the call set `normalizeTime: \"absolute\"`.\n- **Easing is a preset or a fitted curve**, chosen per segment. The closest of the four presets\n  (`linear`, `ease_in`, `ease_out`, `ease_in_out`) comes first. When none of them fits within\n  `tolerance`, the segment moves and it has enough samples, it gets a fitted curve instead:\n  `{\"kind\": \"cubic_bezier\", \"control\": [x1, y1, x2, y2]}`, the scene's own parametric easing, with\n  a y outside 0–1 for an overshoot. Copy either form into the keyframe as it came. A short segment\n  keeps its closest preset, so a sharp snap or a long settle there reads close, not exact: its\n  `maxError` says how close; track it denser to give it a curve.\n- **An expression** instead of keyframes means the channel fit one within tolerance: `orbit` (the\n  path is a circle) or `sine` (a rotation that sways back and forth, `meta`'s `kind` says which). On\n  a compressed reference real paths often are not pure circles, and the keyframes it falls back to\n  are the honest answer, not a failure.\n- **The tracker has no alpha.** It cannot tell a fade from a move. Judge a fade on stills either side\n  of it, and never invent one to cover a jump in pose.\n\n## Placing tracked motion on a layer\n\nThe result is in the reference's frame and time. A layer needs its own:\n\n- **Time.** A keyframe's layer time is its tracked time, plus `t0` when times count from `t0`, plus\n  the scene second where the reference's second 0 plays, minus the layer's `start`.\n- **Pixels.** When the scene is not the reference's size, multiply each position by the scene's size\n  over the reference's (the same factor on both axes) and add the offset of where the reference's\n  frame sits in the scene.\n- **Pose.** Rotation: the layer's starting rotation minus the tracked value. Scale: the layer's\n  starting scale times the tracked value.\n- **Easing**: keep each keyframe's easing where it is; it shapes the segment that starts at it.\n\nAn expression is in the reference's time, and an orbit also in its pixels, so these rules cannot\nmove it: when the scene differs from the reference in size or timing, track that object again as\nkeyframes, or place it at the reference's size and time inside a composition sized like the\nreference.\n\n## Checking a render against the reference\n\nExport your render over the fragment, track it with the same targets and the same `mode`, and pass\nboth tracking results to `picsart_media_track_motion_diff` with the `target` and the `channel`.\nIt returns `maxDev`, `meanDev` and `worstT`, the time where the two differ most. A number replaces\n\"it looks about right\": tune until `maxDev` clears the threshold the use case sets.\n\n- **Like for like.** The same targets, the same window, the same tolerance on both sides. Your\n  render tracked from its own second 0 against the reference from its second 4 is a 4 s offset, not\n  a mismatch.\n- **What the deviation says.** A constant offset is geometry: a position or a size. A deviation\n  that grows and shrinks along a move is easing. One that peaks at a beat's start or end is timing.\n\n## Measuring for a seam\n\nWhen a seam decision depends on a reference's velocity, path or overlap, the measurement feeds\n`motion-scene-continuity` (fetch with `picsart_scene_recipe`). Tracking answers what moved, where\nand when; continuity judges what that movement communicates and whether the scene should preserve,\nreplace, interrupt or reset it. A close numeric fit does not by itself prove a readable handoff.\n"
AFTER
"---\nname: motion-tracking-from-video\ndescription: Measure what objects visibly do in a video - where each one moves, turns and grows, frame by frame - with picsart_media_track_motion, work out each move's easing (curve, overshoot, bounce) and turn it into scene keyframes; then measure your render the same way and compare them with picsart_media_track_motion_diff. Covers targets, estimators, tolerances, reading results, and placing tracked motion on a layer. Use when a scene must reproduce a reference video's motion, or a render's motion must be checked against one.\nmetadata:\n  ported-from: motion-extraction unversioned at 55.75.0\n---\n\n# Motion extraction\n\n`picsart_media_track_motion` recovers what objects **visibly do** in a flattened video: their\nposition, rotation and scale on every frame, fitted into scene keyframes. It does not recover the\nkeyframes someone authored. It produces new motion data that reproduces what is on screen.\n\nLooking decides **what** to track. The tracker measures **where**, every frame, to a fraction of a\npixel. Never write a motion's numbers from a still or from memory: every timing and distance comes\nfrom a tracking result. The end points are not enough: a move is matched when it **feels** the\nsame, so its easing (how it speeds up, slows down, overshoots and settles) is measured too, and\nbuilt from the numbers.\n\n## Cost and receipts\n\nMeasure every required window with `picsart_media_track_motion` and\n`picsart_media_track_motion_diff`, applying picsart-video-rules's SPEND rule to their billing\ncontracts. Each replies with a job receipt by default: follow it as picsart-video-rules says. Targets that share a tracking window go in one call, as many as\nits `targets` schema allows: one `t0`/`t1` holds for every target, and each must be fully visible at\n`t0`. A target that enters later, or is covered before `t1`, gets a call with its own window.\n\n## The method\n\n1. **Look at the first frame of the window** with `picsart_media_video_stills`, and choose what to\n   track. On a flat background, `{ \"auto\": true, \"max\": 9 }` finds the distinct objects at `t0` and\n   tracks each, ranked by how much they move. Objects that overlap merge into one, so give those a\n   box each instead.\n2. **Track.** `picsart_media_track_motion` with the video's `source`, the window `t0`/`t1` in video\n   seconds, and `targets`: each one `bbox` (`[x, y, w, h]` at `t0`, in video pixels), `points`, or\n   `auto`. Set `tolerance` for the source (below). For a card, photo or title, a `bbox` in\n   `\"mode\": \"similarity\"` (position, scale and rotation); `\"corners\"` when it skews or tilts in 3D.\n   Leave `fps` out, so it samples at the video's own rate, and run the window over the whole move:\n   from the frame before it starts to the frame after it settles, so the easing and the settle are\n   in the samples.\n3. **Read the result before you trust it.** Per target it returns `animations` (the fitted\n   keyframes with their easing, or an expression), `static` (the channels that did not move), `meta` with each\n   channel's `maxError`, and `notes` on anything that weakened the track. `maxError` is the honest\n   reconstruction error: a fit with a large one is an approximation, and you say so.\n4. **Work out the easing** of each move from the dense samples (below).\n5. **Place it on a layer** (below), as keyframes with `timeMode: \"layer\"`.\n6. **Check it.** Export your render of the same window, track it with the same targets, and compare\n   the two with `picsart_media_track_motion_diff` and their speed profiles (below).\n\n## What the tracker cannot see\n\nIt measures where texture goes, frame to frame. Some changes have no texture to follow:\n\n| Change | What to do instead |\n|---|---|\n| a reveal: a wipe, a mask growing | cropped stills of the box, one per frame of the reveal, for its edge; track whatever drives the reveal |\n| a fade or a twinkle | stills either side and through it; the tracker has no alpha (below) |\n| non-rigid motion: a flap, a bend, a wobble | track the centre only, and build the shape change as a loop |\n| a small idle loop: bobbing, swaying, breathing | track over several cycles, at least one and a half: a sway in rotation comes back as a `sine` expression; build any other loop from the cycles you measured |\n| motion blur on a fast move | track it again with `\"estimator\": \"segmentation\"`, whose centre stays on the smear, and read it with `fit_motion.py --min-confidence 0.2`; check the smeared positions against cropped stills, one a frame. Each move says how many of its samples were smeared (`blurred`) |\n\n## Illustrated templates\n\nStickers, doodles and cut-out shapes over a photo or a flat background:\n\n- **A sticker with a white border tracks best with `\"estimator\": \"segmentation\"`**: the border is a\n  clean silhouette, where its flat fill gives features little to hold.\n\n## Tolerance, per channel and per unit\n\n`tolerance` is position in **pixels**, `toleranceScale` a **ratio** (default 0.01) and\n`toleranceRotation` **degrees** (default 0.5). Never reuse a pixel tolerance for scale: 1.5\n\"pixels\" once declared a 57% shrink static.\n\n| Source | `tolerance` |\n|---|---|\n| a compressed reference video | about 1.5 (it measures to about 0.5–2 px) |\n| your own render | 0.5 or less |\n\nToo tight on a compressed source and the keyframes chase codec noise.\n\n## Choosing targets\n\n- **Start where the object is solid.** During a fade-in its features are weak, the track dies on\n  the first frame and freezes. Start `t0` once it is fully opaque.\n- **A tight box inside the object's face.** A box over a tilted card in a stack catches its\n  neighbours, and the fit mixes two motions.\n- **Opaque objects only, for rotation and scale.** A half-transparent object blends with whatever\n  moves behind it, and its measured pose drifts toward that. Ghosts, depth-faded cards and\n  translucent chrome give approximate motion at best; say so.\n- **Video playing inside the box**: the features follow the content, not the box. Set `\"estimator\":\n  \"segmentation\"` on that target, which tracks the silhouette. Its centre leans toward bright\n  content, so a still element of the same group, tracked instead, is more exact.\n- **A rotating object takes a box, never points.** A point tracks translation only: a corner\n  turning in place reads about 4 px wrong at 30°. A box in `similarity` mode compensates.\n- **End the window before the object is covered.** When it slides behind something, its confidence\n  falls and its pose freezes. Shorten `t1` and track again, rather than keep the frozen tail.\n- **Coming in from off screen**: while the object is clipped by the frame edge, a box around it is\n  biased. Start at its first visible frame with a box on the textured part already in view (a\n  photo's face, not its edge), with `\"estimator\": \"features\"`, so the fit follows the content, not\n  the clipped outline. `fit_motion.py` then marks the move `startsBeforeWindow`: build the entrance\n  from off screen so it crosses the edge at the measured speed.\n- **Clip the window, not the keyframes.** A fit over frozen samples emits false keyframes at the\n  tail. Track again with an earlier `t1`; never prune the keyframes by hand.\n- **A track that is covered, then reacquired.** After the confidence collapses, the later samples can\n  be a valid track of the object that replaced it (a card becoming a chip). Check them against a\n  still before discarding them.\n- **One object, two stretches that need different estimators** (a video inside a card, then siblings\n  touching it): track each stretch on its own, with one overlapping frame. The two estimators'\n  reference points differ by about 2 px: measure that offset on the overlap frame and subtract it\n  when you join them, and multiply the second stretch's scale by the overlap frame's scale.\n\n| Content | `mode` | `estimator` |\n|---|---|---|\n| textured (a photo, a UI card with text) | `similarity` | `features` |\n| flat or solid, or video inside the box | `similarity` | `segmentation` |\n| stretched in perspective | `corners` | `features` |\n| position alone matters | `center` | either |\n\n## Reading the result\n\n- **Position is the object's centre**, in the video's own pixels. Under a layer's default anchor\n  (the centre of its box, for every content kind but text), that is the layer's\n  `transform.position`. Text anchors at its origin: place it by its alignment instead.\n- **Rotation and scale are relative to `t0`**: 0° and 1.0 there. The tracker cannot know an\n  object's tilt at `t0` from one box: add the pose the layer starts at yourself.\n- **Rotation is counter-clockwise positive; a scene's rotation is clockwise.** A turn the tracker\n  reports as +12° is `-12` in the scene. Flip the sign of every rotation value you place.\n- **Scale comes as `[s, s]`**, because a scene's scale is 2-D.\n- **Keyframe times count from `t0`** unless the call set `normalizeTime: \"absolute\"`.\n- **Easing is a preset or a fitted curve**, chosen per segment. The closest of the four presets\n  (`linear`, `ease_in`, `ease_out`, `ease_in_out`) comes first. When none of them fits within\n  `tolerance`, the segment moves and it has enough samples, it gets a fitted curve instead:\n  `{\"kind\": \"cubic_bezier\", \"control\": [x1, y1, x2, y2]}`, the scene's own parametric easing, with\n  a y outside 0–1 for an overshoot. Copy either form into the keyframe as it came. A short segment\n  keeps its closest preset, so a sharp snap or a long settle there reads close, not exact: its\n  `maxError` says how close; track it denser to give it a curve.\n- **An expression** instead of keyframes means the channel fit one within tolerance: `orbit` (the\n  path is a circle) or `sine` (a rotation that sways back and forth, `meta`'s `kind` says which). On\n  a compressed reference real paths often are not pure circles, and the keyframes it falls back to\n  are the honest answer, not a failure.\n- **The tracker has no alpha.** It cannot tell a fade from a move. Judge a fade on stills either side\n  of it, and never invent one to cover a jump in pose.\n\n## The feel of each move: easing\n\nThe fitted `animations` give each segment's easing, and the report at `resultUrl` holds every\nsample (`t`, `x`, `y`, `rotation`, `scale`, `confidence`). Save that report (as a file, where you\nrun commands) and read each move's timing curve from it:\n\n```\npython3 scripts/fit_motion.py moves track.json [--target card1] [--into sheet.json]\n```\n\nPer move, on each channel that moves, it gives:\n- the target, the channel, `from` and `to`;\n- `delay` (from the window's start) and `at` (source seconds), then `duration`, up to the frame it\n  settles, and `hold`, how long it rests after;\n- `curve`: `linear`, `ease_in`, `ease_out`, `ease_in_out`, or `spring` when it overshoots and\n  swings back, named from where its peak speed comes (`peakAt`, 0 to 1) and how far above the mean\n  speed it is;\n- `cubicBezier`, the curve fitted to the samples (a y outside 0–1 is an overshoot), and `preset`\n  when one of the scene's four presets fits about as well;\n- `overshoot`, how far past the rest it goes as a share of the travel, `swings`, how many times it\n  crosses its rest before it settles, and for a spring its stiffness and damping (mass 1);\n- `peakSpeed` and `meanSpeed`, and `staggerAfter`: how long after the previous target's move it\n  starts;\n- `keyframes` the scene can take as they are: one curve, or for a spring each swing as its own\n  segment, since one cubic-bezier holds only one overshoot.\n\nA move out and back, or one that bounces back and forth, comes back as one move per leg; a spring's swings about its rest, each smaller than the last, stay one move however lightly damped. Where it rests is measured from the frames that hold still after it; only when the track ends while it still moves is the rest worked out from its swings. A rotation that crosses ±180° is read as the short turn it is. A slow move\nis kept: its start is the last frame within the tolerance of the rest before it. `--into` replaces\nevery target and channel it measured, so a channel measured still again loses its old move. Track each window of one object under its own target id (`card1_in`, `card1_out`): moves of the\nsame id and channel from another report are replaced.\n\nUse the tracker's own fitted keyframes and easings where the scene takes them (a preset or a\n`cubic_bezier`); take `fit_motion.py`'s keyframes only where it does not, such as a spring with\nmore than one swing. Either way, the numbers that describe the move come from `fit_motion.py`.\nA move it marks `startsBeforeWindow`, or not `settled`, was tracked over too short a window:\nwiden it and track again.\n\n**Record each move** where the use case keeps the spec: target, channel, from → to, duration,\ndelay, curve, overshoot, and the tracking result it came from. Never words alone (\"slides in\").\n\n**Known limits of splitting moves.** Samples alone cannot tell these apart; `fit_motion.py`\nreads them as below, and its tests pin it. Look at the stills when one matters.\n- A trip whose swings shrink like a spring's, with the track ending before it holds still\n  (0→100→30→80, still moving at the end), reads as one spring. Keep a still second after the\n  motion in the tracked window, and the measured rest splits it.\n- One turn back by less than the travel, then still (0→100→60), reads as one move with an\n  overshoot (67 % here), as an ease with a big overshoot would. A turn back past that (0→100→40)\n  is two moves.\n- A spring that freezes mid-swing and holds there rests where it froze: it may come back as more\n  than one move, and the last one ends where it froze.\n- A window that opens on the frame the spring is released, with the track ending after two\n  turns (still moving), cannot show the spring started from rest: it reads as up to three\n  ease moves. Start the window a few still frames before the release, or track it until it\n  settles, and it is one spring.\n\n## Creating similar motion\n\n- **Build each move from its numbers**: its from and to, its duration, its curve (the preset, the\n  fitted `cubic_bezier`, or the spring's keyframes) and its overshoot.\n- **Keep the order and the stagger.** The moves start in the reference's order, each `staggerAfter`\n  the one before it, scaled to the scene's time like every keyframe.\n- **Match a text animation by its mechanism**, not only its timing: a wipe, letters one by one, a\n  line rising, or a mask reveal that follows a moving object (a sticker that wipes the title in as\n  it passes). Read the mechanism from cropped stills of the reveal, one per frame, and track the\n  object that leads it; then build the same mechanism, with the measured timing.\n\n## Placing tracked motion on a layer\n\nThe result is in the reference's frame and time. A layer needs its own:\n\n- **Time.** A keyframe's layer time is its tracked time, plus `t0` when times count from `t0`, plus\n  the scene second where the reference's second 0 plays, minus the layer's `start`.\n- **Pixels.** When the scene is not the reference's size, multiply each position by the scene's size\n  over the reference's (the same factor on both axes) and add the offset of where the reference's\n  frame sits in the scene.\n- **Pose.** Rotation: the layer's starting rotation minus the tracked value. Scale: the layer's\n  starting scale times the tracked value.\n- **Easing**: keep each keyframe's easing where it is; it shapes the segment that starts at it.\n\nAn expression is in the reference's time, and an orbit also in its pixels, so these rules cannot\nmove it: when the scene differs from the reference in size or timing, track that object again as\nkeyframes, or place it at the reference's size and time inside a composition sized like the\nreference.\n\n## Checking a render against the reference\n\nExport your render over the fragment and track it with **the same box** as the reference: the same\npart of the object, the same size against it, at the same moment of the move, with the same `mode`\nand `estimator`. The tracker reports the centre of the box you drew, so another box is another\npoint, and a card tracked by its face against one tracked by its corner reads 150 px apart while\nboth move alike.\n\nThen measure the deviation with the starting offset removed:\n\n```\npython3 scripts/fit_motion.py diff ref-track.json our-track.json --offset <ref second 0 minus ours>\n```\n\nBoth tracks are read at every sample time of either, over the time both cover. For each channel that changes on either side from the first shared sample (a slow pan too), it gives:\n- `startOffset` and `placement`: where ours sits at the first shared sample against the reference;\n- `maxDev`: the raw deviation;\n- `moveDev`: the deviation once the starting offset is removed, which is the move itself.\n\nThe move passes on `moveDev`, within the threshold the use case sets. The placement is the layout:\nreport it, and fix it when the layout should match. `picsart_media_track_motion_diff` gives the raw\n`maxDev`, `meanDev` and `worstT` for the same pair. A number replaces \"it looks about right\".\n\n**Then check the feel.** A linear move can pass the position check against one that eases. Compare\nthe two speed profiles:\n\n```\npython3 scripts/fit_motion.py compare ref-track.json our-track.json --offset <ref second 0 minus ours>\n```\n\nPer move it checks the start, the duration, where the peak speed comes (not when both moves are\nlinear: a linear move has no peak) and how big it is, the overshoot, the swings and the curve's\nname, and says which differ. `speed` writes each target's\nspeed over time as CSV, to show the two side by side. Fix the measured differences and check\nagain while each correction makes progress. If the evidence or a tool limit prevents a match,\nreport the remaining difference with its numbers and cause. ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) whether to accept that\napproximation or change the approach; never label it a pass.\n\n- **Like for like.** The same targets, the same boxes, the same window, the same tolerance and the\n  same `--min-confidence` on both sides. Your\n  render tracked from its own second 0 against the reference from its second 4 is a 4 s offset, not\n  a mismatch.\n- **What the deviation says.** A constant offset is geometry: a position or a size. A deviation\n  that grows and shrinks along a move is easing. One that peaks at a beat's start or end is timing.\n\n## Measuring for a seam\n\nWhen a seam decision depends on a reference's velocity, path or overlap, the measurement feeds\n`motion-scene-continuity` (fetch with `picsart_scene_recipe`). Tracking answers what moved, where\nand when; continuity judges what that movement communicates and whether the scene should preserve,\nreplace, interrupt or reset it. A close numeric fit does not by itself prove a readable handoff.\n"
Full snapshot data
{
  "description": "Measure what objects visibly do in a video - where each one moves, turns and grows, frame by frame - with picsart_media_track_motion, work out each move's easing (curve, overshoot, bounce) and turn it into scene keyframes; then measure your render the same way and compare them with picsart_media_track_motion_diff. Covers targets, estimators, tolerances, reading results, and placing tracked motion on a layer. Use when a scene must reproduce a reference video's motion, or a render's motion must be checked against one.",
  "included_files": [
    {
      "relative_path": "scripts/fit_motion.py",
      "size_in_bytes": 43817
    }
  ],
  "name": "motion-tracking-from-video",
  "skill_md_contents": "---\nname: motion-tracking-from-video\ndescription: Measure what objects visibly do in a video - where each one moves, turns and grows, frame by frame - with picsart_media_track_motion, work out each move's easing (curve, overshoot, bounce) and turn it into scene keyframes; then measure your render the same way and compare them with picsart_media_track_motion_diff. Covers targets, estimators, tolerances, reading results, and placing tracked motion on a layer. Use when a scene must reproduce a reference video's motion, or a render's motion must be checked against one.\nmetadata:\n  ported-from: motion-extraction unversioned at 55.75.0\n---\n\n# Motion extraction\n\n`picsart_media_track_motion` recovers what objects **visibly do** in a flattened video: their\nposition, rotation and scale on every frame, fitted into scene keyframes. It does not recover the\nkeyframes someone authored. It produces new motion data that reproduces what is on screen.\n\nLooking decides **what** to track. The tracker measures **where**, every frame, to a fraction of a\npixel. Never write a motion's numbers from a still or from memory: every timing and distance comes\nfrom a tracking result. The end points are not enough: a move is matched when it **feels** the\nsame, so its easing (how it speeds up, slows down, overshoots and settles) is measured too, and\nbuilt from the numbers.\n\n## Cost and receipts\n\nMeasure every required window with `picsart_media_track_motion` and\n`picsart_media_track_motion_diff`, applying picsart-video-rules's SPEND rule to their billing\ncontracts. Each replies with a job receipt by default: follow it as picsart-video-rules says. Targets that share a tracking window go in one call, as many as\nits `targets` schema allows: one `t0`/`t1` holds for every target, and each must be fully visible at\n`t0`. A target that enters later, or is covered before `t1`, gets a call with its own window.\n\n## The method\n\n1. **Look at the first frame of the window** with `picsart_media_video_stills`, and choose what to\n   track. On a flat background, `{ \"auto\": true, \"max\": 9 }` finds the distinct objects at `t0` and\n   tracks each, ranked by how much they move. Objects that overlap merge into one, so give those a\n   box each instead.\n2. **Track.** `picsart_media_track_motion` with the video's `source`, the window `t0`/`t1` in video\n   seconds, and `targets`: each one `bbox` (`[x, y, w, h]` at `t0`, in video pixels), `points`, or\n   `auto`. Set `tolerance` for the source (below). For a card, photo or title, a `bbox` in\n   `\"mode\": \"similarity\"` (position, scale and rotation); `\"corners\"` when it skews or tilts in 3D.\n   Leave `fps` out, so it samples at the video's own rate, and run the window over the whole move:\n   from the frame before it starts to the frame after it settles, so the easing and the settle are\n   in the samples.\n3. **Read the result before you trust it.** Per target it returns `animations` (the fitted\n   keyframes with their easing, or an expression), `static` (the channels that did not move), `meta` with each\n   channel's `maxError`, and `notes` on anything that weakened the track. `maxError` is the honest\n   reconstruction error: a fit with a large one is an approximation, and you say so.\n4. **Work out the easing** of each move from the dense samples (below).\n5. **Place it on a layer** (below), as keyframes with `timeMode: \"layer\"`.\n6. **Check it.** Export your render of the same window, track it with the same targets, and compare\n   the two with `picsart_media_track_motion_diff` and their speed profiles (below).\n\n## What the tracker cannot see\n\nIt measures where texture goes, frame to frame. Some changes have no texture to follow:\n\n| Change | What to do instead |\n|---|---|\n| a reveal: a wipe, a mask growing | cropped stills of the box, one per frame of the reveal, for its edge; track whatever drives the reveal |\n| a fade or a twinkle | stills either side and through it; the tracker has no alpha (below) |\n| non-rigid motion: a flap, a bend, a wobble | track the centre only, and build the shape change as a loop |\n| a small idle loop: bobbing, swaying, breathing | track over several cycles, at least one and a half: a sway in rotation comes back as a `sine` expression; build any other loop from the cycles you measured |\n| motion blur on a fast move | track it again with `\"estimator\": \"segmentation\"`, whose centre stays on the smear, and read it with `fit_motion.py --min-confidence 0.2`; check the smeared positions against cropped stills, one a frame. Each move says how many of its samples were smeared (`blurred`) |\n\n## Illustrated templates\n\nStickers, doodles and cut-out shapes over a photo or a flat background:\n\n- **A sticker with a white border tracks best with `\"estimator\": \"segmentation\"`**: the border is a\n  clean silhouette, where its flat fill gives features little to hold.\n\n## Tolerance, per channel and per unit\n\n`tolerance` is position in **pixels**, `toleranceScale` a **ratio** (default 0.01) and\n`toleranceRotation` **degrees** (default 0.5). Never reuse a pixel tolerance for scale: 1.5\n\"pixels\" once declared a 57% shrink static.\n\n| Source | `tolerance` |\n|---|---|\n| a compressed reference video | about 1.5 (it measures to about 0.5–2 px) |\n| your own render | 0.5 or less |\n\nToo tight on a compressed source and the keyframes chase codec noise.\n\n## Choosing targets\n\n- **Start where the object is solid.** During a fade-in its features are weak, the track dies on\n  the first frame and freezes. Start `t0` once it is fully opaque.\n- **A tight box inside the object's face.** A box over a tilted card in a stack catches its\n  neighbours, and the fit mixes two motions.\n- **Opaque objects only, for rotation and scale.** A half-transparent object blends with whatever\n  moves behind it, and its measured pose drifts toward that. Ghosts, depth-faded cards and\n  translucent chrome give approximate motion at best; say so.\n- **Video playing inside the box**: the features follow the content, not the box. Set `\"estimator\":\n  \"segmentation\"` on that target, which tracks the silhouette. Its centre leans toward bright\n  content, so a still element of the same group, tracked instead, is more exact.\n- **A rotating object takes a box, never points.** A point tracks translation only: a corner\n  turning in place reads about 4 px wrong at 30°. A box in `similarity` mode compensates.\n- **End the window before the object is covered.** When it slides behind something, its confidence\n  falls and its pose freezes. Shorten `t1` and track again, rather than keep the frozen tail.\n- **Coming in from off screen**: while the object is clipped by the frame edge, a box around it is\n  biased. Start at its first visible frame with a box on the textured part already in view (a\n  photo's face, not its edge), with `\"estimator\": \"features\"`, so the fit follows the content, not\n  the clipped outline. `fit_motion.py` then marks the move `startsBeforeWindow`: build the entrance\n  from off screen so it crosses the edge at the measured speed.\n- **Clip the window, not the keyframes.** A fit over frozen samples emits false keyframes at the\n  tail. Track again with an earlier `t1`; never prune the keyframes by hand.\n- **A track that is covered, then reacquired.** After the confidence collapses, the later samples can\n  be a valid track of the object that replaced it (a card becoming a chip). Check them against a\n  still before discarding them.\n- **One object, two stretches that need different estimators** (a video inside a card, then siblings\n  touching it): track each stretch on its own, with one overlapping frame. The two estimators'\n  reference points differ by about 2 px: measure that offset on the overlap frame and subtract it\n  when you join them, and multiply the second stretch's scale by the overlap frame's scale.\n\n| Content | `mode` | `estimator` |\n|---|---|---|\n| textured (a photo, a UI card with text) | `similarity` | `features` |\n| flat or solid, or video inside the box | `similarity` | `segmentation` |\n| stretched in perspective | `corners` | `features` |\n| position alone matters | `center` | either |\n\n## Reading the result\n\n- **Position is the object's centre**, in the video's own pixels. Under a layer's default anchor\n  (the centre of its box, for every content kind but text), that is the layer's\n  `transform.position`. Text anchors at its origin: place it by its alignment instead.\n- **Rotation and scale are relative to `t0`**: 0° and 1.0 there. The tracker cannot know an\n  object's tilt at `t0` from one box: add the pose the layer starts at yourself.\n- **Rotation is counter-clockwise positive; a scene's rotation is clockwise.** A turn the tracker\n  reports as +12° is `-12` in the scene. Flip the sign of every rotation value you place.\n- **Scale comes as `[s, s]`**, because a scene's scale is 2-D.\n- **Keyframe times count from `t0`** unless the call set `normalizeTime: \"absolute\"`.\n- **Easing is a preset or a fitted curve**, chosen per segment. The closest of the four presets\n  (`linear`, `ease_in`, `ease_out`, `ease_in_out`) comes first. When none of them fits within\n  `tolerance`, the segment moves and it has enough samples, it gets a fitted curve instead:\n  `{\"kind\": \"cubic_bezier\", \"control\": [x1, y1, x2, y2]}`, the scene's own parametric easing, with\n  a y outside 0–1 for an overshoot. Copy either form into the keyframe as it came. A short segment\n  keeps its closest preset, so a sharp snap or a long settle there reads close, not exact: its\n  `maxError` says how close; track it denser to give it a curve.\n- **An expression** instead of keyframes means the channel fit one within tolerance: `orbit` (the\n  path is a circle) or `sine` (a rotation that sways back and forth, `meta`'s `kind` says which). On\n  a compressed reference real paths often are not pure circles, and the keyframes it falls back to\n  are the honest answer, not a failure.\n- **The tracker has no alpha.** It cannot tell a fade from a move. Judge a fade on stills either side\n  of it, and never invent one to cover a jump in pose.\n\n## The feel of each move: easing\n\nThe fitted `animations` give each segment's easing, and the report at `resultUrl` holds every\nsample (`t`, `x`, `y`, `rotation`, `scale`, `confidence`). Save that report (as a file, where you\nrun commands) and read each move's timing curve from it:\n\n```\npython3 scripts/fit_motion.py moves track.json [--target card1] [--into sheet.json]\n```\n\nPer move, on each channel that moves, it gives:\n- the target, the channel, `from` and `to`;\n- `delay` (from the window's start) and `at` (source seconds), then `duration`, up to the frame it\n  settles, and `hold`, how long it rests after;\n- `curve`: `linear`, `ease_in`, `ease_out`, `ease_in_out`, or `spring` when it overshoots and\n  swings back, named from where its peak speed comes (`peakAt`, 0 to 1) and how far above the mean\n  speed it is;\n- `cubicBezier`, the curve fitted to the samples (a y outside 0–1 is an overshoot), and `preset`\n  when one of the scene's four presets fits about as well;\n- `overshoot`, how far past the rest it goes as a share of the travel, `swings`, how many times it\n  crosses its rest before it settles, and for a spring its stiffness and damping (mass 1);\n- `peakSpeed` and `meanSpeed`, and `staggerAfter`: how long after the previous target's move it\n  starts;\n- `keyframes` the scene can take as they are: one curve, or for a spring each swing as its own\n  segment, since one cubic-bezier holds only one overshoot.\n\nA move out and back, or one that bounces back and forth, comes back as one move per leg; a spring's swings about its rest, each smaller than the last, stay one move however lightly damped. Where it rests is measured from the frames that hold still after it; only when the track ends while it still moves is the rest worked out from its swings. A rotation that crosses ±180° is read as the short turn it is. A slow move\nis kept: its start is the last frame within the tolerance of the rest before it. `--into` replaces\nevery target and channel it measured, so a channel measured still again loses its old move. Track each window of one object under its own target id (`card1_in`, `card1_out`): moves of the\nsame id and channel from another report are replaced.\n\nUse the tracker's own fitted keyframes and easings where the scene takes them (a preset or a\n`cubic_bezier`); take `fit_motion.py`'s keyframes only where it does not, such as a spring with\nmore than one swing. Either way, the numbers that describe the move come from `fit_motion.py`.\nA move it marks `startsBeforeWindow`, or not `settled`, was tracked over too short a window:\nwiden it and track again.\n\n**Record each move** where the use case keeps the spec: target, channel, from → to, duration,\ndelay, curve, overshoot, and the tracking result it came from. Never words alone (\"slides in\").\n\n**Known limits of splitting moves.** Samples alone cannot tell these apart; `fit_motion.py`\nreads them as below, and its tests pin it. Look at the stills when one matters.\n- A trip whose swings shrink like a spring's, with the track ending before it holds still\n  (0→100→30→80, still moving at the end), reads as one spring. Keep a still second after the\n  motion in the tracked window, and the measured rest splits it.\n- One turn back by less than the travel, then still (0→100→60), reads as one move with an\n  overshoot (67 % here), as an ease with a big overshoot would. A turn back past that (0→100→40)\n  is two moves.\n- A spring that freezes mid-swing and holds there rests where it froze: it may come back as more\n  than one move, and the last one ends where it froze.\n- A window that opens on the frame the spring is released, with the track ending after two\n  turns (still moving), cannot show the spring started from rest: it reads as up to three\n  ease moves. Start the window a few still frames before the release, or track it until it\n  settles, and it is one spring.\n\n## Creating similar motion\n\n- **Build each move from its numbers**: its from and to, its duration, its curve (the preset, the\n  fitted `cubic_bezier`, or the spring's keyframes) and its overshoot.\n- **Keep the order and the stagger.** The moves start in the reference's order, each `staggerAfter`\n  the one before it, scaled to the scene's time like every keyframe.\n- **Match a text animation by its mechanism**, not only its timing: a wipe, letters one by one, a\n  line rising, or a mask reveal that follows a moving object (a sticker that wipes the title in as\n  it passes). Read the mechanism from cropped stills of the reveal, one per frame, and track the\n  object that leads it; then build the same mechanism, with the measured timing.\n\n## Placing tracked motion on a layer\n\nThe result is in the reference's frame and time. A layer needs its own:\n\n- **Time.** A keyframe's layer time is its tracked time, plus `t0` when times count from `t0`, plus\n  the scene second where the reference's second 0 plays, minus the layer's `start`.\n- **Pixels.** When the scene is not the reference's size, multiply each position by the scene's size\n  over the reference's (the same factor on both axes) and add the offset of where the reference's\n  frame sits in the scene.\n- **Pose.** Rotation: the layer's starting rotation minus the tracked value. Scale: the layer's\n  starting scale times the tracked value.\n- **Easing**: keep each keyframe's easing where it is; it shapes the segment that starts at it.\n\nAn expression is in the reference's time, and an orbit also in its pixels, so these rules cannot\nmove it: when the scene differs from the reference in size or timing, track that object again as\nkeyframes, or place it at the reference's size and time inside a composition sized like the\nreference.\n\n## Checking a render against the reference\n\nExport your render over the fragment and track it with **the same box** as the reference: the same\npart of the object, the same size against it, at the same moment of the move, with the same `mode`\nand `estimator`. The tracker reports the centre of the box you drew, so another box is another\npoint, and a card tracked by its face against one tracked by its corner reads 150 px apart while\nboth move alike.\n\nThen measure the deviation with the starting offset removed:\n\n```\npython3 scripts/fit_motion.py diff ref-track.json our-track.json --offset <ref second 0 minus ours>\n```\n\nBoth tracks are read at every sample time of either, over the time both cover. For each channel that changes on either side from the first shared sample (a slow pan too), it gives:\n- `startOffset` and `placement`: where ours sits at the first shared sample against the reference;\n- `maxDev`: the raw deviation;\n- `moveDev`: the deviation once the starting offset is removed, which is the move itself.\n\nThe move passes on `moveDev`, within the threshold the use case sets. The placement is the layout:\nreport it, and fix it when the layout should match. `picsart_media_track_motion_diff` gives the raw\n`maxDev`, `meanDev` and `worstT` for the same pair. A number replaces \"it looks about right\".\n\n**Then check the feel.** A linear move can pass the position check against one that eases. Compare\nthe two speed profiles:\n\n```\npython3 scripts/fit_motion.py compare ref-track.json our-track.json --offset <ref second 0 minus ours>\n```\n\nPer move it checks the start, the duration, where the peak speed comes (not when both moves are\nlinear: a linear move has no peak) and how big it is, the overshoot, the swings and the curve's\nname, and says which differ. `speed` writes each target's\nspeed over time as CSV, to show the two side by side. Fix the measured differences and check\nagain while each correction makes progress. If the evidence or a tool limit prevents a match,\nreport the remaining difference with its numbers and cause. ASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) whether to accept that\napproximation or change the approach; never label it a pass.\n\n- **Like for like.** The same targets, the same boxes, the same window, the same tolerance and the\n  same `--min-confidence` on both sides. Your\n  render tracked from its own second 0 against the reference from its second 4 is a 4 s offset, not\n  a mismatch.\n- **What the deviation says.** A constant offset is geometry: a position or a size. A deviation\n  that grows and shrinks along a move is easing. One that peaks at a beat's start or end is timing.\n\n## Measuring for a seam\n\nWhen a seam decision depends on a reference's velocity, path or overlap, the measurement feeds\n`motion-scene-continuity` (fetch with `picsart_scene_recipe`). Tracking answers what moved, where\nand when; continuity judges what that movement communicates and whether the scene should preserve,\nreplace, interrupt or reset it. A close numeric fit does not by itself prove a readable handoff.\n"
}

SHA-256 of public snapshot: 898907830a41809d8b9d0c72d8052c3cd5d9806d392a2437f1fcf550b0d11faf