tools_mjcf

Helpers for inspecting and editing MuJoCo MJCF specifications.

This module contains utility functions for traversing MJCF body trees, querying actuator-to-joint relationships, attaching gripper specifications to robot models, and performing attribute replacements on serialized MJCF.

robotblockset.mujoco.tools_mjcf.actuators_for_joint(joint: Any) → List[Any][source]

Find actuators associated with an MJCF joint.

Parameters:

joint (Any) – Joint element from an MJCF Python specification. The object is expected to provide root and name attributes, as MuJoCo MJCF spec joint objects do.

Returns:

Actuator elements that reference joint. MuJoCo actuator tags such as motor, position, velocity, and general are checked.

Return type:

list[Any]

robotblockset.mujoco.tools_mjcf.print_body_tree_simple(parent: mujoco.MjsBody, level: int = 0) → None[source]

Print a compact MJCF body tree.

Parameters:

  • parent (mujoco.MjsBody) – MJCF body at which tree traversal starts.

  • level (int, optional) – Current indentation level. This is used internally during recursion.

Returns:

The tree is written to standard output.

Return type:

None

Notes

This helper prints body names and joint type suffixes only. Use print_body_tree() when actuator names should also be included.

robotblockset.mujoco.tools_mjcf.print_body_tree(parent: mujoco.MjsBody, spec: mujoco.MjSpec, level: int = 0) → None[source]

Print an MJCF body tree with joint and actuator information.

Parameters:

  • parent (mujoco.MjsBody) – MJCF body at which tree traversal starts.

  • spec (mujoco.MjSpec) – MJCF specification that owns parent. Its actuators are searched to identify the actuator targeting each joint.

  • level (int, optional) – Current indentation level. This is used internally during recursion.

Returns:

The tree is written to standard output.

Return type:

None

robotblockset.mujoco.tools_mjcf.attach_gripper_to_robot(robot_spec: mujoco.MjSpec, gripper_spec: mujoco.MjSpec, robot_site_name: str = 'gripper_mount', prefix: str = 'gripper_') → Any | None[source]

Attach a gripper MJCF specification to a robot mount site.

Parameters:

  • robot_spec (mujoco.MjSpec) – Robot MJCF specification to modify.

  • gripper_spec (mujoco.MjSpec) – Gripper MJCF specification to attach.

  • robot_site_name (str, optional) – Name of the site in robot_spec used as the attachment point.

  • prefix (str, optional) – Prefix applied by MuJoCo to names imported from gripper_spec.

Returns:

Attachment frame returned by mujoco.MjSpec.attach(), or None if robot_site_name is not found.

Return type:

Any or None

Notes

robot_spec is modified in place by MuJoCo’s attach operation.

robotblockset.mujoco.tools_mjcf.replace_in_mjcf_file(spec: mujoco.MjSpec, old: str, new: str, substring: bool = False) → mujoco.MjSpec[source]

Replace XML attribute values in an MJCF specification.

Parameters:

  • spec (mujoco.MjSpec) – Source MJCF specification to serialize before replacement.

  • old (str) – Attribute value to search for.

  • new (str) – Replacement attribute value.

  • substring (bool, optional) – If True, replace matching substrings inside attribute values. If False, replace only exact attribute-value matches.

Returns:

New MJCF specification parsed from the updated XML text.

Return type:

mujoco.MjSpec

robotblockset.mujoco.tools_mjcf.add_polyline_to_scene(scene: mujoco_scene, name: str, points: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...], radius: float = 0.004, rgba: Tuple[float, float, float, float] = (0.0, 1.0, 0.0, 1.0), group: int = 0, contype: int = 0, conaffinity: int = 0) → mujoco_scene[source]

Add a polyline to a MuJoCo scene as capsule geoms.

The scene must have been loaded from XML so that scene.spec is available. The function copies the current specification, appends a named body containing one unnamed capsule geom per segment, recompiles the model, and replaces scene.model and scene.data.

Parameters:

  • scene (mujoco_scene) – Scene object whose spec, model, and data attributes will be updated.

  • name (str) – Name of the body that contains the generated capsule geoms.

  • points (ArrayLike) – Polyline vertices with shape (N, 3). At least two points are required.

  • radius (float, optional) – Capsule radius.

  • rgba (tuple[float, float, float, float], optional) – RGBA color applied to each capsule.

  • group (int, optional) – MuJoCo geom visualization group.

  • contype (int, optional) – MuJoCo collision type bitmask.

  • conaffinity (int, optional) – MuJoCo collision affinity bitmask.

Returns:

The same scene object with updated specification, model, and data.

Return type:

mujoco_scene

Raises:

ValueError – If scene.spec is unavailable, if name is empty, or if points is not an (N, 3) array with N >= 2.

Functions

actuators_for_joint(joint)

Find actuators associated with an MJCF joint.

add_polyline_to_scene(scene, name, points[, ...])

Add a polyline to a MuJoCo scene as capsule geoms.

attach_gripper_to_robot(robot_spec, gripper_spec)

Attach a gripper MJCF specification to a robot mount site.

print_body_tree(parent, spec[, level])

Print an MJCF body tree with joint and actuator information.

print_body_tree_simple(parent[, level])

Print a compact MJCF body tree.

replace_in_mjcf_file(spec, old, new[, substring])

Replace XML attribute values in an MJCF specification.