Animate joint on GLB file via EQL. (#461)

* ai: Start of animate kdl.

* hack: Change the joint animation.

* feat: Attach animation to model.

* chore: Don't use fmt::from_fn() for Rust 1.93.

* chore: Fix Clippy error.

* chore: Why can't you be happy, Clippy!?

* feat: Add animated-rocket example.

* excise: Remove animation config from rocket example.

* perf: Use iterator rather than alloc a vec.

* refactor: Use `rotation_vector` in kdl.

Be more specific. Makes it easier to include translation if we want that
later.

* style: Reformat.

* doc: Update schematic documentation.

* feat: Add animation to crazyflie example.

* doc: Add FAQ to address a Nix issue.

* refactor: rotation_vector now is angle-axis degrees.

Was in radians but rotate vectors in other places are in degrees, so
trying to be uniform in units.

* binary: Move crazyflie model over -0.01.

Makes the rotations easier.

* test: Test round trip for joint animation.

* bug: Fix round-trip problem in animate KDL.

* style: Reformat.

* hack: Adjust crazyflie run_time_step footgun values.

* style: Space, the final prohibition.

* chore: Fix lint error. Clean up comments.

* debug: Print more info on scene ready.

* bug: Fix joint attachment post rebase.

* feat: Add 'up' to viewport KDL and 'direction()' to EQL.

* doc: Add documentation for up.

And missing direction.rs.

* chore: Allow too many arguments.

* test: Fix test failing due to rounding in KDL.

Author: shanecelis

Cargo.lock

@@ -0,0 +1,31 @@
+# Frequently Asked Questions (FAQ)
+
+## When running `nix develop`, it warns that it's "ignoring untrustd substituter". How do I fix that?
+
+If you run `nix develop` and it looks like this:
+```sh
+$ nix develop
+warning: Git tree '/Users/shane/Projects/elodin' has uncommitted changes
+warning: ignoring untrusted substituter 'https://elodin-nix-cache.s3.us-west-2.amazonaws.com', you are not a trusted user.
+...
+```
+Edit the following files to look like this:
+
+```sh
+$ cat /etc/nix/nix.custom.conf
+trusted-users = root YOUR-USER-NAME-HERE
+extra-trusted-substituters = https://elodin-nix-cache.s3.us-west-2.amazonaws.com
+extra-trusted-public-keys = elodin-cache-1:vvbmIQvTOjcBjIs8Ri7xlT2I3XAmeJyF5mNlWB+fIwM=
+```
+
+Once those edits are made, restart the nix daemon.
+
+### macOS
+```sh
+sudo launchctl kickstart -k system/systems.determinate.nix-daemon
+```
+### Linux
+```sh
+sudo systemctl restart nix-daemon
+```
+

FAQ.md

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:387f44e57d48f6e1f55bdfb2231d2a542f083a21d325798537ed2e40e476bf5b
-size 75116
+oid sha256:bd20a12a74fab9a44780c6224f01f3cc26a6954ad355600272e2bde00f814a26
+size 77816

assets/crazyflie.glb

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:14a450805f457c00b2597d6ed87e6fd6a697142e5c83a3513a809682903df25c
+size 33288

assets/flappy-rocket.glb

@@ -36,7 +36,7 @@ order = 6
 - `hsplit` / `vsplit`: children are panels. Child `share=<f32>` controls the weight within the split. `active` (bool) is parsed but not currently used. Optional `name`.
 
 ### panel content
-- `viewport`: `fov` (default 45.0), `active` (bool, default false), `show_grid` (default false), `show_arrows` (default true), `show_view_cube` (default true), `hdr` (default false), `name` (optional label), camera `pos`/`look_at` (optional EQL). Vector arrows can also be declared directly inside the viewport node; those arrows are treated as part of that viewport’s layer and respect its `show_arrows`/`show_grid` settings, allowing you to build a local triad tied to the viewport camera.
+- `viewport`: `fov` (default 45.0), `active` (bool, default false), `show_grid` (default false), `show_arrows` (default true), `show_view_cube` (default true), `hdr` (default false), `name` (optional label), camera `pos`/`look_at` (optional EQL). Vector arrows can also be declared directly inside the viewport node; those arrows are treated as part of that viewport’s layer and respect its `show_arrows`/`show_grid` settings, allowing you to build a local triad tied to the viewport camera. An `up` (default "(0, 1, 0)") specifies a direction vector in the world frame for the camera.
 - `graph`: positional `eql` (required), `name` (optional), `type` (`line`/`point`/`bar`, default `line`), `lock` (default false), `auto_y_range` (default true), `y_min`/`y_max` (default `0.0..1.0`), child `color` nodes (optional list; otherwise palette).
 - `component_monitor`: `component_name` (required), `name` (optional).
 - `action_pane`: `name` (required pane title), `lua` script (required).
@@ -52,6 +52,12 @@ order = 6
 - Positional `eql`: required. Evaluated to a `world_pos`-like value to place the mesh.
 - Mesh child (required, exactly one):
   - `glb`: `path` (required), `scale` (default 1.0), `translate` `(x,y,z)` (default 0s), `rotate` `(deg_x,deg_y,deg_z)` in degrees (default 0s).
+    - `animate` child nodes (optional, multiple): For rigged GLB models, animate specific joints/bones.
+      - `joint`: required string; the exact name of the joint/bone in the GLB file.
+      - `rotation_vector`: required EQL expression; must evaluate to a 3-element vector `(x, y, z)` where:
+        - The vector direction is the rotation axis.
+        - The vector magnitude is the rotation angle in degrees.
+      - Example: `animate joint="Root.Fin_0" rotation_vector="(0, rocket.fin_deflect, 0)"`
   - `sphere`: `radius` (required); `color` (default white).
   - `box`: `x`, `y`, `z` (all required); `color` (default white).
   - `cylinder`: `radius`, `height` (both required); `color` (default white).
@@ -181,7 +187,7 @@ dashboard      = "dashboard" { dashboard_node }+
 
 object_3d = "object_3d"
           <eql>
-          { glb
+          { glb { animate }*
           | sphere
           | box
           | cylinder
@@ -190,6 +196,10 @@ object_3d = "object_3d"
           }
           [emissivity=float]
 
+animate = "animate"
+        joint=string
+        rotation_vector=eql
+
 line_3d = "line_3d"
         <eql>
         [line_width=float]
@@ -248,3 +258,18 @@ vector_arrow
   color 64 128 255
 }
 ```
+
+Rigged GLB model with animated joints:
+
+The `rotation_vector` is an angle-axis: the direction encodes the axis, and the
+magnitude encodes the angle in degrees.
+
+```kdl
+object_3d rocket.world_pos {
+    glb path="rocket.glb"
+    animate joint="Root.Fin_0" rotation_vector="(0, rocket.fin_deflect[0], 0)"
+    animate joint="Root.Fin_1" rotation_vector="(0, rocket.fin_deflect[1], 0)"
+    animate joint="Root.Fin_2" rotation_vector="(0, rocket.fin_deflect[2], 0)"
+    animate joint="Root.Fin_3" rotation_vector="(0, rocket.fin_deflect[3], 0)"
+}
+```

docs/public/content/reference/schematic.md

@@ -139,6 +139,9 @@ class CrazyflieConfig:
     frame: Frame = Frame.CRAZYFLIE_X
 
     # Simulation time step in seconds (500 Hz control loop)
+    #
+    # NOTE: If the simulation is too slow to be practical, try raising this
+    # value.
     sim_time_step: float = 0.002
 
     # Fast loop time step for physics (1000 Hz)

examples/crazyflie-edu/config.py

@@ -36,7 +36,7 @@
 import numpy as np
 
 from config import CrazyflieConfig, create_default_config
-from sim import CrazyflieDrone, create_physics_system, thrust_visualization
+from sim import CrazyflieDrone, create_physics_system, thrust_visualization, propeller_animation
 from sensors import IMU, create_imu_system
 
 # Try to import keyboard controller (optional dependency)
@@ -521,7 +521,11 @@ def create_world() -> tuple[el.World, el.EntityId]:
             }
         }
         object_3d crazyflie.world_pos {
-            glb path="crazyflie.glb" rotate="(0.0, 0.0, 0.0)" translate="(-0.01, 0.0, 0.0)" scale=0.7
+            glb path="crazyflie.glb" rotate="(0.0, 0.0, 0.0)" translate="(0.0, 0.0, 0.0)" scale=0.7
+            animate joint="Root.Propeller_0" rotation_vector="(0, crazyflie.propeller_angle[0], 0)"
+            animate joint="Root.Propeller_1" rotation_vector="(0, crazyflie.propeller_angle[1], 0)"
+            animate joint="Root.Propeller_2" rotation_vector="(0, crazyflie.propeller_angle[2], 0)"
+            animate joint="Root.Propeller_3" rotation_vector="(0, crazyflie.propeller_angle[3], 0)"
         }
 
         // Motor position indicators
@@ -588,7 +592,7 @@ def system(include_physics: bool = True) -> el.System:
                         If False (HITL mode), skip physics (real world is source of truth).
     """
     clock = update_sim_time
-    visualization = thrust_visualization
+    visualization = thrust_visualization | propeller_animation
 
     if include_physics:
         physics = create_physics_system()
@@ -924,7 +928,8 @@ def get_state(self):
     world.run(
         sys,
         sim_time_step=config.dt,
-        run_time_step=1.0 / 60.0,  # 60 FPS for visualization
+        # Run it in real-time: wait if necessary after each time step.
+        run_time_step=config.dt,
         max_ticks=config.total_sim_ticks,
         post_step=sitl_post_step,
     )

examples/crazyflie-edu/main.py

@@ -97,6 +97,16 @@
     el.Component("thrust_viz_m4", el.ComponentType(el.PrimitiveType.F64, (3,))),
 ]
 
+# Propeller rotation angles (accumulated, in radians)
+PropellerAngle = ty.Annotated[
+    jax.Array,
+    el.Component(
+        "propeller_angle",
+        el.ComponentType(el.PrimitiveType.F64, (4,)),
+        metadata={"element_names": "p0,p1,p2,p3"},
+    ),
+]
+
 # =============================================================================
 # Archetypes
 # =============================================================================
@@ -117,6 +127,8 @@ class CrazyflieDrone(el.Archetype):
     thrust_viz_m2: ThrustVizM2 = field(default_factory=lambda: jnp.array([0.0, 0.0, -0.001]))
     thrust_viz_m3: ThrustVizM3 = field(default_factory=lambda: jnp.array([0.0, 0.0, -0.001]))
     thrust_viz_m4: ThrustVizM4 = field(default_factory=lambda: jnp.array([0.0, 0.0, -0.001]))
+    # Propeller rotation angles (accumulated, in radians)
+    propeller_angle: PropellerAngle = field(default_factory=lambda: jnp.zeros(4))
 
 
 # =============================================================================
@@ -309,6 +321,41 @@ def normalize(t: jax.Array) -> jax.Array:
     )
 
 
+@el.map
+def propeller_animation(
+    rpm: MotorRpm,
+    prev_angle: PropellerAngle,
+) -> PropellerAngle:
+    """
+    Update propeller rotation angles based on motor RPM.
+
+    Accumulates rotation angle over time for visual animation.
+    Motors M1 and M3 spin CW (negative rotation), M2 and M4 spin CCW (positive).
+    Output is in degrees for use with rotation_vector animate directive.
+    """
+    config = Config.get_global()
+    dt = config.fast_loop_time_step
+
+    # Convert RPM to degrees per second: omega = rpm * 360 / 60 = rpm * 6
+    omega = rpm * 6.0
+
+    # Motor rotation directions (Crazyflie Quad-X):
+    # M1 (FR): CW  -> negative rotation
+    # M2 (FL): CCW -> positive rotation
+    # M3 (BL): CW  -> negative rotation
+    # M4 (BR): CCW -> positive rotation
+    direction = jnp.array([-1.0, 1.0, -1.0, 1.0])
+
+    # Integrate angle: angle += omega * dt * direction
+    new_angle = prev_angle + omega * dt * direction
+
+    # Keep angles bounded to prevent floating point issues over long runs
+    # Wrap to [-180, 180] degrees range (animation doesn't care about full rotations)
+    new_angle = jnp.mod(new_angle + 180.0, 360.0) - 180.0
+
+    return new_angle
+
+
 # =============================================================================
 # System Composition
 # =============================================================================

examples/crazyflie-edu/sim.py

@@ -152,8 +152,8 @@ def world() -> tuple[el.World, el.EntityId]:
             }
         }
         
-        window path="examples/drone/motor-panel.kdl"
-        window path="examples/drone/rate-control-panel.kdl"
+        //window path="examples/drone/motor-panel.kdl"
+        //window path="examples/drone/rate-control-panel.kdl"
 
         vector_arrow "(1, 0, 0)" origin="drone.world_pos" scale=1.0 name="Drone Velocity X" body_frame=#true
         vector_arrow "(0, 1, 0)" origin="drone.world_pos" scale=1.0 name="Drone Velocity Y" body_frame=#true