Relations Reference

The page documents the spatial relations available in Isaac Lab - Arena. For the placement checks named in each Validation section, see Placement Validation.

Summary

AlignWith	Align bounding-box centres along one world axis, within a band, leaving other axes unconstrained.
AtPosition	Constrains object to specific world coordinates.
ClutterOn	Indicates that an object should be dropped on top of a parent object.
FaceTo	Relates an object's local +X heading to a target object's world-XY direction.
IsAnchor	Indicates that this object is an anchor (unmovable) for relation solving.
NextTo	Indicates that an object should be placed next to a parent object, on a specified side.
NotNextTo	Forbids placing the child next to the parent on the given side.
On	Indicates that an object should be placed on top of a parent object.
PositionLimitsBox	Constrains an object's position to an axis-aligned box in world coordinates.
PositionLimitsCylindrical	Constrains an object's world-XY radius around a fixed center.
RequiresReachability	Indicates that the robot must be able to reach this object.
RotateAroundSolution	Specifies an explicit rotation to apply on top of the solver solution.

API reference

class AlignWith(

parent,

axis,

offset_m=0.0,

tolerance_m=0.02,

relation_loss_weight=1.0,

)

Align bounding-box centres along one world axis, within a band, leaving other axes unconstrained.

YAML kind: align_with

Parameters:

• parent (PlaceableAsset) – Reference asset participating in placement.

• axis (Axis | str) – World axis to align, one of x, y, or z.

• offset_m (float) – Signed subject-minus-reference centre displacement along that axis.

• tolerance_m (float) – Zero-penalty alignment band and maximum error accepted by placement validation.

• relation_loss_weight (float) – Weight of the alignment objective during solving.

Validation

The align_with check rejects a centre error along axis above tolerance_m.

Restrictions

• The subject cannot be an anchor, and the reference must be a different asset placed by relations.

• With FaceTo on the subject or reference, X or Y alignment requires that asset’s placement-box centre to lie on its yaw axis.

class AtPosition(x=None, y=None, z=None, relation_loss_weight=1.0)

Constrains object to specific world coordinates.

YAML kind: at_position

This is a unary relation (no parent) that pins an object’s position to specific x, y, and/or z world coordinates. Any axis set to None is unconstrained by this relation (allowing other relations like On to control that axis).

Note: Loss computation is handled by AtPositionLossStrategy in optimization/losses/relation_loss_strategies.py.

Parameters:

• x (float | None) – Target x world coordinate, or None to leave unconstrained.

• y (float | None) – Target y world coordinate, or None to leave unconstrained.

• z (float | None) – Target z world coordinate, or None to leave unconstrained.

• relation_loss_weight (float) – Weight for the relationship loss function.

Validation

None; a solver objective only.

class ClutterOn(

parent,

spread=0.2,

clearance_m=0.01,

gap_m=0.03,

random_yaw=True,

edge_margin_m=0.0,

relation_loss_weight=1.0,

)

Indicates that an object should be dropped on top of a parent object.

YAML kind: clutter_on

The object’s bottom must clear the support surface; contact is not required. The support may be an anchor or positioned jointly through its own relations.

Parameters:

• parent (PlaceableAsset) – Support fixed with IsAnchor or positioned through its own relations.

• spread (float) – Fraction of support width and depth available for release, centered on the support. For example, 0.2 restricts each axis to its central 20%; settled objects may use the full support.

• clearance_m (float) – Release clearance above the support in metres.

• gap_m (float) – Initial clearance from neighboring release bounds in metres, at least the solver clearance.

• random_yaw (bool) – Sample world-Z yaw in addition to RotateAroundSolution.

• edge_margin_m (float) – Inward margin within the release region in metres.

• relation_loss_weight (float) – Weight for the relation loss.

Validation

The clutter_on_relation check rejects a footprint outside the release region or too little clearance.

Restrictions

• It must be the object’s only spatial relation; RotateAroundSolution may set its base rotation.

• Roll or pitch requires collision_mode="bbox" on the object; mesh supports yaw only.

• The support must be placed by relations and cannot itself use ClutterOn. It must stay upright, with a fixed yaw that is a multiple of 90 degrees, so a movable support cannot use FaceTo or ObjectPlacerParams.random_yaw_init.

• For recording, other objects with placement relations must be anchors or kinematic rigid bodies.

class FaceTo(parent)

Relates an object’s local +X heading to a target object’s world-XY direction.

YAML kind: face_to

This orientation relation does not constrain either object’s position. The subject’s XY position must differ from the target’s.

Parameters:

parent (PlaceableAsset) – Target object that defines the facing direction.

Validation

The face_to check rejects a subject at the target’s XY position.

Restrictions

• A subject can have only one FaceTo, cannot be an anchor, and cannot also use RotateAroundSolution.

• The target must also be placed by relations.

class IsAnchor

Indicates that this object is an anchor (unmovable) for relation solving.

YAML kind: is_anchor

Anchor objects are fixed references that won’t be optimized during relation solving. Multiple objects can be marked as anchors. Each anchor must have an initial_pose set before calling ObjectPlacer.place().

Validation

None; anchors are not moved.

Restrictions

• The anchor’s root rotation must be a multiple of 90 degrees about world Z, with no tilt. For an ObjectReference, this applies to its parent asset’s pose.

• A background with mesh collision cannot have relations, IsAnchor included. Anchor an ObjectReference to its support prim instead.

class NextTo(

parent,

side,

relation_loss_weight=1.0,

distance_m=0.05,

cross_position_ratio=None,

tolerance_m=0.01,

)

Indicates that an object should be placed next to a parent object, on a specified side.

YAML kind: next_to

This relation specifies that a child object should be placed adjacent to the parent object on a specified side, at a given distance. The gap may be anywhere within tolerance_m of distance_m.

Note: Loss computation is handled by NextToLossStrategy in optimization/losses/relation_loss_strategies.py.

Parameters:

• parent (PlaceableAsset) – The parent asset that this object should be placed next to.

• side (Side | str) – Which axis direction to place the object.

• relation_loss_weight (float) – Weight for the relationship loss function.

• distance_m (float) – Target distance from parent’s boundary in meters (default: 5cm).

• cross_position_ratio (float | None) – Where to place the child along the parent’s perpendicular (cross) axis, from -1.0 (min edge) through 0.0 (centered) to 1.0 (max edge). The cross axis depends on the side: for POSITIVE_X / NEGATIVE_X the cross axis is Y; for POSITIVE_Y / NEGATIVE_Y it is X. Default: None (any position within the valid cross-axis range). Set 0.0 explicitly to prefer centering.

• tolerance_m (float) – Allowed gap error in meters. The solver treats any gap within this value of distance_m as satisfied, and validation passes when the side and distance violations are each within it. cross_position_ratio is a soft preference, not gated.

Validation

The next_to check rejects the wrong side or a gap error above tolerance_m.

class NotNextTo(

parent,

relation_loss_weight=1.0,

side=Side.POSITIVE_X,

tolerance_m=0.01,

)

Forbids placing the child next to the parent on the given side.

YAML kind: not_next_to

The inverse of NextTo. Blocks the whole half-plane past the parent’s edge on that side, within the parent’s perpendicular footprint (for side=+Y: all of +Y past the +Y edge, clipped to the parent’s X extent). Anywhere off to either side of that footprint stays free, at any distance.

Note: Loss computation is handled by NotNextToLossStrategy in optimization/losses/relation_loss_strategies.py.

Parameters:

• parent (PlaceableAsset) – The parent asset whose adjacent half-plane is forbidden.

• relation_loss_weight (float) – Weight for the relationship loss function.

• side (Side | str) – Which side of the parent is blocked (default: Side.POSITIVE_X).

• tolerance_m (float) – Slack (meters) for placement validation: the child passes when it has cleared the keep-out zone to within this value.

Validation

The not_next_to check rejects a child that has not cleared the blocked region.

class On(

parent,

relation_loss_weight=1.0,

clearance_m=0.01,

edge_margin_m=0.05,

overlap=False,

)

Indicates that an object should be placed on top of a parent object.

YAML kind: on

This relation specifies that a child object should be placed on top of the parent object, with X/Y bounded within the parent’s extent (optionally inset by edge_margin_m so the child stays off the rim) and Z positioned on the parent’s top surface. With overlap=True, only intersection with the parent’s original footprint is required on both horizontal axes; the margin is ignored.

Note: Footprint overlap does not guarantee stable support; the child may tip or fall.

Note: Loss computation is handled by OnLossStrategy in optimization/losses/relation_loss_strategies.py.

Parameters:

• parent (PlaceableAsset) – The parent asset that this object should be placed on top of.

• relation_loss_weight (float) – Weight for the relationship loss function.

• clearance_m (float) – Safety clearance above parent’s surface in meters (default: 1cm).

• edge_margin_m (float) – Inward inset from each X/Y edge of the parent’s surface in meters (default: 5cm), applied only for containment. Ignored for overlap.

• overlap (bool) – Allow footprint overlap instead of full containment on both X and Y axes (default: False). Ignores edge_margin_m when True.

Validation

The on_relation check rejects a child off the parent’s top or outside its footprint.

class PositionLimitsBox(

x_limits=(None, None),

y_limits=(None, None),

z_limits=(None, None),

relation_loss_weight=1.0,

)

Constrains an object’s position to an axis-aligned box in world coordinates.

YAML kind: position_limits_box, or position_limits

Specify each axis as a (minimum, maximum) pair; None leaves that bound unconstrained. Omitted axes are unconstrained.

Parameters:

• x_limits (Sequence[float | None]) – (minimum, maximum) world x, either None for no bound.

• y_limits (Sequence[float | None]) – (minimum, maximum) world y, either None for no bound.

• z_limits (Sequence[float | None]) – (minimum, maximum) world z, either None for no bound.

• relation_loss_weight (float) – Weight for the relationship loss function.

Validation

None; a solver objective only.

class PositionLimitsCylindrical(

center_x,

center_y,

radius_min=None,

radius_max=None,

relation_loss_weight=1.0,

)

Constrains an object’s world-XY radius around a fixed center.

YAML kind: position_limits_cylindrical

A lower bound creates a cylindrical keep-out region, an upper bound keeps the object inside a cylinder, and both bounds create a cylindrical annulus. The relation constrains only XY; use PositionLimitsBox separately for Z or axis-aligned XY limits.

Parameters:

• center_x (float) – World x of the centre.

• center_y (float) – World y of the centre.

• radius_min (float | None) – Minimum XY distance from the centre, or None for no bound.

• radius_max (float | None) – Maximum XY distance from the centre, or None for no bound.

• relation_loss_weight (float) – Weight for the relationship loss function.

Validation

None; a solver objective only.

class RequiresReachability

Indicates that the robot must be able to reach this object.

YAML kind: requires_reachability

It does not affect placement geometry during optimization, but rejects unreachable placements.

Validation

The ik_reachable check rejects placements the robot cannot reach. It runs only when the embodiment has a cuRobo config.

class RotateAroundSolution(roll_rad=0.0, pitch_rad=0.0, yaw_rad=0.0)

Specifies an explicit rotation to apply on top of the solver solution.

YAML kind: rotate_around_solution

When ObjectPlacer applies positions, objects with this marker will have the specified rotation applied on top of the solved position to create a fixed Pose.

Note: This is NOT a spatial relation - the RelationSolver ignores it. It only affects how ObjectPlacer applies the solved position to the object.

Parameters:

• roll_rad (float) – Roll rotation in radians.

• pitch_rad (float) – Pitch rotation in radians.

• yaw_rad (float) – Yaw rotation in radians.

Validation

None.

Enum parameters take their string values, for example side: positive_x.

class Side(*values)

Axis direction for spatial relationships.

POSITIVE_X = 'positive_x'

NEGATIVE_X = 'negative_x'

POSITIVE_Y = 'positive_y'

NEGATIVE_Y = 'negative_y'

class Axis(*values)

World axis for single-axis relations.

X = 'x'

Y = 'y'

Z = 'z'

class PlaceableAsset

An asset that relations can place. In YAML, a relation’s parent is its reference node.