rinkplanner/docs/assets.md

284 lines
11 KiB
Markdown
Raw Normal View History

# 3D-Assets (extern)
Stand: 2026-11-11
Die 3D-Assets liegen bewusst außerhalb des Git-Repos. Das Repo enthält nur
ein Manifest, ein Sync-Werkzeug und die Dokumentation. Die Binärdateien
bleiben im Workbench-Archiv.
## Verzeichnisse
```
/home/torsten/Dokumente/workbench_rinkplanner/
├── inbox/ # Eingang, unverändert lassen
├── library/ # kuratiert, vom Manifest referenziert
│ └── characters/
├── source/ # .blend, Rig, Rohdaten
│ └── characters/skater/
└── archive/ # alte Stände, Videos, Bilder
```
```
rinkplanner/
├── assets/
│ ├── asset_manifest.json # versioniert
│ └── external/ # gitignored, per Sync befüllt
└── tests/run_asset_manifest_tests.gd
tools/sync_assets.sh
```
`assets/external/` wird nie committet. Ein frischer Checkout braucht einmal
`./tools/sync_assets.sh --sync`, sonst fehlen die 3D-Dateien.
## Workflow
1. Neue Datei in `inbox/` ablegen.
2. Prüfen, bei Bedarf konvertieren und als versionierte Datei nach
`library/` legen (`..._v001.glb`, `..._v002.glb`).
3. Die bearbeitbare Quelle (`.blend`, Rig, Referenzvideo) nach `source/`.
4. Eintrag in `rinkplanner/assets/asset_manifest.json` ergänzen:
ID, Quelle, Ziel, FTP-Pfad, SHA-256, Größe, Platzierung, Rig, Animationen.
5. `./tools/sync_assets.sh --sync` kopiert und importiert.
6. Bei geänderter Datei `./tools/sync_assets.sh --publish` für den Spiegel.
7. Vor dem Commit `./tools/sync_assets.sh --check` laufen lassen.
### Befehle
```bash
./tools/sync_assets.sh --check # Standard: nur lokal prüfen
./tools/sync_assets.sh --sync # kopieren/laden + Godot-Import
./tools/sync_assets.sh --sync --force # abweichendes Ziel überschreiben
./tools/sync_assets.sh --publish # Workbench-Dateien auf den FTP-Spiegel laden
```
`--sync` arbeitet in dieser Reihenfolge:
1. Ziel in `assets/external/` ist vorhanden und hat den Manifest-Hash → OK.
2. Workbench-Quelle ist vorhanden → kopieren.
3. Sonst vom FTP-Spiegel laden.
Damit funktioniert ein frischer Checkout auf einem Rechner ohne
Workbench-Archiv, sofern die FTP-Zugangsdaten vorliegen.
### FTP-Spiegel
Der vorhandene FTP-Server der Kür-Synchronisation dient als
Verteilungskopie. Die Dateien liegen dort unterhalb des App-Verzeichnisses:
```
<FTP_DIRECTORY>/assets/<remote>
# z. B. rinkplanner/assets/characters/skater_figure_rigged_deform_v002.glb
```
`FTP_DIRECTORY` ist das Verzeichnis aus `docs/credentials.txt` (aktuell
`rinkplanner`). Der Unterordner `assets` wird beim ersten Upload automatisch
angelegt (`--ftp-create-dirs`).
Zugangsdaten kommen aus `docs/credentials.txt` (gitignored) oder aus
`RINKPLANNER_FTP_*`-Umgebungsvariablen. Das Format ist dasselbe wie für die
App:
```
FTP_URL=<host>
FTP_USER=<benutzer>
FTP_PASSWORD=<passwort>
FTP_DIRECTORY=rinkplanner
```
Optional:
| Schlüssel | Bedeutung |
| :--- | :--- |
| `FTP_ASSET_DIRECTORY` | überschreibt `<FTP_DIRECTORY>/assets` |
| `FTP_VERIFY=1` | TLS-Zertifikat prüfen (Standard: 0) |
Der Server verwendet explizites FTPS (`AUTH TLS`, Port 21). Sein Zertifikat
hat keinen passenden Hostnamen, deshalb ist die Prüfung standardmäßig aus.
Die Integrität hängt nicht am Zertifikat, sondern am SHA-256 aus dem
Manifest: Nach jedem Upload wird die Datei zurückgeladen und gehasht; nach
jedem Download wird vor dem Verschieben gehasht.
`--publish` ist bewusst ein eigener Befehl. Ein normaler `--sync` lädt nichts
hoch und überschreibt keine Serverdatei.
Auf einem neuen Rechner:
```bash
cp /pfad/zu/credentials.txt docs/credentials.txt
./tools/sync_assets.sh --sync
```
Weitere Umgebungsvariablen:
| Variable | Standard | Zweck |
| :--- | :--- | :--- |
| `RINKPLANNER_WORKBENCH` | `~/Dokumente/workbench_rinkplanner` | Archivpfad |
| `RINKPLANNER_CREDENTIALS` | `<repo>/docs/credentials.txt` | FTP-Konfiguration |
| `GODOT` | `/opt/godot/Godot_v4.7.2-stable_linux.x86_64` | Import-Binary |
Das Skript prüft beim Kopieren, Laden und Veröffentlichen die jeweilige
Datei gegen den Hash aus dem Manifest. `--check` prüft nur das lokale Ziel;
eine still veränderte Workbench-Datei wird nicht kopiert, sondern gemeldet.
## Manifest
```json
{
"id": "character.skater.figure",
"version": 6,
"kind": "character",
"format": "glb",
"source": "library/characters/skater_figure_glide_v006.glb",
"target": "assets/external/characters/skater_figure_glide_v006.glb",
"remote": "characters/skater_figure_glide_v006.glb",
"sha256": "3b49dc76…",
"bytes": 8584300,
"source_scene": "source/characters/skater/skater_rig_v006.blend",
"placement": {
"up_axis": "Y",
"facing": "+Z",
"pivot": "feet",
"height_m": 1.898,
"ground_offset_m": 0.0
},
"rig": {
"type": "humanoid",
"control_bones": 222,
"deform_bones": 30,
"vertex_influences": 8,
"bind": "PSEUDO_VOXELS"
},
"animations": [
"Glide"
]
}
```
| Feld | Bedeutung |
| :--- | :--- |
| `id` | stabile Kennung; Code und Szenen referenzieren die ID, nicht den Dateinamen |
| `version` | Zähler der kuratierten Fassung |
| `source` | Pfad relativ zum Workbench-Archiv |
| `target` | Pfad relativ zum Godot-Projekt, immer unter `assets/external/` |
| `remote` | Pfad relativ zum FTP-Asset-Verzeichnis |
| `sha256` / `bytes` | Integritätsprüfung |
| `source_scene` | bearbeitbare Quelle (`.blend`) für Rig/Animation |
| `placement` | Up-Achse, Blickrichtung, Pivot und Höhe für die 3D-Szene |
| `rig` | Control-/Deform-Bones und Bind-Verfahren |
| `animations` | Liste der exportierten Clipnamen |
## Versionierung
- Dateinamen tragen `_vNNN`; vorhandene Versionen werden nicht überschrieben.
- Eine neue Fassung ist eine neue Datei plus neuer Manifest-Eintrag bzw.
aktualisierte `version` und `sha256`.
- Alte Versionen bleiben in `library/` und im Archiv nachvollziehbar.
- Nicht parsebare oder verworfene Experimente gehören nicht ins Manifest.
## Godot und Export
- `assets/external/` ist gitignored und wird nach dem Sync importiert.
- `asset_manifest.json` wird über `include_filter="*.json"` mit exportiert.
- Die Export-Presets schließen Test- und Gewichts-Assets
(`weights_rings*`), das noch nicht freigegebene Tripo-Evaluationsasset
(`skater_figure_tripo*`) sowie `assets/models/*` aus, nehmen aber die
Skater-GLB samt ihren Quelltexturen
(`assets/external/characters/skater_figure_glide_v006*`) mit. Fehlt die
GLB auf einem frischen Checkout, baut `Skater3D` weiterhin den Platzhalter;
`tools/check_export.sh` weist darauf hin und prüft die Texturen im Build.
- Phase 1 bleibt unberührt: Der 2D-Code lädt keine 3D-Ressourcen.
## Aktueller Bestand
| ID | Datei | Größe | Rig | Clips |
| :--- | :--- | ---: | :--- | :--- |
| `character.skater.figure` | `skater_figure_glide_v006.glb` | 8,59 MB | 222 Control / 30 Deform, 8 Einflüsse | `Glide` (2-s-Loop) |
| `character.skater.figure_tripo` | `skater_figure_tripo_v001_30k.glb` | 7,19 MB | keins (unrigged) | – |
Die 3D-Vorschau lädt `character.skater.figure` über die Manifest-ID.
Fehlt sie, erscheint ein Platzhalter aus Kapsel und Kopf, damit ein frischer
Checkout und die Tests laufen.
### Tripo-Evaluationsasset
`character.skater.figure_tripo` ist der Gewinner des Modellvergleichs vom
2026-11-11 (Tripo H3.1 Image→3D, Request `01a1c9c3-ce93-7cb1-8eb1-ca12dfa66c88`).
Es ist bewusst **nicht** an `Skater3D` angebunden und **nicht** in den
Export-Presets enthalten:
- 30k-Decimation (`skater_figure_tripo_v001_30k.glb`, 29.999 Dreiecke) ist
die Projektfassung; die 116k-Quelle liegt nur in der Workbench
(`library/characters/skater_figure_tripo_v001.glb`).
- Unrigged (`rig.type: "none"`), Blickrichtung `+X`, Höhe 1,7 m. Der
Manifest-Test akzeptiert `type: "none"` mit null Bones/Einflüssen.
- **Lizenz offen:** Tripo gewährt kommerzielle Rechte laut AGB nur „Paid
Users“; ob ein kostenpflichtiger fal-Lauf zählt, ist nicht bestätigt.
Bis zur schriftlichen Antwort von fal/Tripo bleibt das Asset
Evaluationsmaterial und darf nicht in Releases landen.
Details und verworfene Kandidaten:
`docs/findings-2026-11-11-ai-skater-model-comparison.md`.
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.
2. ARP Smart Rig: Marker für Neck, Chin, Shoulder, Hand, Root, Foot setzen.
3. `PSEUDO_VOXELS` als Bind-Engine; das Mesh hat 37 Inseln und offene Kanten,
Heat-Map-Weighting ist dafür ungeeignet.
4. **`Match to Rig` ist Pflicht:** Erst danach sitzen Knie, Füße und Arme
exakt auf dem Mesh. Der erste Auto-Rig-Lauf hatte die Füße bei x = 0,24
statt 0,10.
5. Animationen auf dem Control-Rig erstellen (IK/FK, Fußrollen, Root Motion).
Der erste Clip ist `Glide`: Arme unten, 2-s-Loop, im `.blend`
`skater_rig_v006.blend`.
6. **Armgewichte gelenkgenau und ringweise** setzen (Ellbogen bei
x ≈ 0,37, Handgelenk bei x ≈ 0,65, siehe
`docs/findings-2026-10-31-arm-gewichte.md`). Die PSEUDO-VOXELS-Gewichte
bleichten sonst in `spine_03`/`head`; die offenen Ärmelflächen
kollabierten.
7. Export mit `export_def_bones=True` und **`export_all_influences=True`**;
der Exporter backt Constraints automatisch. Im GLB landen nur die 30
Deform-Bones, aber **8 Bone-Influences pro Vertex**. Mit dem Standard-
Export (4 Einflüsse) kollabieren die Ärmel in Godot.
8. Ergebnis in Godot prüfen (`tests/manual/inspect_rig.gd`,
`tests/manual/capture_rig.gd`); die 3D-Vorschau mit
`tests/manual/capture_3d.gd`.
Details und Messwerte: `docs/findings-2026-10-31-arp-rig.md`.
## Backup und Lizenz
- Das Workbench-Archiv liegt außerhalb des Repos und wird **nicht** vom
Git-Remote gesichert. `library/` und `source/` separat sichern
(restic/rsync).
- Die Skaterin ist ein eigenes GenAI-Asset; das Rig wurde mit AutoRigPro
erstellt. Vor einer Veröffentlichung die Lizenz der Basistexturen prüfen.
## Tests
`tests/run_asset_manifest_tests.gd` prüft Schema, Pfade, FTP-Pfade, Hashes,
Animationen und – falls synchronisiert – Größe, SHA-256 sowie die
8-Bone-Gewichte der Zieldatei. Fehlt das Asset (z. B. in CI), wird der
Dateicheck übersprungen, der Schema-Test bleibt aktiv. Aktuell: 57
Assertions.