🎥

uv環境でのGenesisセットアップ - LuisaRenderのビルドまで

に公開
Python
genesis
uv
luisarender
tech

はじめに

Pythonでプロジェクトを開発する際、uvはパッケージ管理にとても便利で重宝している。
しかし、GenesisのRayTracerを利用するためにはgitで直接クローンを行い、LuisaRenderのビルドも必要になる。 (詳細は以下の記事を参照)

https://genesis-world.readthedocs.io/en/latest/user_guide/getting_started/visualization.html#photo-realistic-ray-tracing-rendering

この記事では、uv環境でGenesisのセットアップからLuisaRenderのビルドを行い、RayTracerを利用できるようにする手順を記録する。

使用知識

  • python
  • uv (venv)
  • git (submodule)

使用環境

  • OS: Ubuntu 24.04.2 LTS
  • cmake: 4.1.0
  • gcc/g++: 13.3.0
  • Python: 3.12.3
  • uv: 0.8.0

※ 公式の検証環境よりも新しいOSを使用

Genesisのインストール手順

uvでのプロジェクト作成

この記事では、genesis-uv-setupという名前でプロジェクトを作成する。

mkdir genesis-uv-setup
cd genesis-uv-setup
uv init

Genesisをsubmoduleに追加

git submodule add https://github.com/Genesis-Embodied-AI/Genesis.git ext/Genesis

以下のように.gitmodulesが作成される。

# .gitmodules
[submodule "ext/Genesis"]
	path = ext/Genesis
	url = https://github.com/Genesis-Embodied-AI/Genesis.git

記事執筆時点でのGenesisの最新バージョンはv0.3.1であるため、以下のコマンドでチェックアウトする。

cd ext/Genesis
git checkout v0.3.1

Genesisのsubmoduleを初期化

この時点で、ext/Genesis/genesis/extにLuisaRenderを含むsubmoduleがクローンされてくる。

cd ext/Genesis
git submodule update --init --recursive

pyproject.tomlの編集

  • 環境指定の追加 (PyMeshLabのインストール失敗を回避するため。issue[1]を参照)
  • Genesisの追加 (pathを追加)
  • Genesisの依存関係(torch)の追加
[project]
name = "genesis-uv-setup"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "genesis-world[render]",
    "torch>=2.8.0",
]

[tool.uv]
required-environments = [
    "sys_platform == 'linux' and platform_machine == 'x86_64'",
]

[tool.uv.sources]
genesis-world = { path = "ext/Genesis" }
torch = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
]
torchvision = [
  { index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
  { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
]

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

Genesisをuvにインストール

uv sync

LuisaRenderのビルド手順

Terminal上で仮想環境をアクティベート

ビルド時にpybind11を内部で利用するため、Terminal上で仮想環境をアクティベートしておく。

source .venv/bin/activate

ビルドツールのインストール

sudo apt install build-essential manpages-dev software-properties-common
sudo snap install cmake --classic

依存関係のインストール

sudo apt install libvulkan-dev xorg-dev # Vulkan, X11 & RandR
sudo apt-get install uuid-dev # UUID 
sudo apt-get install zlib1g-dev # zlib

LuisaRenderのビルド

PYTHON_VERSIONSは使用しているPythonのバージョンに合わせる。
(この記事では3.12)

cd ext/Genesis/genesis/ext/LuisaRender
cmake -S . -B build -D CMAKE_BUILD_TYPE=Release -D PYTHON_VERSIONS=3.12 -D LUISA_COMPUTE_DOWNLOAD_NVCOMP=ON -D LUISA_COMPUTE_ENABLE_GUI=OFF -D LUISA_RENDER_BUILD_TESTS=OFF
cmake --build build -j $(nproc)

ext/Genesis内のpyproject.tomlを以下のように編集する。
これによって、生成されるLuisaRenderのバイナリがパッケージに含まれるようになる。

# ext/Genesis/pyproject.toml
[tool.setuptools.package-data]
genesis = [
    "assets/*",
+   "ext/LuisaRender/build/bin/*",
    "ext/pyrender/fonts/*",
    "ext/pyrender/shaders/*",
    "ext/VolumeSampling",
]

変更をuvの仮想環境に適用

uv sync

テスト

公式のデモ用コードを用いる。
RayTracerのテストを含む

https://github.com/Genesis-Embodied-AI/Genesis/blob/main/examples/rendering/demo.py

screenshot

おわりに

ロボットの強化学習などでGenesisに注目が集まっているため、適宜記事の執筆を行っていきたい。

脚注

  1. https://github.com/cnr-isti-vclab/PyMeshLab/issues/438 ↩︎

Discussion