cmeel-urdfdom: URDF Parser

4.0.1 · active · verified Wed Apr 15

cmeel-urdfdom provides Python bindings for the `urdfdom` C++ library, which is used for parsing Unified Robot Description Format (URDF) XML files. It allows Python applications to load, manipulate, and query robot models defined in URDF. The current version is 4.0.1, with releases typically tracking the underlying `urdfdom` C++ library and often including `cmeel`-specific build suffixes.

Warnings

breaking Underlying C++ library version mismatches can cause API breaks. `cmeel-urdfdom` wraps the C++ `urdfdom` library, and major version updates in either `cmeel-urdfdom` or its dependency `urdfdom-headers` can introduce breaking changes due to alterations in the underlying C++ API or its Python bindings.
Fix: Always check the release notes for `cmeel-urdfdom` and `urdfdom-headers` when upgrading, especially across major versions. Ensure your `urdfdom-headers` dependency matches the `cmeel-urdfdom` requirements as specified in its `pyproject.toml` or `setup.cfg`.
gotcha This is not a pure Python library; it relies on compiled C++ components. While `cmeel` aims to provide pre-built wheels for common platforms, environments without pre-built wheels may require a C++ compiler toolchain (e.g., CMake, C++ compiler) for installation, which can be complex.
Fix: Install in an environment with pre-built wheels (most common Linux, macOS, Windows systems). If installation fails, ensure you have necessary C++ build tools or refer to the `cmeel` documentation for custom build instructions.
gotcha XML parsing errors can be challenging to debug. When parsing malformed or syntactically incorrect URDF XML, the error messages originating from the underlying C++ `urdfdom` parser can sometimes be cryptic or not pinpoint the exact line or issue in the XML string or file.
Fix: Validate URDF files with external tools (e.g., `check_urdf` from `ros_urdf_check` for ROS users, or a generic XML linter) before attempting to load them programmatically. Gradually build complex URDFs from simpler, verified components.

Install

pip install cmeel-urdfdom Install stable version

Imports

URDF
```
from urdfdom.urdf import URDF
```

Quickstart

This quickstart demonstrates how to load a URDF robot model from an XML string using `URDF.load_from_xml_string`. It then shows how to access basic properties like the robot's name, the number of links and joints, and specific details of a link and a joint.

from urdfdom.urdf import URDF

# A simple URDF string for a single link robot
simple_urdf_string = """<?xml version=\"1.0\"?>
<robot name=\"simple_robot\">
  <link name=\"base_link\">
    <visual>
      <geometry>
        <box size=\"1 1 1\"/>
      </geometry>
    </visual>
  </link>
  <joint name=\"fixed_joint\" type=\"fixed\">
    <parent link=\"base_link\"/>
    <child link=\"child_link\"/>
    <origin xyz=\"0 0 1\" rpy=\"0 0 0\"/>
  </joint>
  <link name=\"child_link\">
    <visual>
      <geometry>
        <cylinder radius=\"0.1\" length=\"0.5\"/>
      </geometry>
    </visual>
  </link>
</robot>
"""

try:
    robot = URDF.load_from_xml_string(simple_urdf_string)
    print(f"Successfully loaded robot: {robot.name}")
    print(f"Number of links: {len(robot.links)}")
    print(f"Number of joints: {len(robot.joints)}")

    # Access a link
    if 'base_link' in robot.links:
        print(f"Base link geometry: {robot.links['base_link'].visuals[0].geometry.box.size}")

    # Access a joint
    if 'fixed_joint' in robot.joints:
        joint = robot.joints['fixed_joint']
        print(f"Fixed joint type: {joint.joint_type}")
        print(f"Fixed joint origin: {joint.origin.xyz}")

except Exception as e:
    print(f"Error loading URDF: {e}")

view raw JSON →