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 ROS urdfdom and urdfdom_headers packages however,it does not depend on ROS.
- C++17 Compatible Compiler: GCC 7.1+, Clang 5.0+, MSVC 2017+
- CMake: Version 3.14+
- VTK (Optional): Required for building the visualization engine
Official documentation has not yet been released. The deployment pipeline has some errors; however, manual generation can be done with these commands:
Install Doxygen and Graphviz:
sudo apt install doxygen graphvizFrom the root of the project, run:
cd ./docs/
doxygen Doxyfile Alternatively, it can be generated automatically during the library build process using CMake. See the build section for more information.
- 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 joint marker sizes.
- COLLADA file format for meshes is supported as part of VTK's file format support; however, currently, only STL files have been tested.
- multi-model handling, model interactions, and world parsing/visualization are not yet supported.
- libtinyurdf-1.0.0 september 2024: first release.
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.
The library has been successfully built and tested on the following platforms with the corresponding dependencies:
- Compiler: MSVC 2017, CMake: 3.22.1
- VTK: 9.3.1, Eigen: 3.4.0
- Compiler: GCC 8, CMake: Latest
- 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.
- On Windows (via Chocolatey):
choco install ninja
- On linux
sudo apt-get install ninja-build
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 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.
You can customize the build using the following CMake options:
cmake -G Ninja \
-DBUILD_TESTS=TRUE \ # Build tests (default: OFF)
-DBUILD_PYTHON3=TRUE \ # Enable Python 3 bindings
-DUSE_VTK=TRUE \ # Use VTK as the default renderer (default: OFF)
-DBUILD_EXAMPLES=TRUE \ # Build examples (default: OFF)
-DBUILD_DOCS=TRUE # Build documentation with Doxygen (default: OFF)
-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.
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 URDF 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.
#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;
}This will print all model data to the standard output without any formatting or adjustments
#include "tinyurdf/tinyurdf.h"
int main() {
// construct the parser
URDFParser parser;
// call parsing routine
parser.parse("path/to/tinyurdf/examples/urdf/example.urdf");
/// get the model
std::shared_ptr<Model> model_ = parser.get();
/// get the model name
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;
}#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;
}
The script and the result can be found here: example4, demo
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.
See the LICENSE file for more information.
If you use this repository in your project, please cite it as follows:
@misc{tinyurdf,
author = {wissem chiha},
title = {TinyURDF},
year = {2025}
}