Imported from Emailmail/r200_ubuntu24.04 (
AGENTS.md). Install upstream withnpx skills add Emailmail/r200_ubuntu24.04. Copyright stays with the author.
R200-only librealsense 操作手册
工程边界
本仓库是从 Intel librealsense v1.12.1 裁剪并现代化的 R200 专用 SDK。唯一支持的设备是 Intel RealSense R200，USB VID:PID 为 8086:0a80；唯一视频后端是 Linux V4L2，辅助设备控制使用 libusb-1.0。源码、注释、测试和交付说明使用中文。
当前仓库已经删除 F200、SR300、ZR300、LR200 工厂、IVCAM、fisheye、motion module、Windows/Apple/Qt 工程、WMF/libuvc 后端、旧内核 patch、全局 UVC rebind 脚本和旧 ROS/catkin 工程。不要恢复这些兼容层来掩盖 R200 问题。
未跟踪的 .vscode/ 属于用户环境，不要修改或删除。
R200 数据路径
R200 双 IR 的立体匹配、视差和 Depth 在设备端 DS4 深度引擎完成，主机不执行双目匹配。完整 Depth 路径为：
R200 DS4 stereo/depth engine
-> USB UVC subdevice 1（FourCC Z16，或 DISPARITY16）
-> Linux uvcvideo
-> /dev/videoN
-> src/uvc-v4l2.cpp 的 V4L2 mmap / VIDIOC_DQBUF
-> uvc::subdevice::poll()
-> set_subdevice_mode() 注册的 video_channel_callback
-> dinghy_timestamp_reader::validate_frame()
-> get_frame_counter()/get_frame_timestamp()
-> frame_archive::alloc_frame()
-> subdevice_mode_selection::unpack()（需要时解包）
-> track_frame()/commit_frame()
-> syncronizing_archive
-> rs_wait_for_frames()/rs_poll_for_frames()
-> native_stream::get_frame_data()
-> rs_get_frame_data(device, RS_STREAM_DEPTH)启动路径为：
rs_enable_stream()
-> rs_device_base::enable_stream()
-> device_config::select_modes()
-> rs_start_device()
-> ds_device::start()
-> rs_device_base::start_video_streaming()
-> uvc::set_subdevice_mode()
-> ds_device::on_before_start()
-> ds::set_stream_intent()/set_disparity_mode()
-> uvc::start_streaming()
-> V4L2 VIDIOC_S_FMT/REQBUFS/STREAMON关键源码
src/context.cpp：枚举设备并只按 R200 PID 分派。src/r200.cpp、src/r200.h：make_r200_device()和r200_camera。src/ds-device.cpp、src/ds-device.h：DS 公共配置、R200 stream 模式、启动控制、dinghy timestamp、Depth scale。src/ds-private.cpp、src/ds-private.h：XU 命令、SPI flash admin sector、calibration/intrinsics/extrinsics 和设备信息读取。src/uvc.h、src/uvc-v4l2.cpp：V4L2 subdevice、mmap buffer、UVC XU 与 libusb bulk control。src/types.*：四个 native stream 的模式选择、约束和枚举字符串。src/image.*：pf_z16、pf_y8、pf_y8i、pf_y16、pf_y12i、pf_yuy2、pf_rw10，格式解包、投影、对齐、rectification 和 point cloud。src/archive.*、src/sync.*：帧生命周期、帧队列和相机时间戳同步。src/stream.*：native、aligned、rectified、point synthetic stream。include/librealsense/rs.h、rs.hpp、rscore.hpp、rsutil.h：精简后的 C/C++ API 和投影数学。
原生 stream 与格式
RS_STREAM_NATIVE_COUNT 为 4，顺序固定为 Depth、Color、Infrared、Infrared2。R200 UVC 映射：
| Stream | UVC subdevice | 原生 FourCC | 用户格式 |
|---|---|---|---|
| 左/右 IR | 0 | GREY、Y8I 、Y16 、Y12I |
Y8/Y16 |
| Depth | 1 | Z16 |
Z16/Disparity16 |
| RGB | 2 | YUY2、pRAA |
YUYV/RGB/BGR/RGBA/BGRA/RAW10 |
Depth Z16 是 little-endian 无符号 16 位；米制深度为 pixel * depth_scale，默认 depth_scale=0.001 m/LSB，0 表示无效。DISPARITY16 使用设备 disparity scale，0xffff 表示无效。R200 非 YUY2 原生帧带一行 dinghy 元数据，SDK 在验证后去除/解释该行。
Calibration、对齐与点云
Calibration、intrinsics、extrinsics 和设备信息位于每台 R200 的 SPI flash 非固件区。读取链为 ds::read_camera_info() -> read_admin_sector() -> read_device_pages() -> UVC XU command/response；数据 packed、big-endian，支持 calibration 版本 0/1/2。不要用通用常量替换读取结果。
RGB/Depth 对齐由主机 aligned_stream、src/image.cpp 和 rsutil.h 实现；Depth 与 IR 的 6 像素裁剪/填充也在主机完成。Point Cloud 由 point_stream/deproject_z 生成，格式为 RS_FORMAT_XYZ32F，每点三个 float、单位米。
构建、安装与验证
sudo apt install build-essential cmake pkg-config libusb-1.0-0-dev
cmake -S . -B build -DBUILD_UNIT_TESTS=ON -DBUILD_EXAMPLES=ON
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure
sudo cmake --install build可选 -DBUILD_SHARED_LIBS=OFF 验证静态库。核心库、offline-test 和六个无头示例均不依赖图形栈；当前无头示例集为 c-tutorial-1-depth、cpp-tutorial-1-depth、cpp-callback、cpp-enumerate-devices、cpp-headless、cpp-rgb-only。启用 -DBUILD_OPENCV_EXAMPLE=ON 还会构建 cpp-opencv-viewer 和仅 RGB 的 cpp-rgb-only-viewer。安装后 CMake 消费者使用 find_package(librealsense-r200 CONFIG REQUIRED) 和 realsense::realsense。
已完成验证：
- Ubuntu 24.04.4、GCC 13.3、CMake 3.28 下 Release shared 构建、安装和
offline-test通过。 - Release static 构建、安装和
offline-test通过。 - 安装后的最小 C/C++
find_package消费者编译、链接、运行通过。 - AddressSanitizer + UBSan（关闭 enum 合法性专项检查）offline-test 通过且无泄漏报告。
git diff --check通过。- R200 真机已成功运行
cpp-rgb-only-viewer，确认仅 RGB 连续采集和实时预览路径可用（640x480、RGB8、30 FPS）。
除上述仅 RGB 实时预览外，设备枚举、全部 V4L2 mode、SPI calibration、Depth/IR 真机帧、Depth/RGB/IR 组合流、对齐、点云、拔插和长时间稳定性仍需单独验证。不要把单流 RGB 验证解释为全部真机兼容已确认。
删除和修改规则
任何后续裁剪必须先用 rg 查定义、全部引用、CMake/安装/公共头影响，再单独修改并编译。不得删除 ds-device::set_common_ds_config()、ds::read_camera_info()、XU selector、dinghy reader、device_config::select_modes()、帧 archive/sync、R200 pixel unpacker、projection/alignment/point cloud。修改 ABI 时必须同步更新 C/C++ 头、字符串函数、测试和安装消费者。
Ubuntu 24.04 + ROS2 边界
必须移植/保留的设备知识：R200 PID、UVC interface/subdevice 映射、FourCC 和模式表、XU GUID/selector/结构、SPI calibration 地址和 big-endian 解析、stream intent/disparity/emitter/exposure 控制、dinghy 元数据和 6 像素关系。
可以独立重写的部分：C/C++ 公共 API、V4L2 buffer 管理、帧队列/同步器、YUY2/RAW10 转换、alignment/rectification/point cloud、日志和 diagnostics。ROS2 应是独立的 ament_cmake 工程，通过 sensor_msgs/msg/Image、CameraInfo、PointCloud2 和 TF 发布数据；不要把 ROS2 依赖反向塞进核心采集库。