Implementation:Haosulab ManiSkill Articulation

Knowledge Sources	Haosulab_ManiSkill
Domains	Robotics, Simulation, Articulated Bodies
Last Updated	2026-02-15 08:00 GMT

Overview

Concrete tool for managing batched articulated bodies (robots, mechanisms) across parallel simulation environments.

Description

The Articulation dataclass wraps physx.PhysxArticulation objects, providing a unified interface to manage articulated bodies (such as robot arms, grippers, and articulated objects) across both CPU and GPU simulation backends.

Key data attributes:

links -- List of Link objects forming the kinematic chain.
links_map -- Dictionary mapping link names to Link objects.
root -- The root Link of the kinematic tree.
joints / joints_map -- All joints and a name-to-joint mapping.
active_joints / active_joints_map -- Only the actuated/active joints.

Key capabilities:

Joint state access: get_qpos(), get_qvel(), set_qpos(), set_qvel() for reading/writing joint positions and velocities.
Drive targets: set_joint_drive_targets(), set_joint_drive_velocity_targets() for controlling joints.
Root pose: set_root_pose(), set_root_linear_velocity(), set_root_angular_velocity().
Contact forces: get_net_contact_forces() for querying contact forces on specific links.
Merge support: Articulation.merge() creates a merged view over multiple articulations (potentially with different DOFs), with padded joint data.
Collision mesh access: get_collision_meshes() retrieves trimesh objects.

The class factory method create() constructs the full articulation struct from raw physx articulation objects, automatically building Link and Joint wrappers.

Usage

Articulation objects represent robots and articulated objects in ManiSkill environments. They are created by the scene builder via URDFLoader or MJCFLoader and accessed through the environment's scene.

Code Reference

Source Location

Repository: Haosulab_ManiSkill
File: mani_skill/utils/structs/articulation.py

Signature

@dataclass
class Articulation(BaseStruct[physx.PhysxArticulation]):
    links: list[Link]
    links_map: dict[str, Link]
    root: Link
    joints: list[ArticulationJoint]
    joints_map: dict[str, ArticulationJoint]
    active_joints: list[ArticulationJoint]
    active_joints_map: dict[str, ArticulationJoint]
    name: str = None
    initial_pose: Pose = None
    merged: bool = False

    @classmethod
    def create(cls, physx_articulations, scene, scene_idxs, ...) -> "Articulation": ...
    def get_qpos(self) -> torch.Tensor: ...
    def set_qpos(self, qpos: Array) -> None: ...
    def get_qvel(self) -> torch.Tensor: ...
    def set_qvel(self, qvel: Array) -> None: ...
    def set_joint_drive_targets(self, targets, joints=None) -> None: ...

Import

from mani_skill.utils.structs.articulation import Articulation

I/O Contract

Inputs

Name	Type	Required	Description
physx_articulations	list[PhysxArticulation]	Yes	Raw SAPIEN articulation objects (one per env)
scene	ManiSkillScene	Yes	The scene managing sub-scenes
scene_idxs	torch.Tensor	Yes	Indices for sub-scene mapping
qpos	Array	Yes	Joint positions tensor of shape (N, num_active_joints)

Outputs

Name	Type	Description
qpos	torch.Tensor	Joint positions of shape (N, num_active_joints)
qvel	torch.Tensor	Joint velocities of shape (N, num_active_joints)

Usage Examples

Basic Usage

# Access robot articulation from environment
robot = env.agent.robot

# Get joint positions across all parallel envs
qpos = robot.get_qpos()  # shape (num_envs, num_active_joints)

# Set joint targets for control
targets = torch.zeros(num_envs, robot.max_dof)
robot.set_joint_drive_targets(targets)

# Access specific links
ee_link = robot.links_map["gripper_link"]
ee_pose = ee_link.pose

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment