repository·main·Indexed 42 days ago
https://github.com/huggingface/gym-hilA collection of Gymnasium environments for Human-in-the-Loop (HIL) reinforcement learning, version 0.1.14. Optimized for robotic manipulation using the Franka Panda robot and compatible with the Hugging Face LeRobot codebase. It features MuJoCo-based environments such as PandaPickCubeBase-v0, supporting teleoperation via gamepads or keyboards, and provides specialized wrappers like EEActionWrapper and InputsControlWrapper for demonstration collection.
You can install gym-hil via PyPI or from source. It is recommended to use a Python 3.10 environment.
Using Conda:
conda create -y -n gym_hil python=3.10 && conda activate gym_hilUsing pip (PyPI):
pip install gym-hilUsing source:
git clone https://github.com/HuggingFace/gym-hil.git && cd gym-hil
pip install -e .pip install gym-hilThe Franka Panda Robot environments are based on MuJoCo and support human-in-the-loop interaction via gamepads or keyboards.
Available Environments:
PandaPickCubeBase-v0: Core environment (Franka arm and cube).PandaPickCubeGamepad-v0: Includes gamepad control for teleoperation.PandaPickCubeKeyboard-v0: Includes keyboard control for teleoperation.Accessing Intervention Data:
When running an environment, the info dictionary returned by env.step() contains critical human-in-the-loop metadata:
info["is_intervention"] (boolean): Indicates if a human intervened during the step.info["teleop_action"]: If is_intervention is True, this contains the specific action executed by the human.import gymnasium as gym
import gym_hil
env = gym.make("gym_hil/PandaPickCubeBase-v0", render_mode="human", image_obs=True)
obs, info = env.reset()
for i in range(200):
obs, rew, done, truncated, info = env.step(env.action_space.sample())
if info["is_intervention"]:
teleop_action = info["teleop_action"]
# ...
env.close()You can customize gamepad button and axis mappings using a JSON configuration file. This can be done via the CLI when running teleoperation tests or when initializing the environment in code.
Via CLI:
python examples/test_teleoperation.py --controller-config path/to/controller_config.jsonVia Python API:
env = gym.make(
"gym_hil/PandaPickCubeGamepad-v0",
controller_config_path="path/to/controller_config.json",
)JSON Configuration Schema:
The configuration file maps controller inputs to logical actions. If no path is provided, the package uses its bundled controller_config.json.
{
"default": {
"axes": {
"left_x": 0,
"left_y": 1,
"right_x": 2,
"right_y": 3
},
"buttons": {
"a": 1,
"b": 2,
"x": 0,
"y": 3,
"lb": 4,
"rb": 5,
"lt": 6,
"rt": 7
},
"axis_inversion": {
"left_x": false,
"left_y": true,
"right_x": false,
"right_y": true
}
},
"Xbox 360 Controller": {
...
}
}python examples/test_teleoperation.py --controller-config path/to/controller_config.jsonThe apply_action method in FrankaGymEnv uses a combination of Mocap-based Cartesian control and Operational Space Control (OSC).
cartesian_bounds.grasp_command (scaled by MAX_GRIPPER_COMMAND)._n_substeps (calculated as control_dt // physics_dt) applying opspace control to the robot's joints to track the Mocap position and orientation.You can test teleoperation using the provided example script. By default, it uses a gamepad, but you can switch to keyboard control using the --use-keyboard flag.
Run teleoperation:
python examples/test_teleoperation.pyRun with keyboard:
python examples/test_teleoperation.py --use-keyboardpython examples/test_teleoperation.py --use-keyboardThe hil_wrappers.py module provides specialized Gymnasium wrappers to facilitate human interaction and demonstration collection:
EEActionWrapper: Transforms actions into end-effector space for more intuitive human control.InputsControlWrapper: Integrates gamepad or keyboard control into the environment for teleoperation.GripperPenaltyWrapper: An optional wrapper that adds penalties for excessive gripper actions during training/demonstration.Use GymRenderingSpec to define the visual parameters for MuJoCo environments. This includes resolution and camera selection.
Parameters:
height (int): Vertical resolution (default: 128).width (int): Horizontal resolution (default: 128).camera_id (str | int): The ID or name of the camera to use (default: -1).mode (Literal["rgb_array", "human"]): The rendering mode (default: "rgb_array").from gym_hil.mujoco_gym_env import GymRenderingSpec
spec = GymRenderingSpec(height=256, width=256, camera_id="front", mode="rgb_array")The package exports core environment classes for Mujoco-based robotics tasks:
MujocoGymEnv: The base class for Mujoco-based environments.FrankaGymEnv: A specialized environment class for the Franka robot.GymRenderingSpec: A configuration class for specifying rendering requirements within the environment.MujocoGymEnv is a base class that provides a Gymnasium-compatible interface for MuJoCo simulations. It handles physics stepping, rendering, and resource management.
Initialization Parameters:
xml_path (Path): Path to the MuJoCo XML model file.seed (int): Random seed (default: 0).control_dt (float): Control loop timestep (default: 0.02).physics_dt (float): Physics simulation timestep (default: 0.002).render_spec (GymRenderingSpec): Rendering configuration.from pathlib import Path
from gym_hil.mujoco_gym_env import MujocoGymEnv, GymRenderingSpec
env = MujocoGymEnv(
xml_path=Path("path/to/model.xml"),
control_dt=0.05,
render_spec=GymRenderingSpec(width=64, height=64)
)
# Access underlying MuJoCo objects
model = env.model
data = env.data
# Render a frame
frame = env.render()
env.close()FrankaGymEnv is a specialized environment for the Franka Panda robot. It implements operational space control via a mocap body and provides specific observation/action spaces.
Key Features:
Box space of shape (7,) representing [x, y, z, rx, ry, rz, grasp_command]. The first 3 components are Cartesian deltas, the next 3 are rotation deltas, and the last is a gripper command.Dict containing agent_pos (TCP pose, velocity, and gripper pose). If image_obs=True is passed during init, it also includes pixels for front and wrist cameras.reset_robot() to return the robot to its home_position.Initialization Parameters:
xml_path (Path | None): Path to XML. If None, defaults to the internal scene.xml.render_mode (Literal["rgb_array", "human"]): Rendering mode.image_obs (bool): Whether to include camera pixels in observations.home_position (np.ndarray): Joint positions for reset.cartesian_bounds (np.ndarray): Bounds for the TCP movement.import numpy as np
from gym_hil.mujoco_gym_env import FrankaGymEnv
env = FrankaGymEnv(
image_obs=True,
cartesian_bounds=np.asarray([[0.2, -0.3, 0], [0.6, 0.3, 0.5]])
)
# Action format: [dx, dy, dz, drx, dry, drz, grasp]
action = np.array([0.01, 0.0, 0.0, 0.0, 0.0, 0.0, 0.1], dtype=np.float32)
obs = env.step(action)
# If image_obs=True, obs['pixels']['front'] and obs['pixels']['wrist'] are available
env.reset_robot()PassiveViewerWrapper is a wrapper designed to provide a passive visual view of the environment. It is used to register specific 'Viewer' versions of the base environments, allowing users to observe the simulation without necessarily interacting via HIL controls.The gym_hil package provides factory functions to create and wrap Gymnasium environments with Human-in-the-Loop (HIL) capabilities.
make_env: A factory function used to instantiate environments with specific configurations (like gamepad or keyboard control).wrap_env: Used to apply wrappers to an existing environment.These functions are the primary way to access the various registered HIL environment variants, such as those with viewer support or specific input controls.
from gym_hil import make_env, wrap_env
# Example usage pattern for creating a wrapped environment
env = make_env(env_id="gym_hil/PandaPickCubeBase-v0", use_viewer=True)