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

4
.gitignore vendored
View file

@ -18,6 +18,10 @@ mono_crash.*.json
# Workbench (extern archiviert, nicht versionieren)
workbench/
# Python-Caches
__pycache__/
*.pyc
# Externe 3D-Assets (liegen im Workbench-Archiv, werden per Manifest synchronisiert)
rinkplanner/assets/external/

View file

@ -9,4 +9,5 @@ Planner for Figure Skating free skate
- **ISU-Regelwerk:** [`docs/isu-rules.md`](docs/isu-rules.md)
- **Roadmap:** [`docs/roadmap.md`](docs/roadmap.md)
- **3D-Assets:** [`docs/assets.md`](docs/assets.md)
- **Rotoscoping:** [`docs/rotoscoping.md`](docs/rotoscoping.md)
- **Builds:** [`docs/builds.md`](docs/builds.md)

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.

431
tools/blender/rotoscope.py Executable file
View file

@ -0,0 +1,431 @@
import argparse
import hashlib
import json
import math
import os
import struct
import sys
import bpy
WORKBENCH = os.environ.get(
"RINKPLANNER_WORKBENCH",
os.path.expanduser("~/Documents/workbench_rinkplanner"),
)
DEFAULT_RIG = os.path.join(
WORKBENCH, "source", "characters", "skater", "skater_rig_v003.blend"
)
DEFAULT_WORK = os.path.join(
WORKBENCH,
"source",
"characters",
"skater",
"rotoscope",
"rotoscope_work.blend",
)
VIDEO_EXTENSIONS = {".mp4", ".mov", ".avi", ".mkv", ".webm", ".m4v"}
IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".exr", ".tif", ".tiff", ".bmp"}
def parse_args() -> argparse.Namespace:
argv = sys.argv
if "--" in argv:
argv = argv[argv.index("--") + 1 :]
else:
argv = []
parser = argparse.ArgumentParser(
prog="rotoscope.py",
description="Rotoscoping-Werkbank für den Rinkplanner-Skater.",
)
subparsers = parser.add_subparsers(dest="command", required=True)
setup = subparsers.add_parser("setup", help="Arbeitsdatei anlegen")
setup.add_argument("--rig", default=DEFAULT_RIG)
setup.add_argument("--out", default=DEFAULT_WORK)
setup.add_argument("--reference", default="")
setup.add_argument("--force", action="store_true")
reference = subparsers.add_parser(
"reference", help="Referenzvideo in eine Arbeitsdatei laden"
)
reference.add_argument("--blend", default=DEFAULT_WORK)
reference.add_argument("--reference", required=True)
export = subparsers.add_parser("export", help="Alle Clips als GLB exportieren")
export.add_argument("--blend", default=DEFAULT_WORK)
export.add_argument("--out", required=True)
return parser.parse_args(argv)
def main() -> None:
args = parse_args()
if args.command == "setup":
setup_workbench(args)
elif args.command == "reference":
load_reference_into_workbench(args)
elif args.command == "export":
export_clips(args)
else:
raise SystemExit("Unbekannter Befehl: " + args.command)
def setup_workbench(args: argparse.Namespace) -> None:
if not os.path.isfile(args.rig):
raise SystemExit("Rig-Datei nicht gefunden: " + args.rig)
if os.path.exists(args.out) and not args.force:
raise SystemExit(
"Arbeitsdatei existiert bereits: %s "
"(mit --force überschreiben; das löscht den Arbeitsstand)"
% args.out
)
bpy.ops.wm.open_mainfile(filepath=args.rig)
scene = bpy.context.scene
_prepare_scene(scene)
_remove_helper_objects()
rig = bpy.data.objects.get("rig")
model = bpy.data.objects.get("model")
if rig is None or model is None:
raise SystemExit("Rig oder Modell nicht gefunden.")
rotoscope = bpy.data.collections.new("Rotoscope")
scene.collection.children.link(rotoscope)
camera = _create_camera(scene, rotoscope)
_build_rink_guide(rotoscope)
_reset_rig(rig)
if args.reference:
_load_reference(scene, camera, args.reference)
os.makedirs(os.path.dirname(os.path.abspath(args.out)), exist_ok=True)
bpy.ops.wm.save_as_mainfile(filepath=args.out)
print("SETUP_OK", args.out)
print(
"SETUP_SUMMARY",
json.dumps(
{
"work": args.out,
"rig": rig.name,
"model": model.name,
"camera": camera.name,
"frame_start": scene.frame_start,
"frame_end": scene.frame_end,
"fps": scene.render.fps,
"reference": str(scene.get("rotoscope_reference", "")),
},
ensure_ascii=False,
),
)
def load_reference_into_workbench(args: argparse.Namespace) -> None:
if not os.path.isfile(args.blend):
raise SystemExit("Arbeitsdatei nicht gefunden: " + args.blend)
bpy.ops.wm.open_mainfile(filepath=args.blend)
scene = bpy.context.scene
camera = bpy.data.objects.get("RotoscopeCamera")
if camera is None:
raise SystemExit("RotoscopeCamera fehlt in der Arbeitsdatei.")
_load_reference(scene, camera, args.reference)
bpy.ops.wm.save_as_mainfile(filepath=args.blend)
print("REFERENCE_OK", args.reference)
def export_clips(args: argparse.Namespace) -> None:
if not os.path.isfile(args.blend):
raise SystemExit("Arbeitsdatei nicht gefunden: " + args.blend)
bpy.ops.wm.open_mainfile(filepath=args.blend)
rig = bpy.data.objects.get("rig")
model = bpy.data.objects.get("model")
if rig is None or model is None:
raise SystemExit("Rig oder Modell nicht gefunden.")
for obj in bpy.context.view_layer.objects:
obj.select_set(False)
model.select_set(True)
rig.select_set(True)
bpy.context.view_layer.objects.active = rig
os.makedirs(os.path.dirname(os.path.abspath(args.out)), exist_ok=True)
bpy.ops.export_scene.gltf(
filepath=args.out,
export_format="GLB",
use_selection=True,
export_apply=False,
export_animations=True,
export_animation_mode="ACTIONS",
export_def_bones=True,
export_force_sampling=True,
export_bake_animation=True,
export_anim_single_armature=True,
export_optimize_animation_size=False,
export_yup=True,
)
size = os.path.getsize(args.out)
with open(args.out, "rb") as handle:
digest = hashlib.sha256(handle.read()).hexdigest()
clips = _read_glb_animations(args.out)
source_scene = os.path.relpath(
args.blend,
WORKBENCH,
).replace(os.sep, "/")
sidecar = {
"file": os.path.basename(args.out),
"sha256": digest,
"bytes": size,
"source_scene": source_scene,
"clips": clips,
"clip_names": [clip["name"] for clip in clips],
}
sidecar_path = os.path.splitext(args.out)[0] + ".json"
with open(sidecar_path, "w", encoding="utf-8") as handle:
json.dump(sidecar, handle, ensure_ascii=False, indent=2)
handle.write("\n")
print("EXPORT_OK", args.out)
print("EXPORT_SUMMARY", json.dumps(sidecar, ensure_ascii=False))
def _prepare_scene(scene: bpy.types.Scene) -> None:
scene.render.fps = 24
scene.render.fps_base = 1.0
scene.frame_start = 1
scene.frame_end = 240
scene.render.resolution_x = 1280
scene.render.resolution_y = 720
scene.render.film_transparent = True
scene.unit_settings.system = "METRIC"
scene.unit_settings.scale_length = 1.0
def _remove_helper_objects() -> None:
keep_prefixes = ("cs_",)
for obj in list(bpy.data.objects):
if obj.name.startswith(keep_prefixes):
continue
if obj.type in {"CAMERA", "LIGHT"}:
bpy.data.objects.remove(obj, do_unlink=True)
continue
if obj.name.startswith(("rig_", "glide_")):
bpy.data.objects.remove(obj, do_unlink=True)
def _create_camera(
scene: bpy.types.Scene,
collection: bpy.types.Collection,
) -> bpy.types.Object:
target = bpy.data.objects.new("CameraTarget", None)
target.empty_display_type = "SPHERE"
target.empty_display_size = 0.4
target.location = (0.0, 0.0, 1.0)
collection.objects.link(target)
camera_data = bpy.data.cameras.new("RotoscopeCamera")
camera_data.lens = 28.0
camera_data.sensor_width = 36.0
camera_data.clip_start = 0.1
camera_data.clip_end = 300.0
camera_data.show_background_images = True
camera = bpy.data.objects.new("RotoscopeCamera", camera_data)
camera.location = (0.0, -55.0, 20.0)
collection.objects.link(camera)
track = camera.constraints.new("TRACK_TO")
track.target = target
track.track_axis = "TRACK_NEGATIVE_Z"
track.up_axis = "UP_Y"
scene.camera = camera
return camera
def _build_rink_guide(collection: bpy.types.Collection) -> None:
vertices: list[tuple[float, float, float]] = []
edges: list[tuple[int, int]] = []
outline = _rounded_rect(30.0, 15.0, 8.5, 10)
base = len(vertices)
vertices.extend((x, y, 0.02) for x, y in outline)
for index in range(len(outline)):
edges.append((base + index, base + (index + 1) % len(outline)))
center_start = len(vertices)
vertices.extend([(0.0, -15.0, 0.02), (0.0, 15.0, 0.02)])
edges.append((center_start, center_start + 1))
circle_start = len(vertices)
for index in range(64):
angle = index / 64.0 * 6.283185307179586
vertices.append(
(
4.5 * math.cos(angle),
4.5 * math.sin(angle),
0.02,
)
)
for index in range(64):
edges.append((circle_start + index, circle_start + (index + 1) % 64))
for x in range(-25, 26, 5):
start = len(vertices)
vertices.extend([(float(x), -12.5, 0.01), (float(x), 12.5, 0.01)])
edges.append((start, start + 1))
for y in range(-10, 11, 5):
start = len(vertices)
vertices.extend([(-27.5, float(y), 0.01), (27.5, float(y), 0.01)])
edges.append((start, start + 1))
axis_start = len(vertices)
vertices.extend([(0.0, 0.0, 0.0), (0.0, 0.0, 2.0)])
edges.append((axis_start, axis_start + 1))
mesh = bpy.data.meshes.new("RinkGuideMesh")
mesh.from_pydata(vertices, edges, [])
mesh.update()
guide = bpy.data.objects.new("RinkGuide", mesh)
guide.display_type = "WIRE"
guide.show_in_front = True
guide.hide_render = True
guide.color = (0.15, 0.75, 1.0, 1.0)
collection.objects.link(guide)
def _rounded_rect(
half_length: float,
half_width: float,
radius: float,
segments: int,
) -> list[tuple[float, float]]:
import math
points: list[tuple[float, float]] = []
corners = [
(half_length - radius, -half_width + radius, -math.pi * 0.5, 0.0),
(half_length - radius, half_width - radius, 0.0, math.pi * 0.5),
(-half_length + radius, half_width - radius, math.pi * 0.5, math.pi),
(-half_length + radius, -half_width + radius, math.pi, math.pi * 1.5),
]
points.append((-half_length + radius, -half_width))
for center_x, center_y, start, end in corners:
for index in range(segments + 1):
angle = start + (end - start) * index / segments
point = (
center_x + math.cos(angle) * radius,
center_y + math.sin(angle) * radius,
)
if not points or abs(point[0] - points[-1][0]) > 1e-6 or abs(
point[1] - points[-1][1]
) > 1e-6:
points.append(point)
return points
def _reset_rig(rig: bpy.types.Object) -> None:
if rig.animation_data is not None:
rig.animation_data.action = None
for track in rig.animation_data.nla_tracks:
track.mute = True
for action in bpy.data.actions:
action.use_fake_user = True
for bone in rig.pose.bones:
bone.location = (0.0, 0.0, 0.0)
bone.rotation_quaternion = (1.0, 0.0, 0.0, 0.0)
bone.rotation_euler = (0.0, 0.0, 0.0)
bone.scale = (1.0, 1.0, 1.0)
def _load_reference(
scene: bpy.types.Scene,
camera: bpy.types.Object,
path: str,
) -> None:
if not os.path.isfile(path):
raise SystemExit("Referenz nicht gefunden: " + path)
extension = os.path.splitext(path)[1].lower()
if extension not in VIDEO_EXTENSIONS and extension not in IMAGE_EXTENSIONS:
raise SystemExit("Nicht unterstütztes Referenzformat: " + extension)
while camera.data.background_images:
camera.data.background_images.remove(camera.data.background_images[0])
camera.data.show_background_images = True
if extension in VIDEO_EXTENSIONS:
clip = bpy.data.movieclips.load(path)
background = camera.data.background_images.new()
background.source = "MOVIE_CLIP"
background.clip = clip
background.display_depth = "BACK"
background.frame_method = "FIT"
background.alpha = 0.85
scene.frame_start = 1
scene.frame_end = max(1, int(clip.frame_duration))
if clip.fps > 0.0:
scene.render.fps = max(1, int(round(clip.fps)))
print(
"REFERENCE_CLIP",
json.dumps(
{
"path": path,
"frames": clip.frame_duration,
"fps": clip.fps,
},
ensure_ascii=False,
),
)
else:
image = bpy.data.images.load(path, check_existing=True)
background = camera.data.background_images.new()
background.source = "IMAGE"
background.image = image
background.display_depth = "BACK"
background.frame_method = "FIT"
background.alpha = 0.85
print("REFERENCE_IMAGE", path)
scene["rotoscope_reference"] = path
scene["rotoscope_reference_type"] = (
"video" if extension in VIDEO_EXTENSIONS else "image"
)
def _read_glb_animations(path: str) -> list[dict]:
with open(path, "rb") as handle:
data = handle.read()
_magic, _version, length = struct.unpack_from("<4sII", data, 0)
offset = 12
chunks: list[tuple[int, int, int]] = []
while offset < length:
chunk_length, chunk_type = struct.unpack_from("<II", data, offset)
chunks.append((chunk_type, offset + 8, chunk_length))
offset += 8 + chunk_length
json_chunk = next(chunk for chunk in chunks if chunk[0] == 0x4E4F534A)
document = json.loads(
data[json_chunk[1] : json_chunk[1] + json_chunk[2]].decode("utf-8")
)
result = []
for animation in document.get("animations", []):
duration = 0.0
for sampler in animation.get("samplers", []):
accessor = document["accessors"][sampler["input"]]
duration = max(duration, float(accessor.get("max", [0.0])[0]))
result.append(
{
"name": animation.get("name", ""),
"duration": round(duration, 3),
}
)
return result
if __name__ == "__main__":
main()

134
tools/promote_rotoscope.py Executable file
View file

@ -0,0 +1,134 @@
#!/usr/bin/env python3
"""Übernimmt einen Rotoscoping-Export in das Asset-Manifest.
Liest die vom Blender-Export geschriebene JSON-Metadatendatei, aktualisiert
den Skater-Eintrag und synchronisiert das GLB in das Godot-Projekt. Mit
--publish wird es zusätzlich auf den FTP-Spiegel geladen.
"""
import argparse
import json
import os
import subprocess
import sys
REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
MANIFEST = os.path.join(REPO_ROOT, "rinkplanner", "assets", "asset_manifest.json")
WORKBENCH = os.environ.get(
"RINKPLANNER_WORKBENCH",
os.path.expanduser("~/Documents/workbench_rinkplanner"),
)
ASSET_ID = "character.skater.figure"
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(
description="Rotoscoping-Clips ins Asset-Manifest übernehmen."
)
parser.add_argument("--glb", required=True)
parser.add_argument("--version", type=int, default=0)
parser.add_argument("--manifest", default=MANIFEST)
parser.add_argument("--workbench", default=WORKBENCH)
parser.add_argument("--dry-run", action="store_true")
parser.add_argument("--publish", action="store_true")
parser.add_argument("--no-sync", action="store_true")
return parser.parse_args()
def load_json(path: str) -> dict:
with open(path, encoding="utf-8") as handle:
return json.load(handle)
def main() -> int:
args = parse_args()
glb_path = os.path.abspath(args.glb)
sidecar_path = os.path.splitext(glb_path)[0] + ".json"
if not os.path.isfile(glb_path):
print("GLB fehlt: " + glb_path, file=sys.stderr)
return 1
if not os.path.isfile(sidecar_path):
print("Metadatendatei fehlt: " + sidecar_path, file=sys.stderr)
return 1
workbench = os.path.abspath(args.workbench)
library = os.path.join(workbench, "library", "characters")
if not glb_path.startswith(library + os.sep):
print(
"Das GLB muss unter %s liegen, nicht unter %s."
% (library, glb_path),
file=sys.stderr,
)
return 1
sidecar = load_json(sidecar_path)
manifest = load_json(args.manifest)
assets = manifest.get("assets", [])
entry = next(
(asset for asset in assets if asset.get("id") == ASSET_ID),
None,
)
if entry is None:
print("Asset %s fehlt im Manifest." % ASSET_ID, file=sys.stderr)
return 1
version = args.version or int(entry.get("version", 0)) + 1
if version < 1:
print("Ungültige Version.", file=sys.stderr)
return 1
filename = os.path.basename(glb_path)
clips = sidecar.get("clip_names", [])
if not clips:
print("Der Export enthält keine Clips.", file=sys.stderr)
return 1
entry["version"] = version
entry["source"] = os.path.relpath(glb_path, workbench).replace(os.sep, "/")
entry["target"] = "assets/external/characters/" + filename
entry["remote"] = "characters/" + filename
entry["sha256"] = sidecar["sha256"]
entry["bytes"] = int(sidecar["bytes"])
if sidecar.get("source_scene"):
entry["source_scene"] = sidecar["source_scene"]
entry["animations"] = clips
entry["notes"] = "Rotoscoping-Export mit %d Clip(s)." % len(clips)
print(
json.dumps(
{
"id": ASSET_ID,
"version": version,
"file": filename,
"clips": clips,
"sha256": entry["sha256"],
"bytes": entry["bytes"],
"target": entry["target"],
},
ensure_ascii=False,
indent=2,
)
)
if args.dry_run:
print("DRY-RUN: Manifest und Sync nicht verändert.")
return 0
with open(args.manifest, "w", encoding="utf-8") as handle:
json.dump(manifest, handle, ensure_ascii=False, indent=2)
handle.write("\n")
if args.no_sync:
print("SYNC: übersprungen (--no-sync).")
return 0
sync_script = os.path.join(REPO_ROOT, "tools", "sync_assets.sh")
subprocess.run([sync_script, "--sync"], check=True)
if args.publish:
subprocess.run([sync_script, "--publish"], check=True)
return 0
if __name__ == "__main__":
raise SystemExit(main())

198
tools/rotoscope.sh Executable file
View file

@ -0,0 +1,198 @@
#!/usr/bin/env bash
# Rotoscoping-Werkbank für den Rinkplanner-Skater.
#
# Erzeugt eine vorbereitete Blender-Arbeitsdatei, lädt Referenzvideos und
# exportiert alle Animationsclips als GLB. Das Rig und die Referenzen bleiben
# im Workbench-Archiv, nicht im Repo.
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
WORKBENCH="${RINKPLANNER_WORKBENCH:-$HOME/Documents/workbench_rinkplanner}"
BLENDER="${BLENDER:-$(command -v blender || true)}"
SCRIPT="$REPO_ROOT/tools/blender/rotoscope.py"
RIG="${RINKPLANNER_RIG:-$WORKBENCH/source/characters/skater/skater_rig_v003.blend}"
ROTOSCOPE_DIR="$WORKBENCH/source/characters/skater/rotoscope"
WORK="$ROTOSCOPE_DIR/rotoscope_work.blend"
REFERENCES="$ROTOSCOPE_DIR/references"
DEFAULT_EXPORT="$WORKBENCH/library/characters/skater_figure_clips_v004.glb"
usage() {
cat <<'EOF'
Aufruf: tools/rotoscope.sh <befehl> [optionen]
setup [--reference PFAD] [--force]
Legt die Arbeitsdatei aus dem Rig an und lädt optional eine Referenz.
--force überschreibt eine vorhandene Arbeitsdatei samt Animationen.
reference PFAD
Lädt ein Video oder Standbild in die bestehende Arbeitsdatei.
open
Öffnet die Arbeitsdatei in Blender.
export [--out PFAD]
Exportiert alle Aktionen als GLB und schreibt eine JSON-Metadatendatei.
promote [--version N] [--publish] [--dry-run]
Exportiert nach library/characters/skater_figure_clips_vNNN.glb,
aktualisiert das Manifest und synchronisiert nach assets/external.
--publish lädt den Stand zusätzlich auf den FTP-Spiegel.
test-reference
Erzeugt einen synthetischen Testfilm unter references/test_reference.mp4.
status
Zeigt die verwendeten Pfade.
Umgebung:
RINKPLANNER_WORKBENCH Workbench-Archiv
BLENDER Blender-Binary
RINKPLANNER_RIG Quell-Rig (Standard: skater_rig_v003.blend)
EOF
}
require_blender() {
if [[ -z "$BLENDER" || ! -x "$BLENDER" ]]; then
echo "Blender nicht gefunden. Setze BLENDER=/pfad/zu/blender." >&2
exit 1
fi
}
command="${1:-help}"
if [[ $# -gt 0 ]]; then
shift
fi
case "$command" in
setup)
require_blender
"$BLENDER" -b --python "$SCRIPT" -- setup \
--rig "$RIG" --out "$WORK" "$@"
;;
reference)
require_blender
if [[ $# -lt 1 ]]; then
echo "Pfad zur Referenz fehlt." >&2
exit 2
fi
"$BLENDER" -b --python "$SCRIPT" -- reference \
--blend "$WORK" --reference "$1"
;;
open)
require_blender
if [[ ! -f "$WORK" ]]; then
echo "Arbeitsdatei fehlt: $WORK" >&2
echo "Zuerst: tools/rotoscope.sh setup" >&2
exit 1
fi
"$BLENDER" "$WORK"
;;
export)
require_blender
has_out=0
for argument in "$@"; do
if [[ "$argument" == "--out" ]]; then
has_out=1
fi
done
if [[ "$has_out" -eq 0 ]]; then
set -- "$@" --out "$DEFAULT_EXPORT"
fi
"$BLENDER" -b --python "$SCRIPT" -- export \
--blend "$WORK" "$@"
;;
promote)
require_blender
if ! command -v python3 >/dev/null 2>&1; then
echo "python3 nicht gefunden." >&2
exit 1
fi
version=""
publish=0
dry_run=0
while [[ $# -gt 0 ]]; do
case "$1" in
--version) version="${2:-}"; shift 2 ;;
--publish) publish=1; shift ;;
--dry-run) dry_run=1; shift ;;
*) echo "Unbekannte Option: $1" >&2; exit 2 ;;
esac
done
if [[ -z "$version" ]]; then
version="$(python3 - "$REPO_ROOT/rinkplanner/assets/asset_manifest.json" <<'PY'
import json
import sys
with open(sys.argv[1], encoding="utf-8") as handle:
document = json.load(handle)
entry = next(
(asset for asset in document.get("assets", [])
if asset.get("id") == "character.skater.figure"),
None,
)
print(int(entry.get("version", 0)) + 1 if entry else 1)
PY
)"
fi
if [[ ! "$version" =~ ^[0-9]+$ ]]; then
echo "Ungültige Version: $version" >&2
exit 2
fi
output="$WORKBENCH/library/characters/skater_figure_clips_v$(printf '%03d' "$version").glb"
"$BLENDER" -b --python "$SCRIPT" -- export \
--blend "$WORK" --out "$output"
promote_args=(--glb "$output" --version "$version")
if [[ "$dry_run" -eq 1 ]]; then
promote_args+=(--dry-run)
fi
if [[ "$publish" -eq 1 ]]; then
promote_args+=(--publish)
fi
python3 "$REPO_ROOT/tools/promote_rotoscope.py" "${promote_args[@]}"
;;
test-reference)
if ! command -v ffmpeg >/dev/null 2>&1; then
echo "ffmpeg nicht gefunden." >&2
exit 1
fi
mkdir -p "$REFERENCES"
output="$REFERENCES/test_reference.mp4"
filter_file="$(mktemp "${TMPDIR:-/tmp}/rotoscope-filter.XXXXXX")"
trap 'rm -f "$filter_file"' EXIT
cat > "$filter_file" <<'FILTER'
drawbox=x=20:y=20:w=1240:h=680:color=0x7fa8c9:t=8,
drawbox=x=638:y=20:w=4:h=680:color=0x7fa8c9:t=fill,
drawtext=text='ROTOSCOPE TEST':fontcolor=0x1f3a5f:fontsize=48:x=(w-text_w)/2:y=60,
drawtext=text='O':fontcolor=0xc0392b:fontsize=64:x='w/2+320*sin(2*PI*t/4)':y='h/2+160*cos(2*PI*t/4)'
FILTER
ffmpeg -y -f lavfi -i "color=c=0xdfefff:s=1280x720:r=24:d=8" \
-filter_script:v "$filter_file" \
-c:v libx264 -pix_fmt yuv420p -movflags +faststart "$output" \
>/dev/null 2>&1
echo "Testreferenz: $output"
;;
status)
printf 'Workbench: %s\n' "$WORKBENCH"
printf 'Rig: %s\n' "$RIG"
printf 'Arbeitsdatei: %s\n' "$WORK"
printf 'Referenzen: %s\n' "$REFERENCES"
printf 'Export: %s\n' "$DEFAULT_EXPORT"
;;
help|-h|--help)
usage
;;
*)
echo "Unbekannter Befehl: $command" >&2
usage >&2
exit 2
;;
esac