image-to-figure

Was macht image-to-figure?

Ziel

Aus einem einzelnen Charakterbild (einer Illustration, einem Konzeptblatt oder einem Foto einer Figur) eine texturierte 3D-Figur erstellen, die den Charakter von allen Seiten zeigt: eine Blender-Masterdatei, ein sauberes GLB, Review-Renderings gegen die Drehansichten und ein Drehteller-Video. Der Eigentümer genehmigt Ausgaben und bewertet das Aussehen; du steuerst die Phasen und erkennst Probleme, bevor sie Geld kosten.

Nicht im Umfang: Rigging und Animation, Charaktere, für die der Eigentümer keine Nutzungsrechte hat, und manuelles Modellieren des Charakters in Blender.

Erledigt, wenn

1. views/view_front.png, view_left.png, view_back.png, view_right.png existieren, alle gleich groß, von img2fig crop mit Exit-Code 0.
2. Du die vier Ansichten mit dem Referenzbild und untereinander verglichen und schriftlich berichtet hast: jedes Accessoire befindet sich auf der richtigen Körperseite in jeder Ansicht, nichts erscheint, was nicht im Referenzbild ist (sieh am genauesten bei der Rückansicht, Taschen, Gürteln und Haaraccessoires hin), und Pose und Bodenlinie stimmen über alle Ansichten hinweg überein. Jede Abweichung wurde mit img2fig edit korrigiert und das Blatt vor der Modellierungsphase neu zugeschnitten.
3. models/<provider>/model.glb von img2fig model --execute existiert.
4. img2fig prep mit Exit-Code 0 beendet wurde, seine orientation nicht ambiguous ist (oder du bestätigt hast, dass das Front-Rendering zur Kamera zeigt), prep.dimensions_units[2] innerhalb von 0,01 von 2,9 liegt und prep.faces_out auf oder unter --faces liegt (für triangulierte Eingaben wie Provider-GLBs).
5. Du dir renders/compare.jpg (Eingabeansichten oben, Renderings unten) und renders/face.png angesehen und pro Ansicht berichtet hast, was übereinstimmt und was nicht.
6. turntable/turntable.mp4 existiert (img2fig turntable, Exit-Code 0), falls der Eigentümer ein Video wünschte.
7. img2fig spend einen Gesamtbetrag innerhalb der vom Eigentümer genehmigten Grenze anzeigt.

Ausgabenregeln

• Befehle, die eine kostenpflichtige API aufrufen (lookdev, turnaround, edit, model), drucken nur einen Plan und eine Schätzung, es sei denn, --execute wird angegeben. Zeige die Schätzung des Plans dem Eigentümer und hole eine Freigabe ein, entweder pro Aufruf oder als Budget, das er festlegt; übergib dieses Budget dann als --budget (oder setze IMG2FIG_BUDGET_USD; ohne beides ist die Obergrenze 5 $). Das Budget wird vor jedem kostenpflichtigen Aufruf gegen das Hauptbuch des Arbeitsverzeichnisses (spend.json, zusammengefasst durch img2fig spend) geprüft, und der Aufruf wird abgelehnt (Exit-Code 3), wenn er das Budget überschreiten würde. Fehlgeschlagene Aufrufe werden mit ihrer Schätzung erfasst, da einige fehlschlagen, nachdem der Anbieter sie abgerechnet hat.
• img2fig estimate --stages lookdev,turnaround,edit,model berechnet den Preis für einen gesamten Durchlauf. Typische Größenordnung: unter 0,30 $ pro Bildaufruf, 0,60 $ pro Tripo-Modell, etwa 4 $ für ein Bake-off mit vier Anbietern. Die Schätzungen sind eher zu hoch; cost_from_usage_usd bei Bildaufrufen ist der tokenbasierte Wert.
• Ein Bake-off (--provider all) kostet etwa sieben Tripo-Läufe. Führe es nur durch, wenn der Eigentümer es wünscht oder Tripo bei diesem Charakter eindeutig versagt.

Arbeitsablauf

img2fig doctor                                    # Schlüssel vorhanden? Blender, ffmpeg gefunden?
img2fig lookdev --ref character.png --description "..."            # Plan; --execute nach Genehmigung hinzufügen
img2fig turnaround --ref character.png --description "..."         # verwendet das neueste Look-Dev-Bild
img2fig crop                                       # views/view_{front,left,back,right}.png
img2fig edit --fix "Rückansicht: den runden Schwanz unter der Schleife entfernen; schlichter Rock dort."   # nur bei Bedarf
img2fig crop                                       # erneut zuschneiden: nimmt das neueste Blatt oder die Bearbeitung
img2fig model                                      # Tripo, Plan; --execute nach Genehmigung
img2fig prep                                       # orientieren, normalisieren, dezimieren, bewerten, Renderings, compare.jpg
img2fig turntable                                  # Drehteller/turntable.mp4

Alle Befehle teilen --workdir VERZ (Standard $IMG2FIG_WORKDIR oder ./figure_work); Eingaben standardmäßig die neueste Datei der vorherigen Stufe in diesem Verzeichnis. Jeder Befehl gibt ein JSON-Objekt auf stdout aus; lies ok, die Pfade, warning/warnings, next und bei Fehlschlag error.type, error.message und error.detail (Provider-HTTP-Status und -Body, Blender- oder ffmpeg-Exit-Code und stderr-Ende, Protokollpfad).

Exit-Codes: 0 ok (einschließlich Trockenläufe), 1 Provider-Fehler, 2 Anwendungsfehler, 3 Budget überschritten, 4 fehlender Schlüssel/Binärprogramm/Paket, 5 Blender oder ffmpeg fehlgeschlagen, 6 eine Ergebnisprüfung fehlgeschlagen (das Blatt wurde nicht in die erwarteten Ansichten aufgeteilt), 7 interner Fehler.

Schreiben von --description

Liste auf, was die Figur behalten muss, wobei die Seiten aus Sicht des Charakters und des Betrachters in Klammern angegeben werden: "grüne Klee-Haarspange auf ihrer LINKEN Seite (rechts des Betrachters in der Vorderansicht)". Beschreibe, was das Referenzbild tatsächlich zeigt, nicht, was du generieren wolltest: Bildmodelle verschieben manchmal ein Accessoire auf die andere Seite, und das Referenzbild gewinnt.

Prep-Optionen, die wichtig sind

• --rot auto (Standard) rendert das Modell flach schattiert bei 0/90/180/270 Grad und vergleicht jedes mit view_front.png. Wenn das Ergebnis mehrdeutig ist, wird auf die bekannte Ausrichtung des Providers zurückgegriffen (nur für Tripo bekannt; andernfalls sagt die Ausgabe, das Front-Rendering zu überprüfen). Übergib --rot GRAD, um zu überschreiben.
• --grade matte (Standard), light (blasse Outfits: Weißtöne bleiben sauber), dark (vertieft dunkle Stoffe), none. --keep-gloss 0.3 behält die ursprüngliche Rauheit und Metallizität auf Teilen, die in der Quelle glänzend waren.
• --blush=X,Z (wiederholbar) malt einen weichen Wangenrouge an einem Punkt, der in Figuranteilen angegeben ist; ermittle X,Z durch Messen der Wange in renders/front.png und Ausführen von img2fig point --x PX --y PY. Schreibe negative Werte mit = (--blush=-0.08,0.6), da argparse sie sonst als Optionen liest.
• --faces (Standard 350000) begrenzt die Anzahl der Flächen; die Normalen- und Farbtexturen behalten feine Details.

Bekannte Fallstricke (alle beobachtet)

• Das Bildmodell erfindet Details, und das 3D-Modell baut sie ein. Eine Drehung erhielt einmal einen Pompon-Schwanz auf dem Rücken und ein Abzeichen in den Jackentaschen, die der Charakter nie hatte; das 3D-Modell reproduzierte beide getreu. Behebe dies auf der Bildebene (edit mit einem --fix pro Problem, dann crop und erneut model). Patche das Netz nicht. Eine erste Bearbeitung kann eine andere Erfindung hinterlassen (das Abzeichen wurde zu einer Cupcake-förmigen Dekoration), also vergleiche nach jeder Bearbeitung erneut.
• Kleine Details verschwimmen. Jede Ansicht eines 3840x2160 Blattes ist nur etwa 1000 Pixel breit, daher werden das Gesicht eines Plüschtiers oder die Finger im Modell unscharf. Ein größeres Blatt ist nicht verfügbar; beurteile das Gesichts-Rendering und teile es dem Eigentümer mit, anstatt scharfe kleine Details zu versprechen.
• Anbieter sind sich bei der Ausrichtung uneinig. Tripos GLBs zeigen nach dem Import in +X (benötigt -90 Grad). Die automatische Prüfung behandelt es; sieh trotzdem auf das Front-Rendering.
• Eine vollständig matte Bewertung zerstört Kristall- und Glanzteile. Verwende --keep-gloss oder --grade none, wenn der Charakter Kristall-, Metall- oder Patentteile hat.
• Handgebaute prozedurale Charaktere erreichen nicht die Figurenqualität. Ein aus Primitiven in Blender modelliertes Charakter konnte organische Haare nicht richtig hinbekommen; das Bild-zu-3D-Modell tat es. Fall nicht auf prozedurale Modellierung für organische Formen zurück.
• AgX vs. Standard. Renderings verwenden standardmäßig AgX: Lichter werden nicht abgeschnitten, aber helle und weiße Materialien werden gräulich und weniger gesättigt, weshalb die Bewertungen die Sättigung anheben. --view-transform standard passt die Referenzfarben genauer an, schneidet aber helle Bereiche ab. Die Ausrichtungsprüfung rendert mit Standard, damit Farben fair verglichen werden.
• sRGB vs. linear in Blender. Das Lesen von Pixelfarben eines PNG innerhalb von Blender (Image.pixels) gab codierte sRGB-Werte zurück, keine linearen. Dekodiere sie, bevor du sie als lineare Farben verwendest, falls du die Blender-Skripte erweiterst.

Ressourcen und Grenzen

• Schlüssel kommen nur aus Umgebungsvariablen: OPENAI_API_KEY (Bildstufen) und FAL_KEY (Modellstufe). Gib sie niemals aus oder schreibe sie in Dateien.
• Blender als externes Binärprogramm (getestet auf 5.2; 4.2 oder neuer sollte funktionieren) (blender im PATH oder IMG2FIG_BLENDER); ffmpeg für den Drehteller.
• Das Arbeitsverzeichnis enthält generierte Bilder, Modelle und Renderings des Charakters des Eigentümers. Veröffentliche, lade sie nicht hoch oder committe sie nicht, es sei denn, der Eigentümer bittet darum; behandle Charaktere, die der Eigentümer von jemand anderem lizenziert hat, als privat.
• Prompts befinden sich in src/image_to_figure/prompts.py; --prompt-file ersetzt eine Vorlage für einen Aufruf.

3D-Druck

img2fig print wandelt ein Modell (Standard figure/figure_clean.glb; jedes GLB, STL, OBJ oder PLY mit --model; mit --up auto werden GLB/glTF/OBJ als Y-up und STL/PLY als Z-up gelesen) in einen druckbereiten Festkörper um. Benötigt das print Extra (uv pip install -e '.[print]'); die Installation von pymeshlab (GPL, keine Abhängigkeit) fügt einen expliziten Selbstschnitte-Zähler zum Bericht hinzu.

img2fig print --height 100 --base pedestal                 # Festkörper, FDM oder Resin
img2fig print --height 130 --base pedestal                 # FDM mit dünnen Teilen: größer drucken statt verdicken
img2fig print --height 100 --base pedestal --hollow 2.0    # Resin: 2 mm Wand, Drainagelöcher
img2fig print --model raw_tripo.glb --rot -90 --height 80  # ein rohes Tripo-GLB zeigt in +X

Erledigt, wenn: der Befehl mit Exit-Code 0 endet und checks.printable wahr ist (wasserdicht, eine gültige 2-Mannigfaltigkeit laut manifold3d, positives Volumen); checks.parts 1 ist, es sei denn, lose Teile wurden absichtlich behalten; checks.self_intersecting_faces 0 ist, wenn gemessen; output.height_mm gleich --height plus Sockel innerhalb eines Voxels ist; du dir print/figure_section.png (Wände, Hohlraum und Drainagelöcher) und die figure_preview_*.png Renderings angesehen hast, und jeden Eintrag in warnings gemeldet hast, insbesondere dünne Teile (checks.wall_thickness: thin_part_volume_fraction, largest_thin_parts mit ihren Positionen in mm; relief_volume_fraction ist feines Oberflächendetail, gemeldet aber nie verdickt) und was dagegen zu tun ist. Wenn --thicken verwendet wurde, hast du die Vorschaurenderings mit einem unverdickten Lauf verglichen und keine neuen Beulen im Gesicht, Haar oder Accessoires gesehen; ohne Blender (keine Vorschauen) überprüfe, dass thicken.added_mm3 in derselben Größenordnung wie wall_thickness_before.thin_part_volume_mm3 ist (Beulen zeigen sich als hinzugefügtes Volumen weit darüber) und sieh dir das Schnittbild an.

So funktioniert es: Die Oberfläche wird voxelisiert (Standard-Voxel = Höhe / 500), Lücken werden mit der kleinsten morphologischen Schließung versiegelt, die ein Inneres einschließt (bis zu 8 Voxeln; der Schritt voxelize meldet gap_closing_voxels), und das Innere wird gefüllt, sodass offene Kanten, überlappende Schalen und Selbstschnitte verschwinden; ein vorzeichenbehaftetes Distanzfeld führt dann den Basisschnitt, Sockel, Aushöhlung und Drainagelöcher aus; Marching Cubes, Taubin-Glättung und manifold3d erzeugen das endgültige Netz. Details, die kleiner als etwa ein Voxel sind, gehen verloren, und Teile, die näher als die Schließungslücke sind, verschmelzen.

Optionen: --min-wall (Standard 1,0 mm; Resin kann niedriger sein, FDM benötigt normalerweise 1,2 oder mehr) legt fest, was als dünn gilt; --thicken (standardmäßig aus) wächst dünne Teile auf diese Dicke, siehe unten; --fragments merge|remove|keep mit --merge-gap (Standard 2 mm) entscheidet über schwebende Teile: im Merge-Modus werden Teile innerhalb der Lücke mit einer Brücke verbunden und weiter entfernte werden behalten und gemeldet, niemals stillschweigend verworfen; Krümel unter 1 mm³ werden immer entfernt; --base flat|pedestal|none; --hollow WALL mit --drain-hole bohrt ein Loch pro Hohlraum von unten (Taschen unter 20 mm³ bleiben fest); --color schreibt ein vertexfarbenes PLY aus der Modelltextur für Vollfarbdienste. Die STL und 3MF sind einfarbig.

Dünne Teile. Der Bericht trennt dünne Teile (Blätter, Flossen, Stränge, Bänder und Schnüre, die mehr als --min-wall von einem dickeren Körper abstehen, wobei beide Oberflächen nahe beieinander sind) von Oberflächenrelief (geprägte Linien, Strangkanten, kleine Punkte und konvexe Kanten auf einem dicken Körper). Für FDM, bevorzuge größeres Drucken: jedes dünne Teil skaliert mit der Figur (ein 0,9 mm Band bei 100 mm ist 1,17 mm bei 130 mm), nichts wird umgeformt, und die Dünnwandbehandlung des Slicers (Arachne-Wände, "dünne Wände erkennen") druckt den größten Teil des Restlichen; ein Bruchteil eines Prozents des Volumens unter der Wand ist normal und in Ordnung. Verwende --thicken, wenn die Größe festgelegt ist und einige wenige dünne Teile fest gedruckt werden müssen (eine Bandschlaufe, ein Ahoge, ein hängendes Kabel, ein Rocksaum): es wächst nur dünne Teile, jedes auf etwa --min-wall, und stumpft ihre Spitzen ab; Relief wird nie gewachsen. Wenn nach --thicken noch dünne Teile übrig bleiben, sagt die Warnung dies und schlägt größeres Drucken oder Slicer-Einstellungen vor, nicht einen weiteren Lauf. Kanten der Definition: Relief, das mehr als --min-wall vom Körper aufragt (ein hoher schmaler Kamm, ein tief geprägter Strang), zählt als dünnes Teil und wird abgestumpft; ein kurzes dünnes Netz, das eine Lücke zwischen zwei dicken Teilen überspannt (bis zu etwa doppeltem --min-wall Breite), wird als Relief gemeldet, und ein Slicer kann es fallen lassen und ein Loch hinterlassen, überprüfe daher Netze in der Slicer-Vorschau. Das Wachstum erfolgt in alle Richtungen, daher verlängert --thicken auch Spitzen leicht und kann dünne Teile verschmelzen, die näher als --min-wall beieinander liegen.

Beobachtet während der Erstellung: Das binäre Distanzfeld hinterlässt sichtbare Terrassen, es sei denn, das Ergebnis wird geglättet (Taubin, --smooth, Standard 10 Iterationen, behält Volumen); das Projizieren von Scheitelpunkten zurück auf die Quelloberfläche faltete stattdessen dünne Blätter und wurde verworfen. Glättung und Netzvereinfachung können beide Selbstschnitte in dünnen Regionen einführen; der Befehl versucht weniger Glättung und strengere Toleranzen, bis die Prüfung sauber ist, und meldet, worauf er sich geeinigt hat (Schritt smooth_and_simplify). Aushöhlung muss undrainierbare Taschen fest lassen, da sie sonst versiegelte Hohlräume werden. Bei einer echten Bild-zu-3D-Figur wurden zwei symmetrische 120 mm³ Stücke als separate Schalen 1,3 mm vom Körper modelliert; eine frühe Version entfernte sie, weil sie knapp außerhalb eines 1 mm Merge-Spalts lagen, weshalb entfernte Teile jetzt behalten und gemeldet werden. Bei einer echten 100 mm Figur mit --min-wall 1,2 bedeckte ein frühes --thicken Gesicht, Haar, Schleifen und ein Plüschaccessoire mit kleinen runden Beulen: es behandelte alles, was ein 1,2 mm Ball nicht erreichen konnte, als dünn, einschließlich flachem Relief wie Strangkanten, geprägten Wimpern und Punkten, und wuchs jedes davon um 0,6 mm auf jeder Seite (5,5% mehr Volumen). Ohne Verdickung blieben die gleichen Teile dünn; die Beulen traten nur dort auf. Der abschließende Selbstschnitt-Check bestand nicht ohne Glättung: dünne gewachsene Kanten drangen in benachbarte dicke Teile ein. Jetzt erkennt der Relief-Filter flache Details und wächst sie nicht; der Selbstschnitt-Check akzeptiert nur Netze ohne Schnitte; und dünne Teile, die nach dem Wachsen dünn bleiben, werden gemeldet, aber nie wiederholt gewachsen.