DOCSEARCHbyAlgolia
Submit Docs

yourdfpy

repository·main·Indexed 43 days ago

https://github.com/clemense/yourdfpy

A Python library for loading, manipulating, validating, saving, and visualizing URDF (Unified Robot Description Format) files. It features decoupled parsing from validation and mesh loading, built-in visualization via a CLI or the show() method, and support for Forward Kinematics. Key capabilities include updating joint configurations with update_cfg(), retrieving frame transforms via get_transform(), and exporting models back to XML.

Tokens
4.4K
Snippets
16
Records
20
Agent score
55%

What's inside yourdfpy

  1. Key features of yourdfpy

    main

    Compared to other URDF parsers like urdfpy and urdf_parser_py, yourdfpy provides:

    • Decoupled Parsing: Ability to decouple URDF parsing from validation and mesh loading.
    • Robustness: Higher success rate when loading diverse URDF files from the wild.
    • Full Feature Set: Includes URDF visualization and Forward Kinematics.
    • Performance: Optimized loading times for both mesh-inclusive and mesh-exclusive parsing.

  2. Workflow for submitting code contributions

    main

    Follow this workflow to ensure your code changes are accepted:

    1. Discuss changes: Before starting non-trivial work, create an issue in the tracker to discuss your approach.
    2. Branching: Create a new branch for your feature. Never work directly on the master branch.
      git checkout -b my-feature
    3. Implementation:
      • Add docstrings to new functions, modules, and classes (especially public APIs).
      • Add yourself to AUTHORS.rst.
      • Add unit tests and documentation for new features.
    4. Validation:
      • Commit your changes: git add <FILES> && git commit.
      • Run pre-commit to check code style (flake8/black).
      • Run tests using tox to ensure no regressions:
        tox
        (Use tox -av to see available checks).
    5. Submission:
      • Push your branch: git push -u origin my-feature.
      • Open a Pull Request (PR) via the repository web interface.
    git checkout -b my-feature
git add <MODIFIED FILES>
git commit
tox
git push -u origin my-feature

  4. Compile and preview documentation locally

    main

    The yourdfpy documentation is built using Sphinx. To compile the documentation locally and preview it in your browser, use tox and Python's built-in HTTP server.

    1. Compile the docs:

      tox -e docs

    2. Preview in browser: Run the server pointing to the build directory:

      python3 -m http.server --directory 'docs/_build/html'

      Then navigate to http://localhost:8000.

    tox -e docs
python3 -m http.server --directory 'docs/_build/html'

  6. Set up a local development environment for yourdfpy

    main

    To contribute to yourdfpy, follow these steps to prepare your local machine:

    1. Create an isolated virtual environment to avoid dependency conflicts:

      • Using virtualenv:
        virtualenv <PATH TO VENV>
source <PATH TO VENV>/bin/activate
      • Using Miniconda:
        conda create -n pyscaffold python=3 six virtualenv pytest pytest-cov
conda activate pyscaffold

    2. Clone the repository:

      • Fork the repository on your service provider (e.g., GitHub).
      • Clone your fork:
        git clone git@github.com:YourLogin/yourdfpy.git
cd yourdfpy

    3. Install the package in editable mode:

        pip install -U pip setuptools -e .

    4. Install pre-commit hooks (to automate code style checks):

        pip install pre-commit
  pre-commit install
    git clone git@github.com:YourLogin/yourdfpy.git
cd yourdfpy
pip install -U pip setuptools -e .
pip install pre-commit
pre-commit install

  7. Troubleshoot tox and build issues

    main

    If you encounter problems building or testing the package, try these solutions:

    • Missing dependencies in tox: If tox fails due to missing dependencies (even after updating setup.cfg or docs/requirements.txt), recreate the environment using the -r flag:
      tox -r -e docs
    • Tag/Version issues: Ensure you have fetched all tags from the upstream repository. Run git describe --abbrev=0 --tags to verify the version. If running CI in a fork, ensure all tags are pushed.
    • Tox environment issues: If tox behaves unexpectedly, try creating a fresh virtual environment specifically for it:
      virtualenv .venv
source .venv/bin/activate
.venv/bin/pip install tox
.venv/bin/tox -e all
    • Debugging failing tests: To drop into an interactive debugger (pdb) when a test fails, pass the --pdb flag through tox:
      tox -- -k <NAME_OF_FAILING_TEST> --pdb
    tox -r -e docs
tox -- -k <NAME_OF_FAILING_TEST> --pdb

  8. Use keyboard shortcuts in the URDF visualizer

    main

    While inspecting a model in the visualizer, use the following keyboard shortcuts:

    • a: Toggle rendered XYZ/RGB axis markers (cycles through: off, world frame, every frame)
    • w: Toggle wireframe mode (useful for inspecting the interior of meshes)
    • c: Toggle back face culling (useful in wireframe mode to see the back sides of meshes)

  9. Generate a joint limit trajectory

    main

    The generate_joint_limit_trajectory function creates a time-based trajectory for all actuated joints in a URDF model. It interpolates between the lower and upper joint limits.

    For continuous joints, the trajectory interpolates between 0.0 and 2 * pi. For revolute/prismatic joints, it interpolates between the defined limit.lower and limit.upper (defaulting to $-\pi$ and $+\pi$ if limits are not specified).

    Arguments:

    • urdf_model (yourdfpy.URDF): The loaded URDF model.
    • loop_time (float): The duration in seconds to complete one full loop of the trajectory.

    Returns:

    • dict: A dictionary where keys are joint names and values are numpy.ndarray objects containing the configuration values over time.
    from yourdfpy import URDF

urdf_model = URDF.load("robot.urdf")
trajectory = generate_joint_limit_trajectory(urdf_model, loop_time=6.0)

  10. Load a URDF model with URDF.load()

    main

    Use URDF.load() to parse a URDF file from a filename or a file-like object. This method builds the internal robot representation and can optionally construct scene graphs for visualization and collision detection.

    Key arguments:

    • fname_or_file: Path to the URDF file or a file-like object.
    • build_scene_graph (bool): If True, builds a trimesh.Scene for visual elements. Defaults to True.
    • build_collision_scene_graph (bool): If True, builds a trimesh.Scene for collision elements. Defaults to False.
    • load_meshes (bool): If True, loads the actual mesh files. Defaults to True.
    • load_collision_meshes (bool): If True, loads collision meshes. Defaults to False.
    • mesh_dir (str): A root directory used for resolving mesh paths. Defaults to the directory of the URDF file.
    • force_mesh (bool): If True, concatenates all geometries in a link into a single mesh (may lose texture info but improves performance). Defaults to False.
    • force_collision_mesh (bool): Similar to force_mesh but for collision geometry. Defaults to True.
    from yourdfpy import URDF

# Basic loading
urdf = URDF.load("path/to/robot.urdf")

# Loading with collision geometry and specific mesh directory
urdf = URDF.load(
    "path/to/robot.urdf",
    build_collision_scene_graph=True,
    load_collision_meshes=True,
    mesh_dir="/absolute/path/to/meshes"
)

  11. Visualize the URDF model

    main

    The show() method opens a viewer to display the URDF model. By default, it shows the visual elements.

    • To show collision geometry instead of visual geometry, pass collision_geometry=True.
    • Requirement: To use collision_geometry=True, you must have loaded the URDF with build_collision_scene_graph=True and load_collision_meshes=True.
    # Show visual elements
urdf.show()

# Show collision elements (requires specific loading flags)
urdf.show(collision_geometry=True)

  12. Export URDF model to XML

    main

    You can export the current state of a URDF object back into XML format using several methods:

    • write_xml(): Returns an etree.ElementTree object containing the URDF data.
    • write_xml_string(**kwargs): Returns the URDF as a formatted XML string. Useful for logging or network transmission.
    • write_xml_file(fname): Writes the URDF directly to a file (e.g., robot.urdf). This method uses pretty_print=True.
    # Write to a file
urdf_instance.write_xml_file("exported_robot.urdf")

# Get as a string
xml_str = urdf_instance.write_xml_string(encoding='utf-8')

# Get as an ElementTree
xml_tree = urdf_instance.write_xml()