Implementation:Google deepmind Dm control Primitive Prop

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

Overview

A simple Composer entity consisting of a single MuJoCo geom (sphere, box, capsule, cylinder, or ellipsoid) with built-in position, orientation, and velocity sensors and observables.

Description

The Primitive class extends composer.Entity and creates a minimal MJCF model containing one geom of a specified type and size, along with four MuJoCo sensors: framepos (position), framequat (orientation as quaternion), framelinvel (linear velocity), and frameangvel (angular velocity). Additional geom parameters such as rgba, mass, friction, and others can be passed through via **kwargs and are applied directly to the geom element.

PrimitiveObservables wraps these four sensors as Composer observables using MJCFFeature and includes FreePropObservableMixin, which provides standard free-body observation capabilities. This makes Primitive immediately usable as a prop in any Composer task with full sensor and observation support.

The Primitive entity is the most basic and versatile prop in dm_control. It serves as the building block for simple manipulation objects and is frequently used in tests and prototyping as a lightweight alternative to more complex props like Duplo.

Usage

Use Primitive to create simple objects for manipulation tasks, test environments, or anywhere a basic physical object with sensor feedback is needed. Specify the geom type (sphere, box, capsule, cylinder, or ellipsoid) and appropriate size parameters. Attach it to arenas or other entities as needed.

Code Reference

Source Location

Repository: Google_deepmind_Dm_control
File: dm_control/entities/props/primitive.py
Lines: 1-110

Signature

class Primitive(composer.Entity):
    def _build(self, geom_type, size, name=None, **kwargs):
        ...
    @property
    def geom(self):
        ...
    @property
    def position(self):
        ...
    @property
    def orientation(self):
        ...
    @property
    def linear_velocity(self):
        ...
    @property
    def angular_velocity(self):
        ...
    @property
    def mjcf_model(self):
        ...

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

Import

from dm_control.entities.props.primitive import Primitive

I/O Contract

Inputs (_build)

Name	Type	Required	Description
geom_type	str	Yes	MuJoCo geom type: `'sphere'`, `'box'`, `'capsule'`, `'cylinder'`, or `'ellipsoid'`
size	list or array	Yes	Size parameters (shape depends on geom_type, see below)
name	str or None	No	Name for the MJCF root element
**kwargs	various	No	Additional geom parameters (e.g., `rgba`, `mass`, `friction`)

Size Parameters by Geom Type

geom_type	size format	Description
`'box'`	`[x_half, y_half, z_half]`	Half-lengths along each axis
`'capsule'`	`[radius, half_length]`	Radius and half-length of the cylindrical part
`'cylinder'`	`[radius, half_length]`	Radius and half-length
`'ellipsoid'`	`[x_radius, y_radius, z_radius]`	Radii along each axis
`'sphere'`	`[radius]`	Sphere radius

Outputs

Name	Type	Description
geom	`mjcf.Element`	The geom element of this prop
position sensor	`mjcf.Element`	`framepos` sensor returning 3D position
orientation sensor	`mjcf.Element`	`framequat` sensor returning quaternion orientation
linear_velocity sensor	`mjcf.Element`	`framelinvel` sensor returning 3D linear velocity
angular_velocity sensor	`mjcf.Element`	`frameangvel` sensor returning 3D angular velocity
position observable	`numpy.ndarray` (3,)	Position from sensor data
orientation observable	`numpy.ndarray` (4,)	Orientation quaternion from sensor data
linear_velocity observable	`numpy.ndarray` (3,)	Linear velocity from sensor data
angular_velocity observable	`numpy.ndarray` (3,)	Angular velocity from sensor data

Usage Examples

from dm_control.entities.props.primitive import Primitive

# Create a red sphere
ball = Primitive(geom_type='sphere', size=[0.02], rgba=(1, 0, 0, 1))

# Create a blue box
box = Primitive(geom_type='box', size=[0.05, 0.05, 0.05],
                name='target_box', rgba=(0, 0, 1, 1))

# Create a capsule with custom mass
capsule = Primitive(geom_type='capsule', size=[0.01, 0.05],
                    mass=0.1, friction=[1.0, 0.005, 0.001])

# Access the geom element for further MJCF modifications
print(ball.geom)  # mjcf.Element for the sphere geom

# Access sensors (mjcf.Element references)
pos_sensor = ball.position
quat_sensor = ball.orientation

# In a Composer task, observables are available automatically
# ball.observables.position, ball.observables.orientation, etc.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment