BlenderProc2

一个用于逼真渲染的程序化Blender流程。

文档 | 教程 | 示例 | ArXiv论文 | 研讨会论文 | JOSS文章

功能

加载：*.obj、*.ply、*.blend、*.fbx、BOP、ShapeNet、Haven、3D-FRONT等。
对象：设置或采样对象姿态，应用物理和碰撞检测。
材质：设置或采样基于物理的材质和纹理。
照明：设置或采样灯光，自动照明3D-FRONT场景。
相机：从文件设置、采样或加载相机姿态。
渲染：RGB、立体、深度、法线和分割图像/序列。
写入：.hdf5容器、COCO和BOP注释。

安装

通过pip安装

安装blenderproc最简单的方法是通过pip：

pip install blenderproc

通过git安装

或者，如果您需要对blenderproc进行修改，或者想使用main分支上的最新版本，请克隆仓库：

git clone https://github.com/DLR-RM/BlenderProc

为了仍然可以使用blenderproc命令，并在系统的任何位置使用blenderproc，请进行本地pip安装：

cd BlenderProc
pip install -e .

使用方法

BlenderProc必须在Blender的Python环境中运行，因为只有在那里我们才能访问Blender API。因此，不要使用普通的Python解释器运行脚本，而是要使用BlenderProc的命令行接口。

blenderproc run <你的Python脚本>

通常，一次运行脚本会首先加载或构建一个3D场景，然后在场景中设置一些相机姿态，并为每个相机姿态渲染不同类型的图像（RGB、距离、语义分割等）。通常，您会多次运行脚本，每次产生一个新场景并从中渲染5-20张图像。有了更多经验后，也可以在单个脚本调用期间更改场景，这里说明了如何做到这一点。

快速入门

您可以通过运行以下命令来测试BlenderProc的pip安装：

blenderproc quickstart

这是blenderproc run quickstart.py的别名，其中quickstart.py的内容如下：

import blenderproc as bproc
import numpy as np

bproc.init()

# 创建一个简单的对象：
obj = bproc.object.create_primitive("MONKEY")

# 在旁边创建一个点光源
light = bproc.types.Light()
light.set_location([2, -2, 0])
light.set_energy(300)

# 将相机设置在对象前面
cam_pose = bproc.math.build_transformation_mat([0, -5, 0], [np.pi / 2, 0, 0])
bproc.camera.add_camera_pose(cam_pose)

# 渲染场景
data = bproc.renderer.render()

# 将渲染结果写入hdf5文件
bproc.writer.write_hdf5("output/", data)

BlenderProc创建指定的场景并将图像渲染到output/0.hdf5中。要可视化该图像，只需调用：

blenderproc vis hdf5 output/0.hdf5

就是这样！您已经用BlenderProc渲染了第一张图像！

在Blender GUI中调试

为了理解实际发生的情况，BlenderProc具有在Blender UI中可视化一切的强大功能。要做到这一点，只需使用debug而不是run子命令来调用您的脚本：

blenderproc debug quickstart.py

确保quickstart.py实际存在于您的工作目录中。

现在Blender UI打开，选择脚本标签，并加载正确的脚本。要启动BlenderProc流程，只需按下Run BlenderProc（见图中红圈）。与普通模式一样，打印语句仍然会输出到终端。

流程可以多次运行，因为在每次运行开始时，场景都会被清空。

在IDE中进行断点调试

由于blenderproc在blender的独立Python环境中运行，因此调试blenderproc脚本不能像调试其他Python脚本那样进行。因此，需要进行远程调试，以下是针对vscode和PyCharm的说明：

使用vscode进行调试

首先，在blender的Python环境中安装debugpy包。

blenderproc pip install debugpy

现在将以下配置添加到您的vscode launch.json中。

{                        
    "name": "附加",
    "type": "python",
    "request": "附加",
    "connect": {
        "host": "localhost",
        "port": 5678
    }
}

最后，在要调试的blenderproc脚本顶部（导入语句之后）添加以下几行代码：

import debugpy
debugpy.listen(5678)
debugpy.wait_for_client()

现在像往常一样通过命令行运行你的blenderproc脚本，然后在vscode中启动新添加的"附加"配置。你现在可以添加断点并逐步执行了。

使用PyCharm Professional进行调试

在PyCharm中，转到"编辑配置..."并创建一个基于"Python调试服务器"的新配置。该配置会针对你的具体版本，显示需要安装哪个pip包以及需要在脚本中添加哪些代码。以下假设使用PyCharm 2021.3版本：

首先，在blender的Python环境中安装"pydevd-pycharm"包。

blenderproc pip install pydevd-pycharm~=212.5457.59

现在，在要调试的blenderproc脚本顶部（导入语句之后）添加以下代码：

import pydevd_pycharm
pydevd_pycharm.settrace('localhost', port=12345, stdoutToServer=True, stderrToServer=True)

然后，先在PyCharm中运行你的"Python调试服务器"配置，再通过命令行照常运行你的blenderproc脚本。 PyCharm应该会进入调试模式，阻塞在下一行代码。你现在可以添加断点并逐步执行了。

下一步做什么？

既然你已经运行了第一个BlenderProc脚本，接下来可以学习一些基础知识：

教程

通过以下教程了解BlenderProc的基本使用原理：

示例

我们提供了许多详细解释所有功能的示例，这些示例应该能帮助你理解BlenderProc的工作原理。探索我们的示例是学习BlenderProc功能的最佳方式。我们还为一些数据集提供了支持。

基础场景：基础示例，适合初学者入门
相机采样：在形状内采样不同的相机位置，并对旋转进行约束
对象操作：更改对象的各种参数
材质操作：材质选择和操作
物理定位：在场景中启用对象之间的简单模拟物理交互
语义分割：为给定场景生成语义分割标签
BOP挑战：生成用于BOP挑战2020的姿态标注数据
COCO标注：为场景中选定的对象将COCO标注写入.json文件

以及更多内容，详见我们的示例。

贡献

发现了bug？请帮助我们报告。希望在下一个BlenderProc版本中加入新功能？创建一个issue。做了一些有用的东西或修复了bug？发起一个PR。请查看贡献指南。

更新日志

请参阅我们的更新日志。

引用

如果您在研究项目中使用BlenderProc，请按以下方式引用：

@article{Denninger2023, 
    doi = {10.21105/joss.04901},
    url = {https://doi.org/10.21105/joss.04901},
    year = {2023},
    publisher = {The Open Journal}, 
    volume = {8},
    number = {82},
    pages = {4901}, 
    author = {Maximilian Denninger and Dominik Winkelbauer and Martin Sundermeyer and Wout Boerdijk and Markus Knauer and Klaus H. Strobl and Matthias Humt and Rudolph Triebel},
    title = {BlenderProc2: A Procedural Pipeline for Photorealistic Rendering}, 
    journal = {Journal of Open Source Software}
}