From 145a647d35ecff84960d2197c6c23128618ca73c Mon Sep 17 00:00:00 2001 From: loctv Date: Thu, 23 Jul 2026 11:17:08 +0700 Subject: [PATCH] docs(interface): document the CCW angle-convention contract on LaserScan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every driver must normalize its device's native scale into ROS REP-103 right-handed CCW (0 = front, + = left). Spells out the three stackable device quirks to absorb — shifted 0° reference, clockwise scale, upside-down mounting — and warns that a CW scale decoded as CCW mirrors the world invisibly on single-lidar devices: verify handedness against the real room, not just against motion. Co-Authored-By: Claude Opus 4.8 (1M context) --- include/lidar_interface.hpp | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/include/lidar_interface.hpp b/include/lidar_interface.hpp index 32a9d31..1624e92 100644 --- a/include/lidar_interface.hpp +++ b/include/lidar_interface.hpp @@ -79,6 +79,21 @@ inline const char* to_string(ErrorCode e) { // ROS sensor_msgs/LaserScan-shaped output (radians, meters, seconds). // ranges[i] is at angle_min + i*angle_increment, in sweep order. +// +// ANGLE CONVENTION CONTRACT (ROS REP-103, right-handed): 0 = device front, +// positive = LEFT, increasing counter-clockwise viewed from the top. Every +// driver must NORMALIZE its device's native scale into this frame — three +// independent, stackable device quirks to absorb: +// 1. shifted 0° reference -> ModelConfig::angle_offset_deg +// (OLEI LR-1F/1FMI/1BS5: 0° at the rear; SICK TiM: front at 90°); +// 2. CLOCKWISE angle scale -> mirror the raw angle (θ -> −θ) BEFORE +// the offset (all Slamtec RPLIDARs per the Interface Protocol spec; +// OLEI LR-1BS5, field-verified). Decoding a CW scale as CCW mirrors the +// whole world left/right — undetectable with a single lidar (the SLAM +// map is self-consistently mirrored and heading checks still pass), so +// verify handedness against the real room, not just against motion; +// 3. upside-down mounting -> the physical flip reverses the +// apparent rotation, one more angle negation (the driver's `inverted`). struct LaserScan { uint32_t timestamp_ms = 0; // device clock (ms); 0 if not on the wire float angle_min = 0.f; // rad