TinyURDF 1.0.0
A modern C++ library for parsing and visualizing urdf models
Loading...
Searching...
No Matches
TinyURDF

cmake-build build-docs GitHub commit activity GitHub last commit GitHub License

A modern, fast, cross-platform, C++17 library for parsing and visualizing urdf model files. TinyURDF is designed to represent custom multibody configurations that existing tools do not support, including parallel multibodies or graph-like robots.The library release has no external dependencies. It aims to provide a stable and simple API to load, visualize, and verify robot models, integrate them into larger programs, and offer a lightweight scripting engine. Part of this project was inspired by and refactored from the packages urdfdom and urdfdom_headers packages however, it does not depend on them now.

Prerequisites

  1. C++17 compatible compiler: GCC 7.1+, Clang 5.0+, MSVC 2017+
  2. CMake: version 3.14+
  3. VTK (Optional): required only for building the visualization engine.

Documentation

officiel documenttaion can be found at link. Alternatively, it can be generated automatically during the library build process using cmake, see the build section for more information.

Notes

  • The current version parses and renders only model joints, links, and visual elements other elements like transmissions and sensors will be supported in future releases.
  • Physical consistency verification of model parameters (such as inertia values) is not activated by default.
  • A scaling issue may occurs during rendering due to elements marker sizes.
  • COLLADA file format for links visual or collision meshes is not yet supported, only STL files have been tested.
  • Multi-model handling, model interactions, and world parsing/visualization are not yet supported.
  • File paths should be with absolute given path, relative paths may not yet supported.

Recent Releases

  • [libtinyurdf-1.0.0]() september 2024: first release.

Dependencies

The library parser currently depends heavily on:

These dependencies are fetched and compiled automatically with the global build process, so no separate installation is required.
However, building the rendering interface requires other third-party software, such as the Visualization Toolkit (VTK), which needs to be built separately. See the INSTALL file for more information.

Build

The library has been successfully built and tested on the following platforms with the corresponding dependencies:

Windows

  1. Compiler: MSVC 2017, CMake: 3.22.1
  2. VTK: 9.3.1, Eigen: 3.4.0

Linux

  1. Compiler: GCC 8, CMake: Latest
  2. VTK: 9.3.1, Eigen: 3.4.0

Other platforms or compilers have not yet been tested. Please open an issue on GitHub Issues for any suspected bugs, we recommend using Ninja with Microsoft Visual Studio for faster builds.

Install Ninja

  • On Windows (via Chocolatey):
    choco install ninja
  • On linux
    sudo apt-get install ninja-build

Building the Project

run the following commands to build the project:

mkdir build && cd build
cmake -G Ninja ..
ninja
ninja install

By default, this will use the MSVC compiler on Windows and the default CMake options. To use a different compiler with Ninja, run:

cmake -G Ninja -DCMAKE_CXX_COMPILER=g++ -DCMAKE_C_COMPILER=gcc ..
make
make install

For Unix-based Systems or MinGW on Windows

If you prefer not to use Ninja, you can build the project using Unix Makefiles:

mkdir build && cd build
cmake -G "Unix Makefiles" ..
make
make install

These commands will build and install the static/shared library under the lib/ directory and the include files in the include/ directory of the build folder.

‍[!NOTE]
This build method is typically slower than the Ninja-based build.

#### Build Configuration Options You can customize the build using the following CMake options:

cmake -G Ninja \
-DBUILD_TESTS=TRUE \ # Build tests
-DBUILD_PYTHON3=TRUE \ # Enable Python 3 bindings
-DUSE_VTK=TRUE \ # Use VTK as the default renderer
-DBUILD_EXAMPLES=TRUE \ # Build examples
-DBUILD_DOCS=TRUE # Build documentation with Doxygen
-DBUILD_SHARED_LIBS = TRUE # build shared librarry

‍[!NOTE]
For Python bindings build and installation, enable the -DBUILD_PYTHON3 flag, and run the following command from the root of the project:

pip install --user .

Note that Python bindings are not currently tested, many bugs exist. Use them at your own risk, or feel free to contribute

TinyURDF will soon be available for installation via vcpkg, Conan, and CMake FetchContent.

Examples

The available documentation does not provide extensive examples.

  • Demo example scripts are implemented in the examples folder.
  • Additional test scripts, which may be useful, can be found in the test folder.
  • samples of models files can be found in the urdf directory, these files are mainly get from urdf_files_dataset.

The examples assume that all installation instructions are followed, and the library is successfully installed.

Example 1: parsing a urdf file

#include "tinyurdf/tinyurdf.h"
int main() {
// create the parser
URDFParser parser;
// parse the file
parser.parse("path/to/tinyurdf/examples/urdf/example.urdf");
// get the model
std::shared_ptr<Model> model_ = parser.get();
// print the model info
model_->print(std::cout);
return 0;
}
URDFParser
main user high level interface for parsing URDF files
Definition urdf_parser.h:23
URDFParser::parse
void parse(const std::string &filename)
Definition urdf_parser.cc:8
URDFParser::get
std::shared_ptr< Model > get() override
Definition urdf_parser.cc:67

This will print all model data to the standard output without any formatting or adjustments

Example 2: get a urdf model data

#include "tinyurdf/tinyurdf.h"
int main() {
// construct the parser
URDFParser parser;
// call parsing routine
parser.parse("path/to/tinyurdf/examples/urdf/example.urdf");
std::shared_ptr<Model> model_ = parser.get();
std::string name = model_->getName();
// get model joints
std::vector<std::shared_ptr<Joint>> joints_ = model_->getJoints();
// get model links
std::vector<std::shared_ptr<Link>> links_ = model_->getLinks();
// check whether the model is empty
bool status = model_->empty();
return 0;
}

Example 4: rendering a urdf model

#include "tinyurdf/tinyurdf.h"
int main() {
// create the parser
URDFParser parser;
const char* file_path = "path/to/tinyurdf/examples/urdf/example.urdf";
// parse the file
parser.parse(file_path);
// create the renderer
URDFRenderer render;
// set the model for rendering
render.setModel(*(parser.get()));
// set background color
render.setBackground(0.9, 0.9, 0.9, 1.0);
// disable label text
render.setLabelText(false);
// show the rendered model
render.show();
return 0;
}
URDFRenderer
Definition urdf_renderer.h:10
URDFRenderer::setModel
void setModel(const Model &model)
Definition urdf_renderer.cc:14
URDFRenderer::setLabelText
void setLabelText(bool v)
Definition urdf_renderer.cc:9
URDFRenderer::show
void show()
Definition urdf_renderer.cc:24

The script and the result can be found here: example4, demo

Resources

Contribution

The project is actively in progress, and contributions are welcome. see the CONTRIBUTING file for more information. currently, there are no issue or pull request templates,feel free to open issues or submit pull requests with your ideas and fixes.

License

See the [LICENSE](LICENSE) file for more information.

Citing

If you use this repository in your project, please cite it as follows:

@misc{tinyurdf,
author = {wissem chiha},
title = {TinyURDF},
year = {2025}
}