Infinigen 命令行接口（CLI）完全指南：infinigen2 生成器编排与 datagen 大规模作业管理

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

本篇技术指南系统讲解 Infinigen 项目随包发布的两大命令行入口：Infinigen 2.0 的infinigen2生成 CLI 与 Infinigen 1.0 的python -m infinigen.datagen.manage_jobs作业管理器。通过本文，你将掌握如何用infinigen2串联多个生成器（generator）构建并渲染一个场景、如何用--list检索可用生成器，以及如何借助manage_jobs在单机或 SLURM 集群上规模化批量生成场景。文中所有参数均以当前仓库源码（src/infinigen2/generate.py、src/infinigen/datagen/manage_jobs.py）为依据，可直接对照使用。

一、CLI 入口总览

官方文档 docs/source/cli.md 明确了 Infinigen 随包提供的两个命令行入口点：

入口点如何注册

这两个命令并非 shell 别名，而是通过pyproject.toml的[project.scripts]段注册的 Python 控制台脚本：

[project.scripts] infinigen = "infinigen2.generate:main" infinigen2 = "infinigen2.generate:main"

可见infinigen与infinigen2指向同一个实现infinigen2.generate:main，因此二者等价。安装项目（如pip install .或通过 uv 安装）后即可直接调用。infinigen2模块的版本号定义在 src/infinigen2/init.py（__version__ = "2.0.0a1"）。

二、infinigen2：生成器驱动的场景构建与渲染 CLI

infinigen2的核心设计是生成器链（generator pipeline）：命令接收一个或多个生成器名称，按顺序执行，前一个生成器的输出自动作为后一个生成器的输入，最终产出渲染图像、导出文件或 Blender 场景。

2.1 位置参数generators：串联生成器

infinigen2 bricks_rand material_sphere render_cycles

• 支持任意长度的生成器序列，例如上面的示例依次执行：生成随机砖块对象（bricks_rand）→ 赋予材质球（material_sphere）→ 用 Cycles 渲染（render_cycles）。
• CLI 会自动将输出连接到输入（"chains generators together by connecting outputs to inputs"），无需手动指定数据流。
• 生成器名称的解析逻辑在_resolve_generator()（src/infinigen2/generate.py）：先在GENERATORS_MANIFEST（src/infinigen2/manifest.json）中按短名精确匹配；若匹配不到，再尝试按预设（preset）名称匹配；最后按("Object", "objects")、("Scene", "scenes")、("Exporter", "exporters")、("Material", "materials")等回退类别字符串做模糊导入。

生成器的类别决定其产物如何被放入共享数据字典，见_unpack_by_category()（src/infinigen2/generate.py）：

• Material/MaterialOverlay：写入data["material"]；
• Mask：同时生成data["mask"]与对应的漫反射材质；
• Object：把网格追加进data["objects"]，若带灯光则一并收集；
• Scene：合并场景对象、相机、灯光、碰撞体、地面与尺寸；
• Exporter：追加进data["exports"]，由渲染阶段消费；
• Cameras：整体替换相机列表。

2.2--list：检索可用生成器

infinigen2 --list # 列出全部生成器 infinigen2 --list Scene # 按类别过滤，类别大小写不敏感 infinigen2 --list Scene Exporter

--list接受零个或多个CATEGORY参数（metavar="CATEGORY"），未传时列出全部。该选项实际会把参数转发给python -m infinigen2.list（见 src/infinigen2/list.py），转发时固定附加--columns shortname：

python -m infinigen2.list # 更丰富的列表功能 python -m infinigen2.list --categories Scene python -m infinigen2.list --presets # 列出各生成器模块的 *_preset 变体 python -m infinigen2.list -k brick # 按名称子串过滤 python -m infinigen2.list --columns name category # 自定义输出列 python -m infinigen2.list --separator '\t' --head 20 # 自定义分隔符并截取前 20 行

list.py的完整参数包括：--categories（多值，取 manifest 中的合法类别）、--presets（列出 preset 而非 manifest 条目）、-k（名称子串过滤）、--columns（默认["name"]）、--separator（默认空格）、--missing_values（error/drop，默认drop）、--head/--tail。所有数据来自 src/infinigen2/manifest.json 加载的GENERATORS_MANIFESTDataFrame。

2.3 输出与随机种子

关于种子的两个实现细节（src/infinigen2/generate.py）：

• 未显式给定时，种子由int.from_bytes(os.urandom(8), "big")生成，因此每次运行都不同；
• 最终实际使用的种子会以十六进制写入metadata.json的"seed"字段，方便事后复现同一场景。

2.4 帧、相机与渲染参数

2.5--passes：渲染/导出通道

--passes接受一个或多个ExportType枚举值，定义在 src/infinigen2/exporters/util/format.py（class ExportType(enum.Enum)）：

infinigen2 ... --passes IMAGE DEPTH SURFACE_NORMAL

常用取值包括：IMAGE（RGB）、IMAGE_DENOISED（去噪 RGB）、IMAGE_HDR、IMAGE_DENOISED_HDR、BLENDER_FILE（.blend场景文件）、MESH、CAM_IMU_TUM_TRAJ/OBJ_IMU_TUM_TRAJ（IMU 轨迹，TUM 格式），以及DEPTH、SURFACE_NORMAL、MATERIAL_INDEX、DIFFUSE_COLOR等地面真值通道。每个通道的默认文件命名与数据类型由MAINRENDER_PASS_DEFAULTS、GT_PASS_DEFAULTS、SCENE_PASS_DEFAULTS三张表约定（如IMAGE→%c/%f.png的uint8图像、DEPTH→%c/depth_%f.npy的float32数组），运行时通过resolve_pass_argument()把ExportType映射为具体RenderPass。

渲染管线内部会为--samples与固定值组合出自适应采样参数（min_samples=32、samples_adaptive_threshold=0.005、film_exposure=2.0），这些值硬编码在_main()的pipeline_parameters中（src/infinigen2/generate.py）。

2.6 场景导出与中断行为

infinigen2 ... --save_blend # 保存到输出目录 scene.blend infinigen2 ... --save_blend out.blend # 保存到指定路径

--save_blend为可选值参数（nargs="?"，const=True）：不带路径时保存到输出目录下的scene.blend；带路径时保存到该路径。保存前会为所有对象/材质/节点组/网格设置use_fake_user = True并关闭 Subsurf 修改器的视口显示，以保证导出内容完整可用。

infinigen2 ... --on_interrupt delete # 收到中断信号时删除输出目录 infinigen2 ... --on_interrupt exit # 直接退出 infinigen2 ... --on_interrupt cleanstate # 预留，尚未实现 infinigen2 ... --on_interrupt none # 默认：忽略中断

--on_interrupt控制收到SIGUSR1/SIGTERM信号时的行为，由_make_interrupt_handler()（src/infinigen2/generate.py）实现；其中delete会shutil.rmtree输出目录后退出，适合 SLURM 重启场景。

2.7 调试与追踪：--debug、--trace

infinigen2 ... -d # 打开全局 DEBUG 日志 infinigen2 ... -d objects scenes # 仅对名称含 objects/scenes 的日志器输出 DEBUG infinigen2 ... -q # 日志级别降为 WARNING infinigen2 ... --loglevel DEBUG # 显式指定日志级别

-d/--debug（多值可选）、-q/--quiet与--loglevel（合法值为logging.getLevelNamesMapping()的键）共同控制日志。_DebugFilter过滤器（src/infinigen2/generate.py）保证：给定-d子串时，只对infinigen/procfunc前缀日志器中名称匹配子串的模块放行 DEBUG 记录。

infinigen2 ... --trace codegen # 生成 codegen.py 到输出目录 infinigen2 ... --trace graph # 生成 graph.json（计算图） infinigen2 ... --trace codestats # 打印代码统计 infinigen2 ... --trace codegen graph codestats infinigen2 ... --trace_level GENERATORS # 追踪粒度，默认为 GENERATORS

--trace可组合codegen、codestats、graph三种模式（_execute_trace()，src/infinigen2/generate.py）：codegen把本次执行的计算图反编译为可读 Python 写入codegen.py并用ast.parse校验语法；graph导出graph.json；codestats打印各阶段统计。--trace_level的合法值来自TraceLevel枚举，用于控制追踪粒度（更细粒度会"窥探"随机控制分支）。启用--trace时命令在追踪完成后直接返回，不再执行实际渲染。

2.8 输出产物与元数据

每次infinigen2运行结束后，输出目录包含：

• 各导出通道的文件（图像、npy、网格等），文件名遵循 src/infinigen2/exporters/util/format.py 的通道命名约定；
• metadata.json：完整记录命令行参数（args）、十六进制种子（seed）、硬件信息（hardware，来自 src/infinigen2/util/hardware_info.py 的get_hardware_info()）、各生成器耗时（generator_times）与导出产物清单（exports）。这是复现实验、排查性能瓶颈的关键文件；
• 可选scene.blend、codegen.py、graph.json（视参数而定）。

整个执行由main()包在skip_teardown_on_exit()上下文中（src/infinigen2/generate.py），确保退出时干净清理。

三、python -m infinigen.datagen.manage_jobs：大规模数据生成作业管理器

manage_jobs是 Infinigen 1.0 时代的批量场景生成编排器，负责"在本地机器或 SLURM 集群上编排大规模场景生成"，其完整参数定义在 src/infinigen/datagen/manage_jobs.py 的get_parser()。

3.1 核心参数

3.2 配置加载与互斥约束

manage_jobs通过infinigen.core.init.apply_gin_configs()加载配置（src/infinigen/datagen/manage_jobs.py），其中定义了关键的互斥约束：

mandatory_exclusive_configs = [ "infinigen/datagen/configs/compute_platform", "infinigen/datagen/configs/data_schema", ]

也就是说，src/infinigen/datagen/configs/compute_platform（计算平台：本地 / SLURM 等）与 src/infinigen/datagen/configs/data_schema（数据模式）这两组配置必须且只能各选其一，通过--pipeline_configs指定，例如：

python -m infinigen.datagen.manage_jobs \ --pipeline_configs infinigen/datagen/configs/compute_platform/slurm.gin \ infinigen/datagen/configs/data_schema/stereo.gin

此外，__main__入口对参数组合做了防御性校验（src/infinigen/datagen/manage_jobs.py）：若 pipeline 未启用 upload 却设置了--cleanup except_logs/except_crashed/all，会直接抛ValueError，防止"清理后无输出保留"的悲剧；反之启用 upload 但--cleanup none也会告警，因为 upload 本身会做部分清理。

3.3 运行行为与产物

进入main()（src/infinigen/datagen/manage_jobs.py）后：

1. 将完整命令行写入datagen_command.sh，便于事后复现；
2. 用init_db()初始化场景数据库，以每个场景的种子为目录名创建子目录；
3. 未禁用清理时写出write_html_summary生成的 HTML 进度汇总页；
4. --wandb_mode非disabled时懒加载 wandb 并wandb.init()（project 名默认render），之后每轮循环wandb.log统计；
5. 主循环manage_datagen_jobs()（src/infinigen/datagen/manage_jobs.py）持续调度：计算并发数、根据磁盘占用（超过阈值会睡眠等待并可通过 wandb 告警）、挑选待启动作业、把每个场景的queue_func投递到本地线程或 SLURM 队列；
6. 每轮把全场景状态表写成scenes_db.csv，并周期性打印统计块（print_stats_block，含开始/当前时间与各字段计数）。

因此运行结束后，--output_folder下会有scenes_db.csv（每个场景的状态记录）、datagen_command.sh（命令回放）、jobs.log（文件日志）与每个种子子目录中的场景产物。配合--use_existing可以断点续跑，配合 SLURM 数组任务与--warmup_sec可以做到大规模错峰调度。

四、两个 CLI 的选用建议与关联阅读

• 需要交互式生成单个场景、试验新的生成器组合或调试材质/渲染时，优先使用infinigen2：它面向生成器链编程模型，配合--list、--trace codegen可以快速定位问题；
• 需要大规模、可复现、可断点续跑地批量产出训练数据时，使用python -m infinigen.datagen.manage_jobs：它提供种子管理、SLURM 编排、磁盘保护、wandb 监控与数据清理等一整套工业化能力。

进一步阅读：生成器清单见 src/infinigen2/manifest.json，渲染/导出通道定义见 src/infinigen2/exporters/util/format.py，作业管理的完整调度逻辑见 src/infinigen/datagen/manage_jobs.py，gin 配置体系见 src/infinigen/datagen/configs。官方文档的 CLI 参考、Infinigen 2.0 说明、Hello World 入门 与 Hello Room 入门 可与本文对照阅读。

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