dora-zed/AGENTS.md

AGENTS.md

This file provides guidance to AI coding assistants when working with code in this repository.

What this is

A dora-rs C++ node that interfaces with ZED stereo cameras. On each tick it grabs a frame, runs object detection, and publishes four outputs over the dora dataflow: a BGR image, an XYZRGBA point cloud, camera intrinsics, and detected objects with 3D positions. Camera management lives in src/zed/, detection engines in src/engines/, and the dora event loop in src/main.cc.

Build

scripts/build.sh

The binary is installed to bin/dora_zed relative to the repo root. The script is also the dataflow's build: command: dora 1.0 executes build commands directly rather than through a shell, so cd, && and command substitution do not work there.

Requirements: dora 1.0+ (verified with dora-cli 1.0.1), CMake 3.21+, ZED SDK 5.x (at /usr/local/zed), CUDA Toolkit, ONNX Runtime 1.20+ (system install), Rust stable toolchain (for dora-rs C++ bindings).

The first build clones dora-rs from GitHub and compiles dora-node-api-cxx via Cargo. This takes a while. Subsequent builds are incremental. If DORA_ROOT_DIR is set to a local dora checkout, it builds against that instead.

For a build without installing the SDK stack on the host, see the Dockerfile (Ubuntu 24.04 — the newest release with a ZED SDK; there is no Stereolabs build for 26.04). Run the compile with --gpus all.

Run

dora up
dora start dataflow.yml

Camera and detection behavior is configured entirely through environment variables (see README.md for the full list: ZED_RESOLUTION, ZED_FPS, ZED_DEPTH_MODE, ZED_DETECTION_MODEL, etc.).

Architecture

• src/util/env.h — Shared inline env-variable parsing helpers (get_env_int, get_env_str, get_env_bool, get_env_float).
• src/zed/camera.h — zed::Config, zed::Calibration, and zed::Camera class. Camera wraps the ZED SDK lifecycle: open (with retry loop), warmup, grab (image + point cloud), calibration, and close. Exposes handle() for engine access.
• src/zed/camera.cc — Implementation. SDK enum parsers live in an anonymous namespace.
• src/engines/engine.h — engines::DetectedObject struct and engines::Engine abstract base class (enable, detect, objects, label_names).
• src/engines/zed_native.h/cc — engines::ZedNative: wraps ZED SDK's TensorRT-optimized object detection module.
• src/engines/yolo_helpers.h — Header-only shared helpers used by the ONNX engine: RawDetection, nms(), letterbox(), fuse_bbox(), backproject(). Lives in engines::detail namespace.
• src/engines/yolo_onnx.h/cc — engines::YoloOnnx / YoloOnnxConfig: closed-vocabulary detection for any single-input YOLO ONNX model (YOLOv8, YOLOv11, YOLOv5, etc.). Auto-detects output layout (NC_FIRST / NC_LAST / NC_LAST_OBJ) from tensor shape; override with ZED_ONNX_OUTPUT_FORMAT. Labels loaded from ZED_ONNX_LABELS or ZED_ONNX_LABELS_FILE.
• src/main.cc — Dora event loop. Selects engine via ZED_ENGINE env var (yolo_onnx/onnx or native), holds a std::unique_ptr<engines::Engine>. Parses ZED_PC_MODE (FULL/HALF/ROI) once before the loop. On any input event (intended to be driven by a tick timer; the id is not inspected): calls camera.grab() and detector->detect(), then sends image_bgr, point_cloud, camera_info, and objects outputs. Point cloud output varies by mode: FULL sends the raw sl::Mat pointer (no copy); HALF downsamples by 2 in each dimension; ROI emits only valid points within detected bounding boxes as a flat [N, 4] array. Handles reconnection on grab failure.
• DoraTargets.cmake — Handles building or fetching dora-rs and generating the CXX bridge files. Two paths: local (DORA_ROOT_DIR) or git clone. Produces dora_node_api_cxx library and the node_bridge.cc glue.
• scripts/build.sh — Configure/compile/install in one shell-free-callable step. Referenced by dataflow.yml, the Dockerfile and the README.
• dataflow.yml — Example dora dataflow definition using the git: source format, pinned with tag: — dora 1.0 pins a source with the mutually exclusive tag:, rev: or branch:.
• Dockerfile — Ubuntu 24.04 x86-64 build environment (CUDA 12.8, ZED SDK 5.2, ONNX Runtime, Rust). No ARM64/Jetson image; build natively there. No camera needed; run the compile with --gpus all. Sets NVIDIA_DRIVER_CAPABILITIES=compute,utility,video — the video capability is what makes the container runtime mount NVDEC/NVENC, which libsl_zed.so links against. ONNX Runtime's CMake package files are relocated to /usr/local/lib/cmake because Ubuntu's multiarch CMake does not search lib64. Rust lives at /usr/local/{rustup,cargo} rather than /root so the build can run as the invoking user. docker build -t dora-zed-build . && docker run --rm --gpus all --user "$(id -u):$(id -g)" -v "$PWD:/src" -v dora-zed-cargo:/usr/local/cargo/registry dora-zed-build.
• scripts/export_yolo.py — PEP 723 uv script. Exports a standard YOLOv11 model to ONNX for closed-vocabulary detection. Run: uv run scripts/export_yolo.py --model n --output-dir models/.
• src/test_yolo_onnx.cc — Standalone C++ test binary (bin/test_yolo_onnx). Exercises YoloOnnx with an image (default test/assets/yolo.png). No dora and no live camera required. Uses the same env vars as the main binary. Saves an annotated result image alongside the input.

Key APIs

• dora C++ API (<dora-node-api.h>): init_dora_node(), dora_node.events->next(), event_type(), send_output_with_metadata(), new_metadata().
• ZED SDK (<sl/Camera.hpp>): sl::Camera, sl::InitParameters, sl::RuntimeParameters, sl::Mat, sl::ObjectDetectionParameters, sl::Objects.
• ONNX Runtime (<onnxruntime_cxx_api.h>): Ort::Env, Ort::Session, Ort::SessionOptions, Ort::Value. Used by the yolo_onnx engine.
• Output data is sent as raw byte slices (rust::Slice<const uint8_t>) with typed metadata (shape, dtype, encoding).

Tools

• Issue tracker: Gitea. Use the Gitea MCP tools (mcp__gitea__*) to read and manage issues, pull requests, and other repository operations.

Rules

• Do not mention AI tools in commit messages or documentation.