urdfpy

Urdfpy is a Python library designed for working with Unified Robot Description Format (URDF) files. It provides a simple interface for the following tasks:

• Loading: Reading URDF files into Python objects.
• Manipulating: Modifying the structure or properties of a robot model.
• Saving: Exporting modified models back to URDF files.
• Visualizing: Viewing robot models through a built-in visualizer.

Documentation is built using make within the docs directory. You can generate HTML documentation or clean existing build files.

```bash
cd docs/
make html

# To remove build files if docs are stale
make clean

The generated HTML index is located at docs/build/html/index.html.

To develop on urdfpy, install the package in editable mode with development and documentation dependencies. It is also recommended to install git pre-commit hooks to ensure code style compliance via flake8 before commits.

git clone https://github.com/mmatl/urdfpy.git
cd urdfpy
pip install -e .[dev,docs]
pre-commit install

You can load a URDF model using URDF.load(). Note that you must ensure all links use relative or absolute paths rather than ROS resource URLs (e.g., package://).

You can export a URDF model to a file using robot.save(). Any meshes and images will be dumped using their original names. If the names are relative, they will be saved relative to the new URDF file location.

from urdfpy import URDF

# Loading
robot = URDF.load('tests/data/ur5/ur5.urdf')

# Saving
robot.save('/tmp/ur5/ur5.urdf')

The project uses pytest for testing. Tests are located in the tests directory. You can run the entire suite, specific files, or individual test functions.

# Run all tests
pytest -v tests

# Run tests in a specific file
pytest -v tests/unit/utils/test_transforms.py

# Run a single test function
pytest -v tests/unit/utils/test_images.py::test_rgbd_image

To check how much of the urdfpy codebase is covered by tests, run pytest with the --cov flag, then use the coverage tool to generate an HTML report.

```bash
# Generate coverage data
pytest --cov=urdfpy tests

# Generate HTML report
coverage html

The HTML report will be available at htmlcov/index.html.

You can run style checks on all files managed by version control using pre-commit. Alternatively, you can run flake8 directly on specific files or directories to check for issues like unused imports or undefined variables.

# Run on all files under version control
pre-commit run --all-files

# Run flake8 selectively on a directory or file
flake8 --ignore=E231,W504 /path/to/files

You can install urdfpy using pip. It is compatible with any Python version.

pip install urdfpy

The URDF object provides direct access to the robot's structure:

• robot.links: A collection of all links in the robot.
• robot.joints: A collection of all joints. Each joint object has name, parent, and child attributes.
• robot.actuated_joints: A collection of joints that can be articulated (non-fixed).
• robot.base_link: The link designated as the robot's base.

# Accessing links
for link in robot.links:
    print(link.name)

# Accessing joints
for joint in robot.joints:
    print(f'{joint.name} connects {joint.parent} to {joint.child}')

# Accessing actuated joints
for joint in robot.actuated_joints:
    print(joint.name)

# Accessing base link
print(robot.base_link.name)

Urdfpy provides built-in methods for quick visualization:

• robot.show(cfg=None): Visualizes the robot in a static configuration. cfg is a dictionary mapping joint names to specific values.
• robot.animate(cfg_trajectory=None): Animates the robot over a trajectory. cfg_trajectory is a dictionary where each key is a joint name and each value is a list of configuration values representing the trajectory over time.

# Static visualization
robot.show(cfg={
    'shoulder_lift_joint': -2.0,
    'elbow_joint': 2.0
})

# Trajectory animation
robot.animate(cfg_trajectory={
    'shoulder_pan_joint': [-np.pi / 4, np.pi / 4],
    'shoulder_lift_joint': [0.0, -np.pi / 2.0],
    'elbow_joint': [0.0, np.pi / 2.0]
})