Implementation:Google deepmind Dm control Locomotion Props

Metadata
Knowledge Sources	dm_control
Domains	Reinforcement Learning, Robotics, Object Interaction
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for creating interactive target objects and placing props within dm_control locomotion environments, providing contact-activated target spheres and collision-aware prop placement initializers.

Description

The locomotion props module provides target objects that serve as navigation goals in locomotion tasks. Targets detect activation through MuJoCo contact checking and change their visual appearance (becoming invisible) once reached. The prop initializer provides collision-aware placement of these objects within arenas using rejection sampling.

The available components include:

• TargetSphere: A non-colliding sphere with a checker-pattern texture that activates (becomes invisible) on first contact with any geom (or specific geoms if filtered). Used as collectible goals in maze foraging tasks.
• TargetSphereTwoTouch: A variant that tracks two separate activations with a debounce period between them. Changes texture color on first touch (initial to interval) and again on second touch (interval to final). Returns a tuple Template:Code as its activation state.
• PropPlacer: An initializer that positions a sequence of props at sampled locations and orientations, using rejection sampling to avoid interpenetration. Optionally settles physics after placement to ensure stability.

Usage

Use TargetSphere when building navigation or foraging tasks where the agent must reach goal locations. Use TargetSphereTwoTouch for tasks requiring the agent to visit a location twice. Use PropPlacer when multiple objects need to be placed at random positions without collisions at the start of each episode.

Code Reference

Source Location

Class	File	Lines
TargetSphere	Template:Code	L32-111
TargetSphereTwoTouch	Template:Code	L113-224
PropPlacer	Template:Code	L53-285

Signature

class TargetSphere(composer.Entity):
    def _build(self, radius=0.6, height_above_ground=1,
               rgb1=(0, 0.4, 0), rgb2=(0, 0.7, 0),
               specific_collision_geom_ids=None,
               name='target'):
        ...

class TargetSphereTwoTouch(composer.Entity):
    def _build(self, radius=0.6, height_above_ground=1,
               rgb_initial=((0, 0.4, 0), (0, 0.7, 0)),
               rgb_interval=((1., 1., .4), (0.7, 0.7, 0.)),
               rgb_final=((.4, 0.7, 1.), (0, 0.4, .7)),
               touch_debounce=.2,
               specific_collision_geom_ids=None,
               name='target'):
        ...

class PropPlacer(composer.Initializer):
    def __init__(self, props, position,
                 quaternion=IDENTITY_QUATERNION,
                 ignore_collisions=False,
                 max_attempts_per_prop=20,
                 settle_physics=False,
                 min_settle_physics_time=0.,
                 max_settle_physics_time=2.,
                 max_settle_physics_attempts=1,
                 raise_exception_on_settle_failure=False):
        ...

Import

from dm_control.locomotion.props import target_sphere
from dm_control.composer.initializers import prop_initializer

I/O Contract

Inputs (TargetSphere)

Parameter	Type	Description
radius	float	Radius of the target sphere in meters. Default 0.6.
height_above_ground	float	Height of the sphere center above the ground plane. Default 1.
rgb1	tuple of 3 floats	Primary color for the checker texture pattern. Default (0, 0.4, 0).
rgb2	tuple of 3 floats	Secondary color for the checker texture pattern. Default (0, 0.7, 0).
specific_collision_geom_ids	set of int or None	If set, only activate on contact with these specific geom IDs.
name	str	Name of this entity in the MJCF model. Default Template:Code.

Inputs (PropPlacer)

Parameter	Type	Description
props	sequence of Entity	The props to place.
position	array or Variation	Fixed position or distribution to sample positions from.
quaternion	array or Variation	Fixed orientation or distribution to sample orientations from.
ignore_collisions	bool	If True, skip rejection sampling. Default False.
max_attempts_per_prop	int	Maximum rejection sampling attempts per prop. Default 20.
settle_physics	bool	If True, step physics after placement until velocities stabilize. Default False.

Outputs

Property/Method	Type	Description
TargetSphere.activated	bool	Whether the target has been contacted this episode.
TargetSphere.geom	mjcf.Element	The sphere geom element for binding in physics.
TargetSphereTwoTouch.activated	tuple(bool, bool)	(touched_once, touched_twice) state.
PropPlacer.__call__(physics, random_state)	None	Places all props; raises EpisodeInitializationError on failure.

Usage Examples

Creating a green target sphere:

from dm_control.locomotion.props import target_sphere

target = target_sphere.TargetSphere(
    radius=0.4,
    height_above_ground=0.5,
    rgb1=(0, 0.4, 0),
    rgb2=(0, 0.7, 0),
    name='goal')

# Attach to an arena
arena.attach(target)

# Check activation during episode
if target.activated:
    print("Target reached!")

Creating a two-touch target:

from dm_control.locomotion.props import target_sphere

target = target_sphere.TargetSphereTwoTouch(
    radius=0.5,
    height_above_ground=0.8,
    touch_debounce=0.2,
    name='two_touch_goal')

# During episode, check activation state
touched_once, touched_twice = target.activated
if touched_twice:
    print("Target fully activated (visited twice)!")

Using PropPlacer for collision-free placement:

from dm_control.composer.initializers import prop_initializer
from dm_control.composer.variation import distributions
from dm_control.locomotion.props import target_sphere

# Create multiple targets
targets = [
    target_sphere.TargetSphere(radius=0.3, name=f'target_{i}')
    for i in range(5)
]

# Attach them to the arena
for t in targets:
    arena.attach(t)

# Create a placer that samples positions uniformly
placer = prop_initializer.PropPlacer(
    props=targets,
    position=distributions.Uniform(low=(-3, -3, 0.5), high=(3, 3, 0.5)),
    ignore_collisions=False,
    max_attempts_per_prop=20,
    settle_physics=False)

# Call during episode initialization
# placer(physics, random_state)

Using TargetSphere as a factory in ManyGoalsMaze:

import functools
from dm_control.locomotion.props import target_sphere
from dm_control.locomotion.tasks import random_goal_maze

# Create a target builder (factory function)
target_builder = functools.partial(
    target_sphere.TargetSphere,
    radius=0.4,
    rgb1=(0, 0, 0.4),
    rgb2=(0, 0, 0.7))

# Pass to ManyGoalsMaze which calls target_builder(name=...) for each target
task = random_goal_maze.ManyGoalsMaze(
    walker=walker,
    maze_arena=arena,
    target_builder=target_builder,
    target_reward_scale=50.0)

Related Pages

• Principle:Google_deepmind_Dm_control_Props_and_Targets