Infinigen 安装完全指南：Python 包、Blender 内嵌与 Docker 三种部署方式详解-平芜编程栈

计算机视觉
数据增强
媒体生成

【免费下载链接】infinigen

Infinite Photorealistic Worlds using Procedural Generation

项目地址：https://gitcode.com/gh_mirrors/in/infinigen

导读

Infinigen 是普林斯顿大学视觉实验室开源的程序化三维场景生成器，可生成无限逼真的自然场景、室内场景与仿真资产。本文将基于官方 Installation.md 文档，并结合仓库内 setup.py、pyproject.toml 等真实源码，完整讲解三种安装路线：Python 包安装（默认、无头执行）、Blender 内嵌 Python 安装（可在 Blender UI 中交互使用）以及Docker 容器安装。读完本文，你将能够根据自身硬件（Linux / Mac / Windows / WSL2）与功能需求（Minimal / Terrain / CUDA / OpenGL / Fluid）选择正确配置，并成功跑通 Hello World 场景与 Hello Room 场景。

一、安装方式总览与平台支持矩阵

Infinigen 提供两种安装形态，二者核心区别在于infinigen包被装进哪个 Python 环境：

Python Module（默认推荐）
- 只能无头（headless）执行，无法打开 Blender 图形界面；
- 将infinigen包安装到用户自己的 Python 环境；
- 以 pip 依赖方式安装bpy（Blender 的 Python 绑定），对应 pyproject.toml 中的"bpy==4.2.0"。
Blender Python Script
- 可以在 Blender UI 中交互式使用 Infinigen；
- 将infinigen包安装到Blender 自带的 Python 解释器中，而非用户自己的 Python；
- 使用标准独立安装（standalone）的 Blender 程序。

无论选择哪种方式，不同操作系统对若干功能集的支持程度有差异，官方支持矩阵如下：

功能集	用于生成…	Linux x86_64	Mac x86_64	Mac ARM	Windows x86_64	Windows WSL2 x86_64
Minimal Install（最小安装）	物体与材质	支持	支持	支持	实验性	实验性
Terrain (CPU)（地形- CPU）	完整场景	支持	支持	支持	不支持	实验性
Terrain (CUDA)（地形- GPU）	加速、更快出视频	支持	不支持	不支持	不支持	实验性
OpenGL Annotations	额外的训练标注数据	支持	支持	支持	不支持	实验性
Fluid Simulation（流体模拟）	火焰、模拟水面	支持	实验性	实验性	不支持	实验性

文档明确提示：表中标为experimental的字段表示"可行但未经测试且缺少文档"，标为no的字段则表示"大体上可能实现但尚未落地"。因此：

想运行 Hello World 演示（生成完整自然场景）或生成完整场景的用户，应选择Python Module + Terrain (CPU)；
想在 Blender UI 中使用 Infinigen 资产、或自行开发新资产的用户，应选择Blender-Python 脚本 + Minimal Install。

其余可选功能（相机配置、地面真值标注、流体模拟）可参阅 Configuring Infinigen、Ground Truth Annotations 与 Generating Fluid Simulations。

二、安装前的系统依赖（Dependencies）

官方文档推荐先安装 anaconda 或 miniconda（平台安装说明可参考 miniconda 官方文档），然后按平台安装系统级依赖。

Ubuntu / Debian / WSL 等 Linux 系：

sudo apt-get install wget cmake g++ libgles2-mesa-dev libglew-dev libglfw3-dev libglm-dev zlib1g-dev

Mac ARM（M1/M2/…）：

arch -arm64 brew install wget cmake llvm open-mpi libomp glm glew zlib

Mac x86_64（Intel）：

brew install wget cmake llvm open-mpi libomp glm glew zlib

没有 sudo 权限时的 Conda 方案：

conda install conda-forge::gxx=11.4.0 mesalib glew glm menpo::glfw3 export C_INCLUDE_PATH=$CONDA_PREFIX/include:$C_INCLUDE_PATH export CPLUS_INCLUDE_PATH=$CONDA_PREFIX/include:$CPLUS_INCLUDE_PATH export LIBRARY_PATH=$CONDA_PREFIX/lib:$LIBRARY_PATH export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:$LD_LIBRARY_PATH

源码佐证：这些依赖正是编译期真正需要的。查看 compile_terrain.sh 可以看到，地形组件需要g++/clang++、OpenMP（-fopenmp）、GLM 头文件（-I../datagen/customgt/dependencies/glm）等；而 Dockerfile 中安装的libgles2-mesa-dev libglew-dev libglfw3-dev libglm-dev zlib1g-dev与上述清单完全对应，说明这套依赖是构建链路的硬性要求。

三、Python 包方式安装（默认路线）

3.1 Developer Install（完整开发安装）

官方推荐使用 uv 管理环境。安装 uv 后执行：

git clone https://github.com/princeton-vl/infinigen.git cd infinigen git submodule update --init uv venv uv pip install -e ".[dev,terrain,vis]" uv run pre-commit install

这条命令实际做了三件事，可以从 pyproject.toml 中拆解：

[dev]可选依赖：pre-commit、pytest系列、ruff==0.14.5、sphinx文档构建工具链等，供开发者提交代码与跑测试使用；
[terrain]可选依赖：infinigen[infinigen1]、landlab==2.6.0、pyrender<0.2.0、setuptools<81（landlab 仍依赖pkg_resources），对应地形完整生成能力；
[vis]可选依赖：einops、numba（用于地面真值可视化）、pyglet<2（供trimesh_scene.show()使用）。

同时注意 pyproject.toml 中的硬性约束：requires-python = "==3.11.*"，即仅支持 Python 3.11；核心依赖bpy==4.2.0（Blender 4.2 的 Python 绑定）会在 pip 阶段自动拉入。

3.2 Minimal Install（最小安装）

如果不生成地形或 OpenGL 地面真值，只做 Infinigen-Indoors（室内）或单物体生成，官方提供最小安装以规避 C++ 编译与部分易出问题的依赖（如 landlab）：

INFINIGEN_MINIMAL_INSTALL=True uv pip install -e .

原理深入：查看 setup.py 可知，INFINIGEN_MINIMAL_INSTALL环境变量默认即为True（第 22 行）。当它为True时：

跳过ensure_submodules()，不会自动拉取 .gitmodules 中声明的子模块（infinigen_gpl、OcMesher以及 customgt 的 eigen/argparse/cnpy/glm/json/stb/glfw 等）；
跳过make terrain、make customgt等原生编译步骤（第 58-62 行）；
不注册bnurbs与infinigen.terrain.marching_cubes两个 Cython 扩展（第 66-84 行）。

因此 Minimal 模式既不碰 C++ 也不碰 Cython，安装速度最快、依赖最少，是室内与单体资产生成场景的推荐起点。

3.3 Legacy (1.0) 生成管线安装

仓库中infinigen_examples.generate_nature/generate_indoors属于遗留 1.0 管线，需要额外的依赖与原生构建（地形、marching_cubes扩展、git 子模块），默认 2.0 安装不会带入。1.0 使用pip（而非uv）安装，且必须先完成上文系统依赖部分：

git clone --recurse-submodules https://github.com/princeton-vl/infinigen.git cd infinigen conda create --name infinigen python=3.11 conda activate infinigen INFINIGEN_MINIMAL_INSTALL=False INFINIGEN_INSTALL_TERRAIN=True pip install -e ".[infinigen1]"

如需额外编译 OpenGL 地面真值标注器，在上述命令中再追加环境变量：

INFINIGEN_INSTALL_CUSTOMGT=True pip install -e ".[infinigen1]"

pyproject.toml 中[infinigen1]可选依赖解释了"1.0 为什么要单独装"：它聚合了vis依赖以及gin_config>=0.5.0、coacd、networkx、psutil、scikit-learn<1.4.0、shapely<=2.0.5、tqdm、submitit（v1 datagen 的 SLURM 提交）等 1.0 专属依赖；terrain可选依赖也正是建立在infinigen[infinigen1]之上的。

安装报错时的标准排障姿势：在命令末尾追加-vv > logs.txt 2>&1重新执行，然后把生成的logs.txt作为附件提交到 GitHub Issue。

四、安装到 Blender 内置 Python 解释器

若要在 Blender UI 中交互使用 Infinigen，或开发自己的资产，需要把包装进 Blender 自带 Python。

4.1 交互式安装脚本

首先完成一次上文"正常安装"，然后（Linux / Mac / WSL 下）执行：

git clone https://github.com/princeton-vl/infinigen.git INFINIGEN_MINIMAL_INSTALL=True bash scripts/install/interactive_blender.sh

剖析 interactive_blender.sh，该脚本做了以下事情：

按平台确定下载链接并下载Blender 4.2.0（Linux 为blender-4.2.0-linux-x64.tar.xz，Mac ARM 为blender-4.2.0-macos-arm64.dmg，Mac x86_64 为blender-4.2.0-macos-x64.dmg），解压/挂载到仓库根目录下的blender/（Linux）或Blender.app/（Mac）；
用 Blender 内置解释器（例如blender/4.2/python/bin/python3.11）执行ensurepip，然后以该解释器运行pip install -e .，从而把infinigen包写入Blender 的 site-packages而非系统 Python；
全程set -e，任一步骤失败立即终止。

安装完成后，可用辅助脚本启动 Blender UI：

python -m infinigen.launch_blender

launch_blender.py 会在仓库根目录下依次查找blender/blender与Blender.app/Contents/MacOS/Blender，找到后自动注入 blendscript_import_infinigen.py 完成包导入（第 13-17、61 行）；若找不到可执行文件，会抛出提示你补齐 Blender-Python 安装步骤的明确错误。

4.2 Blender 模式下的命令改写规则

重要警告：如果你采用 Blender-Python 脚本方式安装，文档中形如python -m <MODULEPATH> <ARGUMENTS>的命令不能直接照抄，应改写为：

python -m infinigen.launch_blender -m <MODULEPATH> -- <ARGUMENTS>

原因同样在 launch_blender.py：-m参数会被翻译为--python <路径>交给独立 Blender 的无头模式执行（第 46-56 行），即把模块当作脚本在 Blender 环境中运行，而不是用系统 Python 运行。

同样地，出错时在命令末尾追加> logs.txt 2>&1重跑，并提交logs.txt到 Issue。

五、在 Docker 容器中使用 Infinigen

5.1 Linux 上的 Docker 工作流

git clone https://github.com/princeton-vl/infinigen.git cd infinigen make docker-build make docker-setup make docker-run

对应关系如下（均来自 Makefile）：

命令	作用
`make docker-build`	以 miniconda3 为基础镜像构建（默认 tag`infinigen_docker_img`），镜像内创建`infinigen`conda 环境并执行`pip install -e ".[dev]"`（见 Dockerfile 第 26-28 行）
`make docker-build-cuda`	改用`nvidia/cuda:12.0.0-devel-ubuntu22.04`基础镜像，开启 CUDA 地形编译
`make docker-setup`	配置 X11 转发：安装`x11-xserver-utils`、生成 Xauthority 并`xhost +local:docker`（仅在需要 OpenGL 时必需）
`make docker-run`	以`--gpus=all`并挂载 X11 socket 与`outputs`目录启动容器，自动回退到`/dev/dri`设备模式
`make docker-run-no-gpu`	不进行 GPU 直通
`make docker-run-no-opengl`	不带 OpenGL 地面真值
`make docker-run-no-gpu-opengl`	两者都关闭（同时注入`BLENDER=/opt/infinigen/blender/blender`环境变量）

注意事项：

不用 OpenGL 时可跳过make docker-setup；
用exit退出容器，用docker exec -it infinigen bash重新进入；
每次运行场景前记得conda activate infinigen。

5.2 Windows 上的 Docker 工作流

先安装 WSL2 与 Docker Desktop，并在设置中启用 "Use the WSL 2 based engine..."，保持 Docker Desktop 打开，然后按上述 Linux 流程执行即可。

六、安装后的验证与下一步

完成安装后，可通过运行官方示例快速验证环境是否就绪：

自然场景首秀：Hello World 演示（对应 generate_nature.py），需要 Terrain (CPU) 能力；
室内场景首秀：Hello Room 演示（对应 generate_indoors.py），Minimal 安装即可胜任；
生成单个资产：Generating Individual Assets。

仓库内置的测试亦可作为安装完整性的校验，例如 tests/infinigen/core/test_gins.py 会校验各类 gin 配置在安装环境下的可解析性，tests/infinigen2/test_generators.py 则验证 v2 生成器可正常导入运行——在dev依赖齐全的安装中，可执行pytest tests跑完整测试套件。

七、常见问题速查

Q1：一定要用 Python 3.11 吗？是。requires-python = "==3.11.*"是硬约束，且bpy==4.2.0、landlab==2.6.0等核心依赖均针对 3.11 生态锁定版本。

Q2：Windows 原生支持吗？Minimal 安装为"实验性"，Terrain/CUDA/OpenGL 原生 Windows 均不支持；推荐通过 WSL2 运行（各功能集标为"实验性"），或直接走 Docker 方案。

Q3：只想生成室内场景，需要编译地形吗？不需要。使用INFINIGEN_MINIMAL_INSTALL=True uv pip install -e .即可，室内与单物体生成不依赖地形 C++ 组件。

Q4：为什么文档中的python -m ...命令在 Blender 模式下不能直接用？因为系统 Python 里没有 Blender 上下文。必须改写为python -m infinigen.launch_blender -m <MODULEPATH> -- <ARGUMENTS>，由 launch_blender.py 转交给独立 Blender 执行。

Q5：安装/编译报错怎么办？先确认系统依赖是否齐全（见第二节），再在命令末尾追加-vv > logs.txt 2>&1（Blender 模式为> logs.txt 2>&1）重跑，将logs.txt附带进 GitHub Issue 反馈。