Relations and Strategies#

Relations describe where a placeable asset should be positioned or oriented. Attach them to an asset with add_relation(). Arena considers all relations on that asset together.

Positional relations use solver strategies that convert the requested arrangement into optimization objectives. Orientation relations and placement modifiers are handled separately. Most users keep the default strategies; advanced users can replace entries in RelationSolverParams.strategies.

from isaaclab_arena.relations.relations import IsAnchor, NextTo, On

table.add_relation(IsAnchor())
mug.add_relation(On(table))
bowl.add_relation(On(table))
bowl.add_relation(NextTo(mug))

This describes the intended arrangement without requiring coordinates derived from the dimensions of the table, mug, and bowl.

Anchors#

An anchor is a fixed reference in the relation graph. Mark it with IsAnchor(); the solver does not move it. This marker does not make an asset static or kinematic in physics. A standalone anchor needs a fixed initial pose; in YAML, an omitted pose defaults to identity. An ObjectReference instead derives its pose from the referenced prim within its parent asset. A tabletop or counter reference is a common anchor.

An anchor’s fixed root rotation must be a multiple of 90 degrees about world Z, with no tilt. For an ObjectReference, this restriction applies to its parent asset’s pose; the referenced prim’s authored rotation is already included in its bounds. The solver rotates these bounds into world-aligned bounds.

When the support surface is part of a larger background, use an ObjectReference to identify that surface:

from isaaclab_arena.assets.object_reference import ObjectReference
from isaaclab_arena.assets.object_type import ObjectType

table_reference = ObjectReference(
    name="table",
    prim_path="{ENV_REGEX_NS}/maple_table_robolab/table",
    parent_asset=background,
    object_type=ObjectType.RIGID,
)
table_reference.add_relation(IsAnchor())
mug.add_relation(On(table_reference))

Anchor the background asset directly when its complete bounds represent the support. Use an ObjectReference when only an internal tabletop, counter, or similar prim should support placement.

Common Relations#

Most environments can be described with a small set of relations:

On(parent)

Places an object on a support surface and keeps its footprint within the support bounds. Use clearance_m to leave a vertical gap and edge_margin_m to keep the object away from the support edges.

Set overlap=True to allow the object to extend beyond the support:

box.add_relation(On(table, overlap=True))

This requires overlap in both X and Y (edge contact counts), ignores edge_margin_m, and keeps the same height constraint. It does not guarantee stable support: the object may tip or fall. The default is overlap=False.

On uses the top and horizontal footprint of the parent’s axis-aligned bounding box. For L-shaped, hollow, or concave supports, anchor an ObjectReference that identifies the valid support surface.

The default ON_TREE initializer samples parents before their children, using each parent’s sampled pose and bounds. This sets the starting poses; the solver then optimizes the complete layout jointly.

ClutterOn(parent)

Defines a release pose above a support, before physics. The support can be fixed with IsAnchor or placed through its own relations, such as tray On(table) with tools ClutterOn(tray).

The solver optimizes the support and clutter positions together using the relation and collision losses. An anchored support remains fixed. ObjectPlacer initializes clutter inside a central release region and above overlapping footprints. The release region follows the support as the solver moves it.

Clutter footprints may overlap in XY during initialization; overlapping objects start at separated heights. The height-processing order is shuffled per candidate, so asset order does not always put the same object underneath the others. Setting placement_seed makes this order reproducible with the same placement configuration.

Parameter

Default

Meaning

spread

0.2

Fraction of the support’s width and depth, in (0, 1]. A value of 0.2 selects the central 20% of each axis, or 4% of the XY area.

clearance_m

0.01

Minimum height of the object’s bottom above the support top, in metres.

gap_m

0.03

Initial gap to neighboring release bounds, in metres. Sampling uses the larger of this value and the solver’s collision clearance; subsequent solving uses the shared collision clearance.

edge_margin_m

0.0

Inward margin within the release region, in metres. The rotated object footprint must fit inside the remaining region.

random_yaw

True

Sample world-Z yaw in addition to RotateAroundSolution. This setting controls clutter independently of ObjectPlacerParams.random_yaw_init.

Restrictions:

  • ClutterOn must be the object’s only spatial relation. RotateAroundSolution sets its base rotation; random yaw preserves that rotation’s tilt.

  • Both bbox and mesh collision modes support yaw-only clutter. Roll or pitch requires collision_mode="bbox" on the object.

  • The support must participate in placement and cannot itself use ClutterOn. It must remain upright with a fixed yaw that is a multiple of 90 degrees. For a non-anchor support, disable random_yaw_init and do not use FaceTo on the support.

  • For recording, non-clutter objects with placement relations must be fixed anchors or kinematic rigid bodies.

The clutter_on_relation check enforces the release footprint and minimum height without requiring contact or an upper height limit. With explicit enabled_checks or required_checks, include clutter_on_relation for clutter and on_relation for ordinary On objects. Both checks are enabled by default. The standard validation and pooling rules apply. Disable ObjectPlacerParams.allow_best_loss_fallbacks to reject invalid pooled layouts; direct ObjectPlacer.place() callers must check each result’s success.

A settled pose is the final pose after the configured physics interval. An accepted layout passes the required pre-physics and enabled, applicable post-physics checks. Settled objects may use the full support footprint, beyond the smaller release region. Release checks do not certify the final pile or prevent collisions during falling. Try the movable-bowl example in the shared Clutter Layouts recording and replay workflow.

NextTo(parent)

Places an object beside another object. A side and distance can be specified when needed. Geometric validation rejects candidates that are not on the requested side, or whose gap to the parent differs from distance_m by more than tolerance_m (0.01 m by default). Placing the object closer than requested also fails.

With no additional arguments, NextTo(parent) places the subject on the parent’s positive X side at a distance of 0.05 m.

side accepts Side.POSITIVE_X, Side.NEGATIVE_X, Side.POSITIVE_Y, or Side.NEGATIVE_Y.

NotNextTo(parent)

Defines a side-specific keep-out region next to the parent. The region extends outward from the selected side and spans the parent’s footprint along the perpendicular axis. Validation rejects candidates inside that region. The keep-out margin defaults to 0.1 m. Advanced users can change it by providing a NotNextToLossStrategy for NotNextTo in RelationSolverParams.strategies.

AtPosition(...)

Constrains selected world-coordinate axes. It can be combined with On so the relation determines height while coordinates determine horizontal position.

PositionLimitsBox and PositionLimitsCylindrical

PositionLimitsBox constrains selected world X, Y, or Z coordinates between optional minimum and maximum values. PositionLimitsCylindrical constrains the XY distance from a chosen center using a minimum radius, maximum radius, or both; it does not constrain Z. Both relations contribute solver losses; no built-in validator certifies these bounds.

FaceTo(target)

Rotates an object around world Z so that its local +X heading points toward another object.

from isaaclab_arena.relations.relations import FaceTo

target.add_relation(On(table))
camera_prop.add_relation(On(table))
camera_prop.add_relation(FaceTo(target))

FaceTo determines the heading after position solving:

  • It cannot be combined with RotateAroundSolution.

  • When random yaw initialization is enabled, it replaces the random heading.

  • The target must also participate in relation placement.

  • A movable subject can have only one FaceTo relation.

  • The subject and target must have different XY positions.

Combining Relations#

Relations are most useful in small combinations:

  • On alone means “somewhere on this surface.”

  • On with NextTo means “on this surface, beside that object.”

  • On with AtPosition means “at this horizontal location on the surface.”

  • A positional relation with FaceTo controls both location and orientation.

Avoid specifying more relations than the environment needs. Extra constraints can make the intended layout harder or impossible to satisfy.

Placement Modifiers#

RotateAroundSolution is a pose modifier applied after solving. It changes how a solved pose is used rather than adding a spatial constraint: it adds a fixed roll, pitch, or yaw to the solved pose. The robot-placement example later in this sequence uses it to set the robot’s final heading.

To randomize an object’s position within a region, constrain it with PositionLimitsBox instead of pinning it with AtPosition. Each solved layout lands somewhere inside the box, so resets drawn from the layout pool spread the object across it.

Relations in Environment Specifications#

YAML environment specifications use the same model:

relations:
  - kind: is_anchor
    subject: table
  - kind: 'on'
    subject: mug
    reference: table
  - kind: next_to
    subject: bowl
    reference: mug

Each entry identifies the relation, its subject, and—when needed—the object it references. Add parameters only when the default relation does not express the intended arrangement. Quote 'on' so YAML treats it as a string rather than a Boolean value.

Collision handling is integrated into placement and is not expressed as a relation.

Replay a Recorded Layout#

Placement poses can be replayed from an episode JSONL containing solved poses from earlier runs, bypassing relation solving and post-physics settling.

Following is an example Experiment Definition with an episode JSONL for replay:

# Copyright (c) 2026, The Isaac Lab Arena Project Developers (https://github.com/isaac-sim/IsaacLab-Arena/blob/main/CONTRIBUTORS.md).
# All rights reserved.
#
# SPDX-License-Identifier: Apache-2.0

runs:
  clamp_replay:
    environment:
      type: isaaclab_arena_environments/robolab/tasks/clamp_in_right_bin.yaml
    environment_builder:
      num_envs: 1
      presets: PHYSX
      recorded_variation_samples_path: isaaclab_arena_environments/experiment_configs/placement_record_replay/clamp_placement_replay.jsonl
    policy:
      type: zero_action
    rollout_limit:
      num_episodes: 3

Run it from the repository root:

python isaaclab_arena/evaluation/experiment_runner.py \
    --experiment_config isaaclab_arena_environments/experiment_configs/placement_record_replay/settled_placement_replay_experiment.yaml \
    --device cpu --viz kit

Python callers use ArenaEnvBuilderCfg(recorded_variation_samples_path="layouts.jsonl"). All file paths are relative to the working directory. Placement replay does not rerun geometry, reachability or settling checks. resolve_on_reset and placement_seed are ignored.

File Format#

Each row contains one complete sample under placement:

{"placement": {"layout_id": "layout_000000", "poses": {"cube": {"position_xyz": [0.1, 0.2, 0.3], "rotation_xyzw": [0.0, 0.0, 0.0, 1.0]}}}}

Pose keys are runtime scene-root names. Ordinary objects use their instance names; a single-root embodiment commonly uses "robot"; compound assets must include every name returned by asset.get_scene_root_keys(). Positions are environment-local metres and rotations are xyzw quaternions.

Replay Configuration#

Replay validates finite poses, unit quaternions, consistent root coverage, and reset ownership before constructing the scene. It rejects:

  • unknown roots or incomplete compound assets;

  • missing non-anchor assets constrained by relations;

  • RigidObjectSet assets, whose identity cannot be recovered from poses alone;

  • disabled pose resets, nonzero initial root velocity, or non-fixed asset-owned pose-reset policies.

After validation, one coordinated placement event becomes the root-pose reset writer for all recorded assets and zeros their root velocities. Articulation joint reset behavior remains independent.

Next Steps#

See Record and Replay Placement Poses to settle layouts and save poses for reuse. For table and container examples, see Clutter Layouts.

Continue to Collision Handling to learn how Arena checks placed assets against one another and against fixed geometry.