📸 可视化与渲染#
Genesis 的可视化系统由你刚刚创建的场景的 visualizer 管理（即 scene.visualizer）。有两种可视化场景的方式：1）使用在单独线程中运行的交互式查看器，2）通过手动向场景添加相机并使用相机渲染图像。
查看器#
如果你连接到显示器，可以使用交互式查看器来可视化场景。Genesis 使用不同的 options 组来配置场景中的不同组件。要配置查看器，你可以在创建场景时更改 viewer_options 中的参数。此外，我们使用 vis_options 来指定与可视化相关的属性，这些属性将由查看器和相机（我们很快会添加）共享。
使用更详细的查看器和可视化设置创建场景（这看起来有点复杂，但仅用于说明目的）：
scene = gs.Scene(
show_viewer = True,
viewer_options = gs.options.ViewerOptions(
res = (1280, 960),
camera_pos = (3.5, 0.0, 2.5),
camera_lookat = (0.0, 0.0, 0.5),
camera_fov = 40,
max_FPS = 60,
),
vis_options = gs.options.VisOptions(
show_world_frame = True, # 在其原点可视化 `world` 的坐标系
world_frame_size = 1.0, # 世界坐标轴的长度，单位为米
show_link_frame = False, # 不可视化实体连杆的坐标系
show_cameras = False, # 不可视化添加的相机的网格和视锥体
plane_reflection = True, # 开启平面反射
ambient_light = (0.1, 0.1, 0.1), # 环境光设置
),
renderer = gs.renderers.Rasterizer(), # 使用光栅化器进行相机渲染
)
在这里，我们可以指定查看器相机的姿态和视场角（fov）。如果 max_FPS 设置为 None，查看器将尽可能快地运行。如果 res 设置为 None，Genesis 将自动创建一个 4:3 窗口，高度设置为显示器高度的一半。还要注意，在上述设置中，我们设置为使用光栅化后端进行相机渲染。Genesis 提供两种渲染后端：gs.renderers.Rasterizer() 和 gs.renderers.RayTracer()。查看器始终使用光栅化器。默认情况下，相机也使用光栅化器。
场景创建后，你可以通过 scene.visualizer.viewer 或简单地使用 scene.viewer 作为快捷方式来访问查看器对象。你可以查询或设置查看器相机姿态：
cam_pose = scene.viewer.camera_pose
scene.viewer.set_camera_pose(cam_pose)
相机与无头渲染#
现在让我们手动向场景添加一个相机对象。相机不连接到查看器或显示器，仅在你需要时返回渲染的图像。因此，相机可以在无头模式下工作。
cam = scene.add_camera(
res = (1280, 960),
pos = (3.5, 0.0, 2.5),
lookat = (0, 0, 0.5),
fov = 30,
GUI = False
)
如果 GUI=True，每个相机将创建一个 opencv 窗口来动态显示渲染的图像。注意这与查看器 GUI 不同。
然后，一旦我们构建场景，就可以使用相机渲染图像。我们的相机支持渲染 RGB 图像、深度、分割掩码和表面法线。默认情况下，仅渲染 RGB，你可以在调用 camera.render() 时通过设置参数来开启其他模式：
scene.build()
# 渲染 RGB、深度、分割掩码和法线图
rgb, depth, segmentation, normal = cam.render(depth=True, segmentation=True, normal=True)
如果你使用了 GUI=True 并且连接了显示器，你应该能看到 4 个窗口。（有时 opencv 窗口会有额外的延迟，所以如果窗口是黑色的，你可以调用额外的 cv2.waitKey(1)，或者简单地再次调用 render() 来刷新窗口。）
使用相机录制视频
现在，让我们只渲染 RGB 图像，移动相机并录制视频。Genesis 提供了一个方便的实用工具来录制视频：
# 开始相机录制。一旦开始，所有渲染的 RGB 图像将在内部记录
cam.start_recording()
import numpy as np
for i in range(120):
scene.step()
# 更改相机位置
cam.set_pose(
pos = (3.0 * np.sin(i / 60), 3.0 * np.cos(i / 60), 2.5),
lookat = (0, 0, 0.5),
)
cam.render()
# 停止录制并保存视频。如果未指定 `filename`，将使用调用者文件名自动生成名称。
cam.stop_recording(save_to_filename='video.mp4', fps=60)
你将把视频保存到 video.mp4：
以下是涵盖上述所有内容的完整代码脚本：
import genesis as gs
gs.init(backend=gs.cpu)
scene = gs.Scene(
show_viewer = True,
viewer_options = gs.options.ViewerOptions(
res = (1280, 960),
camera_pos = (3.5, 0.0, 2.5),
camera_lookat = (0.0, 0.0, 0.5),
camera_fov = 40,
max_FPS = 60,
),
vis_options = gs.options.VisOptions(
show_world_frame = True,
world_frame_size = 1.0,
show_link_frame = False,
show_cameras = False,
plane_reflection = True,
ambient_light = (0.1, 0.1, 0.1),
),
renderer=gs.renderers.Rasterizer(),
)
plane = scene.add_entity(
gs.morphs.Plane(),
)
franka = scene.add_entity(
gs.morphs.MJCF(file='xml/franka_emika_panda/panda.xml'),
)
cam = scene.add_camera(
res = (640, 480),
pos = (3.5, 0.0, 2.5),
lookat = (0, 0, 0.5),
fov = 30,
GUI = False,
)
scene.build()
# 渲染 RGB、深度、分割和法线
# rgb, depth, segmentation, normal = cam.render(rgb=True, depth=True, segmentation=True, normal=True)
cam.start_recording()
import numpy as np
for i in range(120):
scene.step()
cam.set_pose(
pos = (3.0 * np.sin(i / 60), 3.0 * np.cos(i / 60), 2.5),
lookat = (0, 0, 0.5),
)
cam.render()
cam.stop_recording(save_to_filename='video.mp4', fps=60)
照片级真实感光线追踪渲染#
Genesis 提供光线追踪渲染后端以实现照片级真实感渲染。你可以在创建场景时通过设置 renderer=gs.renderers.RayTracer() 轻松切换到使用此后端。此相机允许更多参数调整，如 spp、aperture、model 等。
设置#
测试环境
Ubuntu 22.04, CUDA 12.4, python 3.9
获取子模块，特别是 genesis/ext/LuisaRender。
# 在 Genesis/ 目录内
git submodule update --init --recursive
pip install -e ".[render]"
安装/升级 g++ 和 gcc 到版本 >= 11。
sudo apt install build-essential manpages-dev software-properties-common
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt update && sudo apt install gcc-11 g++-11
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 110
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 110
# 验证版本
g++ --version
gcc --version
如果你的本地版本不符合要求版本，请安装 CMake。我们使用 snap 而不是 apt，因为我们需要 CMake 版本 >= 3.26。但是，请记住使用正确的 cmake。你可能有 /usr/local/bin/cmake，但 snap 安装的包位于 /snap/bin/cmake（或 /usr/bin/snap）。请通过 echo $PATH 仔细检查二进制路径的顺序。
sudo snap install cmake --classic
cmake --version
安装依赖项，
sudo apt install libvulkan-dev xorg-dev # Vulkan, X11 & RandR
sudo apt-get install uuid-dev # UUID
sudo apt-get install zlib1g-dev # zlib
如果你没有 sudo，以下命令也可以在你的 conda 环境中安装所需的依赖项：
conda install -c conda-forge gcc=11.4 gxx=11.4
conda install -c conda-forge cmake=3.26.1
conda install -c conda-forge vulkan-tools vulkan-headers xorg-xproto # Vulkan, X11 & RandR
conda install -c conda-forge libuuid # UUID
conda install -c conda-forge zlib # zlib
构建 LuisaRender。请记住使用正确的 cmake。默认情况下，我们使用 OptiX 降噪器（仅适用于 CUDA 后端）。如果你需要 OIDN 降噪器，请附加 -D LUISA_COMPUTE_DOWNLOAD_OIDN=ON。
cd genesis/ext/LuisaRender
cmake -S . -B build -D CMAKE_BUILD_TYPE=Release -D PYTHON_VERSIONS=3.9 -D LUISA_COMPUTE_DOWNLOAD_NVCOMP=ON -D LUISA_COMPUTE_ENABLE_GUI=OFF -D LUISA_RENDER_BUILD_TESTS=OFF # 记得检查 python 版本
cmake --build build -j $(nproc)
如果你真的难以完成构建，我们在这里有一些构建版本，你可以检查你的机器是否恰好有相同的设置。命名遵循 build_<commit-tag>_cuda<version>_python<version>。下载与你系统匹配的版本，重命名为 build/ 并放在 genesis/ext/LuisaRender 中。
最后，你可以运行示例，
cd examples/rendering
python demo.py
你应该能够得到
使用 gs-madrona 批量渲染#
Genesis 通过 gs-madrona 提供高吞吐量批量渲染后端。你可以通过设置 renderer=gs.renderers.BatchRenderer(use_rasterizer=True/False) 轻松切换到 gs-madrona 后端
前提条件#
请首先按照官方 README 说明安装最新版本的 Genesis。
简易安装（仅 x86）#
Python>=3.10 的预编译二进制 wheel 可在 PyPI 上获取。可以使用任何 Python 包管理器（例如 uv 或 pip）安装：
pip install gs-madrona
从源码构建#
pip install .
测试（可选）#
如果尚未克隆 Genesis Simulator 仓库
git clone https://github.com/Genesis-Embodied-AI/Genesis.git
运行 Genesis 提供的以下示例脚本
python Genesis/examples/rigid/single_franka_batch_render.py
所有生成的图像将存储在当前目录下的 ./image_output 中。
要使用光线追踪器，在
single_franka_batch_render.py中更改use_rasterizer=False
renderer = gs.options.renderers.BatchRenderer(
use_rasterizer=False,
)
常见问题#
运行
cmake -S . -B build时仍检测不到已安装的库， 你可以通过显式设置XXX_INCLUDE_DIR等选项手动指示 CMake 检测依赖项，例如ZLIB_INCLUDE_DIR=/path/to/include。对于 conda 环境，XXX_INCLUDE_DIR通常遵循/home/user/anaconda3/envs/genesis/include格式。执行
cmake -S . -B build时出现 Pybind 错误，CMake Error at src/apps/CMakeLists.txt:12 (find_package): By not providing "Findpybind11.cmake" in CMAKE_MODULE_PATH this project has asked CMake to find a package configuration file provided by "pybind11", but CMake did not find one. Could not find a package configuration file provided by "pybind11" with any of the following names: pybind11Config.cmake pybind11-config.cmake
你可能忘记执行
pip install -e ".[render]"。或者，你可以简单地执行pip install "pybind11[global]"。运行
cmake -S . -B build时出现 CUDA 运行时编译错误，/usr/bin/ld: CMakeFiles/luisa-cuda-nvrtc-standalone-compiler.dir/cuda_nvrtc_compiler.cpp.o: in function `main': cuda_nvrtc_compiler.cpp:(.text.startup+0x173): undefined reference to `nvrtcGetOptiXIRSize' /usr/bin/ld: cuda_nvrtc_compiler.cpp:(.text.startup+0x197): undefined reference to `nvrtcGetOptiXIR'
你需要安装”系统级”的 cuda-toolkit（官方安装指南）。首先检查 cuda-toolkit，
nvcc --version # 这应该与你的 nvidia-smi 中的 cuda 版本一致 which nvcc # 只是检查你正在使用预期的 cuda-toolkit
如果你无法从
nvcc获得正确的输出，请按照官方 cuda-toolkit 安装指南进行操作。作为示例，以下是安装 cuda-12.4 的 cuda-toolkit 的方法。按照此处的说明下载安装程序。wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-ubuntu2204.pin sudo mv cuda-ubuntu2204.pin /etc/apt/preferences.d/cuda-repository-pin-600 wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda-repo-ubuntu2204-12-4-local_12.4.0-550.54.14-1_amd64.deb sudo dpkg -i cuda-repo-ubuntu2204-12-4-local_12.4.0-550.54.14-1_amd64.deb sudo cp /var/cuda-repo-ubuntu2204-12-4-local/cuda-*-keyring.gpg /usr/share/keyrings/ sudo apt-get update sudo apt-get -y install cuda-toolkit-12-4
记得设置二进制和运行时库路径。在
~/.bashrc中，添加以下内容（注意我们将 CUDA 路径附加到末尾，因为/usr/local/cuda-12.4/bin中还有另一个gcc和g++，可能不是版本 11，而这是构建所需的），PATH=${PATH:+${PATH}:}/usr/local/cuda-12.4/bin LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}/usr/local/cuda-12.4/lib64
记得重新启动终端或执行
source ~/.bashrc。另一种错误类型是，<your-env-path>/bin/ld: /lib/x86_64-linux-gnu/libc.so.6: undefined reference to `_dl_fatal_printf@GLIBC_PRIVATE' <your-env-path>/bin/ld: /lib/x86_64-linux-gnu/libc.so.6: undefined reference to `_dl_audit_symbind_alt@GLIBC_PRIVATE' <your-env-path>/genesis-test1/bin/ld: /lib/x86_64-linux-gnu/libc.so.6: undefined reference to `_dl_exception_create@GLIBC_PRIVATE' <your-env-path>/bin/ld: /lib/x86_64-linux-gnu/libc.so.6: undefined reference to `__nptl_change_stack_perm@GLIBC_PRIVATE' <your-env-path>/bin/ld: /lib/x86_64-linux-gnu/libc.so.6: undefined reference to `__tunable_get_val@GLIBC_PRIVATE' <your-env-path>/bin/ld: /lib/x86_64-linux-gnu/libc.so.6: undefined reference to `_dl_audit_preinit@GLIBC_PRIVATE' <your-env-path>/bin/ld: /lib/x86_64-linux-gnu/libc.so.6: undefined reference to `_dl_find_dso_for_object@GLIBC_PRIVATE'
这可能是由于你的 conda 环境中的 cuda-toolkit 导致的。请执行以下操作并安装系统级 CUDA，
which nvcc conda uninstall cuda-toolkit
或者，你可以将你的 conda 库路径添加到运行时库路径，
ls $CONDA_PREFIX/lib/libcudart.so # 你应该有这个 # 在你的 ~/.bashrc 中，添加 LD_LIBRARY_PATH=${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}/usr/local/cuda-12.4/lib64
最后，记得在完成上述修复后清除构建，
rm -r build
在
cmake -S . -B build时出现 C/CXX 编译器错误，CMake Error at /snap/cmake/1435/share/cmake-3.31/Modules/CMakeDetermineCCompiler.cmake:49 (message): Could not find compiler set in environment variable CC: /home/tsunw/miniconda3/envs/genesis-test1/bin/x86_64-conda-linux-gnu-cc. Call Stack (most recent call first): CMakeLists.txt:21 (project) CMake Error: CMAKE_C_COMPILER not set, after EnableLanguage CMake Error: CMAKE_CXX_COMPILER not set, after EnableLanguage
你可能没有使用版本 11 的
gcc和g++。请仔细检查（i）版本（ii）二进制文件是否指向预期的路径（iii）二进制路径的顺序，gcc --version g++ --version which gcc which g++ echo $PATH # 例如，/usr/local/cuda-12.4/bin/gcc（版本 = 10.5）不应该在 /usr/bin/gcc（如果通过 apt 正确安装，版本 = 11）之前
运行
examples/rendering/demo.py时出现导入错误，[Genesis] [11:29:47] [ERROR] Failed to import LuisaRenderer. ImportError: /home/tsunw/miniconda3/envs/genesis-test1/bin/../lib/libstdc++.so.6: version `GLIBCXX_3.4.30' not found (required by /home/tsunw/workspace/Genesis/genesis/ext/LuisaRender/build/bin/liblc-core.so)
Conda 的
libstdc++.so.6不支持 3.4.30。你需要将系统的移到 conda 中（参考）。cd $CONDA_PREFIX/lib mv libstdc++.so.6 libstdc++.so.6.old ln -s /usr/lib/x86_64-linux-gnu/libstdc++.so.6 libstdc++.so.6
断言 ‘lerror’ 失败：无法写入进程：管道损坏：你可能需要使用与编译时相同版本的 CUDA。