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

205 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```bash
./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:
```bash
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
```bash
./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
```bash
./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
```bash
./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.
```bash
./tools/rotoscope.sh promote --version 4 --publish
```
Vor dem Schreiben des Manifests prüfen:
```bash
./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:
```bash
./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:
```bash
./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.