Initial commit

2025-11-30 09:05:02 +08:00
commit 265175ed82
23 changed files with 3329 additions and 0 deletions
--- a/docs/tutorials/robotics/using-urdf.md
+++ b/docs/tutorials/robotics/using-urdf.md
@@ -0,0 +1,134 @@
+# Using URDF Files in Vuer
+
+## Overview
+
+Vuer enables loading URDF (Unified Robot Description Format) files for robotics visualization. The framework supports mesh files in `.dae`, `.stl`, `.obj`, and `.ply` formats.
+
+## Basic Implementation
+
+The code example demonstrates loading URDF models:
+
+```python
+from asyncio import sleep
+from vuer import Vuer, VuerSession
+from vuer.schemas import Urdf
+
+app = Vuer()
+
+@app.spawn(start=True)
+async def main(proxy: VuerSession):
+    proxy.upsert @ Urdf(
+        src="https://docs.vuer.ai/en/latest/_static/perseverance/rover/m2020.urdf",
+        jointValues={},
+        rotation=[3.14 / 2, 0, 0],
+        position=[0, 0, -1.5],
+        key="perseverance",
+    )
+
+    # Keep the session alive
+    while True:
+        await sleep(1.0)
+
+app.run()
+```
+
+## Key Parameters
+
+### src
+URL path to the URDF file. Can be a local path or remote URL.
+
+### jointValues
+Dictionary for joint configuration. Use empty `{}` for default joint positions.
+
+Example with joint values:
+```python
+jointValues={
+    "joint_1": 0.5,
+    "joint_2": -0.3,
+    "knee_joint": 1.2,
+}
+```
+
+### rotation
+Euler angles `[x, y, z]` for model orientation in radians.
+
+### position
+3D coordinates `[x, y, z]` for model placement.
+
+### key
+Unique identifier for the model. Used for updates and removal.
+
+## Supported Mesh Formats
+
+Vuer supports URDF files with mesh files in the following formats:
+- `.dae` (COLLADA)
+- `.stl` (STereoLithography)
+- `.obj` (Wavefront OBJ)
+- `.ply` (Polygon File Format)
+
+## Complete Example with Multiple Robots
+
+```python
+from asyncio import sleep
+from vuer import Vuer, VuerSession
+from vuer.schemas import Urdf, Scene, AmbientLight
+
+app = Vuer()
+
+@app.spawn(start=True)
+async def main(session: VuerSession):
+    session.set @ Scene(
+        # Add lighting
+        AmbientLight(intensity=1.0),
+
+        # Load first robot
+        Urdf(
+            src="/static/robots/robot1.urdf",
+            position=[0, 0, 0],
+            rotation=[0, 0, 0],
+            key="robot-1",
+        ),
+
+        # Load second robot
+        Urdf(
+            src="/static/robots/robot2.urdf",
+            position=[2, 0, 0],
+            rotation=[0, 0, 0],
+            key="robot-2",
+        ),
+    )
+
+    # Keep the session alive
+    while True:
+        await sleep(1.0)
+
+app.run()
+```
+
+## Serving Local URDF Files
+
+To serve URDF files from your local filesystem:
+
+```python
+from vuer import Vuer
+
+# Point to the directory containing your URDF files
+app = Vuer(static_root="path/to/urdf/directory")
+
+@app.spawn(start=True)
+async def main(session):
+    session.upsert @ Urdf(
+        src="/static/my_robot.urdf",  # Relative to static_root
+        position=[0, 0, 0],
+        key="my-robot",
+    )
+
+    while True:
+        await sleep(1.0)
+
+app.run()
+```
+
+## Source
+
+Documentation: https://docs.vuer.ai/en/latest/tutorials/robotics/urdf.html