Installation

System requirements

Component	Required
OS	Linux (Ubuntu 20.04 / 22.04 tested)
GPU	NVIDIA, ≥ 8 GB VRAM (CUDA 11.8 or 12.x)
Python	3.10 or 3.11
Disk	~3 GB for code + assets; per-policy checkpoints separate

MetaFine has been tested with SAPIEN 3.0.2 and ManiSkill 3.0.0b22 on driver 535.x. Other GPU / driver combinations are likely to work but are not currently exercised in CI.

Install the simulation core

Create a fresh conda env, clone the repository, and install in editable mode:

$ conda create -n metafine python=3.10 -y
$ conda activate metafine

$ git clone https://github.com/Hiangx-robotics/MetaFine.git metafine
$ cd metafine
$ pip install -e .

This pulls the 15 core runtime dependencies — sapien, mani_skill, gymnasium, torch, h5py, pandas, tyro, trimesh, transforms3d, opencv-python, pyyaml, transformers, and the numerical stack. The install is editable, so any code change in the repo is picked up live.

Optional extras

Two optional extras are declared in pyproject.toml:

$ pip install -e ".[ai]"     # + openai client (AI planner path)
$ pip install -e ".[dev]"    # + pytest for the test suite

The per-policy VLA stacks are deliberately not in the core dep set — they pin conflicting torch / transformers versions. Install only the policies you need (see Policies → Overview).

Download assets

The 40+ part-annotated articulated objects (PartNet-Mobility subset + custom URDFs) and the example task-graph YAMLs ship as a separate dataset so the source repo stays small. Pull from either mirror:

# ModelScope
$ modelscope download --dataset your-handle/metafine

# Hugging Face
$ huggingface-cli download your-handle/metafine --repo-type dataset

Unpack the archive next to the repo root so the resulting layout is metafine/assets/<asset_id>/ and metafine/configs/<name>.yaml.

Per-policy stacks

Every supported VLA backbone is a separately-installable subdirectory under core/policies/. Each has its own pinned dependencies — do not install more than you need:

$ pip install -e core/policies/pi05         # π0.5
$ pip install -e core/policies/openvla      # OpenVLA
$ pip install -e core/policies/openvla-oft  # OpenVLA-OFT
$ # ... see core/policies/<name>/README.md for the rest

Verify the install

From anywhere on the host (not just the repo dir) the import + Gym registration should succeed:

$ python -c "import core.env, core.skill; \
                  import gymnasium as gym; \
                  env = gym.make('grasp_part'); \
                  print('Ready:', type(env.unwrapped).__name__); env.close()"
# → Ready: GraspPartEnv

If you see Ready: GraspPartEnv, the simulation core, the skill registry, and the asset library are all wired up. Continue to Quickstart.