blendtorch

blendtorch 是一个 Python 框架，旨在将 Blender 无缝集成到 PyTorch 中，用于基于人工视觉数据的深度学习。我们利用 Eevee——一种新的基于物理的实时渲染器——来实时合成图像和标注，从而在许多情况下避免模型训练停滞。

如果您觉得该项目有所帮助，请考虑引用它。

功能概览

• 数据生成：将分布式 Blender 渲染流直接实时注入 PyTorch 数据管道，适用于监督学习和领域随机化应用。支持任意可 pickle 序列化的对象与图像/视频一同发送。内置录制功能，可在无需 Blender 的情况下回放数据。双向通信通道允许 Blender 模拟在神经网络训练过程中自适应调整。
  更多信息 [examples/datagen], [examples/compositor_normals_depth], [examples/densityopt]
• OpenAI Gym 支持：创建并运行远程控制的 Blender Gym 环境，以训练强化学习智能体。Blender 充当仿真、可视化以及交互式实时操控的环境。
  更多信息 [examples/control]

下图展示了 blendtorch 的基本概念，用于为实际检测任务生成人工训练数据。

开始使用

1. 阅读下方的安装说明
2. 如需开始使用 blendtorch 进行训练数据生成，请参阅 [examples/datagen]。
3. 如需了解如何使用 blendtorch 创建强化学习训练环境，请参阅 [examples/control]。

前提条件

本包已在以下环境中测试通过：

• Blender >= 2.83/2.91/3.0/3.1（Python >= 3.7）
• PyTorch >= 1.5/1.10（Python >= 3.7）

操作系统包括 Windows 10 和 Linux。其他版本也可能适用，但尚未经过测试。

安装

blendtorch 由两个独立的子包组成：

• bendtorch.btt 位于 pkg_pytorch，提供 PyTorch 视角；
• blendtorch.btb 位于 pkg_blender，提供 Blender 视角。

bendtorch.btt 将被安装到您的本地 Python 环境中，而 blendtorch.btb 则会被安装到 Blender 自带的 Python 环境中。

1. 克隆此仓库

   git clone https://github.com/cheind/pytorch-blender.git <DST>
   

2. 扩展 PATH

   确保 Blender 可执行文件位于您的环境查找路径 PATH 中。在 Windows 上，可以通过以下命令实现：

   set PATH=c:\Program Files\Blender Foundation\Blender 2.91;%PATH%
   

   在 Ubuntu 上，如果使用 snap 安装了 Blender，则可通过在 ~/.bashrc 中添加以下行来包含路径：

   export PATH=/snap/blender/current/${PATH:+:${PATH}}
   

3. 完成 Blender 设置

   至少打开一次 Blender，并完成初始设置。若遗漏此步骤，部分测试（尤其是与强化学习相关的测试）可能会失败（Blender 2.91）。

4. 安装 blendtorch.btb

   运行以下命令将 blendtorch-btb 安装到 Blender 自带的 Python 环境中：

   blender --background --python <DST>/scripts/install_btb.py
   

5. 安装 blendtorch.btt

   运行以下命令将 blendtorch-btt 安装到您打算运行 PyTorch 的 Python 环境中：

   pip install -e <DST>/pkg_pytorch
   

6. 安装 gym [可选]

   虽非必需，但建议在计划使用 blendtorch 进行强化学习时安装 OpenAI gym：

   pip install gym
   

7. 安装开发依赖 [可选]

   此步骤为可选。如计划运行单元测试：

   pip install -r requirements_dev.txt
   pytest tests/
   

故障排除

运行以下命令检查是否正确输出了 Blender 版本（>=2.83）：

blender --version

接下来，确保 blendtorch-btb 安装正确：

blender --background --python-use-system-env --python-expr "import blendtorch.btb as btb; print(btb.__version__)"

成功时应打印出 blendtorch 的版本号。然后，确认 blendtorch-btt 安装无误：

python -c "import blendtorch.btt as btt; print(btt.__version__)"

同样，成功时应显示 blendtorch 的版本号。

架构

有关深入的架构讨论，请参阅 [examples/datagen] 和 [examples/control]。双向通信机制在 [examples/densityopt] 中有详细说明。

运行时

下表展示了针对简单立方体场景（640x480xRGBA）的每批次（8 张）和每张图像的平均运行时间。详情请参阅 benchmarks/benchmark.py。这些计时包括渲染、传输、解码和批次整理。报告的时间数据基于 Blender 2.8。Blender 2.9 在该场景上的表现相当，但在更复杂的渲染中通常更快。

Blender 实例数	每批次运行时间（秒）	每张图像运行时间（秒）	参数
1	0.236	0.030	启用 UI 刷新
2	0.14	0.018	启用 UI 刷新
4	0.099	0.012	启用 UI 刷新
5	0.085	0.011	不启用 UI 刷新

注意：若无需图像传输，例如在物理模拟的强化学习中，轻松可达 2000Hz。

引用

该代码伴随着我们在基于人工图像的机器学习领域的学术工作 [1],[2]。引用 blendtorch 时，请参考以下文献：

@inproceedings{blendtorch_icpr2020_cheind,
    author = {Christoph Heindl, Lukas Brunner, Sebastian Zambal and Josef Scharinger},
    title = {BlendTorch: A Real-Time, Adaptive Domain Randomization Library},
    booktitle = {
        1st Workshop on Industrial Machine Learning 
        at International Conference on Pattern Recognition (ICPR2020)
    },
    year = {2020},
}

@inproceedings{robotpose_etfa2019_cheind,
    author={Christoph Heindl, Sebastian Zambal, Josef Scharinger},
    title={Learning to Predict Robot Keypoints Using Artificially Generated Images},
    booktitle={
        24th IEEE International Conference on 
        Emerging Technologies and Factory Automation (ETFA)
    },    
    year={2019}
}

注意事项

• 尽管 Blender 2.8x 支持离屏渲染，但它需要一个 UI 前端，因此无法在 --background 模式下运行。如果您的应用不需要离屏渲染，您可以启用后台模式（示例请参见 tests/）。
• Blender 生成的渲染默认使用线性颜色空间，因此在显示时会比预期更暗。

blendtorch 快速上手指南

blendtorch 是一个 Python 框架，旨在将 Blender 无缝集成到 PyTorch 中，用于基于人工视觉数据的深度学习。它利用 Eevee 实时渲染器合成图像和标注，避免模型训练停滞，支持监督学习、域随机化及强化学习环境构建。

环境准备

本工具已在以下环境中测试通过：

• 操作系统: Windows 10 或 Linux
• Blender: 版本 >= 2.83 (推荐 2.91/3.0/3.1)，内置 Python >= 3.7
  • 下载地址：Blender 官网
• PyTorch: 版本 >= 1.5 (推荐 1.10+)，Python >= 3.7
  • 安装建议（国内加速）：

    pip install torch torchvision torchaudio -i https://pypi.tuna.tsinghua.edu.cn/simple
    

• OpenAI Gym (可选): 仅在使用强化学习功能时需要

  pip install gym -i https://pypi.tuna.tsinghua.edu.cn/simple
  

注意: 首次安装 Blender 后，请务必至少打开一次 Blender 并完成初始设置向导，否则部分测试（特别是强化学习相关）可能会失败。

安装步骤

blendtorch 由两个子包组成：btt (PyTorch 端) 和 btb (Blender 端)。请按顺序执行以下步骤：

1. 克隆仓库

   git clone https://github.com/cheind/pytorch-blender.git <DST>
   cd <DST>
   

   (请将 <DST> 替换为你希望存放代码的实际目录路径)

2. 配置环境变量 确保 Blender 可执行文件在系统的 PATH 中。

   • Windows:

     set PATH=c:\Program Files\Blender Foundation\Blender 2.91;%PATH%
     

     (请根据实际安装路径调整)
   • Linux (Snap 安装): 在 ~/.bashrc 中添加：

     export PATH=/snap/blender/current/${PATH:+:${PATH}}
     

3. 安装 Blender 端组件 (blendtorch.btb) 此步骤将包安装到 Blender 自带的 Python 环境中：

   blender --background --python <DST>/scripts/install_btb.py
   

4. 安装 PyTorch 端组件 (blendtorch.btt) 此步骤将包安装到你运行 PyTorch 的 Python 环境中：

   pip install -e <DST>/pkg_pytorch
   

   (国内用户可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 加速)

5. 验证安装

   • 检查 Blender 端：

     blender --background --python-use-system-env --python-expr "import blendtorch.btb as btb; print(btb.__version__)"
     

   • 检查 PyTorch 端：

     python -c "import blendtorch.btt as btt; print(btt.__version__)"
     

   若均输出版本号，则安装成功。

基本使用

blendtorch 的核心工作流是：Blender 作为服务端实时渲染数据，通过双向通信通道将图像和张量数据流式传输给 PyTorch 训练脚本。

场景 1：生成训练数据 (Data Generation)

适用于监督学习和域随机化。Blender 实时渲染图像并发送给 PyTorch DataLoader。

简要流程：

1. 在 Blender 中编写脚本，使用 blendtorch.btb 设置渲染输出和通信端口。
2. 在 PyTorch 侧使用 blendtorch.btt 创建数据集类，连接该端口获取数据。

参考官方示例获取完整代码：

• 基础数据生成：examples/datagen
• 合成深度图与法线图：examples/compositor_normals_depth

场景 2：强化学习环境 (Reinforcement Learning)

适用于创建远程控制的 Blender Gym 环境。Blender 充当仿真、可视化和交互环境。

简要流程：

1. 定义继承自 gym.Env 的类，内部调用 Blender 进行步长仿真 (step) 和重置 (reset)。
2. PyTorch 代理通过与该环境交互来训练策略网络。

参考官方示例获取完整代码：

• 控制与环境交互：examples/control

性能提示

• 多实例加速: 可以启动多个 Blender 实例并行渲染以提升数据吞吐率（例如 4 个实例可将单张图像渲染时间降至约 0.012 秒）。
• 后台模式: 若不需要离屏渲染的高级特性，可尝试在后台模式运行以提升稳定性；但注意 Blender 2.8x 的离屏渲染通常需要 UI 前端支持。
• 色彩空间: Blender 默认输出线性色彩空间图像，直接显示可能会偏暗，请在预处理阶段进行伽马校正。