Implementation:ARISE Initiative Robosuite PlacementSamplers
| Knowledge Sources | |
|---|---|
| Domains | Robotics, Scene Generation |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
The placement_samplers module provides classes for sampling valid object positions and orientations in robosuite environments, supporting uniform random placement, boundary-aware sampling, and sequential composite sampling for multi-object scenes.
Description
This module defines three classes that form a hierarchy for object placement in simulation scenes.
ObjectPositionSampler is the abstract base class that defines the interface: it holds a list of MujocoObject instances, a reference position, a z-offset, and configuration flags for boundary checking and valid placement verification. Its sample method (to be implemented by subclasses) accepts a dictionary of existing fixtures and returns a combined dictionary mapping object names to (position, quaternion, MujocoObject) tuples.
UniformRandomSampler extends ObjectPositionSampler and places objects within a rectangular region defined by x_range and y_range relative to a reference position. It supports random rotations around a configurable axis (x, y, or z) with either uniform random, range-bounded, or fixed rotation angles. When ensure_object_boundary_in_range is True, it adjusts the sampling bounds inward by each object's horizontal radius to keep objects fully within the specified region. The collision check ensures that sampled objects do not overlap based on horizontal radii, with up to 5000 retry attempts before raising a RandomizationError. Objects with an init_quat attribute have their sampled rotation composed with the initial orientation via quaternion multiplication.
SequentialCompositeSampler chains multiple ObjectPositionSampler instances together, executing them in order so that later samplers can place objects relative to previously placed ones. It maintains an ordered dictionary of sub-samplers, each with their own sampling arguments. The hide method provides a convenience for removing objects from the visible workspace by sampling them at far-away coordinates. The add_objects_to_sampler method allows dynamically assigning objects to specific sub-samplers by name.
Usage
Use UniformRandomSampler for simple uniform placement of objects within a rectangular workspace. Use SequentialCompositeSampler when objects need to be placed relative to each other (e.g., objects on top of other objects, or objects next to fixed fixtures). These samplers are used by task environments during scene initialization and reset.
Code Reference
Source Location
- Repository: ARISE_Initiative_Robosuite
- File: robosuite/utils/placement_samplers.py
Signature
class ObjectPositionSampler:
def __init__(self, name, mujoco_objects=None, ensure_object_boundary_in_range=True,
ensure_valid_placement=True, reference_pos=(0,0,0), z_offset=0.0, rng=None): ...
def add_objects(self, mujoco_objects): ...
def reset(self): ...
def sample(self, fixtures=None, reference=None, on_top=True) -> dict: ...
class UniformRandomSampler(ObjectPositionSampler):
def __init__(self, name, mujoco_objects=None, x_range=(0,0), y_range=(0,0),
rotation=None, rotation_axis="z", ensure_object_boundary_in_range=True,
ensure_valid_placement=True, reference_pos=(0,0,0), z_offset=0.0, rng=None): ...
def sample(self, fixtures=None, reference=None, on_top=True) -> dict: ...
class SequentialCompositeSampler(ObjectPositionSampler):
def __init__(self, name): ...
def append_sampler(self, sampler, sample_args=None): ...
def add_objects_to_sampler(self, sampler_name, mujoco_objects): ...
def hide(self, mujoco_objects): ...
def sample(self, fixtures=None, reference=None, on_top=True) -> dict: ...
Import
from robosuite.utils.placement_samplers import (
ObjectPositionSampler,
UniformRandomSampler,
SequentialCompositeSampler,
)
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| name | str | Yes | Name of the sampler instance |
| mujoco_objects | MujocoObject or list or None | No | Object(s) to place |
| x_range | tuple(float, float) | No | Min and max x-coordinates for placement (default: (0,0)) |
| y_range | tuple(float, float) | No | Min and max y-coordinates for placement (default: (0,0)) |
| rotation | None or float or Iterable | No | Rotation specification: None=full random, float=fixed, tuple=(min,max) |
| rotation_axis | str | No | Axis about which to rotate: "x", "y", or "z" (default: "z") |
| ensure_object_boundary_in_range | bool | No | Whether to keep objects fully within range bounds (default: True) |
| ensure_valid_placement | bool | No | Whether to check for collision-free placement (default: True) |
| reference_pos | 3-tuple | No | Global reference position for sampling (default: (0,0,0)) |
| z_offset | float | No | Vertical offset added to placement height (default: 0.0) |
| fixtures (sample) | dict or None | No | Existing placements: object_name -> (pos, quat, obj) |
| reference (sample) | str or 3-tuple or None | No | Reference for relative placement |
| on_top (sample) | bool | No | Whether to place on top of reference object (default: True) |
Outputs
| Name | Type | Description |
|---|---|---|
| sample result | dict | Maps object names to (position, quaternion, MujocoObject) tuples. Quaternions are in (w,x,y,z) form. |
Usage Examples
import numpy as np
from robosuite.utils.placement_samplers import (
UniformRandomSampler,
SequentialCompositeSampler,
)
# Create a uniform random sampler for workspace objects
object_sampler = UniformRandomSampler(
name="ObjectSampler",
mujoco_objects=[cube_object, can_object],
x_range=(-0.2, 0.2),
y_range=(-0.2, 0.2),
rotation=None, # Full random rotation around z-axis
rotation_axis="z",
ensure_object_boundary_in_range=True, # Keep objects within bounds
ensure_valid_placement=True, # No overlapping placements
reference_pos=(0.5, 0.0, 0.8), # Center of the table
z_offset=0.01, # Slight offset above surface
)
# Sample placements
placements = object_sampler.sample()
for name, (pos, quat, obj) in placements.items():
print(f"{name}: pos={pos}, quat={quat}")
# Create a sequential composite sampler for relative placement
composite_sampler = SequentialCompositeSampler(name="CompositeSampler")
# First, place the base object
base_sampler = UniformRandomSampler(
name="BaseSampler",
mujoco_objects=[plate_object],
x_range=(-0.1, 0.1),
y_range=(-0.1, 0.1),
reference_pos=(0.5, 0.0, 0.8),
)
composite_sampler.append_sampler(base_sampler)
# Then, place a second object on top of the first
top_sampler = UniformRandomSampler(
name="TopSampler",
mujoco_objects=[cup_object],
x_range=(0, 0),
y_range=(0, 0),
)
composite_sampler.append_sampler(
top_sampler,
sample_args={"reference": plate_object.name, "on_top": True},
)
# Sample all placements sequentially
all_placements = composite_sampler.sample()