feat: Rotoscoping-Werkbank ohne vorhandenes Videomaterial

- Blender-Setup mit Kamera, Rink-Guide und Video-Referenz
- CLI fuer setup/reference/open/export/promote/test-reference
- Multi-Clip-GLB-Export und Manifest-Uebernahme inkl. FTP-Option
- synthetischer Testfilm validiert Szene, Export und Promote
- Doku, Architektur (D15) und Roadmap aktualisiert
This commit is contained in:
torsten 2026-10-31 13:02:46 +01:00
parent 723e1bc84a
commit 7f35162966
10 changed files with 1091 additions and 3 deletions

View file

@ -3,8 +3,8 @@
Stand: 2026-10-31
Grundlage: `rinkplanner/rinkplanner_definition_agent_guidelines.md`
Übergeordnete Reihenfolge: `docs/roadmap.md`
Letzte Session: `docs/findings-2026-10-31-3d-vorschau.md`
(Session davor: `docs/findings-2026-10-31-asset-ftp.md`)
Letzte Session: `docs/findings-2026-10-31-rotoscoping.md`
(Session davor: `docs/findings-2026-10-31-3d-vorschau.md`)
## 1. Leitentscheidung
@ -23,6 +23,7 @@ wird nicht weiterentwickelt. Phase 2 konsumiert später dasselbe Datenmodell
/home/torsten/repos/rinkplanner/ # Repo-Root
├── docs/ # Architektur, ADRs, Regelwerk-Doku
├── tools/ # Host-Helfer (Tests, Export, CI)
│ └── blender/ # Rotoscoping-Werkbank
└── rinkplanner/ # Godot-Projekt (res://)
├── project.godot
├── src/
@ -201,6 +202,16 @@ wird ein Platzhalter gebaut. Der Modus ist bewusst kein Editor: Auswahl,
Zeichnen und Elementdialoge bleiben in 2D. Die Kamera folgt dem Skater oder
zeigt eine Übersicht; der Wechsel läuft über den Button „Kamera".
**D15 – Rotoscoping bleibt in Blender; Godot konsumiert nur GLB-Clips.**
Die Werkbank unter `tools/blender/` erzeugt aus dem Produktions-Rig eine
vorbereitete Blender-Szene mit Kamera, Rink-Guide und Referenzvideo,
exportiert alle Aktionen als GLB und übernimmt sie per
`tools/rotoscope.sh promote` in das Asset-Manifest. Clips sind **in-place**:
Die Fortbewegung kommt aus der Kür-Kurve, nicht aus Root-Motion. Video- und
Arbeitsdateien bleiben im Workbench-Archiv. Godot kennt nur die GLB und die
Clipnamen; die Zuordnung Element → Clip ist ein späterer Schritt. Details:
`docs/rotoscoping.md`.
## 4. View- und Controller-Grenzen
- **View** (`Node2D`/`Control`) liest das Modell und zeichnet. Sie verändert
@ -476,6 +487,10 @@ Aktueller Stand:
- **3D-Vorschau:** 44 Assertions für Koordinatenabbildung, Rink-Geometrie,
Kamera-Modi, Platzhalter-Fallback und den 2D/3D-Moduswechsel samt
geteilter Playback-Position.
- **Blender-Werkbank:** Rotoscoping wird separat geprüft
(`tools/rotoscope.sh test-reference` → `setup` → `export` → `promote
--dry-run`), nicht in `./tools/test.sh`, weil Blender und ffmpeg
Host-Abhängigkeiten sind.
Autosave/Restore wird zusätzlich in einem isolierten `XDG_DATA_HOME`
end-to-end geprüft.

View file

@ -197,6 +197,23 @@ Kapsel und Kopf, damit ein frischer Checkout und die Tests laufen.
Testdateien (nicht im Manifest): `skater_figure_anim_test_v001.glb` mit dem
2-Sekunden-Clip `TestWave`.
## Rotoscoping-Clips
Die Blender-Werkbank für neue Animationsclips ist separat dokumentiert:
`docs/rotoscoping.md`. Kurzfassung:
```bash
./tools/rotoscope.sh setup
./tools/rotoscope.sh open
./tools/rotoscope.sh export --out /tmp/clips.glb
./tools/rotoscope.sh promote --version 4 [--publish]
```
`promote` exportiert nach `library/characters/`, aktualisiert Version,
Quelle, Ziel, FTP-Pfad, Hash und die Liste der Clips im Manifest und
synchronisiert nach `assets/external/`. Die 3D-Vorschau lädt die GLB über
die Manifest-ID `character.skater.figure` und spielt derzeit `Glide`.
## Rig-Pipeline (AutoRigPro)
1. GLB in Blender importieren, Füße auf Z=0, Transform anwenden.

View file

@ -0,0 +1,103 @@
# Findings 2026-10-31 – Rotoscoping-Werkbank
## Ziel
Die Rotoscoping-Pipeline vollständig aufsetzen, ohne dass bereits
Videomaterial vorliegt. Die Werkbank muss später nur noch ein Video laden,
eine Aktion animieren und die Clips ins Asset-Manifest übernehmen.
## Umsetzung
```
tools/blender/rotoscope.py # Szene, Referenz, GLB-Export
tools/rotoscope.sh # CLI: setup, reference, open, export,
# promote, test-reference, status
tools/promote_rotoscope.py # GLB + Sidecar -> Manifest -> Sync/FTP
docs/rotoscoping.md # Workflow und Konventionen
```
### Vorbereitete Szene
`setup` öffnet `skater_rig_v003.blend` und legt eine Arbeitsdatei an:
- `RotoscopeCamera` (28 mm) mit `CameraTarget` und Track-To,
- `RinkGuide`: 60 × 30 m Drahtgitter mit Bande, Mittellinie, Mittelkreis,
5-m-Raster und 2-m-Höhenachse,
- Rig und Modell, Pose auf Ruhezustand zurückgesetzt,
- alle Aktionen mit Fake User, insbesondere `Glide`,
- optional ein Referenzvideo als Kamera-Hintergrund.
Die Arbeitsdatei liegt unter
`workbench/source/characters/skater/rotoscope/rotoscope_work.blend` und wird
nur mit `--force` überschrieben.
### Referenzvideo
- Videos werden als `MOVIE_CLIP` in den Kamera-Hintergrund gelegt
(nur Kameraansicht, nicht im finalen Render).
- Bildrate und Frame-Bereich kommen aus dem Clip.
- Standbilder werden als `IMAGE` unterstützt.
- Die Kamera bleibt pro Clip fest; bewegte Kameras müssen manuell getrackt
werden.
### Export und Übernahme
`export` exportiert **alle** Aktionen als GLB:
- `export_def_bones=True` (30 Deform-Bones),
- Constraints werden gebacken,
- Sidecar-JSON mit Clipnamen, Dauer, SHA-256 und Größe.
`promote`:
1. exportiert nach `library/characters/skater_figure_clips_vNNN.glb`,
2. aktualisiert Version, Quelle, Ziel, FTP-Pfad, Hash, Clips und
`source_scene` im Manifest,
3. synchronisiert nach `assets/external/` und importiert in Godot,
4. optional `--publish` auf den FTP-Spiegel.
## Synthetischer Testfilm
`tools/rotoscope.sh test-reference` erzeugt mit ffmpeg einen 8-s-Film
(1280 × 720, 24 fps, 192 Frames) mit Rink-Rahmen und bewegtem Punkt.
Damit geprüft:
| Schritt | Ergebnis |
| :--- | :--- |
| `setup --reference test_reference.mp4` | Frame 1–192, fps 24, Kamera-Hintergrund `MOVIE_CLIP` |
| Szene | `RotoscopeCamera`, `CameraTarget`, `RinkGuide` (145 Vertices, 127 Kanten), Rig/Modell |
| Rig | Pose T-Pose, `Glide` mit Fake User, keine aktive Aktion |
| `export` | GLB mit `Glide` (2,0 s), Sidecar geschrieben |
| Zusatzclip `TestClip` | Export mit `Glide` (2,0 s) und `TestClip` (1,0 s) |
| `promote --dry-run` | Version 99, Ziel, Clips und Hash korrekt in temporärem Manifest |
Der Test bestätigt auch, dass der Export ohne aktive Aktion funktioniert:
Fake-User-Aktionen werden mitgenommen.
## Konventionen
- Clips sind **in-place**; die Fortbewegung kommt aus der Kür-Kurve.
- 24 fps, Loop-Clips mit identischem ersten und letzten Frame.
- Namen: `Glide`, `Forward`, `Backward`, `CrossoverL/R`,
`ThreeTurnL/R`, `Spin`, `Jump`, `Landing`.
- Die `Glide`-Aktion bleibt als Basis im Export, bis sie ersetzt wird.
- Nicht gewünschte Aktionen vor dem Export löschen; der Export nimmt alle
Aktionen mit.
## Offen
- Erste echte Clips aus Referenzmaterial.
- Zuordnung Element → Clip in Godot (Pirouette → `Spin`, Sprung → `Jump`).
- Kamera-Solve für bewegte Aufnahmen (manuell über Blender Motion Tracking).
- Automatische Prüfung, ob ein Clip loop-fähig ist.
- Referenzvideo-Offset beim Trimm aus einem längeren Video komfortabler
machen.
## Dateien
```
workbench/source/characters/skater/rotoscope/rotoscope_work.blend
workbench/source/characters/skater/rotoscope/references/test_reference.mp4
workbench/library/characters/skater_figure_clips_v004.glb (nach promote)
```

View file

@ -188,8 +188,10 @@ UI-Feedback der Tester ohnehin noch ausstehen.
- [x] Animations-Bake und Godot-Import eines Testclips (`TestWave`)
- [x] 3D-Rink, Kamera und Skater auf denselben Kurven (schreibgeschützte Vorschau)
- [x] Erster Produktionsclip `Glide` als 2-s-Loop
- [x] Rotoscoping-Workflow (Blender-Werkbank, Referenz, Multi-Clip-Export, Manifest)
- [ ] Erste echte Clips aus Referenzmaterial (Vorwärts, Rückwärts, Pirouette)
- [ ] Clip-Zuordnung Element → Animation in Godot
- [ ] 3D-Bearbeitung, freie Kamera und Orbit-Steuerung
- [ ] Rotoscoping-Workflow und weitere echte Animationsclips
- [ ] NLA-/Animations-Tracks aus Blender
- [ ] Blender-MCP und Godot-Editor-MCP für den Asset-Workflow
- [x] Klare Trennung: Phase 1 bleibt ohne 3D-Abhängigkeiten lauffähig

183
docs/rotoscoping.md Normal file
View file

@ -0,0 +1,183 @@
# 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_v003.blend`.
- Für den synthetischen Testfilm: `ffmpeg`.
- Für den FTP-Upload: `docs/credentials.txt` wie beim Asset-Sync.
## 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 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`. 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/Documents/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.