rinkplanner/docs/assets.md
torsten 135f4ce040 feat: Ultra-Skater im Kürkleid und Rig-Werkzeug
Zweiter Durchlauf für Geometrie und Outfit: Referenzbild per Tripo-Image-Edit
auf ein petrolfarbenes Kürkleid umgestellt (20 Credits), daraus ein
Ultra-Image→3D (geometry_quality=detailed, 50 Credits).

- v008: 59.488 Dreiecke, 1,7 m, 222 Control-/30 Deform-Bones, Glide
  unverändert per Rotations-Retargeting
- Lider, Ohren und Haaransatz deutlich besser als v007; Finger bleiben
  verschmolzen
- Manifest-Eintrag auf Version 2 (v008), Skater3D-Fallback und
  check_export.sh nachgezogen
- tools/blender/build_skater.py: Rig, Retarget und Export in einem Befehl,
  reproduziert die manuelle GLB byte-identisch
- Lizenz-Log um Bild-Edit und Ultra-Lauf ergänzt, Doku und AGENTS.md aktualisiert
2026-11-12 06:04:47 +01:00

13 KiB
Raw Blame 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

./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:

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

{
  "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*) und das ungenutzte, unrigged Tripo-Mesh (skater_figure_tripo*) sowie assets/models/* aus, nehmen aber beide Skater-GLB samt Quelltexturen mit (assets/external/characters/skater_figure_glide_v006* und skater_figure_glide_v008*). 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_tripo_glide skater_figure_glide_v008.glb 3,08 MB 222 Control / 30 Deform, 4 Einflüsse Glide (2-s-Loop)
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_tripo_glide über die Manifest-ID. Fehlt sie, erscheint ein Platzhalter aus Kapsel und Kopf, damit ein frischer Checkout und die Tests laufen.

Tripo-Skater mit Glide (v008, aktiv)

character.skater.figure_tripo_glide ist seit 2026-11-12 die Figur, die Skater3D lädt. Version 2 (v008) entstand im Ultra-Modus und trägt ein petrolfarbenes Kürkleid mit Pailletten statt des Trainingskleids:

  • 59.488 Dreiecke, Textur v3.5, Höhe 1,7 m, Blickrichtung +Z, Pivot Füße.
  • Referenzbild per Tripo-Image-Edit aus flux2pro_reference_front.png erzeugt (Task 316752d8-16e7-49c8-beb1-d2223afc9f79, 20 Credits).
  • Mesh: geometry_quality=detailed, 60k-Face-Budget, Task 834f0e29-65db-49d2-a02b-7a6239a4d07a, 50 Credits.
  • Rig lokal in Blender mit AutoRigPro: 222 Control-Bones, 30 Deform-Bones, Bind PSEUDO_VOXELS, 4 Einflüsse pro Vertex.
  • Glide per reinem Rotations-Retargeting von skater_figure_glide_v006 übernommen (2-s-Loop, 48 Frames bei 24 fps).
  • Klingenabstand in der Vorschau: ±0,154 m (Konstante BLADE_LATERAL_OFFSET_M in skater_3d.gd).
  • Bekannte Schwächen: Lider ohne Augengeometrie, Finger als verschmolzene Blobs. Im Ultra-Modus sind Ohren und Gesichtsform deutlich besser, die Finger bleiben aber ungetrennt.

Der komplette Weg vom Mesh zum geriggten Export ist als ein Befehl reproduzierbar:

blender --python tools/blender/build_skater.py -- \
  model.glb skater_figure_glide_v008.glb \
  --source-rig rinkplanner/assets/external/characters/skater_figure_glide_v006.glb

Ablauf, Stolpersteine und Messwerte: docs/findings-2026-11-12-tripo-skater-rig.md.

Tripo-Mesh ohne Rig

character.skater.figure_tripo bleibt als unrigged Zwischenstand im Manifest (Gewinner des Modellvergleichs vom 2026-11-11, Request 01a1c9c3-ce93-7cb1-8eb1-ca12dfa66c88), ist aber 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: Erzeugt über fal (tripo3d/h3.1/image-to-3d); fal Support hat am 2026-11-12 bestätigt, dass der Vertrag mit fal besteht und Tripos Free-/Paid-User-AGB nicht greifen. Seit der Umstellung auf die Tripo-Pay-as-you-go-API (siehe v008) gilt: kommerzielle Nutzung ist über den bezahlten API-Zugang abgedeckt; fal erhebt keine Rechte an Outputs, garantiert aber keine Originalität oder Nichtrechtsverletzung. Details in docs/findings-2026-11-11-ai-skater-model-comparison.md. Aus den Export-Presets bleibt das unrigged Asset ausgeschlossen, weil es nicht an Skater3D angebunden ist.

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:

./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.