メインコンテンツへ移動
AIチュートリアル

Proceduraでテキストから編集可能な3Dモデルを作成する

Proceduraを使って、テキストプロンプトや参照画像から編集可能なOpenSCADプログラムと3Dメッシュを作成する方法を学びます。このチュートリアルでは、インストール、モデル設定、基本的な生成、高品質なワークフロー、マテリアル、可動化、バッチ処理、ステージの再実行、ブラウザベースのStudioについて解説します。

約20分で読了
Proceduraでテキストから編集可能な3Dモデルを作成する

Proceduraとは？

Proceduraは、テキストプロンプトを編集可能なプロシージャルアセンブリに変換するエージェント型3Dモデリングパイプラインです。点群や三角形メッシュだけを生成するのではなく、名前付きパーツが型付きメイトによって接続された、パラメトリックなOpenSCADプログラムを書き出します。ソースを確認して編集し、再コンパイルできます。

Procedura

このシステムは凍結された大規模言語モデルを使用し、専用の3D学習は必要ありません。テキストだけで実行を開始できるほか、既存の参照画像を再構成したり、別途設定した画像モデルで参照画像を生成したりできます。

Proceduraは--paintでパーツごとのPBRマテリアルを割り当て、--motionおよび--motion-urdfで関節オブジェクトをOpenUSDとURDFに書き出すこともできます。

主な機能

  • 編集可能なプロシージャル出力：コンパイル済みのジオメトリに加え、OpenSCADソースコードも生成します。
  • パーツ単位の生成：オブジェクトを計画し、名前付きコンポーネントを段階的に構築します。
  • 参照画像の再構成：既存の画像を入力として受け付け、忠実度を大幅に向上させます。
  • 3Dフィードバック：新しいパーツを生成する前に、現在のビルドをレンダリングできます。
  • アセンブリ対応モデリング：公称寸法を共有するペグ、ソケット、ボルトパターン、スナップなどの嵌合機能に対応します。
  • 反復的な改良：レンダー、批評、パッチ、ゲートのサイクルを使って下書きを改善します。
  • マテリアル：ビジョンベースの処理により、パーツごとに色、メタルネス、粗さを割り当てられます。
  • 関節動作：動作を計画し、OpenUSDとURDFファイルを書き出し、必要に応じてNVIDIA Isaac Simで物理検証を行えます。
  • 追跡可能な実行：プロンプト、応答、ツール呼び出し、ゲート判定、中間レンダー、編集内容を保存します。
  • Web Studio：実行を作成し、その成果物を確認するためのブラウザーインターフェースを提供します。
Proceduraの3Dモデリング例

前提条件とインストール

リポジトリをクローンし、依存関係のインストーラーを実行します。

git clone git@github.com:SpatiaOS/Procedura.git
cd Procedura
bash scripts/install-deps.sh

インストーラーは、Bun 1.3以降、プロジェクトパッケージ、Manifold対応のOpenSCADスナップショット、Blender、スターター用の.envファイルをセットアップします。デフォルトでは、Bunは~/.bun、OpenSCADは~/opt/openscad、Blenderは~/opt/blender/に配置されます。

スクリプトは繰り返し安全に実行できます。既存の動作するコンポーネントはそのまま残されます。オプションモードを使うと、依存関係の確認、Blenderのスキップ、別のインストール先の指定ができます。

bash scripts/install-deps.sh --check
bash scripts/install-deps.sh --no-blender
PREFIX=/opt bash scripts/install-deps.sh

--checkは、何もインストールせずに不足している要件を報告します。--no-blenderは約350 MBのBlenderのダウンロードをスキップしますが、複数のレンダリング機能とフィードバック機能にはBlenderが必要です。

OpenSCADはManifoldバックエンドに対応している必要があります。古いディストリビューションのパッケージではCGALにフォールバックし、処理が桁違いに遅くなる場合があります。Proceduraは起動時に--backendの有無を確認し、通常は互換性のないビルドの使用を拒否します。その遅延を意図的に受け入れる場合に限り、PROCEDURA_ALLOW_CGAL_OPENSCAD=1を設定してください。

インストーラーはNVIDIA Isaac Simをインストールしません。Isaac Simが必要なのは、モーションワークフローに関連する物理検証だけです。それ以外のProceduraの機能はIsaac Simなしで動作します。インストーラーは既存の.envファイルも保持します。

LLMエンドポイントの設定

ProceduraにはAPIキーもホスト型推論バックエンドも含まれていません。生成された.envファイルを開き、エンドポイントとキーを指定します。

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
PROCEDURA_MODEL=gpt-5.2

エンドポイントは、サーバー送信イベントに対応したPOST {base}/chat/completionsをサポートしている必要があります。利用可能な選択肢には、OpenAI API、OpenRouter、企業ゲートウェイ、vLLM、Ollama、LM Studioをベースとするローカルサーバーなどがあります。

モデル選択は文字列なので、設定したエンドポイントが提供する任意のモデル識別子を使用できます。動作確認済みのプリセットとモデル解決ルールはsrc/config/models.tsに記載されています。

ネイティブGeminiトランスポートを使用する

ネイティブGenAIパスでGeminiを使用するには、GEMINI_API_KEYとGEMINI_BASE_URLを設定し、モデル識別子の先頭にgemini:を付けます。

PROCEDURA_MODEL=gemini:gemini-3-pro-preview

このパスでは、thinkingConfigやファーストクラスの思考パーツなど、ネイティブ機能を利用できます。

画像生成（オプション）

Proceduraは、明示的に設定または要求しない限り画像APIを呼び出しません。参照画像の生成を有効にするには、画像モデルを追加します。

PROCEDURA_IMAGE_MODEL=gpt-image-1

画像モデルはOPENAI_BASE_URLとOPENAI_API_KEYを再利用します。--imageも画像モデルの設定もない場合、実行はテキストのみで行われ、画像生成料金が暗黙に発生することはありません。

最初のモデルを作成する

出力ディレクトリは必須です。-oまたは--outputで指定し、その後にテキストプロンプトを渡します。

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt "a brutalist brass daybed with tapered legs"

このデフォルトワークフローでは、コンポーネントの計画を立て、それらを一つずつ構築し、全体の形状を改良します。テキストのみで動作し、画像APIは使用せず、パーツごとのドラフトループにBlenderを組み込みません。実用性を保ちながら最も低コストな構成です。

サポートされているすべてのオプションを確認するには、次を実行します。

bun run scripts/procedura.ts --help

参照画像で忠実度を高める

参照画像の提供は、プロジェクトで確認された個別の改善策の中で、忠実度を最も大きく向上させます。手元にある画像を説明的なプロンプトとともに渡します。

bun run scripts/procedura.ts -o outputs/daybed \
  --image ref.png \
  --prompt "a brass daybed with tapered legs"

または、画像モデルを指定して、この実行中に参照画像を生成することもできます。

bun run scripts/procedura.ts -o outputs/daybed \
  --image-model gpt-image-1 \
  --prompt "a brass daybed with tapered legs"

シェルで引用しにくい長い説明は、プロンプトをファイルに保存します。

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt-file my_prompt.txt

完全な品質パイプラインを実行する

完全な実行では、参照画像からの再構築、視覚的フィードバック、組み立て用機能、マテリアル、モーション、そしてより長い改良予算を組み合わせられます。大規模な計画では、より長いLLMの制限時間が必要になる場合があるため、まず両方のタイムアウト変数を引き上げます。

export PROCEDURA_LLM_TIMEOUT_MS=1800000
export PROCEDURA_LLM_DEADLINE_MS=1800000

bun run scripts/procedura.ts -o outputs/gripper \
  --image gripper_ref.png \
  --3d-feedback \
  --assembly \
  --paint \
  --motion --motion-urdf \
  --max-steps 12 \
  --prompt "a two-finger parallel robot gripper"

各オプションにはそれぞれ固有の役割があります。

  • --3d-feedbackは、各パーツを作成する前に、現在のアセンブリをレンダリングしたビューを生成器に渡します。パーツごとにBlenderのパスが1回追加されます。
  • --assemblyは、重なり合うジオメトリだけに頼らず、実際にかみ合うインターフェースを追加します。
  • --paintは、ビジョン呼び出しを使用して、名前付きパーツにPBRマテリアルのプロパティを割り当てます。
  • --motionは、関節動作を計画し、OpenUSDデータを書き出します。
  • --motion-urdfは、URDFファイルとリンクごとのメッシュも追加で作成します。
  • --max-steps 12は、最大12回の改良サイクルを許可します。各サイクルではレンダー、批評、パッチ適用、ゲート処理を実行し、LLM呼び出しを2回消費します。

計画処理に時間のかかる呼び出しが発生する場合、パイプラインが実質的な処理を行っている可能性があります。READMEでは、PROCEDURA_MAX_PARTSを制限するのではなく、タイムアウトを延長することを推奨しています。パーツ数の制限は、速度と引き換えにモデル品質を下げるためです。

改良を再開、再作成、またはスキップする

Proceduraは、既存の出力ディレクトリで改良ループを続行できます。プロンプトを省略し、新しいステップ予算を指定します。

bun run scripts/procedura.ts -o outputs/daybed --max-steps 12

既存のドラフトを破棄して作り直すには、--redoを追加します。

bun run scripts/procedura.ts -o outputs/daybed \
  --prompt "a brutalist brass daybed" \
  --redo

ドラフトだけが必要な場合は、--no-refineを使用します。Proceduraはそのドラフトを最終出力ファイルに昇格させます。以前のモノリシックなワークフローでは、--one-shotにより計画段階なしで1回の生成呼び出しを行えますが、参照画像が必要です。

bun run scripts/procedura.ts -o outputs/daybed \
  --one-shot \
  --image ref.png \
  --prompt "a brutalist brass daybed"

出力ディレクトリを理解する

完了した実行には、次のアーティファクトが含まれる場合があります。

  • image.png：提供または生成された参照画像。
  • plan.json：計画されたパーツ構成。
  • _parts/NN_name/：増分生成用のパーツごとのアーティファクト。
  • draft.scadおよびdraft.obj：初期のプロシージャルソースとコンパイル済みメッシュ。
  • final.scadおよびfinal.obj：改良済みの納品物。
  • final_summary.txt：最終判定と、出荷された接続情報。
  • preview_final/：最終メッシュをBlenderでアンビエントオクルージョンレンダリングしたもの。
  • final_materials.json：--paintで生成された、パーツごとの色、メタルネス、粗さ。
  • final_painted.scad、final_painted.obj、final_painted.mtl：ペイント済みモデルのアセット。
  • preview_painted/：ペイント済みモデルのPBR Cyclesレンダー。
  • motion/final_motion.usda：OpenUSDの関節動作出力。
  • motion/urdf/およびmotion/links/：要求した場合のURDFデータとリンクごとのメッシュ。
  • _trajectory/procedura-id.jsonl：プロンプト、応答、ツール呼び出し、ゲート判定。
  • _refine_steps/step_NNN/：各改良サイクルのレンダー、診断、編集、コンパイルデータ。

Proceduraが書き出すすべてのOBJファイルは、単位バウンディングボックスに正規化されます。STLの書き出しはオプションで、--export-stlで有効にできます。

マテリアルまたはモーションを個別に再実行する

ペイントとモーションは完成済みの実行ディレクトリを対象に動作するため、ジオメトリを再生成せずに、別のモデルで各段階を再実行したり、失敗後に再試行したりできます。

bun run scripts/paint.ts RUN_DIRECTORY --model MODEL_KEY --refine-steps 2
bun run scripts/motion.ts RUN_DIRECTORY --model MODEL_KEY --urdf --no-validate

オプションの--no-validateフラグは、モーションの検証をスキップします。Isaac Simを利用できない場合や、書き出された関節動作ファイルだけが必要な場合に便利です。

データセットを処理する

複数のケースには、JSON Lines形式のプロンプトファイルとバッチスクリプトを使用します。

bun run scripts/batch.ts \
  --prompts cases.jsonl --images \
  --incremental \
  --motion --validate --urdf \
  --max-steps 3 \
  --parallel 2 \
  --out-root outputs/batch_v1

この論文のワークフローでは、形状と関節構造をまとめて生成し、その後、完成した各ケースを個別にペイントします。これにより、ペイントの失敗によって完成済みのジオメトリが無効になるのを防げます。

bun run scripts/paint.ts outputs/batch_v1/CASE_ID

--motion --validateを使用する場合は、並列数を2程度に維持してください。複数のヘッドレスIsaac SimインスタンスによってGPUメモリを使い果たす可能性があります。リファインのみのバッチでは、約8～12ワーカーまで対応できる場合がありますが、各サイクルでBlenderを起動するため、APIのレート制限より先にメモリがボトルネックになることがあります。

実行アーティファクトを比較する

Proceduraには、複数の設定のレンダー、ソースファイル、メトリクス、軌跡を並べて表示できるローカル結果サーバーが含まれています。

bun run scripts/results-server.ts \
  --root a=outputs/run_a \
  --root b=outputs/run_b

プロンプト、ステージごとのモデル、リファイン予算、3Dフィードバックやアセンブリ対応生成などのオプションをテストする際に便利です。

Procedura Studioを使う

Studioは、同じパイプライン向けのWebフロントエンドです。プロンプト、任意の参照画像、プリセット、ステージごとの設定を指定して実行を構成できます。実行中は、パーツの生成状況を確認しながら、計画、パーツのアーティファクト、リファイン履歴、最終3Dメッシュ、マテリアル、関節構造を調べられます。

cd web
bun install
bun run start

http://localhost:8080を開いてください。StudioはリポジトリのルートからCLIを起動し、同じ.envを読み込むため、別途API設定を用意する必要はありません。

高度なヒント

  1. まず低コストで始め、その後に品質機能を追加する。画像生成、視覚的フィードバック、ペイント、モーションを有効にする前に、デフォルトのテキストのみの実行でエンドポイントとプロンプトを検証してください。
  2. 可能な限り実物の参照を使う。このプロジェクトでは、--imageが単独で最も大きな忠実度向上をもたらす要素だと位置付けています。
  3. ステージごとにモデルを上書きする。--agent-model、--scad-model、--paint-model、または--motion-modelを使うと、個々のステージに異なるエンドポイントモデルキーを指定できます。
  4. 成功したジオメトリを保持する。失敗時に全体の再構築を強制したくない場合は、ペイントとモーションを別々の後処理ステージとして実行してください。
  5. 並列実行中のメモリを監視する。APIエンドポイントがより多くの同時リクエストに対応できる場合でも、BlenderとIsaac Simはかなりのメモリを消費することがあります。
  6. デバッグ時は軌跡を調べる。JSONL形式の軌跡とステップごとのリファインディレクトリには、プロンプト、モデルの応答、編集内容、コンパイラの結果、ゲート判定が記録されています。
  7. OpenSCADバックエンドのサポートを確認する。生成が停止したように見える場合は、Proceduraが古いCGAL専用ビルドではなく、Manifold対応のOpenSCADを使用していることを確認してください。

まとめ

Proceduraは、言語モデルによる計画と、プロシージャルCAD、メッシュコンパイル、視覚的リファイン、マテリアル、任意の関節構造を組み合わせています。設定済みのエンドポイントと簡単なテキストプロンプトから始め、品質要件に応じて参照画像、3Dフィードバック、アセンブリ機能、ペイント、モーションを追加してください。主な成果物は編集可能なソースコードであるため、生成後も作成されたオブジェクトを検査し、再利用できます。

ProceduraはMITライセンスで提供されています。プロジェクトのドキュメント、論文、その他の詳細はProceduraプロジェクトページから確認できます。