rinkplanner/docs/findings-2026-10-31-arm-gewichte.md
torsten d4b227a936 fix: Armgewichte ringweise, Aermel behalten Volumen
- PSEUDO-VOXELS-Gewichte bleichten in spine/head; die offenen
  Aermelflaechen kollabierten trotz 8 Bone-Influences
- x-basierte Ringgewichtung fuer die Armregion, 8 Influences
- neues Quell-Rig und GLB v005, Manifest, Sync und FTP aktualisiert
- Rotoscoping-Default auf skater_rig_v005.blend
- 1189 Assertions gesamt
2026-10-31 15:35:17 +01:00

126 lines
4.6 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.

# Findings 2026-10-31 – Kollabierende Ärmel im 3D-Export
## Symptom
In der Godot-Vorschau sahen die Ärmel der Skaterin zermatscht aus: Die
Stoffärmel knickten an Schulter und Ellbogen ein, obwohl die ungeriggte GLB
und die Blender-Ansicht sauber aussahen.
## Diagnose
Das Mesh hat **3.104 Vertices mit mehr als vier Knochen-Einflüssen**, maximal
neun. Der glTF-Exporter meldete:
```
There are more than 4 joint vertex influences.
The 4 with highest weight will be used (and normalized).
```
Der Blender-Render nutzt alle Einflüsse und zusätzlich
`use_deform_preserve_volume = True`; Godot nutzt Linear Blend Skinning mit
der Anzahl, die im GLB steht.
Vergleichsexporte aus `skater_rig_v003.blend`, jeweils mit dem `Glide`-Clip:
| Variante | Einflüsse | Hierarchie | Godot-Ergebnis |
| :--- | ---: | :--- | :--- |
| `v003` (Produktion) | 4 | nur Deform-Bones | Ärmel kollabiert |
| `influences4_full` | 4 | alle 222 Bones | Ärmel kollabiert |
| `influences8_def` | 8 | nur Deform-Bones | sauber |
| `influences8_full` | 8 | alle 222 Bones | sauber |
Damit war klar: **Der 4-Einfluss-Trim ist die Ursache, nicht die flache
Deform-Hierarchie.** Die zusätzlichen Gewichte an den Ärmeln fehlten Godot.
## Fix
- Produktions-Export mit `export_all_influences=True`.
- Neue Datei `skater_figure_glide_v004.glb`:
- 8.584.300 Bytes,
- 30 Deform-Joints,
- `JOINTS_1`/`WEIGHTS_1` vorhanden,
- Clip `Glide`, 2,0 s,
- SHA-256 `50a3b84a…`.
- Manifest auf Version 4 aktualisiert; Control-Bones auf die tatsächlichen
222 korrigiert, `vertex_influences: 8` ergänzt.
- Lokal synchronisiert und per FTP veröffentlicht.
- `Skater3D`-Fallback auf v004 umgestellt.
- Die Rotoscoping-Werkbank exportiert ebenfalls mit
`export_all_influences=True` und warnt, wenn `JOINTS_1` im GLB fehlt.
## Test
Der Manifest-Test prüft bei synchronisiertem Asset, dass die importierte
Mesh-Oberfläche `Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS` trägt. Damit fällt ein
Rückfall auf 4 Einflüsse sofort auf.
- 3D-Assets: **57 Assertions** (vorher 54).
- 3D-Vorschau: 57 Assertions.
- Gesamtsuite: **1189** grün.
- Sichtprüfung: Rückansicht der Ärmel in Godot bei 600 × 600, zusätzlich
die normale 3D-Vorschau.
## Nachtrag: Ringweise Armgewichtung (v005)
Die 8 Einflüsse verhinderten den groben Kollaps, aber die Ärmel blieben
flach und knickten am Ellbogen. Die PSEUDO-VOXELS-Gewichte waren über den
Arm verteilt:
- Oberarm bei x = 0,40: `arm_stretch` 0,25, `forearm_stretch` 0,16,
**`spine_03`** 0,15, **`hand`** 0,09, **`head`** 0,08.
- Handgelenk bei x = 0,75: `hand` 0,36, `forearm_twist` 0,20,
**`spine_03`** 0,08.
Die Ärmel sind offene, einlagige Flächen. Unterschiedliche Gewichte rund um
den Arm ließen den Querschnitt kollabieren. Ein pauschales Entfernen der
Torso-Gewichte faltete die Schulter; eine abgestufte Variante beulte den
Oberarm auf.
Die Lösung ist eine **ringweise, rein x-basierte Gewichtung** der Armregion
(0,20–0,85 m, z 1,28–1,72 m):
| x-Bereich | Gewichte |
| :--- | :--- |
| 0,20–0,30 | `spine_03` → `shoulder`, `arm_stretch` |
| 0,30–0,42 | `shoulder` → `arm_stretch` |
| 0,42–0,50 | `arm_stretch` |
| 0,50–0,58 | `arm_stretch` → `forearm_stretch` |
| 0,58–0,66 | `forearm_stretch` |
| 0,66–0,74 | `forearm_stretch` → `hand` |
| > 0,74 | `hand` |
Die Twist-Bones erhalten jeweils 25 % der Arm-/Unterarmgewichtung
(`c_arm_twist_offset`, `forearm_twist`). Alle Vertices eines Rings bekommen
dieselben Gewichte; dadurch bleibt der Ärmelquerschnitt erhalten.
Ergebnis:
- neue Quelle `skater_rig_v005.blend`,
- neues GLB `skater_figure_glide_v005.glb`, 8.584.300 Bytes,
SHA-256 `f2b80124…`, 8 Bone-Influences,
- Manifest Version 5, lokal synchronisiert und per FTP veröffentlicht,
- Ärmel in Blender und Godot rund und ohne flache Knicke.
## Offen
- Das Mesh hat weiterhin bis zu neun Einflüsse; der Export behält acht. Die
Sichtprüfung ist sauber, bei anderen Bewegungen kann der neunte Einfluss
theoretisch fehlen.
- Blender nutzt Preserve Volume, Godot nicht. Falls künftige Clips an
Schulter oder Hüfte zwicken, hilft Weight-Cleanup, nicht ein höherer
Einfluss-Export.
- Ein generischer Export-Check für alle künftigen Assets wäre sinnvoll;
aktuell prüft der Manifest-Test nur den Charakter.
- Die ringweise Gewichtung ist auf die T-Pose und die x-Achse dieses Meshes
zugeschnitten; bei einem neuen Skater-Mesh muss sie neu angewendet werden.
## Dateien
```
workbench/library/characters/skater_figure_glide_v005.glb
workbench/source/characters/skater/skater_rig_v005.blend
rinkplanner/assets/asset_manifest.json
rinkplanner/tests/run_asset_manifest_tests.gd
tools/blender/rotoscope.py
rinkplanner/src/presentation3d/skater_3d.gd
```