img2threejsで何が変わったか
画像から編集できるThree.jsコードへ
「画像から3Dをつくる」と聞くと、完成したメッシュファイルが一つ落ちてくると思うかもしれません。
img2threejsが選んだ答えは、少し違います。参照画像を観察し、部品の仕様に分け、検証しながら、名前のついたThree.jsのコードへ組み立てる。検索では image2threejs と書かれることもありますが、公式の表記は img2threejs です。
きれいな一枚より、あとで触れる部品を返す
3Dの仕事では、最初の見た目がよくても、その後に「この輪だけ色を変えたい」「このふたを開けたい」「商品ごとに寸法を変えたい」が来ます。ここで一枚のメッシュだけを受け取ると、別のツールで分解し直すか、最初から作り直すことになります。
img2threejsは、そこを最初から分けて作ります。丸みのある箱、円柱、球、リング、押し出し形状などのプリミティブを、意味のある名前を持つグループとして配置し、マテリアル、回転軸、ソケット、コライダーまで仕様に残します。
INTERPRETATION「画像を3Dにする」のではなく、「画像に写る関係を、コードで再編集できる形にする」。この言い換えが、プロジェクトの価値を一番正確に表します。
中身は、4つの動きに分かれている
一枚の写真をいきなりコードへ変換しない。観察と判断を途中の成果物にしてから、次の工程へ渡します。
-
01
ANALYZE
見えている証拠を拾う
輪郭、取り付け部、穴、継ぎ目、材質の境界、光る部分を観察します。写真から分からない裏側は、分からないまま不確実性として残します。
-
02
SPEC
部品の仕様にする
ObjectSculptSpecというJSONに、部品ツリー、マテリアル、変形、ソケット、品質条件を記録します。薄い仕様のままコードへ進まないゲートがあります。
-
03
BUILD
現在のパスだけ生成する
ブロックアウト、構造、形、マテリアル、表面、照明、インタラクション、最適化を順番に進めます。毎回、モデル全体を読み直して作り直す設計ではありません。
-
04
REVIEW
画像とレンダーを見比べる
ブラウザでレンダーし、参照画像との比較シートを作ります。見た目の判断はエージェントの視覚レビューが担い、決められたゲートを通らない限り次へ進みません。
出力は、ファイル一つではない
公式READMEが示す成果物は、単なる画像やバイナリではありません。レビューの履歴を含む仕様と、Three.jsのファクトリがセットになります。つまり、差分を読める。レビューできる。自分のアプリへ組み込める。
ObjectSculptSpec
部品の階層、材質、繰り返し、ソケット、レビュー履歴を持つJSON仕様。なぜその部品を作ったかを、コードの外にも残せます。
Three.js factory
THREE.Group を組み立てるTypeScript。部品が名前を持つので、色、位置、親子関係、アニメーションの入口を後から編集できます。
レンダーと比較シート
参照画像と生成結果を並べた確認材料。文章だけで「似ている」と言わず、どこが足りないかを次の修正へ渡します。
reference.png
↓ observe / plan
ObjectSculptSpec.json
├─ components: body, hinge, ring
├─ materials: matte, metal, emissive
└─ runtime: pivots, sockets, colliders
↓ compile
createObjectNameModel(spec, options): THREE.Group
↓ integrate
browser scene / interaction / animation上は構造をつかむための簡略図です。実際のファクトリ名や部品名は対象物で変わります。
メッシュよりコードが強い場面、弱い場面
コード生成は、すべての3D制作を置き換える提案ではありません。後工程の種類で、向き不向きがはっきりします。
| 後工程 | コード中心の出力 | 判断 |
|---|---|---|
| 色や材質の変更 | マテリアル名や値を編集しやすい | 相性がよい |
| ヒンジや部品のアニメーション | pivot / socketなど、動かす場所を残せる | 相性がよい |
| Gitでのレビュー | TypeScriptとJSONの差分を読める | 相性がよい |
| 見えない裏側の正確さ | 一枚の画像からは、推測の域を出ない | 追加資料が必要 |
| 手作業の彫刻・精密なトポロジー | コード生成の守備範囲とは異なる | Blender等を検討 |
FACT 公式README自身も、単一画像は隠れた面や正確な形状を保証できず、キャラクターは写実的な人物モデルではなくスタイライズされた再構成だと説明しています。
強さは生成より、止まれることにある
画像生成に慣れていると、最初の出力がそれらしく見えれば成功と思いがちです。ところが3Dでは、正面から似ていても、横を向けると厚みがない、部品が一つに潰れている、関節が動かないということが起きます。
img2threejsは、その失敗を「完成」と呼ばないために、各パスの前に条件を置きます。実際のレンダー、比較シート、しきい値を満たす視覚レビュー、識別に重要な特徴の確認。この組み合わせがそろって初めて、次のパスへ進みます。
決定的なPythonスクリプトが検証・記録を担当し、エージェントのトークンは仕様の判断、コード、比較画像の視覚確認へ寄せる。ここが、単に「AIに3Dコードを書かせる」流れとの違いです。
向いている画像は、情報が多い画像ではない
大切なのは解像度だけではありません。輪郭と部品の関係を読み取れるかどうかです。
最初に選びやすい
- 対象物が一つで、背景から分離している
- 正面・側面・上面など、輪郭を確認できる
- 硬い表面や機械部品など、形の境界が明確
- Webのプロダクトビューアや試作で使いたい
先に追加資料を用意する
- 隠れた面、重なり、反射で形が見えない
- 植物・動物・人物など、単純なプリミティブにしにくい
- 大規模なシーンや、複数物体の相対位置が主役
- 最終納品に精密なトポロジーや他エンジン出力が必要
ここで「向かない」と書くのは、失敗を責めるためではありません。見えないものを見えたことにしないほうが、作り直しの時間を減らせるからです。公式ドキュメントが不確実性を記録する設計を選んでいるのも、そのためです。
試すなら、一つの硬い物体から
背景の少ない卓上物を一つ選び、できれば正面・側面・上面の情報を用意します。
公式GitHubの SKILL.md と入力検証の説明を確認してから、Agent Skillとして導入します。
最初の出力を信じ切らず、正面だけでなく斜めから回し、欠けた部品と不自然な厚みを記録します。
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs
python3 forge/stage1_intake/probe_image.py ./reference.png
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality上は公式READMEにあるローカル導入・検証の入口を短く抜き出したものです。実行場所、画像、仕様ファイルは自分の環境に合わせて確認してください。リポジトリを取得しただけで、モデル生成が終わるわけではありません。
導入前に、二つの境界を確認する
公式リポジトリとホストを分ける
上流の GitHubリポジトリ は、READMEとLICENSEでApache License 2.0を掲げています。一方、img2threejs.org は独立したホスト型インターフェースで、フッターでは上流をMITライセンスと記載しています。
同じ名前に見えても、ローカルのオープンソースSkillと、独立ホストの利用規約・生成物の扱いを同一視しないでください。
「無料」と「安い」は別に考える
上流コードはPython 3.10以上の標準ライブラリ中心ですが、レビューに使うAgentやモデルのコストは別に発生します。公式のトークン資料も、1オブジェクトあたり約8万〜18万トークンを測定済みベンチマークではない工学的推定として示しています。
また、確認日にはGitHub Releasesにv1.5 beta、CHANGELOGには1.4.xのcurrent release lineという表記が併存していました。導入時は、タグとリリースノートを固定して使うのが安全です。
画像は、完成品ではなく最初の証拠になる。
img2threejsの面白さは、写真が立体になることだけではありません。写真を見て、部品を名づけ、仕様にし、比較して、足りなければ止まる。その判断の履歴までコードの近くに置けることです。
最初に試すなら、複雑な人物や街ではなく、机の上の一つの道具がいい。見えない面を無理に埋めず、どこまでが画像の証拠で、どこからが推測かを残す。その小さな検証が、ブラウザの3Dを「眺める素材」から「改造できる部品」へ変えていきます。