rinkplanner/docs/rotoscoping.md
torsten ec3336550d feat: Video-Werkzeuge ins Repo (tools/video)
Die beiden allgemeinen Schnitt-Skripte lagen nur in der Werkbank und waren
damit nicht auf dem Mac verfügbar:

- `tools/video/cut_video.py` — exakter Schnitt aus einer MP4 (ffmpeg).
- `tools/video/downsample.py` — Bildrate reduzieren, auf 1920x1280 skalieren.
- `tools/video/README.md` — Kurzanleitung: Voraussetzungen, Ablauf vom
  Sichten bis zur Übergabe an Blender, Merksätze.

Die Analyse-Helfer `scan_takes.py` und `window_scan.py` bleiben in der
Werkbank: Sie enthalten feste Pfade und Zeitfenster der jeweiligen Aufnahme
(YOLO-Gewichte) und taugen nur für diese Sitzung.

In der Werkbank verweisen die beiden Skripte jetzt per Symlink hierher, damit
es keine zweite Fassung gibt. `docs/rotoscoping.md` nennt den neuen Ort.
2026-11-13 16:37:48 +01:00

6.4 KiB
Raw Blame History

Rotoscoping-Workflow

Stand: 2026-10-31

Die Rotoscoping-Werkbank liegt in Blender, nicht in Godot. Godot konsumiert nur die exportierten GLB-Clips. Videomaterial und Arbeitsdateien bleiben im Workbench-Archiv; das Repo enthält die Skripte und die Dokumentation.

Voraussetzungen

  • Blender 5.2 mit AutoRigPro (für die Control-Rig-Bones).
  • Das Produktions-Rig: workbench/source/characters/skater/skater_rig_v008.blend (Rig der jeweils aktiven Figur, siehe docs/assets.md).
  • ffmpeg zum Sichten und Schneiden der Referenzclips (siehe tools/video/README.md).
  • Für den FTP-Upload: docs/credentials.txt wie beim Asset-Sync.

Der Default ist nur die Quelldatei für neue Arbeitsdateien. Das eigentliche Rotoscoping (Posen setzen, keyframen) bleibt manuell. Eine bereits vorhandene rotoscope_work.blend wird nicht automatisch auf ein neues Rig migriert.

Einmal einrichten

./tools/rotoscope.sh setup
./tools/rotoscope.sh open

setup legt an:

workbench/source/characters/skater/rotoscope/
├── rotoscope_work.blend       # Arbeitsdatei (nicht überschreiben)
└── references/                # Videos und Standbilder

setup überschreibt eine vorhandene Arbeitsdatei nur mit --force. --force löscht den Arbeitsstand; für ein neues Video in derselben Datei ./tools/rotoscope.sh reference <pfad> verwenden.

Die Arbeitsdatei enthält:

  • RotoscopeCamera mit CameraTarget (Track-To-Constraint),
  • RinkGuide: 60 × 30 m Rink als Drahtgitter, Mittellinie, Mittelkreis, 5-m-Raster und 2-m-Höhenachse am Ursprung,
  • das Skater-Rig und Modell, Pose auf Ruhezustand zurückgesetzt,
  • die vorhandene Glide-Aktion als Fake-User (bleibt exportierbar).

Die Kamera steht standardmäßig auf einer ganzen-Rink-Ansicht (28 mm, 55 m entfernt). Für eine Nahaufnahme die Kamera näher an den Skater schieben; das CameraTarget bleibt der Blickpunkt.

Referenz vorbereiten

Lange Aufnahmen werden vor dem Rotoscoping geschnitten und verkleinert. Die beiden Skripte dafür liegen in tools/video/, die Kurzanleitung daneben:

tools/video/cut_video.py DJI_0002.MP4 0:16 0:32
tools/video/downsample.py DJI_0002__cutted_16_32.mp4 24

Ein Clip zeigt eine Bewegung; 1920 × 1280 bei 24 fps reichen für die Blender-Vorschau. Die Suche nach dem passenden Zeitfenster (Kontaktabzüge, Figurengröße je Take) übernehmen scan_takes.py und window_scan.py aus der Werkbank.

Referenz laden

./tools/rotoscope.sh reference /pfad/zum/video.mp4

Unterstützt werden Videos (.mp4, .mov, .avi, .mkv, .webm) und Standbilder (.png, .jpg, .exr, .tif). Das Video erscheint als Kamera-Hintergrund (nur in der Kameraansicht, nicht im finalen Render). Bildrate und Frame-Bereich werden aus dem Video übernommen.

In Blender:

  1. Numpad 0 – Kameraansicht.
  2. Rink-Guide an den Banden des Videos ausrichten (Kamera verschieben, drehen, Brennweite ändern).
  3. Bei einer Nahaufnahme den Rink-Guide ausblenden und den Skater im Bild zentrieren.

Die Kamera bleibt während eines Clips fest. Für eine bewegte Kamera muss die Kamera in Blender manuell getrackt werden (Movie Clip Editor, Motion Tracking); die Werkbank automatisiert das bewusst nicht.

Clips animieren

Im Action Editor eine neue Aktion anlegen und mit den ARP-Controls poseweise keyframen. Empfohlene Namen:

Glide, Forward, Backward,
CrossoverL, CrossoverR,
ThreeTurnL, ThreeTurnR,
Spin, Jump, Landing

Konventionen:

  • In-Place: Keine Translation des Root-Controls. Die Fortbewegung kommt in Godot aus der Kür-Kurve. Ein Clip beschreibt nur die Körperbewegung.
  • Loop: Bei zyklischen Clips (Glide, Forward, Backward) sind erster und letzter Frame identisch.
  • Framerate: 24 fps, wie die bestehenden Clips.
  • Fake User: Jede Aktion mit use_fake_user sichern, damit sie beim Schließen der Datei nicht verloren geht und exportiert wird.
  • Nicht löschen: Die Glide-Aktion bleibt als Basis im Export.

Der referenzierte Skater im Video und das Rig müssen nicht deckungsgleich sein; wichtig ist die Pose, nicht die absolute Position im Rink.

Exportieren

./tools/rotoscope.sh export --out /tmp/meine_clips.glb

Der Export:

  • schreibt eine GLB mit allen Aktionen,
  • backt die Constraints,
  • exportiert nur die 30 Deform-Bones,
  • schreibt eine JSON-Metadatendatei neben die GLB (Clipnamen, Dauer, SHA-256, Quelle).

In das Projekt übernehmen

./tools/rotoscope.sh promote --version 4

promote exportiert nach

workbench/library/characters/skater_figure_clips_v004.glb

aktualisiert rinkplanner/assets/asset_manifest.json (Version, Quelle, Ziel, FTP-Pfad, Hash, Clips), kopiert die Datei nach assets/external/ und stößt den Godot-Import an. Mit --publish wird sie zusätzlich auf den FTP-Spiegel geladen.

./tools/rotoscope.sh promote --version 4 --publish

Vor dem Schreiben des Manifests prüfen:

./tools/rotoscope.sh promote --version 4 --dry-run

Godot

Die 3D-Vorschau lädt die GLB über die Manifest-ID character.skater.figure_tripo_glide. Derzeit spielt sie den Clip Glide. Weitere Clips stehen nach dem Import im AnimationPlayer zur Verfügung; die Zuordnung Element → Clip (z. B. Spin bei einer Pirouette) ist der nächste Schritt.

Synthetischer Testfilm

Ohne eigenes Videomaterial lässt sich die Pipeline vollständig prüfen:

./tools/rotoscope.sh test-reference
./tools/rotoscope.sh setup \
  --reference "$HOME/Dokumente/workbench_rinkplanner/source/characters/skater/rotoscope/references/test_reference.mp4" \
  --out /tmp/rotoscope_test.blend --force

Der Testfilm ist 8 s lang, 1280 × 720, 24 fps und enthält einen bewegten Punkt. Nach dem Setup:

  • Frame-Bereich 1–192,
  • Kamera-Hintergrund MOVIE_CLIP,
  • Rink-Guide sichtbar,
  • Rig in Ruhepose.

Export-Test:

./tools/rotoscope.sh export --out /tmp/rotoscope_test.glb

Erwartet: GLB mit den vorhandenen Aktionen (mindestens Glide) und eine JSON-Metadatendatei daneben.

Grenzen

  • Die Kamera wird manuell ausgerichtet; es gibt keinen automatischen Kamera-Solve.
  • AutoRigPro und die Gewichtung sind bereits erledigt; die Werkbank automatisiert keine neuen Meshes.
  • Der Export enthält alle Aktionen der Arbeitsdatei. Nicht gewünschte Aktionen vorher löschen oder ohne Fake User ablegen.
  • Root-Motion-Clips sind möglich, aber die Godot-Vorschau erwartet In-Place-Clips.
  • Das Referenzvideo wird nicht versioniert und nicht in die GLB gebacken.