orca_sim provides simulation environments for the ORCA hand. You can start building your ORCA hand today at orcahand.com.

Install

We recommend using python 3.11 inside of a virtual environment. You can create a virtual environment using uv (how to install uv):

uv venv orca --python 3.11
source orca/bin/activate
uv pip install orca_sim

Alternatively, you can use conda (how to install conda):

conda create -n orca python=3.11 -y
conda activate orca
python -m pip install orca_sim

As we are continuously iterating on orca_sim, you can fetch the latest main building this package from source, so to be in the loop with the latest developments.

git clone https://github.com/orcahand/orca_sim
cd orca_sim && uv pip install -e .

Warning

We are still iterating (a lot!) on this package. If you need stability, consider sticking to the Pypi package (pip install orca_sim).

Getting started

orca_sim follows the Gymnasium API, and uses Mujoco for physics simulation and rendering. You can instantiate an environment with one hand (or both) via:

from orca_sim import OrcaHandRight  # or OrcaHandLeft, OrcaHandCombined

env = OrcaHandRight()
obs, info = env.reset()
obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
env.close()

The 'extended' version of different hands contain additional bodies (incl. inertial properties) such as the camera mount, the U2D2 board and fans.

Hands versioning

By default, any environment defaults to the latest fully-supported embodiment files.

from orca_sim import OrcaHandRight, OrcaHandRightExtended

env = OrcaHandRight()  # latest version of the standard right hand
extended_env = OrcaHandRightExtended()  # latest version of the extended right hand

orca_sim stored different hand versions under versioned scenes/ and models/ directories. You can still pin an older version explicitly when needed:

from orca_sim import OrcaHandCombinedExtended

env = OrcaHandCombinedExtended(version="v1")  # loads the v1 hand

See our random_policy.py example to see how to instantiate and interface an ORCA hand.

Sample task: in-hand cube orientation

orca_sim now also ships a task-level example that augments the right hand with a free-floating cube whose one target face is colored red:

from orca_sim import OrcaHandRightCubeOrientation

env = OrcaHandRightCubeOrientation(version="v2", render_mode="human")
obs, info = env.reset(seed=0)

By default, the task resets to a palm-up open-hand pose with the cube resting on the palm and the red face pointing downward. You can also randomize the initial cube orientation while keeping it unsolved:

env = OrcaHandRightCubeOrientation(
    version="v2",
    initial_red_face="random",
    cube_pos_xy_jitter=0.01,
)
obs, info = env.reset(seed=0)

If you want to keep the environment completely deterministic while you are still building it, you can use the nominal reset directly and add randomization later:

env = OrcaHandRightCubeOrientation(version="v2")

nominal = env.nominal_reset_options()
obs, info = env.reset(options=nominal)

randomized = env.sample_randomized_reset_options(
    seed=0,
    initial_red_face="random",
    cube_pos_xy_jitter=0.01,
)
obs, info = env.reset(options=randomized)

The implementation is intentionally split so it doubles as a porting template:

• The task scene lives in src/orca_sim/scenes/v2/scene_right_cube_orientation.xml and composes the existing hand MJCF with a single task cube.
• The nominal palm-up hand pose and in-palm cube spawn are now authored into the task-specific scene/model files, so opening the XML directly in MuJoCo shows the intended setup.
• The task logic lives in src/orca_sim/task_envs.py, including reset-time cube randomization and optional hand-pose overrides for custom MJCF layouts.