ml-hypersim

环境要求

• Anaconda Python 环境（README 用 Anaconda 作为快速上手方式）
• 仓库自带的 requirements.txt 文件
• V-Ray Standalone 与 V-Ray AppSDK（渲染管线必需）
• 同时可用的 Windows 与 macOS/Linux 环境（部分步骤限定系统）
• 大容量存储，建议每批约 4TB 的便携硬盘

安装与启动步骤

1. 1创建并激活环境

   在仓库根目录执行，用 requirements.txt 一次性安装全部必需 Python 库，并激活新建的 hypersim-env 环境。

   conda create --name hypersim-env --file requirements.txt
   conda activate hypersim-env

   复制

2. 2安装可选库

   mayavi、opencv、pillow 属于可选依赖，可按需单独安装，缺失它们不影响核心管线。

   pip install mayavi
   conda install -c conda-forge opencv
   conda install -c anaconda pillow

   复制

3. 3配置 V-Ray 路径

   把 V-Ray Standalone 的 bin 加入 PATH，把 AppSDK 的 bin 加入 DYLD_LIBRARY_PATH，示例路径需改成你自己的安装位置。

   export PATH=$PATH:/Applications/ChaosGroup/V-Ray/Standalone_for_mavericks_x64/bin
   export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/Applications/ChaosGroup/V-Ray/AppSDK/bin

   复制

4. 4复制 AppSDK 库

   把 AppSDK bin 下的动态库与 plugins 目录手动复制到 ml-hypersim/code/python/tools，示例路径需替换为实际路径。

   cp /Applications/ChaosGroup/V-Ray/AppSDK/bin/libcgauth.dylib          /Users/mike/code/github/ml-hypersim/code/python/tools
   cp /Applications/ChaosGroup/V-Ray/AppSDK/bin/libvray.dylib            /Users/mike/code/github/ml-hypersim/code/python/tools
   cp /Applications/ChaosGroup/V-Ray/AppSDK/bin/libvrayopenimageio.dylib /Users/mike/code/github/ml-hypersim/code/python/tools
   cp /Applications/ChaosGroup/V-Ray/AppSDK/bin/libvrayosl.dylib         /Users/mike/code/github/ml-hypersim/code/python/tools
   cp /Applications/ChaosGroup/V-Ray/AppSDK/bin/libVRaySDKLibrary.dylib  /Users/mike/code/github/ml-hypersim/code/python/tools
   cp -a /Applications/ChaosGroup/V-Ray/AppSDK/bin/plugins               /Users/mike/code/github/ml-hypersim/code/python/tools

   复制

5. 5验证 AppSDK 安装

   运行官方检查脚本，若输出配置正确的提示信息说明环境就绪，否则需回头检查环境变量和复制的库文件。

   python code/python/tools/check_vray_appsdk_install.py

   复制

6. 6生成占据图

   必须在 macOS 或 Linux 上执行，处理 Volume 1-9 的场景；要等上一步渲染与下载全部完成后才能开始。

   python code/python/tools/dataset_generate_octomaps.py --dataset_dir /Volumes/portable_hard_drive/evermotion_dataset --scene_names "ai_00*"

   复制

7. 7生成相机轨迹

   同样限定在 macOS 或 Linux 执行，输入与输出目录沿用上一步，继续处理同一批场景。

   python code/python/tools/dataset_generate_camera_trajectories.py --dataset_dir /Volumes/portable_hard_drive/evermotion_dataset --scene_names "ai_00*"

   复制

8. 8生成 3D 边界框

   在 macOS 或 Linux 上执行，bounding_box_type 取 object_aligned_2d，场景范围保持与前几步一致。

   python code/python/tools/dataset_generate_bounding_boxes.py --dataset_dir /Volumes/portable_hard_drive/evermotion_dataset --bounding_box_type object_aligned_2d --scene_names "ai_00*"

   复制

关键配置

如何确认成功

执行 python code/python/tools/check_vray_appsdk_install.py，若打印 [HYPERSIM: CHECK_VRAY_APPSDK_INSTALL] The V-Ray AppSDK is c

常见问题

注意事项

• 数据集采用 Creative Commons Attribution-ShareAlike 3.0 Unported 许可。
• dataset_dir_when_rendering 必须是绝对路径，且 Windows 下的盘符要始终保持一致。
• 管线会产生大量中间数据，磁盘 I/O 往往是瓶颈，建议使用高速盘或便携硬盘。
• 引用该数据集或工具包时请按 README 指出论文引用。