diff --git a/docs/content/howto/urdf.md b/docs/content/howto/urdf.md new file mode 100644 index 000000000000..e37d9337584a --- /dev/null +++ b/docs/content/howto/urdf.md @@ -0,0 +1,65 @@ +--- +title: Loading URDF models +order: 600 +--- + +Rerun features a built-in [data-loader](https://rerun.io/docs/reference/data-loaders/overview) for [URDF](https://en.wikipedia.org/wiki/URDF) files. + + + A robot model loaded from an URDF file visualized in Rerun. + + + + + +## Overview + +Using a `URDF` in Rerun only requires you to load the file with the logging API. +This will automatically invoke the data-loader, which will take care of: +* resolving paths to meshes +* loading meshes and shapes as Rerun entities +* loading the joint transforms and associated frame IDs of links + +Once that is done, the joints can be updated by sending `Transform3D`s, where you have to set the `parent_frame` and `child_frame` fields explicitly to each joint's specific frame IDs. + +> ⚠️ Note: previous versions required you to send transforms with _implicit_ frame IDs, i.e. having to send each joint transform on a specific entity path. +> This was dropped in favor of _explicitly-named_ frame IDs, which is more in line with ROS and allows you to send all transform updates on one entity (e.g. a `transforms` entity like in the example below). + +## Example + +Here is an example that demonstrates how to load and update a `URDF` with the Python SDK: + +```python +from pathlib import Path + +import rerun as rr + +rr.init("urdf_example", spawn=True) + +# `log_file_from_path` automatically uses the built-in URDF data-loader. +urdf_path = Path("/path/to/robot.urdf") +rr.log_file_from_path(urdf_path, static=True) + +# Later, in your logging code, you'll update the joints using transforms. +# A minimal example for updating a revolute joint that connects two links: +joint_axis = [0, 1, 0] # comes from URDF +joint_angle = 1.216 # radians +rotation = rr.RotationAxisAngle(axis=joint_axis, angle=joint_angle) +# Make sure that `parent_frame` and `child_frame` match the joint's frame IDs in the URDF file. +rr.log( + "transforms", + rr.Transform3D( + rotation=rotation, + parent_frame="link_1", + child_frame="link_2" + ) +) +``` + +For similar code in Rust, we have a full example [here](github.com/rerun-io/rerun/tree/main/examples/rust/animated_urdf). + +## References + +* [🐍 Python `log_file_from_path`](https://ref.rerun.io/docs/python/stable/common/logging_functions/#rerun.log_file_from_path) +* [🦀 Rust `log_file_from_path`](https://docs.rs/rerun/latest/rerun/struct.RecordingStream.html#method.log_file_from_path) +* [🌊 C++ `log_file_from_path`](https://ref.rerun.io/docs/cpp/stable/classrerun_1_1RecordingStream.html#a20798d7ea74cce5c8174e5cacd0a2c47)