toddlerbot.descriptions package¶

Submodules¶

toddlerbot.descriptions.assemble_xml module¶

Robot XML assembly module for MuJoCo simulation.

Assembles complete robot XML descriptions by combining torso, arm, and leg components from OnShape CAD exports. Handles collision mesh processing, joint constraints, keyframe generation, and output formatting for various simulation environments.

toddlerbot.descriptions.assemble_xml.add_gripper_constraints(root: Element, offsets: Dict[str, float])¶

toddlerbot.descriptions.assemble_xml.add_keyframes(root: Element, home_pos: Dict[str, float], offsets: Dict[str, float], target_robot_dir: str)¶

toddlerbot.descriptions.assemble_xml.add_offsets(root: Element, robot_config: dict, target_robot_dir: str)¶

Adds offsets to the robot configuration based on the provided local configuration.

Parameters:

robot_config_local (Dict[str, Dict[str, float]]) – A dictionary containing the robot’s local configuration with offsets.
root (ET.Element) – The root XML element to which the offsets will be added.

This function iterates through the robot configuration and adds an ‘offset’ element for each key in the local configuration.

toddlerbot.descriptions.assemble_xml.add_self_contacts(root: Element, contact_config: Dict[str, List[str]])¶

Adds contact and exclusion pairs to an XML element based on a collision configuration.

Parameters:

root (ET.Element) – The root XML element to which contact pairs and exclusions will be added.
collision_config (Dict[str, Dict[str, Any]]) – A dictionary containing collision configuration for each body. Each entry specifies which other bodies it can contact with.

Raises:

ValueError – If a geometry name cannot be found for any of the specified body pairs.

toddlerbot.descriptions.assemble_xml.add_sites(root: Element, offsets: Dict[str, float], robot_config: Dict[str, str])¶

Adds foot sites to the XML structure based on the specified foot name in the configuration.

Parameters:

root (ET.Element) – The root element of the XML structure to which foot sites will be added.
foot_name (str) – The name of the foot to identify target geometries.

The function searches for geometries in the XML structure that match the specified foot name and contain “collision” in their name. For each matching geometry, it calculates the position for a new site and adds it as a child element to the geometry’s parent, with predefined specifications for type, size, and color.

toddlerbot.descriptions.assemble_xml.add_waist_constraints(root: Element, offsets: Dict[str, float])¶

Adds waist constraints to the given XML element by creating and configuring tendon elements for waist roll and yaw.

This function modifies the provided XML element by removing any existing ‘tendon’ element and adding a new one with specific constraints for waist roll and yaw. The constraints are defined using coefficients and backlash values from the general configuration.

Parameters:

root (ET.Element) – The root XML element to which the waist constraints will be added.
general_config (Dict[str, Any]) – A dictionary containing configuration values, including offsets and backlash for waist roll and yaw.

toddlerbot.descriptions.assemble_xml.align_body_frames_to_global(root)¶: Aligns all body frames in the MJCF tree to the global frame (quat = 1 0 0 0) and updates all child elements (joint axis, geom/site/inertial pos and quat) accordingly so the world behavior is preserved.

toddlerbot.descriptions.assemble_xml.assemble_xml(robot_name: str, torso_name: str, arm_name: str, leg_name: str)¶

Assembles a URDF file for a robot based on the provided configuration.

This function constructs a complete URDF (Unified Robot Description Format) file by combining a base body URDF with optional arm and leg components specified in the configuration. It updates mesh file paths and ensures the correct structure for simulation.

Raises:: ValueError – If a source URDF for a specified link cannot be found.

toddlerbot.descriptions.assemble_xml.compute_bounding_box(mesh: Trimesh)¶

Computes the size and center of the bounding box for a given 3D mesh.

Parameters:: mesh (trimesh.Trimesh) – The 3D mesh for which to compute the bounding box.
Returns:: A tuple containing the size (width, height, depth) of the bounding box and the center point of the bounding box.
Return type:: tuple

toddlerbot.descriptions.assemble_xml.configure_fixed(root: Element)¶: Configures robot for fixed-base simulation by removing free joint.

toddlerbot.descriptions.assemble_xml.configure_mjx(root: Element, robot_config: dict)¶: Configures robot for MJX (GPU-accelerated MuJoCo) simulation.

toddlerbot.descriptions.assemble_xml.configure_motors(root: Element)¶: Configures motor actuators by replacing position controllers with motor controllers.

toddlerbot.descriptions.assemble_xml.create_scene_xml(root: Element, target_robot_dir: str, variant: str = '', important_contacts: List[str] = ['ankle_roll_link', 'hand'])¶

Generates an XML scene file for a robot model based on the provided MJCF file path and configuration.

Parameters:

mjcf_path (str) – The file path to the MJCF XML file of the robot model.
is_fixed (bool) – A flag indicating whether the robot is fixed in place. If True, adjusts camera positions and scene settings accordingly.

Creates an XML scene file that includes the robot model, visual settings, and camera configurations. The scene is saved in the same directory as the input MJCF file with a modified filename.

toddlerbot.descriptions.assemble_xml.find_body_and_parent(root: Element, target_name: str)¶: Recursively find the body with name=target_name and its parent.

toddlerbot.descriptions.assemble_xml.list_to_string(lst: list, digits: int = 6) → str¶: Convert a list of strings to a comma-separated string.

toddlerbot.descriptions.assemble_xml.main()¶

Parses command-line arguments to configure and assemble a URDF (Unified Robot Description Format) file.

This function sets up an argument parser to accept parameters for robot configuration, including the robot’s name, body, arm, and leg components. It then calls the assemble_xml function with the parsed arguments to generate the URDF file.

toddlerbot.descriptions.assemble_xml.string_to_list(string: str) → list¶: Convert a comma-separated string to a list of strings.

toddlerbot.descriptions.assemble_xml.update_collision(old_geom: Element, collision_config: dict, mesh_dir: str, ignore_keywords: list = ['arm', 'leg', 'gear', 'neck', 'hip_roll', 'shoulder_pitch'])¶

Updates MuJoCo geom element to minimal-volume bounding primitive or convex mesh.

Parameters:

old_geom – Original geometry element to replace
collision_config – Configuration mapping mesh names to collision shapes
mesh_dir – Directory containing mesh files
ignore_keywords – Keywords to skip collision generation for

Returns:

List of new geometry elements for collision

toddlerbot.descriptions.assemble_xml.update_joint_params(root: Element, joint_params: Dict[str, float])¶

toddlerbot.descriptions.assemble_xml.write_fixed_xml(root: Element, target_robot_dir: str)¶

toddlerbot.descriptions.assemble_xml.write_mjx_fixed_xml(root: Element, target_robot_dir: str, robot_config: dict)¶

toddlerbot.descriptions.assemble_xml.write_mjx_xml(root: Element, target_robot_dir: str, robot_config: dict)¶: Writes MJX-optimized robot XML file.

toddlerbot.descriptions.assemble_xml.write_pos_fixed_xml(root: Element, target_robot_dir: str)¶

toddlerbot.descriptions.assemble_xml.write_pos_xml(root: Element, target_robot_dir: str)¶

toddlerbot.descriptions.assemble_xml.write_xml(root: Element, target_robot_dir: str)¶: Writes main robot XML file with motor configuration.

toddlerbot.descriptions.convert_to_urdf module¶

MuJoCo MJCF to URDF conversion utility.

Converts MuJoCo XML robot descriptions to URDF format for use with ROS and other robotics frameworks. Handles geometry, joint, and inertial transformations between the two formats.

toddlerbot.descriptions.convert_to_urdf.convert(robot_name: str, asset_file_prefix: str, fix_extra_joints: list = [])¶

Converts MuJoCo MJCF robot description to URDF format.

Parameters:

robot_name – Name of the robot to convert
asset_file_prefix – Prefix path for asset files
fix_extra_joints – List of joint keywords to fix (make non-actuated)

toddlerbot.descriptions.convert_to_urdf.create_body(xml_root, name, inertial_pos, inertial_rpy, mass, ixx, iyy, izz)¶

Creates URDF link element with specified inertial properties.

Parameters:

xml_root – Parent XML element to attach link to
name – Link name
inertial_pos – Position of center of mass
inertial_rpy – Orientation of inertial frame
mass – Link mass
ixx – Principal moments of inertia
iyy – Principal moments of inertia
izz – Principal moments of inertia

Returns:

Created link element

toddlerbot.descriptions.convert_to_urdf.create_dummy_body(xml_root, name)¶: Creates dummy URDF link with negligible mass for kinematic connections.

toddlerbot.descriptions.convert_to_urdf.create_joint(xml_root, name, type, parent, child, pos, rpy, axis=None, jnt_range=None)¶

Creates URDF joint element connecting parent and child links.

Parameters:

xml_root – Parent XML element
name – Joint name
type – Joint type (fixed, revolute, prismatic, floating)
parent – Parent link name
child – Child link name
pos – Joint position
rpy – Joint orientation
axis – Joint axis for revolute/prismatic joints
jnt_range – Joint limits [min, max]

Returns:

Created joint element

toddlerbot.descriptions.convert_to_urdf.get_geom_pose(root, geom_name)¶

toddlerbot.descriptions.convert_to_urdf.get_mesh_paths(root: Element) → tuple¶

Extract mesh and texture information from MJCF/XML file.

Returns:

A tuple containing:

mesh_files (dict): Mapping of mesh names to their file paths
mesh_textures (dict): Mapping of mesh names to list of texture names they use
texture_files (dict): Mapping of texture names to their file paths

Return type:

tuple

toddlerbot.descriptions.convert_to_urdf.list_to_string(lst: list, digits: int = 6) → str¶: Convert a list of strings to a comma-separated string.

toddlerbot.descriptions.convert_to_urdf.string_to_list(string: str) → list¶: Convert a comma-separated string to a list of strings.

toddlerbot.descriptions.get_xml module¶

OnShape robot assembly XML generation utility.

Downloads and processes robot assemblies from OnShape CAD platform, converting them to MuJoCo XML format for simulation. Handles configuration generation, mesh processing, and file cleanup.

toddlerbot.descriptions.get_xml.main()¶: Main entry point for OnShape assembly processing.

toddlerbot.descriptions.get_xml.process_xml_and_stl_files(assembly_path: str)¶

Processes XML and STL files within a specified assembly directory.

Parameters:: assembly_path (str) – The path to the directory containing the XML and STL files.
Raises:: ValueError – If no XML file is found in the specified directory.

toddlerbot.descriptions.get_xml.run_onshape_to_robot(doc_id_list: List[str], assembly_list: List[str], max_stl_size: int = 1)¶

Downloads and converts OnShape assemblies to robot XML format.

Parameters:

doc_id_list – List of OnShape document IDs
assembly_list – List of assembly names to process
max_stl_size – Maximum STL file size in MB

toddlerbot.descriptions.onshape_to_robot module¶

Complete OnShape-to-robot conversion pipeline.

Orchestrates the full robot description generation workflow from OnShape CAD to final XML and URDF files. Provides interactive prompts for each conversion step and supports multiple robot configurations.

toddlerbot.descriptions.onshape_to_robot.main()¶: Main entry point for OnShape-to-robot conversion pipeline.

toddlerbot.descriptions.onshape_to_robot.prompt_yes_no(prompt)¶: Prompts user for yes/no input and returns boolean result.

Module contents¶

Robot model descriptions and URDF/XML generation tools.

This package provides functionality for robot model management and conversion, including tools for:

Converting Onshape CAD models to robot descriptions
URDF to MuJoCo XML conversion utilities
Robot model assembly and configuration management
XML processing and modification tools
Model parameter extraction and validation

The descriptions framework supports the entire workflow from CAD design through simulation model generation, enabling rapid prototyping and iteration of robot designs with automatic model generation pipelines.