Implementation:Google deepmind Dm control Reference Pose Utils

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

Overview

The Reference Pose Utils module provides utility functions for creating walkers, setting walker and prop poses from reference features, and extracting walker features for reward computation in reference pose tracking tasks.

Description

The add_walker function creates a walker instance and attaches it to an arena, with optional ghost mode for visualization. In ghost mode, the walker is rendered as a semi-transparent grey figure with all contacts disabled (contype=0, conaffinity=0) and all actuators and actuator-related sensors removed. This enables visual comparison between the reference motion and the agent's actual motion without physical interference. Ghost walkers can optionally be made fully invisible by setting visible=False.

The pose-setting functions form a pipeline for initializing walkers from reference data. get_qpos_qvel_from_features stacks position, quaternion, and joint values into full qpos/qvel arrays. set_walker_from_features and set_walker apply these to a walker's freejoint and joint elements, with support for position offsets, rotation shifts, and optional nulling of xy position and yaw. set_props_from_features positions props from reference data with an optional z-offset.

The get_features function extracts comprehensive walker state into a dictionary suitable for reward computation: root position and quaternion, joint positions, center of mass, end effector positions, appendage positions, body positions and quaternions, linear and angular velocities, joint velocities, and optionally prop positions and quaternions.

Usage

Use these utilities when implementing or extending reference pose tracking tasks. add_walker is used during task setup to create both the controlled walker and optional ghost reference walkers. set_walker and get_features are called every step to set reference poses and extract features for reward computation respectively.

Code Reference

Source Location

• Repository: Google_deepmind_Dm_control
• File: dm_control/locomotion/tasks/reference_pose/utils.py
• Lines: 1-170

Signature

def add_walker(walker_fn, arena, name='walker', ghost=False, visible=True,
               position=(0, 0, 0)):

def get_qpos_qvel_from_features(features):

def set_walker_from_features(physics, walker, features, offset=0):

def set_walker(physics, walker, qpos, qvel, offset=0,
               null_xyz_and_yaw=False,
               position_shift=None, rotation_shift=None):

def set_props_from_features(physics, props, features, z_offset=0):

def get_features(physics, walker, props=None):

Import

from dm_control.locomotion.tasks.reference_pose import utils
from dm_control.locomotion.tasks.reference_pose.utils import add_walker
from dm_control.locomotion.tasks.reference_pose.utils import get_features
from dm_control.locomotion.tasks.reference_pose.utils import set_walker

I/O Contract

Inputs (add_walker)

Name	Type	Required	Description
walker_fn	callable	Yes	Factory function that creates a walker given a name keyword argument
arena	Arena	Yes	The arena to attach the walker to
name	str	No	Name for the walker (default: 'walker')
ghost	bool	No	If True, create a non-physical ghost walker for visualization (default: False)
visible	bool	No	If False and ghost is True, make the ghost fully invisible (default: True)
position	tuple	No	Spawn position as (x, y, z) (default: (0, 0, 0))

Inputs (get_features)

Name	Type	Required	Description
physics	mjcf.Physics	Yes	The MuJoCo physics instance
walker	Walker	Yes	The walker entity to extract features from
props	list of Prop	No	Optional list of prop entities to include in features

Outputs

Name	Type	Description
add_walker return	Walker	The created walker instance, attached to the arena
get_features return	dict	Dictionary mapping feature names to numpy arrays (position, quaternion, joints, center_of_mass, end_effectors, appendages, body_positions, body_quaternions, velocity, angular_velocity, joints_velocity, and optionally prop_positions, prop_quaternions)
get_qpos_qvel_from_features return	tuple of np.ndarray	Tuple of (full_qpos, full_qvel) arrays

Usage Examples

from dm_control.locomotion.tasks.reference_pose import utils

# Create a walker and a ghost reference walker
walker = utils.add_walker(walker_fn, arena, name='walker')
ghost = utils.add_walker(walker_fn, arena, name='ghost',
                         ghost=True, visible=True)

# Set walker pose from reference features
utils.set_walker_from_features(physics, walker, reference_features)

# Set walker with explicit qpos/qvel
qpos, qvel = utils.get_qpos_qvel_from_features(features)
utils.set_walker(physics, walker, qpos, qvel, offset=np.array([0, 0, 0.01]))

# Extract features for reward computation
current_features = utils.get_features(physics, walker, props=props)

# Set prop poses from features
utils.set_props_from_features(physics, props, features, z_offset=0.01)