Ersetze grobe 3D-Markierungen durch präzise UV-Farbmasken

frontend/docs/falukant-character-appearance.md

@@ -4,42 +4,45 @@
 
 Die vorhandenen Meshy-GLBs enthalten ein gemeinsames Mesh und Material für Haut,
 Kleidung, Haare und Augen. Eine Änderung der allgemeinen Materialfarbe würde
-deshalb die gesamte Figur färben. Die Bereiche müssen einmal pro Modell
-zugeordnet werden; die Geometrie wird dabei nicht anhand von Farbähnlichkeiten
-automatisch geraten.
+alle Bereiche färben. Die Zuordnung erfolgt deshalb über eine eigene UV-Maske:
+Rot markiert Haare, Grün die Iris, Schwarz unveränderte Bereiche.
 
-Unter `/falukant/dev-all-characters` öffnet sich jetzt standardmäßig die
-Vorschau **Farben und Modellbereiche**. Die bisherige Altersübersicht bleibt
-über **Alle Altersmodelle** erreichbar.
+Die erste Version verwendete ganze Dreiecke als Markierung. Gerade an Augen
+waren diese zu grob. Version 2 bemalt stattdessen einzelne Texturpixel. Die
+Dreiecke, ihre Indizes und die ursprünglichen UV-Koordinaten bleiben unverändert.
+
+Unter `/falukant/dev-all-characters` öffnet sich standardmäßig die Vorschau
+**Farben und Modellbereiche**. Die Altersübersicht bleibt über **Alle Altersmodelle**
+erreichbar.
 
 1. Geschlecht/Alter wählen oder eine lokale GLB-Datei öffnen. Für die Bearbeitung
    möglichst die Quelldatei aus `YourPart3Assets/models-src/3d/falukant/characters`
    statt eines bereits reduzierten Laufzeitmodells verwenden.
-2. In **Drehen / Zoom** das Modell ausrichten. Das Mausrad zoomt, die rechte
-   Maustaste verschiebt die Ansicht.
-3. **Haare markieren** wählen und sichtbare Haarflächen überstreichen. Zum
-   Erreichen weiterer Seiten wieder in den Drehmodus wechseln.
-4. Für **Iris markieren** nahe heranzoomen und einen kleinen Pinsel verwenden.
-   Augenweiß, Pupillen, Lider und Wimpern aussparen.
-5. Mit **Markierung entfernen** Bereiche auf ihre ursprüngliche Textur
-   zurücksetzen. Die letzten zehn Pinselstriche lassen sich rückgängig machen.
-6. Augen-/Haarfarbe ändern und die Zuordnung prüfen. Die Checkbox zeigt zum
-   Vergleich die Originalfarben. Haut und Kleidung werden nicht eingefärbt.
-7. Das bearbeitete GLB herunterladen und erneut öffnen, um die Zuordnung zu
-   kontrollieren. Exportiert werden die Materialbereiche mit ihren ursprünglichen
-   Texturen, nicht die gewählten Vorschaufarben.
+2. In **Drehen / Zoom** ausrichten. Das Mausrad zoomt bis zur Nahansicht; die
+   rechte Maustaste verschiebt die Ansicht. Die Editor-Kamera erlaubt auch das
+   genaue Betrachten der Iris, ohne dass die Nah-Clipping-Ebene sie abschneidet.
+3. **Haare markieren** wählen und über die sichtbaren Haarflächen streichen.
+   Zum Erreichen anderer Seiten wieder in den Drehmodus wechseln.
+4. Für **Iris markieren** einen kleinen Pinsel verwenden. Der sichtbare Kreis
+   zeigt die Pinselgröße. Pupille, Augenweiß, Lider und Wimpern aussparen.
+5. **Markierung entfernen** radiert lokal. **Alle Markierungen löschen** entfernt
+   die gesamte Zuordnung, etwa zum Ersetzen alter dreieckiger Markierungen.
+   Die letzten zehn Pinselstriche bzw. Löschaktionen sind rückgängig machbar.
+6. Farben ausprobieren. Die Checkbox zeigt zum Vergleich die Originalfarben.
+   Außerhalb der Maske bleiben Haut und Kleidung unverändert.
+7. Das bearbeitete GLB herunterladen und erneut öffnen. Gespeichert wird die
+   Maske mit den ursprünglichen Texturen, nicht die gewählte Vorschaufarbe.
 
-Die Originaldateien im Asset-Repository werden vom Editor nicht überschrieben.
-Nach Kontrolle die heruntergeladene Datei unter dem bisherigen Quellnamen im
-Asset-Repository ablegen, z. B. `female_20y.glb`, und das Asset-Repository committen.
-Die bestehende Pipeline `npm run build-runtime-models -- --assets-dir
-../YourPart3Assets --category characters` erstellt daraus die optimierten GLBs.
-Die Exportdatei erhält bewusst keinen `_opt`-Suffix, da solche Dateien vom
-Quellmodell-Build übersprungen werden.
+Originaldateien im Asset-Repository werden nicht automatisch überschrieben.
+Nach Kontrolle die Datei unter dem bisherigen Quellnamen dort ablegen, z. B.
+`female_20y.glb`, und das Asset-Repository committen. Die bestehende Pipeline
+`npm run build-runtime-models -- --assets-dir ../YourPart3Assets --category characters`
+erstellt daraus die optimierten GLBs. Die Exportdatei erhält keinen `_opt`-Suffix,
+da solche Dateien vom Quellmodell-Build übersprungen werden.
 
-Noch nicht markierte Modelle behalten ihr bisheriges Aussehen. Diese Änderung
-ersetzt nicht automatisch alle bestehenden GLBs. Es gibt keine neue
-Datenbankmigration oder Speicherung pro Spielcharakter.
+Unmarkierte Modelle behalten ihr bisheriges Aussehen. Die vollständige
+Markierung aller Modellvarianten ist eine einmalige Aufgabe je Modell. Es gibt
+keine neue Datenbankmigration oder Speicherung pro Spielcharakter.
 
 ## Schnittstelle für die Anzeige
 
@@ -53,42 +56,55 @@ Datenbankmigration oder Speicherung pro Spielcharakter.
 />
 ```
 
-Nur sechsstellige Hexfarben werden angewendet. `null` oder ein fehlender Wert
-zeigt für den jeweiligen Bereich die Originaltextur. Farbänderungen benötigen
-keinen erneuten Download und keine neue Modellinstanz.
+Nur sechsstellige Hexfarben werden angewendet. Fehlende Werte oder `null`
+zeigen die Originaltextur. Farbänderungen benötigen keinen neuen Modell-Download.
 
 Materialien enthalten glTF-`extras` in dieser Form:
 
 ```json
 {
   "falukantAppearance": {
-    "version": 1,
-    "region": "hair",
-    "source": "material-0"
+    "version": 2,
+    "region": "masked",
+    "uvSet": 0,
+    "maskPng": "data:image/png;base64,..."
   }
 }
 ```
 
-Bereiche sind `body`, `hair` und `iris`. `source` ordnet die Bereiche dem
-ursprünglichen Material zu. Alternativ werden für extern vorbereitete Modelle
-die exakten Materialnamen `hair`, `iris`, `falukant_hair` und `falukant_iris`
-erkannt. Die Standardmaterialien und Texturkoordinaten bleiben erhalten.
-Der Pinsel teilt Dreiecke in Materialgruppen; die Genauigkeit hängt deshalb
-von der vorhandenen Geometrie ab. Sehr grobe Augenbereiche benötigen eine
-feinere Geometrie oder eine spätere Texturmaskierung.
+Die Maske liegt als PNG direkt im GLB. Neue Masken verwenden passend zur
+Originaltextur 2048×2048 bis 4096×4096 Pixel. Sie wird
+nicht in die Farbtextur eingebrannt und benötigt keinen eigenen Server-Endpunkt.
+Die bestehende Draco-/Textur-Optimierung erhält die Material-Extras und verändert
+die Maske nicht. Beim Laden wird sie als lineare Datentextur ohne Y-Spiegelung
+interpretiert, passend zu den glTF-UVs. Für die normale Spielanzeige wird sie
+im Speicher auf höchstens 2048 Pixel Kantenlänge reduziert; im Editor bleibt
+die gespeicherte Auflösung erhalten. Haar- und Irisfarbe werden darüber im
+Shader gemischt; auch eingebrannte Farben emissiver Texturen werden berücksichtigt.
 
-Die Farbanpassung erhält Helligkeitsdetails und berücksichtigt auch eingebrannte
-Farben in emissiven Texturen. Shader-Uniforms werden pro Material gehalten und
-nicht als Laufzeitobjekte in das GLB geschrieben. Der Export stellt die originale
-Wurzeltransformation wieder her und übernimmt vorhandene Animationen.
+Der Pinsel rastert UV-Dreiecke anhand ihrer baryzentrischen Oberflächenpositionen.
+Damit bleibt seine Größe in der Modelloberfläche konsistent und er kann über
+UV-Nähte hinweg malen. Er färbt keine ganzen Dreiecke als Ersatz für kleine
+Pinselstriche. Die Genauigkeit ist durch die Maskenauflösung begrenzt; mehrfach
+verwendete UV-Bereiche teilen sich auch die Maske.
+
+Rückgängig speichert nur veränderte 64×64-Pixel-Kacheln pro Pinselstrich statt
+zehn vollständiger Masken. Im Export landen ausschließlich PNG-Daten und
+Versionsinformationen, keine Shader- oder Undo-Objekte. Die originale
+Wurzeltransformation und vorhandene Animationen werden übernommen.
+
+Version-1-Materialzuordnungen und die exakten Materialnamen `hair`, `iris`,
+`falukant_hair`, `falukant_iris` werden weiterhin geladen. Bestehende grobe
+Markierungen werden nicht automatisch als Iris erkannt oder korrigiert. Sie
+lassen sich lokal radieren oder vollständig löschen und pixelgenau neu anlegen.
+Beim nächsten Export wird das Ergebnis als Version 2 gespeichert.
 
 ## Spätere altersabhängige Attribute
 
-Ergrauen kann später über eine altersabhängige Haarfarbe auf derselben
-Schnittstelle aufsetzen. Für Wachstum oder Veränderungen der Gesichtsform
-braucht es gezielt vorbereitete Morph-Targets oder austauschbare Geometrie.
-Die bisherigen voneinander unabhängigen Altersmodelle werden durch die
-Farbzuordnung nicht automatisch zu einem verformbaren Basismodell.
+Ergrauen kann über eine altersabhängige Haarfarbe aufsetzen. Für Wachstum oder
+Veränderungen der Gesichtsform braucht es Morph-Targets oder austauschbare
+Geometrie. Die bisherigen unabhängigen Altersmodelle werden durch die Maskierung
+nicht automatisch zu einem verformbaren Basismodell.
 
 ## Prüfung
 
@@ -98,7 +114,8 @@ npm run test:character-appearance
 npm run build
 ```
 
-Zusätzlich wurde ein vorhandenes `female_20y.glb` im Browser geladen, mit Haar-
-und Irisbereichen versehen, exportiert, mit der bestehenden Draco-/Simplify-
-Pipeline optimiert und erneut importiert. Beide Bereiche und ihre glTF-Metadaten
-blieben erhalten. Die vollständige Markierung aller Modellvarianten steht noch aus.
+Regressionstests prüfen kleine Iris-Pinsel auf großen Dreiecken, unveränderte
+Geometrie, UV-Nähte, unabhängige Farben/Instanzen, lokales Radieren, Rückgängig
+und Version-1-Kompatibilität. Im Browser wird zusätzlich das vorhandene
+`female_20y.glb` in starker Vergrößerung geprüft, mit Maske exportiert,
+Draco-optimiert und erneut importiert.