KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

isaacgym-utils

★ 100 Open GitHub ↗

Wrappers and utilities for Nvidia IsaacGym

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# isaacgym-utils
This repo contains wrappers and utilities for `isaacgym`

Supported version of Isaac Gym: 1.0rc2

Supported `up_axis` mode: `z` (`UP_AXIS_Z` in the Isaac Gym documentation)

## Installation

### Install IsaacGym

Install IsaacGym from [Nvidia](https://developer.nvidia.com/isaac-gym)

This library supports the latest IsaacGym version - `1.0.preview2`.
It will not work with older versions.

### Install isaacgym-utils

Install `isaacgym-utils`:

```bash
git clone git@github.com:iamlab-cmu/isaacgym-utils.git
pip install -e isaacgym-utils
```

By default, only "core" dependencies are installed. To install dependencies needed for optional `isaagym-utils` capabilities, modify the above `pip install` command to indicate the desired optional capability. The following commands will also install the core dependencies.

Reinforcement learning (RL):
```
pip install -e isaacgym-utils[rl]
```

Parallel IsaacGym instances via Ray:
```
pip install -e isaacgym-utils[ray]
```

Multiple capabilities can be specified:
```
pip install -e isaacgym-utils[ray,rl]
```

Or, install all capabilities:
```
pip install -e isaacgym-utils[all]
```

## Running examples

Examples scripts can be found in `isaacgym-utils/examples/`.
These scripts need to be run at the root level of `isaacgym-utils`:

```bash
cd isaacgym-utils
python examples/run_franka.py
```

Each example script has a corresponding config file in `cfg/` that can be used to change object properties like friction.

### Running with Ray

[Ray](https://github.com/ray-project/ray) is a fast and simple framework for building and running distributed applications.

Requires the `[ray]` or `[all]` installation of `isaacgym-utils`.

See `isaacgym_utils/examples/franka_pick_block_ray.py` for an example of running multiple `isaacgym` instances in parallel using Ray.

### RL environment

Requires the `[rl]` or `[all]` installation of `isaacgym-utils`.

See `isaacgym_utils/rl/vec_env.py` for the abstract Vec Env base class that is used for RL.
It contains definitions of methods that are expected to be overwritten by a child class for a specific RL environment.

See `isaacgym_utils/rl/franka_vec_env.py` for an example of an RL env with a Franka robot using joint control, variable impedance control, and hybrid force-position control.

See `examples/run_franka_rl_vec_env.py` for an example of running the RL environment, and refer to the corresponding config for changing various aspects of the environment (e.g. in the YAML config, the fields under `franka.action` determine what type of action space is used).

For new tasks and control schemes, you can make a new class that inherits `GymVecEnv` (or `GymFrankaVecEnv` if using the Franka) and overwrite the appropriate methods.

## Loading external objects
To load external meshes, the meshes need to be wrapped in an URDF file.
See `assets/ycb` for some examples.
The script `scripts/mesh_to_urdf.py` can help make these URDFs, but using it is not necessary.
Then, they can be loaded via `GymURDFAsset`.
See `GymFrankaBlockVecEnv._setup_single_env_gen` in `isaacgym_utils/rl/franka_vec_env.py` for an example.

## Tensor API

To use IsaacGym's Tensor API, set `scene->gym->use_gpu_pipeline: True` in the yaml configs.

This switches `isaacgym-utils`' API to use the Tensor API backend, and you can access the tensors directly using `scene.tensors`.

To directly write values into writable tensors (see IsaacGym docs for more details), instead of relying on `isaacgym-utils`' internal implementations, you should:
1. Write to a tensor in `scene.tensors`
2. Call `scene.register_actor_tensor_to_update` to ensure that the writes are committed during the next simulation step.

## Things to Note

* Attractors can't be used if `use_gpu_pipeline: True`
* If using `physx` and not controlling the an actor with joint PD control, you must set `dof_props->stiffness` to have all `0`'s, otherwise IsaacGym's internal PD control is still in effect, even if you're sending torque commands or using attractors. This is not a problem when using the `flex` backend.
* We only support `scene->gym->up_axis: z` - setting the `up_axis` to `x` or `y` will give unexpected behaviors for camera rendering. This is a bug internal to IsaacGym.
* `flex` w/ backend supports getting point-wise contacts. `physx` backend w/ `use_gpu_pipeline: True` and `use_gpu: True` only supports getting body-wise contacts (summing up all point-wise contacts). Other `physx` configurations do not support getting any contact forces.
* `flex` does not support `use_gpu_pipeline: True`

## Citation

If you use `isaacgym-utils` in a publication, please consider citing the repo:

```
@misc{isaacgym-utils,
title = {IsaacGym Utilities},
year = {2021},
note = {Developed by the CMU Intelligent Autonomous Manipulation Lab},
url={https://github.com/iamlab-cmu/isaacgym-utils},
author = {Liang, Jacky},
}
```

isaacgym-utils

Was this content helpful?

Recent Feedback

Download README