rotoscope
Drawing-by-drawing copy of a reference animation clip: decode it into distinct drawings, trace each to vector paths, render them through the ink.js brush engine, measure each against its source, and fit brush overrides until every drawing passes. Use when: 'rotoscope this', 'trace this clip', 'copy this animation one to one', 'replicate this video exactly', 'match the reference frame by frame', 'measure the replica against the source'. Not for an original film or a style study without a reference clip.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 30
- Forks
- 7
01 前言 Front Matter
- metadata
- { "summary": "Trace, render, measure and fit a 1:1 replica of a reference animation", "workflow-stage": "implement" }
- description
- Drawing-by-drawing copy of a reference animation clip: decode it into distinct drawings, trace each to vector paths, render them through the ink.js brush engine, measure each against its source, and fit brush overrides until every drawing passes. Use when: 'rotoscope this', 'trace this clip', 'copy this animation one to one', 'replicate this video exactly', 'match the reference frame by frame', 'measure the replica against the source'. Not for an original film or a style study without a reference clip.
- argument-hint
- <reference video> <work dir>
- user-invocable
- true
- disable-model-invocation
- false
02 资源文件 11
- 参考文档fixtures/shfred0.overrides.json1.4 KB
- 脚本fixtures/synthetic.js1.4 KB
- 参考文档reference/method.md7.1 KB
- 脚本scripts/brush.json40 B
- 脚本scripts/extract.py9.8 KB
- 脚本scripts/fit.py5.1 KB
- 脚本scripts/measure.py7.5 KB
- 脚本scripts/regress.py8.7 KB
- 脚本scripts/review.py5.3 KB
- 脚本scripts/roto.js4.9 KB
- 脚本scripts/test_regress.py1.2 KB
03 SKILL.md 正文
Rotoscope
Produce a measured 1:1 replica of a reference clip whose pixels come from traced paths and brush
parameters only. Never replay or embed source bitmaps. Read
reference/method.md first: the defaults, why they hold, and the
diagnostics in the order to read them.
Run every script as python3 ${CLAUDE_PLUGIN_ROOT}/scripts/pydeps.py run --data-dir "${CLAUDE_PLUGIN_DATA}" -- <script> ...; it never installs a package, and a missing tool or
package stops it with exit 2 and one remedy line (/animation:setup checks them all). Below, $R
stands for ${CLAUDE_PLUGIN_ROOT}/skills/rotoscope/scripts/.
Work directory
One work directory per reference clip, outside the plugin; it grows to hundreds of MB.
| Path | Written by | Holds |
|---|---|---|
src/dNNN.png, d/index.json |
extract.py --video |
distinct drawings; size, duration, [k, pts, t1] |
d/dNNN.json |
extract.py |
T-layer paths with holes, tone layers, colors, applied overrides |
overrides.json |
you, fit.py |
per-drawing parameters (below); survives re-extraction |
out/<tag>/ |
measure.py, review.py |
replicas, heatmaps, table-*.md, review-*.md, crops/ |
learnings.md |
measure.py, you |
one line per run, plus your findings |
Override file
Tool-neutral JSON that carries every hand decision. Entries apply in file order to each drawing
whose k (an index or [k0, k1]) holds it; later entries win, and brush merges key by key.
{"overrides": [
{"k": [0, 30], "brush": {"bias": 0.18, "blur": 0.7}, "why": "sparse line art, replica too thin"},
{"k": [203, 217], "sharp": [2.0, 0.6], "levels": [40, 80, 170, 215]},
{"k": [64, 74], "tint": true}
]}
brush keys: bias, blur, grain, tones (see roto.js). sharp is the unsharp mask
[amount, sigma] or null; levels are the tone gray levels; both retrace. tint adds
warm-paper layers. why is for the reader; the tools ignore it. Geometry never goes in this file:
a fix that needs hand-edited paths is a finding to report, not an override.
Loop
- Extract:
$R/extract.py <work> --video <clip>. After an override change,$R/extract.py <work> --applyretraces only drawings whosesharporlevelschanged. - Measure:
$R/measure.py <work> [--only K0-K1] [--tag name] --playwright-core '${user_config.playwright_core}'. It exits 0 only when every drawing meets themeasure.pytarget (reference/method.md, Target). Run long ranges in the background. - Fit:
$R/fit.py <work> [--only K0-K1] --playwright-core '${user_config.playwright_core}'bisectsbiasper drawing from the replica-only / source-only balance and appends the result tooverrides.json; apply it with--apply. It fits bias only: blur, sharpening and tone levels are yours, guided by the diagnostics inmethod.md. On shfred0, fitting every drawing from the default bias passes them all at a mean XOR 0.3% below the hand fits. - Review:
$R/review.py <work> <tag>adds the manual checks as columns (largest one-color cluster and whether it is a blob, frame-edge XOR, tone-tile difference, paper color) and writes one 1:1 crop per drawing of its hottest window. Read every crop, not only the flagged ones: a passing number can hide a visible defect such as a tint. Never downscale a crop or review a GIF. - Record: append to
<work>/learnings.mdwhat failed, the cause, the change and the before and after numbers.
Repeat 2-5 by shot or drawing range until the table passes and the crops show no one-color cluster.
A film of the replica: ${CLAUDE_PLUGIN_ROOT}/scripts/render.py $R/roto.js <frames dir> --fps <the source's frame rate> --root <work> --encode mp4 --playwright-core '${user_config.playwright_core}'
writes the frames, render.json and <frames dir>.mp4 beside them.
Retro
At the end of a clip, read learnings.md next to earlier runs' learnings. A finding that recurs
across shots or clips with the same fix (the same override on most drawings, the same diagnostic
leading to the same change) becomes a default: change the constant in extract.py or
roto.js, re-run the regression, and record the finding with its numbers in method.md. A one-off
stays in the clip's override file.
Regression
The shfred0 study ships as a fixture (fixtures/shfred0.overrides.json, parameters only; the clip
is not shipped). Given that clip and an empty work directory, $R/regress.py <shfred0.mp4> <work>
extracts with the fixture, renders and measures every drawing, checks the encoded replica against
the woodcut-ink pack, and exits 0 only when every drawing and the replica pass.
$R/regress.py --synthetic <work> needs no clip: it renders, encodes and re-traces
fixtures/synthetic.js and checks the render, encode and decode contracts. Run both after any
change to the scripts.
Next
/animation:learn-style <work dir> <pack dir>
It measures this work directory's traces and drawings into a style pack.
Gotchas
renderFrame(t)andrenderDrawing(k)return Promises; a capture that does not await them saves the canvas before the drawing lands.- Chromium's canvas
blur()filter does nothing below a floor (reference/method.md, Rendering, holds the dated record), soroto.jsblurs in JS;gauss()must not add 0.5 before writing to aUint8ClampedArray, which already rounds. - A drawing JSON is one line of 1-4 MB. Change parameters through the override file and
--apply, never by editing the JSON. - Gray XOR and SSIM cannot see color. Read
paper_errand the crops for tints. - An all-ink or all-paper frame has a floor near 0.02%; a few hundred border pixels decide it, so judge it by the ratio and the edge column, not by the XOR alone.
04 同仓库更多 Skills
track
Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.
reviewer-media
Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from /review:explain-change's digest, has /explainer-video:produce render it and hands the manifest to /source-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
route
Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.
principles
Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is /architecture:improve.
write
Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').