image-to-figure

image-to-figure は何をしますか？

目標

一枚のキャラクター画像（イラスト、コンセプトシート、フィギュアの写真など）から、すべての方向からキャラクターに一致するテクスチャ付き3Dフィギュアを生成します。最終成果物は、Blenderマスターファイル、クリーンなGLB、ターンアラウンドビューに対するレビューレンダリング、そしてターンテーブル動画です。オーナーが支出を承認し、見た目を判断します。あなたは各段階を推進し、費用が発生する前に問題を発見します。

対象外：リギングとアニメーション、オーナーが使用権を持たないキャラクター、Blenderでの手動モデリング。

完了条件

1. views/view_front.png、view_left.png、view_back.png、view_right.png がすべて同じサイズで存在し、img2fig crop が終了コード0で実行されていること。
2. 4つのビューをリファレンス画像および互いに比較し、以下の項目を文書で報告していること：すべてのアクセサリーが各ビューで体の正しい側にあり、リファレンスにないものが何も表示されていないこと（特に背面ビュー、ポケット、ベルト、ヘアアクセサリーを注意深く確認）。ポーズと地面のラインがすべてのビューで一致していること。差異があれば img2fig edit で修正し、モデル段階の前にシートを再クロップしていること。
3. models/<provider>/model.glb が img2fig model --execute によって存在すること。
4. img2fig prep が終了コード0で完了し、その orientation が ambiguous ではなく（または前面レンダリングがカメラを向いていることを確認）、prep.dimensions_units[2] が2.9の0.01以内であり、prep.faces_out が --faces 以下であること（三角形化された入力（プロバイダーのGLBなど）の場合）。
5. renders/compare.jpg（上部に入力ビュー、下部にレンダリング）と renders/face.png を確認し、ビューごとに何が一致し、何が一致しないかを報告していること。
6. オーナーが動画を希望した場合、turntable/turntable.mp4 が存在すること（img2fig turntable、終了コード0）。
7. img2fig spend の合計がオーナーの承認した範囲内であること。

支出ルール

• 有料APIを呼び出すコマンド（lookdev、turnaround、edit、model）は、--execute が指定されない限り、計画と見積もりのみを表示します。計画の見積もりをオーナーに提示し、承認を得てください。承認は呼び出しごと、またはオーナーが設定した予算の形で行います。その後、その予算を --budget として渡すか（または IMG2FIG_BUDGET_USD を設定、どちらもなければ上限は5ドル）、予算は作業ディレクトリの台帳（spend.json、img2fig spend で要約）に対して有料呼び出しのたびにチェックされ、超過する場合は呼び出しが拒否されます（終了コード3）。失敗した呼び出しも見積もり額で記録されます。プロバイダーが課金した後に失敗する場合があるためです。
• img2fig estimate --stages lookdev,turnaround,edit,model は、実行全体の価格を見積もります。一般的な桁数：画像呼び出しあたり0.30ドル未満、Tripoモデルあたり0.60ドル、4プロバイダーでのベイクオフで約4ドル。見積もりはやや高めです。画像呼び出しの cost_from_usage_usd はトークンベースの数値です。
• ベイクオフ（--provider all）は、約7回のTripo実行分のコストがかかります。オーナーが明示的に要求した場合、またはこのキャラクターでTripoが明らかに失敗した場合にのみ実行してください。

ワークフロー

img2fig doctor                                    # キーは存在する？ Blender、ffmpegは見つかる？
img2fig lookdev --ref character.png --description "..."            # 計画を表示、承認後 --execute を追加
img2fig turnaround --ref character.png --description "..."         # 最新のルックデブ画像を使用
img2fig crop                                       # views/view_{front,left,back,right}.png を生成
img2fig edit --fix "背面ビュー：リボンの下にある丸い尾を削除。スカートは無地に。"   # 必要な場合のみ
img2fig crop                                       # 再クロップ：最新のシートまたは編集結果を使用
img2fig model                                      # Tripo、計画を表示、承認後 --execute
img2fig prep                                       # 向き調整、正規化、デシメーション、グレード、レンダリング、compare.jpg
img2fig turntable                                  # turntable/turntable.mp4 を生成

すべてのコマンドは --workdir DIR（デフォルトは $IMG2FIG_WORKDIR または ./figure_work）を共有します。入力は、そのディレクトリ内の前のステージの最新ファイルをデフォルトとします。各コマンドは標準出力に1つのJSONオブジェクトを出力します。ok、パス、warning/warnings、next、そして失敗時には error.type、error.message、error.detail（プロバイダーのHTTPステータスとボディ、Blenderまたはffmpegの終了コードとstderrの末尾、ログパス）を読み取ってください。

終了コード：0 OK（ドライランを含む）、1 プロバイダーエラー、2 使用法エラー、3 予算超過、4 キー/バイナリ/パッケージが見つからない、5 Blenderまたはffmpegの失敗、6 結果チェックの失敗（シートが期待されたビューに分割されなかった）、7 内部バグ。

--description の書き方

フィギュアが保持しなければならないものを、キャラクターの視点と見る人の視点を括弧内に記載して列挙します：「彼女の左側（前面ビューでは見る人の右側）にある緑のクローバーのヘアクリップ」。リファレンス画像が実際に示しているものを記述し、生成しようとした意図は記述しないでください。画像モデルがアクセサリーを反対側に移動することがあり、その場合リファレンスが優先されます。

重要なPrepオプション

• --rot auto（デフォルト）は、モデルをフラットシェーディングで0/90/180/270度でレンダリングし、それぞれを view_front.png と比較します。結果が曖昧な場合は、プロバイダーの既知の向きにフォールバックします（現在Tripoのみ既知。それ以外の場合は、フロントレンダリングを確認するように出力されます）。上書きするには --rot DEG を渡します。
• --grade matte（デフォルト）、light（淡い衣装：白をきれいに保つ）、dark（暗い布地を濃くする）、none。--keep-gloss 0.3 は、元の粗さと金属性を、ソースで光沢があった部分に保持します。
• --blush=X,Z（繰り返し可能）は、フィギュアの比率で指定した位置に柔らかい頬紅をペイントします。X,Z は renders/front.png で頬の位置を測定し、img2fig point --x PX --y PY を実行して取得します。負の値は = を使って記述します（--blush=-0.08,0.6）。そうしないとargparseがオプションと解釈します。
• --faces（デフォルト350000）は面数を制限します。法線テクスチャとカラーテクスチャは細かいディテールを保持します。

既知の落とし穴（すべて観測済み）

• 画像モデルがディテールを invent し、3Dモデルがそれを構築する。 ターンアラウンドで、背面にポンポンの尾とジャケットのポケットにバッジが追加されたことがありましたが、キャラクターには元々ありませんでした。3Dモデルは両方を忠実に再現しました。これは画像段階で修正してください（問題ごとに1つの --fix を指定して edit し、その後 crop と model を再度実行します）。メッシュにパッチを当てないでください。最初の編集で別の invent されたものが残ることがあるため（バッジがカップケーキ型の飾りになった）、編集のたびに再度比較してください。
• 小さな特徴がぼやける。 3840x2160のシートの各ビューは約1000ピクセル幅しかないため、ぬいぐるみの顔や指はモデルで柔らかくなります。より大きなシートは利用できません。顔のレンダリングを判断し、鋭い小さな詳細を約束せずにオーナーに伝えてください。
• プロバイダーによって向きが異なる。 TripoのGLBはインポート後 +X 方向を向きます（-90度の回転が必要）。自動チェックで処理されますが、それでもフロントレンダリングを確認してください。
• 全面マットグレードはクリスタルや光沢部分を台無しにする。 キャラクターにクリスタル、メタル、または光沢部分がある場合は、--keep-gloss または --grade none を使用してください。
• 手動で作成された手続き型キャラクターはフィギュア品質に達しない。 Blenderでプリミティブからモデリングされたキャラクターは、有機的な髪をうまく表現できませんでした。画像から3Dへのモデルの方が優れていました。有機的な形状に対して手続き型モデリングにフォールバックしないでください。
• AgX vs Standard。 レンダリングはデフォルトでAgXを使用します。ハイライトはクリップしませんが、淡く白いマテリアルは灰色がかって彩度が低下します。そのため、グレードが彩度を引き上げます。--view-transform standard はリファレンスの色により近くなりますが、明るい領域がクリップします。向きのチェックレンダリングはStandardを使用するため、色の比較は公平に行われます。
• BlenderにおけるsRGBとリニア。 Blender内でPNGのピクセルカラー（Image.pixels）を読み取ると、エンコードされたsRGB値が返され、リニア値は返されません。Blenderスクリプトを拡張する場合は、リニアカラーとして使用する前にデコードしてください。

リソースと境界

• キーは環境変数からのみ取得します：OPENAI_API_KEY（画像ステージ）と FAL_KEY（モデルステージ）。キーを印刷したりファイルに書き込んだりしないでください。
• Blenderは外部バイナリとして（5.2でテスト済み。4.2以降で動作すると予想されます）（PATH上の blender または IMG2FIG_BLENDER）。ターンテーブルにはffmpegが必要です。
• 作業ディレクトリには、生成された画像、モデル、およびオーナーのキャラクターのレンダリングが保存されます。オーナーが要求しない限り、公開、アップロード、またはコミットしないでください。オーナーが他者からライセンスしたキャラクターはプライベートとして扱ってください。
• プロンプトは src/image_to_figure/prompts.py にあります。--prompt-file は、1回の呼び出し用のテンプレートを置き換えます。

3Dプリント

img2fig print は、モデル（デフォルトは figure/figure_clean.glb。--model で任意のGLB、STL、OBJ、PLYを指定可能。--up auto の場合、GLB/glTF/OBJはY-up、STL/PLYはZ-upとして読み取られます）をプリント可能なソリッドに変換します。print エクストラ（uv pip install -e '.[print]'）が必要です。pymeshlab（GPL、依存関係ではありません）もインストールすると、レポートに明示的な自己交差カウントが追加されます。

img2fig print --height 100 --base pedestal                 # ソリッド、FDMまたはレジン
img2fig print --height 130 --base pedestal                 # FDMで薄い部分がある場合：厚くするよりも大きく印刷
img2fig print --height 100 --base pedestal --hollow 2.0    # レジン：壁厚2mm、ドレインホール
img2fig print --model raw_tripo.glb --rot -90 --height 80  # 生のTripo GLBは+X方向を向く

完了条件：コマンドが終了コード0で完了し、checks.printable が真（manifold3dによる水密で有効な2-多様体、正の体積）であること。checks.parts が、緩いパーツを意図的に保持した場合を除き1であること。checks.self_intersecting_faces が測定時に0であること。output.height_mm が --height にベース（台座）を加えたものと1ボクセル以内で一致すること。print/figure_section.png（壁、空洞、ドレインホール）と figure_preview_*.png レンダリングを確認し、warnings のすべてのエントリ、特に薄い部分（checks.wall_thickness：thin_part_volume_fraction、largest_thin_parts とその位置（mm）、relief_volume_fraction は表面の細かいディテールで、報告されるが厚くされない）とその対処法を報告していること。--thicken が使用された場合、プレビューレンダリングを厚くしていない実行と比較し、顔、髪、アクセサリーに新しい隆起がないことを確認すること。Blenderなし（プレビューなし）の場合は、thicken.added_mm3 が wall_thickness_before.thin_part_volume_mm3 と同程度であること（隆起はそれをはるかに超える追加ボリュームとして現れる）と断面画像を確認すること。

仕組み：サーフェスがボクセル化され（デフォルトのボクセルサイズ = 高さ / 500）、最も小さな形態学的クロージング（最大8ボクセル、voxelize ステップで gap_closing_voxels を報告）でギャップがシールされ、内部が充填されるため、開いたエッジ、重なり合うシェル、自己交差が消失します。次に符号付き距離場がベースカット、台座、中空化、ドレインホールを処理します。マーチングキューブ、Taubinスムージング、manifold3dが最終メッシュを生成します。約1ボクセルより小さい詳細は失われ、クロージングギャップより近い部分は融合します。

オプション：--min-wall（デフォルト1.0mm。レジンはそれより低く設定可能、FDMは通常1.2以上が必要）は、何を薄いと見なすかを設定します。--thicken（デフォルトではオフ）は、薄い部分をその厚さまで成長させます（下記参照）。--fragments merge|remove|keep と --merge-gap（デフォルト2mm）は、浮遊部分を決定します。マージモードでは、ギャップ内の部分はブリッジで結合され、より遠くの部分は保持され報告され、静かに削除されることはありません。1mm3未満の小さな破片は常に削除されます。--base flat|pedestal|none。--hollow WALL と --drain-hole は、各空洞の下から1つの穴を開けます（20mm3未満のポケットは中空化されずに残ります）。--color は、フルカラーサービス向けにモデルのテクスチャから頂点カラーのPLYを書き込みます。STLと3MFは単色です。

薄い部分。レポートは、薄い部分（厚い本体から --min-wall より突き出ているシート、フィン、ストランド、リボン、コードで、両方の表面が互いに近いもの）と、表面レリーフ（厚い本体上のエンボスライン、ストランドのエッジ、小さなドット、凸状エッジ）を区別します。FDMの場合は、より大きく印刷することを優先します。すべての薄い部分はフィギュアとともにスケールします（100mmで0.9mmのリボンは130mmで1.17mmになります）。形状は変更されず、スライサーの薄肉処理（Arachne壁、「薄壁を検出」）が残りのほとんどを印刷します。壁の下の体積の数パーセントの端数は正常であり問題ありません。サイズが固定されており、いくつかの薄い部分（リボンのループ、アホゲ、吊り下げコード、スカートの裾）を確実に印刷する必要がある場合に --thicken を使用します。これは薄い部分のみを、それぞれ約 --min-wall まで成長させ、先端を鈍らせます。レリーフは決して成長しません。--thicken 後も薄い部分が残る場合、警告はその旨を伝え、別の実行ではなく、より大きく印刷するかスライサー設定を推奨します。定義の境界：--min-wall より高く本体から隆起するレリーフ（高くて細い頂部、深くエンボスされたストランド）は薄い部分としてカウントされ、鈍らされます。2つの厚い部分の間のギャップにまたがる短くて薄いウェブ（最大約2倍の --min-wall 幅）はレリーフとして報告され、スライサーで落とされて穴が残る可能性があるため、スライサープレビューでウェブを確認してください。成長は全方向に行われるため、--thicken は先端をわずかに長くし、--min-wall よりも互いに近い薄い部分を融合させる可能性があります。

構築中に観測されたこと：バイナリ距離場は、結果がスムージングされない限り（Taubin、--smooth、デフォルト10イテレーション、体積を保持）、目に見えるテラスを残します。頂点を元のサーフェスに投影し直す代わりに、薄いシートを折り返してしまうため、この方法は採用されませんでした。スムージングとメッシュ簡略化は、どちらも薄い領域に自己交差を導入する可能性があります。コマンドは、チェックがクリーンになるまでスムージングを減らし、許容差を厳しくし、最終的に採用したものを報告します（smooth_and_simplify ステップ）。中空化は、排水不可能なポケットをソリッドのままにしておかなければなりません。そうしないと密閉された空隙になります。実際の画像から3Dへのフィギュアでは、2つの対称な120mm3のピースが本体から1.3mm離れた別々のシェルとしてモデル化されていました。初期バージョンでは、1mmのマージギャップのすぐ外側にあったため、それらが削除されました。そのため、現在は遠くのパーツは保持され報告されるようになっています。実際の100mmのフィギュアで --min-wall 1.2 の場合、初期の --thicken は顔、髪、リボン、ぬいぐるみのアクセサリーを小さな丸い隆起で覆いました。これは、1.2mmのボールが到達できないすべてのものを薄いと見なし、ストランドのエッジ、エンボス状のまつ毛やドットなどの浅いレリーフも含め、それらをすべて各方向に0.6mm成長させたためです（体積5.5%増加）。厚くしない場合と比較すると…（元のSkill.mdが途中で切れています）

...（以下、原文のSkill.mdに従い翻訳を継続）