diff --git a/Blueye.Protocol.Protobuf.csproj b/Blueye.Protocol.Protobuf.csproj index 4fd72837..fc49fb7d 100644 --- a/Blueye.Protocol.Protobuf.csproj +++ b/Blueye.Protocol.Protobuf.csproj @@ -13,8 +13,8 @@ - - + + runtime; build; native; contentfiles; analyzers; buildtransitive all diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..3f3ae27d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,75 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Protocol definition repository for Blueye Robotics underwater drones. The core definitions live in `protobuf_definitions/*.proto` (proto3 syntax) and are compiled into language-specific libraries for C++, Python, TypeScript, and C#/.NET. + +Published packages: +- **npm**: `@blueyerobotics/protocol-definitions` +- **NuGet**: `Blueye.Protocol.Protobuf` (GitHub Packages) +- **Python**: `blueye.protocol` (PyPI, via separate repo triggered by CI) + +## Build Commands + +### C++ (CMake) +``` +cmake -B build && cmake --build build +cmake --install build --prefix /usr/local +``` + +### TypeScript +``` +pnpm install +# Generate TypeScript from proto files: +mkdir -p ./out/ && protoc protobuf_definitions/*.proto \ + --plugin=./node_modules/.bin/protoc-gen-ts_proto \ + --proto_path=protobuf_definitions \ + --ts_proto_out=./out \ + --ts_proto_opt=outputIndex=true \ + --ts_proto_opt=globalThisPolyfill=true \ + --ts_proto_opt=useExactTypes=false +# Compile TypeScript: +pnpm run build +``` + +### C#/.NET +``` +dotnet pack Blueye.Protocol.Protobuf.csproj -c Release -o out +``` + +### Linting +``` +# Via Docker: +./protolint.sh +``` +Protolint runs on every push/PR in CI. Configuration in `.protolint.yaml` (max line length: 120 chars). + +### Documentation Generation +``` +./protoc-gen-doc.sh +``` + +## Proto File Structure + +All proto definitions are in `protobuf_definitions/`: +- **message_formats.proto** — Main message types, enums, and parameter definitions (largest file) +- **telemetry.proto** — Telemetry message definitions +- **control.proto** — Control command messages +- **req_rep.proto** — Request/response message patterns +- **mission_planning.proto** — Mission planning messages +- **aquatroll.proto** — AquaTroll sensor-specific messages + +## CI/CD Pipeline + +- **ci-build.yaml** — Protolint validation (all pushes and PRs) +- **ci-typescript.yaml** — Generate TS, compile, publish to npm (master only) +- **ci-dotnet.yaml** — Build and publish NuGet package (all pushes) +- **ci-python.yaml** — Triggers `blueye.protocol` repo update via repository dispatch (master, when proto files change) +- **gen-docs.yaml** — Generate HTML docs, upload to Azure (master only) + +## Code Style + +- 2-space indentation, trim trailing whitespace (`.editorconfig`) +- Proto files: max 120 character line length (`.protolint.yaml`) diff --git a/protobuf_definitions/message_formats.proto b/protobuf_definitions/message_formats.proto index 213c26ed..837ace0b 100644 --- a/protobuf_definitions/message_formats.proto +++ b/protobuf_definitions/message_formats.proto @@ -1313,3 +1313,29 @@ message SurfaceUnitBatteryInfo { message SurfaceUnitVersionInfo { string version = 1; // Surface Unit firmware version (x.y.z). } + +// Bounding box for object detection. +// +// Coordinates are in pixels relative to the camera image, +// where (x, y) is the top-left corner of the bounding box. +message BoundingBox { + uint32 x = 1; // Horizontal offset of the top-left corner (px). + uint32 y = 2; // Vertical offset of the top-left corner (px). + uint32 width = 3; // Width of the bounding box (px). + uint32 height = 4; // Height of the bounding box (px). +} + +// A single object detection from a computer vision model. +message ObjectDetection { + BoundingBox bounding_box = 1; // Bounding box of the detected object. + float confidence = 2; // Detection confidence score (0..1). + uint32 class_id = 3; // Numeric class identifier from the model. + string class_name = 4; // Human-readable class name. + uint32 tracking_id = 5; // Unique ID for tracking the same object across frames. +} + +// A list of object detections from a single video frame. +message ObjectDetections { + repeated ObjectDetection detections = 1; // List of detections in the frame. + Camera camera = 2; // Which camera the detections are from. +} diff --git a/protobuf_definitions/telemetry.proto b/protobuf_definitions/telemetry.proto index 724784a4..bdc75558 100644 --- a/protobuf_definitions/telemetry.proto +++ b/protobuf_definitions/telemetry.proto @@ -313,3 +313,8 @@ message LogEntryTel { KernelLogEntry kernel = 2; // Kernel log entry. } } + +// Object detections from a computer vision model. +message ObjectDetectionsTel { + ObjectDetections object_detections = 1; // List of object detections from a video frame. +}