From e5fc958dcaaf025b9386e05620125ecd68d5fe69 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Fri, 5 Jun 2026 00:14:39 +0800 Subject: [PATCH 1/2] docs(quick_start): restructure installation guide Improve install.md with setup paths, package indexes, Docker and verification steps, and troubleshooting. Deduplicate gensim install commands in simready_pipeline.md via cross-link. Co-authored-by: Cursor --- .../generative_sim/simready_pipeline.md | 44 +--- docs/source/quick_start/install.md | 224 ++++++++++++------ 2 files changed, 160 insertions(+), 108 deletions(-) diff --git a/docs/source/features/generative_sim/simready_pipeline.md b/docs/source/features/generative_sim/simready_pipeline.md index 58aa9cf1..3be5a4c4 100644 --- a/docs/source/features/generative_sim/simready_pipeline.md +++ b/docs/source/features/generative_sim/simready_pipeline.md @@ -23,49 +23,9 @@ python -m embodichain preview-asset \ ## Prerequisites -The full pipeline uses Blender, trimesh, pyrender, and an OpenAI-compatible multimodal chat completions endpoint. Install EmbodiChain with the `gensim` extra and enable both the EmbodiChain package index and Blender package index. +The full pipeline uses Blender, trimesh, pyrender, and an OpenAI-compatible multimodal chat completions endpoint. Install EmbodiChain with the `gensim` extra first — see [Installation (gensim extra)](../../quick_start/install.md#optional-generative-simulation-gensim) for package indexes and install commands. -Install from PyPI with `uv`: - -```bash -uv pip install "embodichain[gensim]" \ - --extra-index-url http://pyp.open3dv.site:2345/simple/ \ - --trusted-host pyp.open3dv.site \ - --extra-index-url https://download.blender.org/pypi/ -``` - -Install from source with `uv`: - -```bash -git clone https://github.com/DexForce/EmbodiChain.git -cd EmbodiChain -uv pip install -e ".[gensim]" \ - --extra-index-url http://pyp.open3dv.site:2345/simple/ \ - --trusted-host pyp.open3dv.site \ - --extra-index-url https://download.blender.org/pypi/ -``` - -Install from PyPI with `pip`: - -```bash -pip install "embodichain[gensim]" \ - --extra-index-url http://pyp.open3dv.site:2345/simple/ \ - --trusted-host pyp.open3dv.site \ - --extra-index-url https://download.blender.org/pypi/ -``` - -Install from source with `pip`: - -```bash -git clone https://github.com/DexForce/EmbodiChain.git -cd EmbodiChain -pip install -e ".[gensim]" \ - --extra-index-url http://pyp.open3dv.site:2345/simple/ \ - --trusted-host pyp.open3dv.site \ - --extra-index-url https://download.blender.org/pypi/ -``` - -Set the OpenAI-compatible LLM api(OpenAI, Gemini, Doubao, etc.) before running the pipeline, or configure them in `embodichain/gen_sim/simready_pipeline/configs/gen_config.json`. Environment variables override the JSON config. +Set the OpenAI-compatible LLM API (OpenAI, Gemini, Doubao, etc.) before running the pipeline, or configure them in `embodichain/gen_sim/simready_pipeline/configs/gen_config.json`. Environment variables override the JSON config. OpenAI-compatible API example: diff --git a/docs/source/quick_start/install.md b/docs/source/quick_start/install.md index ae408f83..58dc14f3 100644 --- a/docs/source/quick_start/install.md +++ b/docs/source/quick_start/install.md @@ -1,136 +1,228 @@ # Installation -## System Requirements +EmbodiChain is a Python framework built on the [DexSim](https://github.com/DexForce) simulation engine (`dexsim_engine` on PyPI). This guide covers system requirements, package indexes, Docker and local install paths, optional generative-simulation dependencies, and verification. + +After installation, continue with the [Quick Start Tutorial](../tutorial/index.rst). + +## Choose your setup + +| Path | Best for | Notes | +|------|----------|-------| +| **Docker** | First run, reproducible GPU sim | Pre-built image with CUDA 12.8, Vulkan, and Python 3.11 | +| **Local + [uv](https://github.com/astral-sh/uv)** | Day-to-day development | Fast installs; recommended with a virtual environment | +| **Local + pip** | Simple environments | Use a virtual environment | + +## System requirements | Component | Requirement | -|-----------|------------| -| **OS** | Linux (x86_64): Ubuntu 20.04+ | -| **GPU** | NVIDIA with compute capability 7.0+ | -| **NVIDIA Driver** | 535 - 570 (580+ is untested and may be unstable) | +|-----------|-------------| +| **OS** | Linux x86_64 (Ubuntu 20.04+ recommended) | +| **GPU** | NVIDIA GPU with compute capability 7.0+ | +| **NVIDIA driver** | ≥ 535 (tested on driver branches up to 580.x) | +| **CUDA** | 12.x (aligned with the Docker image and `dexsim_engine` wheels) | +| **Vulkan** | Host ICD/layer files for GPU rendering (see Docker notes) | | **Python** | 3.10 or 3.11 | +| **Display** (optional) | X11 `DISPLAY` for interactive viewer windows | > [!NOTE] -> Ensure your NVIDIA driver is compatible with your chosen PyTorch wheel. We recommend installing PyTorch from the [official PyTorch instructions](https://pytorch.org/get-started/locally/) for your CUDA version. +> **PyTorch:** EmbodiChain depends on PyTorch transitively (for example via `dexsim_engine` and `pytorch_kinematics`). If you install or upgrade PyTorch separately, match the wheel to your CUDA version using the [official PyTorch install selector](https://pytorch.org/get-started/locally/). -## Installation +## Package indexes -### Docker (Recommended) +EmbodiChain and its simulation backend are published on a DexForce package index. Generative-simulation extras also need Blender's index for the `bpy` wheel. -We strongly recommend using our pre-configured Docker environment, which contains all necessary dependencies including CUDA, Vulkan, and GPU rendering support. +| Index | URL | Used for | +|-------|-----|----------| +| **DexForce (required)** | `http://pyp.open3dv.site:2345/simple/` | `embodichain`, `dexsim_engine`, and related wheels | +| **Blender (gensim only)** | `https://download.blender.org/pypi/` | `bpy` | -**1. Pull the image:** +Reuse these flags on every `pip` / `uv pip` install command: ```bash -docker pull dexforce/embodichain:ubuntu22.04-cuda12.8 -``` +DEXFORCE_INDEX="http://pyp.open3dv.site:2345/simple/" +DEXFORCE_TRUSTED_HOST="pyp.open3dv.site" +BLENDER_INDEX="https://download.blender.org/pypi/" -**2. Start a container:** +PIP_EXTRA_ARGS="--extra-index-url ${DEXFORCE_INDEX} --trusted-host ${DEXFORCE_TRUSTED_HOST}" +GENSIM_EXTRA_ARGS="${PIP_EXTRA_ARGS} --extra-index-url ${BLENDER_INDEX}" +``` -Use the provided run script ([`docker/docker_run.sh`](../../../docker/docker_run.sh)), which handles GPU driver and Vulkan mounting: +> [!TIP] +> To avoid repeating flags, you can configure pip once: +> `pip config set global.extra-index-url "${DEXFORCE_INDEX}"` and +> `pip config set global.trusted-host "${DEXFORCE_TRUSTED_HOST}"`. -```bash -./docker/docker_run.sh -``` +## Docker (recommended for first run) -### uv (Recommended for local development) +The pre-configured image includes CUDA 12.8, Vulkan-related mounts, and dependencies needed for GPU simulation and rendering. -> [!TIP] -> [uv](https://github.com/astral-sh/uv) is an extremely fast Python package manager and project manager. We recommend using `uv` for local development due to its significantly faster dependency resolution and installation times compared to pip. +### Prerequisites -**Install uv:** +- [Docker](https://docs.docker.com/engine/install/) with [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) +- NVIDIA driver ≥ 535 on the host +- For **GUI** runs: working X11 forwarding (`DISPLAY`, `~/.Xauthority`, `/tmp/.X11-unix`) +- For **headless** servers: no display required; use `--headless` in tutorial scripts -```bash -curl -LsSf https://astral.sh/uv/install.sh | sh -``` +### Pull and start a container -**Install from PyPI:** +**1. Pull the image:** ```bash -uv pip install embodichain --extra-index-url http://pyp.open3dv.site:2345/simple/ --trusted-host pyp.open3dv.site +docker pull dexforce/embodichain:ubuntu22.04-cuda12.8 ``` -**Install from source (editable mode):** +**2. Start a container** using the repo script `docker/docker_run.sh` (mounts GPU drivers, Vulkan, shared memory, and your data directory): ```bash git clone https://github.com/DexForce/EmbodiChain.git cd EmbodiChain -uv pip install -e . --extra-index-url http://pyp.open3dv.site:2345/simple/ --trusted-host pyp.open3dv.site +./docker/docker_run.sh ``` -### pip (PyPI) +| Argument | Meaning | +|----------|---------| +| `container_name` | Name for the new container | +| `data_path` | Host directory mounted at `/root/workspace` inside the container | -> [!TIP] -> We strongly recommend using a virtual environment to avoid dependency conflicts. +The script checks for Vulkan ICD/layer and EGL vendor JSON files on the host. Warnings usually mean reduced rendering support; the script exits only when required driver paths are missing entirely. + +**3. Attach to the running container:** ```bash -pip install embodichain --extra-index-url http://pyp.open3dv.site:2345/simple/ --trusted-host pyp.open3dv.site +docker exec -it bash ``` -### From Source +Inside the container, install or update EmbodiChain with the [local installation](#local-installation) commands if needed, then [verify](#verify-installation). -> [!TIP] -> We strongly recommend using a virtual environment to avoid dependency conflicts. +> [!NOTE] +> The script uses `--network=host`, `--gpus all`, and a large `--shm-size` for simulation workloads. Adjust mounts in `docker/docker_run.sh` if your driver files live under `/etc` instead of `/usr/share`. -```bash -git clone https://github.com/DexForce/EmbodiChain.git -cd EmbodiChain -pip install -e . --extra-index-url http://pyp.open3dv.site:2345/simple/ --trusted-host pyp.open3dv.site -``` +## Local installation -### Generative Simulation Dependencies +Use a dedicated virtual environment to avoid conflicts with system Python packages. -If you want to use the generative simulation features, install EmbodiChain with the `gensim` extra. This installs the additional rendering and asset-processing dependencies, including `pyrender` and `bpy`. The `bpy` wheel is distributed from Blender's package index, so the Blender index must be included in the install command. +### 1. Create a virtual environment -**Install from PyPI with `uv`:** +**With uv (recommended):** ```bash -uv pip install "embodichain[gensim]" \ - --extra-index-url http://pyp.open3dv.site:2345/simple/ \ - --trusted-host pyp.open3dv.site \ - --extra-index-url https://download.blender.org/pypi/ +curl -LsSf https://astral.sh/uv/install.sh | sh +uv venv --python 3.11 .venv +source .venv/bin/activate ``` -**Install from source with `uv`:** +**With pip:** + +```bash +python3.11 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +``` + +### 2. Install EmbodiChain + +Set the index variables from [Package indexes](#package-indexes), then pick one row: + +| Source | Tool | Command | +|--------|------|---------| +| PyPI | uv | `uv pip install embodichain ${PIP_EXTRA_ARGS}` | +| PyPI | pip | `pip install embodichain ${PIP_EXTRA_ARGS}` | +| Git clone | uv | `uv pip install -e . ${PIP_EXTRA_ARGS}` | +| Git clone | pip | `pip install -e . ${PIP_EXTRA_ARGS}` | + +**Example — editable install from source with uv:** ```bash git clone https://github.com/DexForce/EmbodiChain.git cd EmbodiChain -uv pip install -e ".[gensim]" \ - --extra-index-url http://pyp.open3dv.site:2345/simple/ \ - --trusted-host pyp.open3dv.site \ - --extra-index-url https://download.blender.org/pypi/ +uv venv --python 3.11 .venv && source .venv/bin/activate +uv pip install -e . \ + --extra-index-url http://pyp.open3dv.site:2345/simple/ \ + --trusted-host pyp.open3dv.site ``` -**Install from PyPI with `pip`:** +**Example — install from PyPI with pip:** ```bash -pip install "embodichain[gensim]" \ - --extra-index-url http://pyp.open3dv.site:2345/simple/ \ - --trusted-host pyp.open3dv.site \ - --extra-index-url https://download.blender.org/pypi/ +pip install embodichain \ + --extra-index-url http://pyp.open3dv.site:2345/simple/ \ + --trusted-host pyp.open3dv.site ``` -**Install from source with `pip`:** +This pulls in `dexsim_engine` (Python package `dexsim`) and the rest of the core dependencies declared in `pyproject.toml`. + +## Optional: generative simulation (`gensim`) + +Install the `gensim` extra for SimReady asset pipelines, Blender-based mesh processing, and `pyrender`. The `bpy` wheel is hosted on Blender's index and must be included in the install command. + +| Source | Tool | Command | +|--------|------|---------| +| PyPI | uv | `uv pip install "embodichain[gensim]" ${GENSIM_EXTRA_ARGS}` | +| PyPI | pip | `pip install "embodichain[gensim]" ${GENSIM_EXTRA_ARGS}` | +| Git clone | uv | `uv pip install -e ".[gensim]" ${GENSIM_EXTRA_ARGS}` | +| Git clone | pip | `pip install -e ".[gensim]" ${GENSIM_EXTRA_ARGS}` | + +**Example:** ```bash -git clone https://github.com/DexForce/EmbodiChain.git -cd EmbodiChain pip install -e ".[gensim]" \ - --extra-index-url http://pyp.open3dv.site:2345/simple/ \ - --trusted-host pyp.open3dv.site \ - --extra-index-url https://download.blender.org/pypi/ + --extra-index-url http://pyp.open3dv.site:2345/simple/ \ + --trusted-host pyp.open3dv.site \ + --extra-index-url https://download.blender.org/pypi/ ``` -## Verify Installation +> [!TIP] +> When using **uv** from a source checkout, `pyproject.toml` already defines the Blender index under `[tool.uv.index]` for the `bpy` source. You still need the DexForce index flags for `dexsim_engine`. -Run the demo script to confirm everything is set up correctly: +For SimReady pipeline usage and LLM configuration, see [SimReady Asset Pipeline](../features/generative_sim/simready_pipeline.md). + +## Verify installation + +### Quick check (all install methods) ```bash +python -c "import embodichain, dexsim; print('embodichain', embodichain.__version__); print('dexsim', dexsim.__version__)" +``` + +You should see version strings for both packages with no import errors. + +### Simulation tutorial (source tree or Docker with repo) + +The tutorial script `scripts/tutorials/sim/create_scene.py` ships with the repository. Run it from the **repository root**: + +```bash +cd /path/to/EmbodiChain python scripts/tutorials/sim/create_scene.py ``` -If the installation is successful, you will see a simulation window with a rendered scene. To run without a display: +- **With a display:** omit `--headless` to open the DexSim viewer after the scene is built. +- **Headless / SSH:** use `--headless` to run without a window (FPS logs in the terminal): ```bash python scripts/tutorials/sim/create_scene.py --headless ``` + +Optional GPU smoke test: + +```bash +python scripts/tutorials/sim/create_scene.py --headless --device cuda +``` + +Press `Ctrl+C` to stop; the script cleans up the simulation on exit. + +## Troubleshooting + +| Symptom | What to try | +|---------|-------------| +| `Could not find a version` / `No matching distribution` for `embodichain` or `dexsim_engine` | Add the DexForce index and `--trusted-host pyp.open3dv.site` (see [Package indexes](#package-indexes)). | +| `No module named 'dexsim'` after install | Reinstall with the DexForce index; `dexsim` is provided by the `dexsim_engine` package. | +| Docker Vulkan / EGL warnings from `docker_run.sh` | Install host NVIDIA drivers and Vulkan user-space packages; paths must be files under `/etc` or `/usr/share`, not directories. | +| Viewer does not open | Export `DISPLAY`, allow X11 access (`xhost +local:` on the host), and ensure `~/.Xauthority` is mounted (the run script does this by default). | +| PyTorch / CUDA errors at runtime | Reinstall a PyTorch build that matches your driver/CUDA from [pytorch.org](https://pytorch.org/get-started/locally/). | +| `bpy` install fails | Include the Blender index (`https://download.blender.org/pypi/`) and use Python 3.10 or 3.11. | + +## Next steps + +- [Quick Start Tutorial](../tutorial/index.rst) +- [Simulation Manager](../overview/sim/sim_manager.md) +- [Build documentation](docs.md) From 0da022d3298620bd52819aa6504f269144ab0a53 Mon Sep 17 00:00:00 2001 From: yuecideng Date: Fri, 5 Jun 2026 00:16:52 +0800 Subject: [PATCH 2/2] wip --- embodichain/lab/gym/envs/managers/manager_base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embodichain/lab/gym/envs/managers/manager_base.py b/embodichain/lab/gym/envs/managers/manager_base.py index 645902ba..5167b6e7 100644 --- a/embodichain/lab/gym/envs/managers/manager_base.py +++ b/embodichain/lab/gym/envs/managers/manager_base.py @@ -372,7 +372,7 @@ def _process_functor_cfg_at_play(self, functor_name: str, functor_cfg: FunctorCf * Resolving the scene entity configuration for the functor. * Initializing the functor if it is a class. - Since the above steps rely on PhysX to parse over the simulation scene, they are deferred + Since the above steps rely on dexsim to parse over the simulation scene, they are deferred until the simulation starts playing. Args: