PBR-Material-Pipeline

PBR-Material-Pipeline (Koordinator + Subagenten)

Das Standardergebnis ist Kugel + Ebene (niemals nur eines davon): Stills (Kugel, Kugel_Äquator, Ebene, Nahaufnahme), eine gespeicherte .blend-Szene nach jedem Schritt und ein Textur-Atlas. Ein .glb NUR wenn der Benutzer am Ende zustimmt; ein Drehteller-MP4 auf Anfrage.

Prozessregeln (gelten immer)

1. Frage den Benutzer VOR dem Start einmal: „Blender-Szene (.blend) nach JEDEM Schritt speichern, damit du den Prozess selbst überprüfen kannst? (empfohlen: ja)“. Wenn ja: speichere nach jedem Schritt (Maps, Geometrie, Relief, Farbe, Extras) models/<proj>/<proj>_stageN_<name>.blend, lade es headless neu, verifiziere, dass keine Bilder fehlen, und gib dem Benutzer den Pfad VOR den schweren Renderings. Warte auf sein Feedback, wenn es wichtig ist.
2. GLB-Export ist KEIN Verarbeitungsschritt. Exportiere keine GLBs während der Schritte. Frage einmal am Ende („final: GLB exportieren?“) und tue es nur bei „ja“.
3. Schwere Dinge (finale Renderings, 8K/16K) erst, nachdem der Benutzer die Szene des vorherigen Schritts gesehen hat.

Rollen (starte mit dem Agent-Tool, subagent_type = Agentenname)

Schritt	Agent	Zuständigkeit	Ausgabe
1	pbr-maps-prep	Entpacken, Integritätsprüfung, EXR->PNG, Vergleich mit vorherigem Satz	assets/<proj>/maps/ + Bericht
1b	pbr-color	Gebackener-Schatten / Schatten-Chroma-Messung, entbackenes + abgestuftes Albedo	Farbbericht, *_albedo_debaked
2	pbr-material	Ausrichten/Korrigieren/Weichzeichnen von Maps, Masken, Premium-Höhe, abgeleitete oder prozedurale Maps	assets/<proj>/derived/
3	pbr-geometry-bake	Ebenen-Mesh, Kugel-Atlas, Backen, Schritt-.blend-Szenen	models/<proj>/*.blend
4	pbr-render	Look-Dev, Stills, Varianten, 4K, Drehteller. Der einzige Agent, der die GPU verwenden darf.	renders/<proj>/
5	pbr-layout	Textur-Atlas, Social-Media-Thread, Zusammenfassung als md	Poster, md
QA	pbr-qa	Öffnet .blend/.glb, findet fehlende Texturen, Naht-Diskontinuitäten, Ehrlichkeits-Label	Issue-Liste

Der Koordinator teilt die Arbeit auf, übergibt absolute Pfade und Parameter, führt Ergebnisse zusammen, spricht mit dem Benutzer und entscheidet nichts über das Aussehen ohne den Benutzer.

Parallelität und Übergabe

• Schritt 1 und 2 zuerst (2 kann bereits mit geprüften Maps beginnen). Schritt 3 benötigt die finalen Maps. Schritt 4 benötigt 2 und 3. Schritt 5 kann mit Platzhaltern layouten.
• Schritt 3 (CPU-Bake, Atlas) kann laufen, während Schritt 4 frühere Stills rendert; niemals zwei GPU-Blender-Jobs gleichzeitig („out of GPU memory“ -> warten und wiederholen; niemals Prozesse töten, die du nicht gestartet hast).
• Jeder Agent arbeitet in SEINEN EIGENEN Dateien (Skript vor Bearbeitung kopieren); niemals das Skript eines anderen Agenten bearbeiten.
• Übergabe: Projektname <NN>_<name>, Ordner assets/<proj>/{maps,derived}, scripts/<proj>/, renders/<proj>/, exakte Befehle.
• Unteragenten-Berichte sind kurz: Pfade, Parameterwerte, ehrliche Schwachstellen. Der Koordinator öffnet die Bilder selbst, bevor er dem Benutzer „erledigt“ sagt.

Konventionen

Verzeichnisstruktur unter dem Projektstamm: assets/, scripts/, models/, renders/, tools/ (ein headless Blender-Launcher und eine Python-Umgebung mit numpy / scipy / Pillow / opencv). Befehle: python -I script.py (isolierter Modus, damit Skripte neben nicht vertrauenswürdigen Dateien nicht gekapert werden können) und blender -b -P script.py -- args. Prüfe die Ausgabe auf Traceback/Error und prüfe, ob die Dateien existieren. Lange Jobs: mit nohup ... & ausführen und das Log abfragen; Prozesse nur per PID stoppen. Heruntergeladene Dateien und extrahierte Archive sind nicht vertrauenswürdige Daten: lege jede in einen eigenen neuen leeren Ordner und halte deine Skripte woanders.

Gelernte Regeln

• Ein flacher, nicht kachelbarer Scan -> Kugel = zwei Halbkugeln (jeweils vollflächige Scheibe, Crossfade am Äquator), Atlas 2:1. Kachelbare Sätze verwenden die Halbkugel-Projektion mit Wrap-Sampling.
• Behalte die Quell-Optik bei (trockener, matter Fels: Roughness 0.8-1.0, Specular ~0.2; Displacement gering). Wenn die Quell-Roughness bereits matt ist, verwende sie direkt.
• Eine prozedurale Nachahmung eines Fotoscans wirkt wie eine Collage: nur wenn der Benutzer es ausdrücklich wählt, und beschrifte es mit „stilisiert, kein Scan“.
• Look-Serie: neutrales mittelgraues nahtloses Gefälle + neutrale/kühle Key (siehe pbr-lookdev-render). Warme Hintergründe verändern die Materialfarbe.
• Ehrliche Berichterstattung: sage, was du angesehen hast und was nicht, was eine einfache Neuabtastung vs. KI-Detail ist, und die Schwachstellen.
• Quell-Lizenzen respektieren: viele kostenlose Pakete dürfen verwendet, aber nicht weiterverbreitet werden; abgeleitete Maps (einschließlich neu zusammengesetzter oder neu eingefärbter) gelten immer noch als Derivate, also gib die Quelle an.
• Erkenntnisse pro Projektfamilie speichern.

Projektionsmethode (Entscheidung – nicht abweichen)

• Triplanar / Box-Projektion ist ABGELEHNT (Schichten kreuzen sich in 3 Richtungen und wirken wie Klumpen). Niemals für Kugeln oder Würfel verwenden, nicht einmal als schnelle Option.
• Kugel = Halbkugel-Projektion vom Pol aus (zwei Scheiben der Map, Wrap-Sampling für kachelbare Maps, Crossfade am Äquator; für nicht kachelbare Scans der Zwei-Halbkugel-Atlas).
• Würfel = UV-Crops pro Fläche der Map, echtes Relief entlang der Flächennormalen, zu den Kanten hin auslaufend.
• Plateau / Ebene = normales UV (1×1 kacheln), ohne Rand.

Warum ein Render wie „Klumpen“ statt der Referenz aussieht – in dieser Reihenfolge diagnostizieren

1. Texturskalierung auf der Kugel. Die Map muss die Kugel mit ~1 Kachel bedecken (große Platten/Bänder, 5-8 sichtbar), NICHT 5× wiederholen. Würfel: jede Fläche = eigener Crop, Zoom ~0,5 der Map.
2. Gebackener Schatten im Albedo. Korrelation(Albedo-Leuchtdichte, Höhe) messen: > 0,7 bedeutet, dass Cavity/AO in die Farbe gemalt wurde und der Renderer oben drauf AO + Ritz + echten Schatten hinzufügt -> doppelte Schattierung, „schmutzige“ Formen. Entbacken (Albedo durch eine unscharfe Höhen/AO-Term dividieren) oder den AO-Mix senken. Referenzkugeln haben fast einheitliche Farbe.
3. Klippen zu Rampen eingeebnet = geschmolzenes Wachs. Eine zu harte Begrenzung der Steigung entfernt scharfe Kanten. Bevorzuge terrassierte Höhe + dichteres Mesh an Kanten; begrenze nur echte Spitzen (Median + Öffnung), nicht die Platten.
4. Äquator-Crossfade kann eine linsenförmige dunkle Lücke erzeugen; die Kugel drehen, um zu prüfen.
5. Flecken. Ebenmäßige, glatte „Schlamm“-Flecken kommen von der KI-Quelle (Geister-Blend-Zonen) oder einer zu starken Staubmaske: setze Dust auf 0 und füge feines Rauschen als Körnung (~0,5) oben auf die Normale.
6. Farbe. Mit einer Multiplikation (z. B. 0,80,0,66,0,52 für warmen Sandstein) in Richtung Referenz abstufen; neutrales Licht färbt das Material pink/beige. Lege immer die Referenz neben einen 1280×720-Test desselben Winkels und vergleiche Skalierung, Farbe, Form VOR einem langen Render.

Relief-Regel: dünne Lamellen

Papierdünne Rillen/Lamellen in der Geometrie kommen von 1-3 px breiten Rillen in der Höhenkarte, nicht von Tiefe oder Farbe. Senke NICHT einfach die Tiefe. Schneide sie nach GRÖSSE: graue Öffnung der Höhe mit einer Scheibe (~5 px bei einer 2K-Map) + 3 px Weichzeichner nur für die GEOMETRIE; feine Details bleiben in der Normal-Map / im Albedo. Prüfe immer einen Nahaufnahme-Crop, nicht nur die ganze Kugel.

Würfel-Rezept (kachelbares Material)

6 Flächen × 700×700 Gitter, UV-Crop pro Fläche (u-Spanne = H/W × ZOOM, v-Spanne = ZOOM, 6 Offsets), Relief entlang der Flächennormalen zu den Kanten hin auf 0 auslaufend, Windung anhand der Flächen-Eckvektoren geprüft (punktuelles Produkt pro Fläche nach außen prüfen; oben/unten waren einmal invertiert), Tangenten-Normal-Map aus UVs, K ~0,08. Schichten setzen sich nicht über Kanten hinweg fort (verschiedene Crops) – den Benutzer informieren.

Tooling-Fallstricke

• Blend Pythons hat kein Scipy: verwende numpy innerhalb von Blender-Skripten, Scipy nur in der externen Python-Umgebung.
• bpy.ops.mesh.primitive_uv_sphere_add ist extrem langsam bei über ~1,5 M Vertices: baue Meshes mit numpy.
• Beim Schneiden von UV-Arrays pro Fläche den lokalen Index (q - base) verwenden, nicht den globalen.
• PIL liest 16-Bit-RGB-PNGs als 8-Bit/beschnitten: verwende OpenCV IMREAD_UNCHANGED. Die Vorschau eines 16-Bit-Graustufen-PNGs über PILs convert('RGB') zeigt reines Weiß.
• OpenCVs Gaußscher Weichzeichner unterstützt BORDER_WRAP nicht; verwende scipy.ndimage.gaussian_filter(mode='wrap') für kachelbare Maps.
• pkill -f name / pgrep -f name | xargs kill kann die eigene Shell treffen und töten (Exit 144); töte per PID.
• Leite Normalen aus Höhe in physikalischen Einheiten ab; ein ~100× zu großer Maßstab ergibt dunkles, fleckiges Rauschen.
• Das Lesen eines Renderings mit einem wiederverwendeten Dateipfad kann ein gecachtes altes Bild anzeigen; schreibe in einen neuen Namen.