跳到主要内容
AI教程

使用 Procedura 从文本构建可编辑的 3D 模型

学习使用 Procedura 将文本提示词或参考图像转换为可编辑的 OpenSCAD 程序和 3D 网格。

AI我搜编辑部阅读约 16 分钟
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 modeling example

前置条件与安装

克隆代码仓库并运行依赖项安装程序：

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 的其余功能无需它也能运行。安装程序还会保留现有的 .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 传输方式

要通过 Gemini 的原生 GenAI 路径使用它，请设置 GEMINI_API_KEY 和 GEMINI_BASE_URL，然后在模型标识符前添加 gemini: 前缀：

PROCEDURA_MODEL=gemini:gemini-3-pro-preview

此路径支持 thinkingConfig 和一等思考部分等原生功能。

可选的图像生成

除非你明确配置或请求图像 API，否则 Procedura 不会调用它。要启用生成式参考图像，请添加图像模型：

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"

对于不便在 shell 中用引号包裹的长描述，可以将提示词保存到文件：

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 处理。
  • --assembly 会添加真实的配合接口，而不只是依赖重叠几何体。
  • --paint 使用视觉调用为命名部件分配 PBR 材质属性。
  • --motion 规划关节运动并导出 OpenUSD 数据。
  • --motion-urdf 还会创建 URDF 文件和各连杆网格。
  • --max-steps 12 最多允许进行 12 个优化循环。每个循环都会执行渲染、评审、修补和门控操作，并消耗两次 LLM 调用。

较长的规划调用可能表示流水线正在执行实质性工作。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 会在没有规划阶段的情况下仅执行一次生成调用，并且必须提供参考图像：

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 使用的是支持 Manifold 的 OpenSCAD，而不是仅支持旧版 CGAL 的构建。

总结

Procedura 将语言模型规划与程序化 CAD、网格编译、视觉优化、材质和可选关节运动结合起来。首先配置端点并使用简单文本提示词，然后随着质量要求提高，逐步添加参考图像、3D 反馈、装配特征、上色和运动功能。由于主要交付物是可编辑的源代码，生成后的对象仍然可以检查和复用。

Procedura 采用 MIT 许可证。项目文档、论文及更多详情可在 Procedura 项目页面查看。