Implementation:Haosulab ManiSkill PlacementSamplers

Knowledge Sources	Haosulab_ManiSkill
Domains	Robotics, Simulation, Scene_Building
Last Updated	2026-02-15 08:00 GMT

Overview

Concrete tool providing object placement sampling utilities for RoboCasa kitchen environments, supporting uniform random sampling, sequential composite sampling, and multi-region sampling strategies.

Description

This module implements object position samplers that determine where to place kitchen objects within the simulation scene. Objects are placed on surfaces (counters, tables, etc.) with collision checking to ensure valid, non-overlapping placements.

Classes defined:

ObjectPositionSampler -- Abstract base class for all placement samplers. Manages a list of MujocoObject instances, reference positions, and z-offsets. Defines the sample() interface that returns a dictionary mapping object names to (pos, quat, obj) tuples. Also defines valid placement sides (left, right, front, back, and combinations).

UniformRandomSampler -- Places objects uniformly at random within specified x and y ranges relative to a reference position. Supports:

Configurable rotation ranges and rotation axis (x/y/z)
Boundary enforcement to keep objects within the sampling region
Collision validation with up to 5000 retry attempts
Reference-relative placement (on top of other objects)
Quaternion composition with reference rotation

SequentialCompositeSampler -- Chains multiple sub-samplers together, executing them sequentially. Each sub-sampler can reference objects placed by previous samplers. Includes a hide() helper to teleport unwanted objects out of the workspace.

MultiRegionSampler -- Samples from one of four quadrant regions, selected randomly. Each quadrant has its own UniformRandomSampler with region-specific position and range parameters.

RandomizationError -- Custom exception raised when object placement fails after exhausting retries.

Helper function rotate_2d_point() rotates a 2D vector counterclockwise by a given angle.

Usage

Used by the RoboCasa scene builder during scene initialization to place kitchen objects on fixture surfaces.

Code Reference

Source Location

Repository: Haosulab_ManiSkill
File: mani_skill/utils/scene_builder/robocasa/utils/placement_samplers.py

Signature

def rotate_2d_point(input, rot) -> np.array: ...

class RandomizationError(Exception): ...

class ObjectPositionSampler:
    def __init__(self, name, mujoco_objects=None, ensure_object_boundary_in_range=True,
                 ensure_valid_placement=True, reference_pos=(0,0,0), reference_rot=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), reference_rot=0,
                 z_offset=0.0, rng=None, side="all"): ...
    def sample(self, placed_objects=None, reference=None, on_top=True) -> dict: ...

class SequentialCompositeSampler(ObjectPositionSampler):
    def __init__(self, name, rng=None): ...
    def append_sampler(self, sampler, sample_args=None): ...
    def hide(self, mujoco_objects): ...
    def add_objects_to_sampler(self, sampler_name, mujoco_objects): ...
    def sample(self, placed_objects=None, reference=None, on_top=True) -> dict: ...

class MultiRegionSampler(ObjectPositionSampler):
    def __init__(self, name, regions, side="all", mujoco_objects=None,
                 rotation=None, rotation_axis="z", ...): ...
    def sample(self, fixtures=None, reference=None, on_top=True) -> dict: ...

Import

from mani_skill.utils.scene_builder.robocasa.utils.placement_samplers import (
    ObjectPositionSampler, UniformRandomSampler, SequentialCompositeSampler,
    MultiRegionSampler, RandomizationError, rotate_2d_point
)

I/O Contract

Method	Input	Output
`sample()`	`placed_objects: dict`, `reference`, `on_top: bool`	`dict` mapping object names to `(pos, quat, obj)` tuples
`add_objects()`	`mujoco_objects: MujocoObject or list`	None (adds to internal list)
`append_sampler()`	`sampler: ObjectPositionSampler`, `sample_args: dict`	None (adds sub-sampler)

Usage Examples

from mani_skill.utils.scene_builder.robocasa.utils.placement_samplers import (
    UniformRandomSampler, SequentialCompositeSampler
)

# Create a composite sampler for placing objects on a counter
composite = SequentialCompositeSampler(name="counter_placement")

# Add a sampler for the main placement area
counter_sampler = UniformRandomSampler(
    name="counter_top",
    x_range=(-0.2, 0.2),
    y_range=(-0.1, 0.1),
    rotation=(0, 2 * np.pi),
    rotation_axis="z",
    reference_pos=counter.pos,
    z_offset=0.01,
)
composite.append_sampler(counter_sampler)

# Sample placements
placements = composite.sample()

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment