Document built-in URDF loader

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.
+
+<picture style="zoom: 0.5">
+  <img src="https://static.rerun.io/urdf-viewer/ebdefa158ab6f26f9dc1cb1924fce4b846fe8db2/full.png" alt="A robot model loaded from an URDF file visualized in Rerun.">
+  <source media="(max-width: 480px)" srcset="https://static.rerun.io/urdf-viewer/ebdefa158ab6f26f9dc1cb1924fce4b846fe8db2/480w.png">
+  <source media="(max-width: 768px)" srcset="https://static.rerun.io/urdf-viewer/ebdefa158ab6f26f9dc1cb1924fce4b846fe8db2/768w.png">
+  <source media="(max-width: 1024px)" srcset="https://static.rerun.io/urdf-viewer/ebdefa158ab6f26f9dc1cb1924fce4b846fe8db2/1024w.png">
+</picture>
+
+## Overview
+
+Using an `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 an `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)