From 6ee825f48541b8d9502d3802878e833cca06da74 Mon Sep 17 00:00:00 2001
From: Jacob Dahl <37091262+dakejahl@users.noreply.github.com>
Date: Wed, 18 Mar 2026 14:53:16 -0800
Subject: [PATCH] docs(optical_flow): clarify that integrated flow values are
 angular, not translational (#26811)

The flow output table shows forward movement producing +Y flow and
rightward movement producing -X flow, which confuses users whose sensors
have X-forward/Y-right coordinate systems. Add an info note explaining
that integrated flow values are angular rotations (radians) about the
body axes using the right-hand convention, which is why the axes are
cross-coupled with translational motion.
---
 docs/en/sensor/optical_flow.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/en/sensor/optical_flow.md b/docs/en/sensor/optical_flow.md
index ddc8a48297..3a6da0f3cf 100644
--- a/docs/en/sensor/optical_flow.md
+++ b/docs/en/sensor/optical_flow.md
@@ -34,6 +34,12 @@ The output of the flow when moving in different directions must be as follows:
 | Right            | - X             |
 | Left             | + X             |
 
+::: info
+The integrated flow values are **angular measurements** (radians) representing rotation of the image about the sensor's body axes using the right-hand convention.
+They are _not_ translational displacements along those axes, which is why forward vehicle movement (along X) appears in the Y flow axis, and rightward movement (along Y) appears in the X flow axis.
+Specifically, forward movement causes the ground image to rotate about the Y axis (+ Y), while rightward movement causes a negative rotation about the X axis (- X).
+:::
+
 Sensor data from the optical flow device is fused with other velocity data sources.
 The approach used for fusing sensor data and any offsets from the center of the vehicle must be configured in the [estimator](#estimators).