Implementation:ARISE Initiative Robosuite ToolHang Environment
| Knowledge Sources | |
|---|---|
| Domains | Robotics, Simulation, Manipulation |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
Concrete tool for simulating a multi-step tool hanging manipulation task provided by robosuite.
Description
The ToolHang class implements a challenging single-arm robot tool hanging task on a tabletop workspace. The environment features three objects: a stand with a mounting slot, a hook frame that must be inserted into the stand, and a ratcheting wrench (tool) that must be hung on the frame. The robot must first assemble the frame onto the stand and then hang the tool on the frame's hook, making this one of the most complex single-arm tasks in robosuite.
The reward function uses only sparse rewards. A discrete reward of 1.0 is provided when the task is successfully completed, scaled by reward_scale. The success criterion requires both sub-tasks to be satisfied simultaneously: (1) the frame must be correctly assembled onto the stand (the stand base must be upright, the bottom of the hook frame must be close enough to the base, and the frame must be between the walls of the stand), and (2) the tool must be correctly hung on the frame (the robot is not touching the tool, the tool hole is making contact with the frame hook, the tool hole is close to the frame hook line, opposite sides of the tool hole are on opposite sides of the hook, and the tool is inserted far enough along the hook).
The environment sets up a SequentialCompositeSampler for object placement with carefully calibrated position and rotation ranges for each of the three objects. The stand is placed at a fixed position while the frame and tool have small randomization ranges. Observations include positions, orientations, and relative poses for the stand base, frame intersection site, and tool body, as well as boolean indicators for whether the frame is assembled and whether the tool is on the frame.
Usage
Use this environment for benchmarking advanced manipulation policies that require long-horizon multi-step reasoning, including object assembly and tool use. This is considered one of the hardest single-arm tasks in robosuite and is commonly used for evaluating imitation learning and offline reinforcement learning approaches.
Code Reference
Source Location
- Repository: ARISE_Initiative_Robosuite
- File: robosuite/environments/manipulation/tool_hang.py
- Lines: 1-739
Signature
class ToolHang(ManipulationEnv):
def __init__(
self,
robots,
env_configuration="default",
controller_configs=None,
gripper_types="default",
base_types="default",
initialization_noise="default",
table_full_size=(0.8, 0.8, 0.05),
table_friction=(1.0, 5e-3, 1e-4),
use_camera_obs=True,
use_object_obs=True,
reward_scale=1.0,
reward_shaping=False,
has_renderer=False,
has_offscreen_renderer=True,
render_camera="frontview",
render_collision_mesh=False,
render_visual_mesh=True,
render_gpu_device_id=-1,
control_freq=20,
lite_physics=True,
horizon=1000,
ignore_done=False,
hard_reset=True,
camera_names="agentview",
camera_heights=256,
camera_widths=256,
camera_depths=False,
camera_segmentations=None,
renderer="mjviewer",
renderer_config=None,
seed=None,
):
Import
from robosuite.environments.manipulation.tool_hang import ToolHang
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| robots | str or list of str | Yes | Specification for a single single-arm robot (e.g., "Panda") |
| table_full_size | 3-tuple | No | (x, y, z) dimensions of the table. Default: (0.8, 0.8, 0.05) |
| table_friction | 3-tuple | No | MuJoCo friction parameters for the table. Default: (1.0, 5e-3, 1e-4) |
| reward_scale | None or float | No | Scales the normalized reward. Default: 1.0 |
| reward_shaping | bool | No | If True, uses dense rewards (currently only sparse is implemented). Default: False |
| control_freq | float | No | Control signals per second. Default: 20 |
| horizon | int | No | Episode length in timesteps. Default: 1000 |
Outputs
| Name | Type | Description |
|---|---|---|
| base_pos | np.array (3,) | 3D position of the stand base geom |
| base_quat | np.array (4,) | Quaternion orientation of the stand base |
| frame_pos | np.array (3,) | 3D position of the frame intersection site |
| frame_quat | np.array (4,) | Quaternion orientation of the frame |
| tool_pos | np.array (3,) | 3D position of the tool body |
| tool_quat | np.array (4,) | Quaternion orientation of the tool |
| frame_is_assembled | float (1,) | 1.0 if the frame is correctly assembled on the stand, 0.0 otherwise |
| tool_on_frame | float (1,) | 1.0 if the tool is correctly hung on the frame, 0.0 otherwise |
| {obj}_to_{prefix}eef_pos | np.array (3,) | Relative position from each object to end-effector |
| reward | float | Scalar reward value per step |
Usage Examples
import robosuite as suite
import numpy as np
# Create a ToolHang environment
env = suite.make(
env_name="ToolHang",
robots="Panda",
has_renderer=False,
has_offscreen_renderer=False,
use_camera_obs=False,
use_object_obs=True,
reward_scale=1.0,
horizon=1000,
)
obs = env.reset()
for i in range(1000):
action = np.random.randn(env.action_dim)
obs, reward, done, info = env.step(action)
if done:
break
env.close()