Implementation:Google deepmind Dm control Manipulation Primitive

Knowledge Sources	Google_deepmind_Dm_control
Domains	Robotics, Manipulation
Last Updated	2026-02-15 04:00 GMT

Overview

The Primitive module defines composable prop entities made from single primitive MuJoCo geoms (sphere, box, ellipsoid, cylinder, capsule) for use as manipulable objects in manipulation tasks.

Description

The base Primitive class extends composer.Entity and builds an MJCF model containing a single geom of a specified type with configurable size and mass. Each prop includes five sensors: a touch sensor (via a slightly enlarged transparent site), a position sensor (framepos), an orientation sensor (framequat), a linear velocity sensor (framelinvel), and an angular velocity sensor (frameangvel). The PrimitiveObservables class exposes all five sensors as observables, inheriting from both composer.Observables and FreePropObservableMixin.

Five convenience subclasses provide specific shapes with sensible defaults: Sphere (default radius 0.05), Box (default half-lengths [0.05, 0.1, 0.15]), Ellipsoid (default radii matching box half-lengths), Cylinder (default radius 0.05, half-length 0.15), and Capsule (same defaults as cylinder). The BoxWithSites variant extends Box by adding eight corner sites at all vertices of the box geom, enabling precise spatial tracking of box corners for tasks that require orientation-aware manipulation.

All props can have their visual appearance customized through the geom property (for changing color, friction, etc.) and support the standard Composer entity lifecycle including attachment to arenas and other entities.

Usage

Use these primitive props as manipulable objects in manipulation tasks. Select the appropriate shape subclass based on your task requirements: Sphere for rolling tasks, Box or BoxWithSites for stacking and placement tasks, Cylinder for grasping tasks, etc. The touch sensor is useful for detecting when a gripper has made contact with the prop.

Code Reference

Source Location

• Repository: Google_deepmind_Dm_control
• File: dm_control/manipulation/props/primitive.py
• Lines: 1-212

Signature

class Primitive(composer.Entity):
    def _build(self, geom_type, size, mass=None, name=None):
    def _build_observables(self):
    def geom(self):  # property
    def touch(self):  # property
    def position(self):  # property
    def orientation(self):  # property
    def linear_velocity(self):  # property
    def angular_velocity(self):  # property
    def mjcf_model(self):  # property
    def name(self):  # property

class PrimitiveObservables(composer.Observables,
                           composer.FreePropObservableMixin):
    def position(self):  # observable
    def orientation(self):  # observable
    def linear_velocity(self):  # observable
    def angular_velocity(self):  # observable
    def touch(self):  # observable

class Sphere(Primitive):
    def _build(self, radius=0.05, mass=None, name='sphere'):

class Box(Primitive):
    def _build(self, half_lengths=None, mass=None, name='box'):

class BoxWithSites(Box):
    def _build(self, half_lengths=None, mass=None, name='box'):
    def corner_sites(self):  # property

class Ellipsoid(Primitive):
    def _build(self, radii=None, mass=None, name='ellipsoid'):

class Cylinder(Primitive):
    def _build(self, radius=0.05, half_length=0.15, mass=None, name='cylinder'):

class Capsule(Primitive):
    def _build(self, radius=0.05, half_length=0.15, mass=None, name='capsule'):

Import

from dm_control.manipulation.props.primitive import Primitive
from dm_control.manipulation.props.primitive import Sphere
from dm_control.manipulation.props.primitive import Box
from dm_control.manipulation.props.primitive import BoxWithSites
from dm_control.manipulation.props.primitive import Ellipsoid
from dm_control.manipulation.props.primitive import Cylinder
from dm_control.manipulation.props.primitive import Capsule

I/O Contract

Inputs (Primitive._build)

Name	Type	Required	Description
geom_type	str	Yes	MuJoCo geom type string (e.g., 'sphere', 'box', 'ellipsoid', 'cylinder', 'capsule')
size	list or np.ndarray	Yes	Up to 3 numbers specifying the geom size, depending on the type
mass	float	No	Mass of the geom; if None, uses MuJoCo's density-based mass computation
name	str	No	Name for this prop entity

Inputs (Sphere._build)

Name	Type	Required	Description
radius	float	No	Sphere radius (default: 0.05)
mass	float	No	Mass of the sphere
name	str	No	Name for this prop (default: 'sphere')

Outputs

Name	Type	Description
mjcf_model	mjcf.RootElement	The MJCF model root element for this prop
geom	mjcf element	The prop's geom element for customizing appearance and physics
touch	mjcf sensor	Touch sensor for detecting contact
position	mjcf sensor	Framepos sensor for ground truth position
orientation	mjcf sensor	Framequat sensor for ground truth orientation
linear_velocity	mjcf sensor	Framelinvel sensor for ground truth linear velocity
angular_velocity	mjcf sensor	Frameangvel sensor for ground truth angular velocity
corner_sites (BoxWithSites)	tuple of mjcf sites	Eight corner sites at box vertices

Usage Examples

from dm_control.manipulation.props import primitive

# Create a sphere prop
sphere = primitive.Sphere(radius=0.04, mass=0.1, name='ball')

# Create a box with corner sites for precise tracking
box = primitive.BoxWithSites(
    half_lengths=[0.04, 0.06, 0.02],
    mass=0.2,
    name='block',
)
corners = box.corner_sites  # 8 corner site elements

# Create a cylinder prop
cyl = primitive.Cylinder(radius=0.03, half_length=0.1, name='rod')

# Customize prop appearance
sphere.geom.rgba = [1, 0, 0, 1]   # red
sphere.geom.friction = [1.0, 0.005, 0.001]

# Attach prop to an arena
arena.add_free_entity(sphere)

# Access sensor observables
sphere.observables.position.enabled = True
sphere.observables.touch.enabled = True