# macrobomaster/cv architecture

> Architecture diagram of the GitHub repository macrobomaster/cv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/macrobomaster/cv
- Repository: https://github.com/macrobomaster/cv

## Overview

This repository is a robotics-vision and field-control stack. Its principal runtime workflow turns camera frames into plate detections and tracked targets, combines those with localization and occupancy estimates, then plans chassis motion and computes gimbal aim and firing commands. Separate daemons provide tag-based localization, navigation, state-driven goals, and communications; the tree also contains auto-aim model training and synthetic-data generation. The excerpts support key message flows, but not every daemon’s wiring, so uncertain links are omitted.

Main entry points: [`cv/system/navd/navd.py`](https://github.com/macrobomaster/cv/blob/main/cv/system/navd/navd.py) (Path planning), [`cv/system/camerad/camerad.py`](https://github.com/macrobomaster/cv/blob/main/cv/system/camerad/camerad.py) (Camera daemon), [`cv/system/slamd/slamd.py`](https://github.com/macrobomaster/cv/blob/main/cv/system/slamd/slamd.py) (Field localization), [`cv/system/plated/plated.py`](https://github.com/macrobomaster/cv/blob/main/cv/system/plated/plated.py) (Plate tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_perception["Perception"]
  node_camera["Camera daemon<br/>[camerad.py]"]
  node_autoaim["Auto-aim inference<br/>[autoaimd.py]"]
  node_plate_track["Plate tracking<br/>[plated.py]"]
  node_tag_detect["AprilTag detection<br/>[tagd.py]"]
  node_occupancy_service["Camera occupancy<br/>[occupancyd.py]"]
  node_ipm["Ground projection<br/>[ipm.py]"]
end

subgraph group_localization["Localization and Navigation"]
  node_slam["Field localization<br/>[slamd.py]"]
  node_slam_filter["Pose filter<br/>[filter.py]"]
  node_nav["Path planning<br/>[navd.py]"]
  node_nav_planner["Grid planner<br/>[planner.py]"]
  node_occupancy_grid["Occupancy grid<br/>[occupancy.py]"]
end

subgraph group_control["Robot Control"]
  node_decision["Aim and fire<br/>[decisiond.py]"]
  node_gimbal["Gimbal control<br/>[gimbald.py]"]
  node_states["Robot state machine<br/>[stated.py]"]
  node_comms["Device communications<br/>[commsd.py]"]
end

subgraph group_runtime["Runtime Infrastructure"]
  node_supervisor["Service supervisor<br/>[supervisor.py]"]
  node_messaging["Message bus<br/>[messaging.py]"]
  node_frame_ring[("Shared frame ring<br/>[frame_ring.py]")]
end

subgraph group_learning["Model Training"]
  node_aim_model["Auto-aim model<br/>[model.py]"]
  node_aim_training["Auto-aim training<br/>[train.py]"]
  node_aim_data["Synthetic scenes<br/>[__init__.py]"]
end

node_camera_hardware(("Camera hardware"))
node_robot_sensors(("Robot sensors"))
node_robot_actuators(("Robot actuators"))
node_operator(("Operator"))

node_camera_hardware -->|"captures"| node_camera
node_camera -->|"writes frames"| node_frame_ring
node_camera -->|"publishes frames"| node_autoaim
node_autoaim -->|"runs inference"| node_aim_model
node_autoaim -->|"publishes detections"| node_plate_track
node_camera -->|"publishes frames"| node_occupancy_service
node_camera -->|"provides frames"| node_tag_detect
node_tag_detect -->|"provides tag detections"| node_slam
node_robot_sensors -->|"provides motion data"| node_slam
node_slam -->|"updates pose"| node_slam_filter
node_slam -->|"publishes pose"| node_plate_track
node_slam -->|"publishes pose"| node_occupancy_service
node_occupancy_service -->|"projects contacts"| node_ipm
node_occupancy_service -->|"publishes occupancy"| node_nav
node_plate_track -->|"publishes target"| node_decision
node_plate_track -->|"provides obstacles"| node_nav
node_operator -->|"sets mode"| node_states
node_states -->|"sends goals"| node_nav
node_nav -->|"plans route"| node_nav_planner
node_nav -->|"updates grid"| node_occupancy_grid
node_nav -->|"commands chassis"| node_robot_actuators
node_decision -->|"sends setpoints"| node_gimbal
node_decision -->|"commands firing"| node_robot_actuators
node_gimbal -->|"commands gimbal"| node_robot_actuators
node_gimbal -->|"publishes state"| node_decision
node_comms -->|"dispatches commands"| node_robot_actuators
node_supervisor -->|"starts services"| node_messaging
node_aim_data -->|"generates samples"| node_aim_training
node_aim_training -->|"trains weights"| node_aim_model

click node_camera "https://github.com/macrobomaster/cv/blob/main/cv/system/camerad/camerad.py"
click node_autoaim "https://github.com/macrobomaster/cv/blob/main/cv/system/autoaimd/autoaimd.py"
click node_plate_track "https://github.com/macrobomaster/cv/blob/main/cv/system/plated/plated.py"
click node_tag_detect "https://github.com/macrobomaster/cv/blob/main/cv/system/tagd/tagd.py"
click node_occupancy_service "https://github.com/macrobomaster/cv/blob/main/cv/system/occupancyd/occupancyd.py"
click node_ipm "https://github.com/macrobomaster/cv/blob/main/cv/occupancy/ipm.py"
click node_slam "https://github.com/macrobomaster/cv/blob/main/cv/system/slamd/slamd.py"
click node_slam_filter "https://github.com/macrobomaster/cv/blob/main/cv/slam/filter.py"
click node_nav "https://github.com/macrobomaster/cv/blob/main/cv/system/navd/navd.py"
click node_nav_planner "https://github.com/macrobomaster/cv/blob/main/cv/nav/planner.py"
click node_occupancy_grid "https://github.com/macrobomaster/cv/blob/main/cv/nav/occupancy.py"
click node_decision "https://github.com/macrobomaster/cv/blob/main/cv/system/decisiond/decisiond.py"
click node_gimbal "https://github.com/macrobomaster/cv/blob/main/cv/system/gimbald/gimbald.py"
click node_states "https://github.com/macrobomaster/cv/blob/main/cv/system/stated/stated.py"
click node_comms "https://github.com/macrobomaster/cv/blob/main/cv/system/commsd/commsd.py"
click node_supervisor "https://github.com/macrobomaster/cv/blob/main/cv/system/core/supervisor.py"
click node_messaging "https://github.com/macrobomaster/cv/blob/main/cv/system/core/messaging.py"
click node_frame_ring "https://github.com/macrobomaster/cv/blob/main/cv/system/common/frame_ring.py"
click node_aim_model "https://github.com/macrobomaster/cv/blob/main/cv/autoaim/model.py"
click node_aim_training "https://github.com/macrobomaster/cv/blob/main/cv/autoaim/train.py"
click node_aim_data "https://github.com/macrobomaster/cv/blob/main/cv/autoaim/syndata/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_camera,node_autoaim,node_plate_track,node_tag_detect,node_occupancy_service,node_ipm toneBlue
class node_slam,node_slam_filter,node_nav,node_nav_planner,node_occupancy_grid toneAmber
class node_decision,node_gimbal,node_states,node_comms toneMint
class node_supervisor,node_messaging,node_frame_ring toneRose
class node_aim_model,node_aim_training,node_aim_data,node_camera_hardware,node_robot_sensors,node_robot_actuators,node_operator toneIndigo
```

## Components

### Perception

- [Camera daemon](https://github.com/macrobomaster/cv/blob/main/cv/system/camerad/camerad.py): `cv/system/camerad/camerad.py`
- [Auto-aim inference](https://github.com/macrobomaster/cv/blob/main/cv/system/autoaimd/autoaimd.py): `cv/system/autoaimd/autoaimd.py`
- [Plate tracking](https://github.com/macrobomaster/cv/blob/main/cv/system/plated/plated.py): `cv/system/plated/plated.py`
- [AprilTag detection](https://github.com/macrobomaster/cv/blob/main/cv/system/tagd/tagd.py): `cv/system/tagd/tagd.py`
- [Camera occupancy](https://github.com/macrobomaster/cv/blob/main/cv/system/occupancyd/occupancyd.py): `cv/system/occupancyd/occupancyd.py`
- [Ground projection](https://github.com/macrobomaster/cv/blob/main/cv/occupancy/ipm.py): `cv/occupancy/ipm.py`

### Localization and Navigation

- [Field localization](https://github.com/macrobomaster/cv/blob/main/cv/system/slamd/slamd.py): `cv/system/slamd/slamd.py`
- [Pose filter](https://github.com/macrobomaster/cv/blob/main/cv/slam/filter.py): `cv/slam/filter.py`
- [Path planning](https://github.com/macrobomaster/cv/blob/main/cv/system/navd/navd.py): `cv/system/navd/navd.py`
- [Grid planner](https://github.com/macrobomaster/cv/blob/main/cv/nav/planner.py): `cv/nav/planner.py`
- [Occupancy grid](https://github.com/macrobomaster/cv/blob/main/cv/nav/occupancy.py): `cv/nav/occupancy.py`

### Robot Control

- [Aim and fire](https://github.com/macrobomaster/cv/blob/main/cv/system/decisiond/decisiond.py): `cv/system/decisiond/decisiond.py`
- [Gimbal control](https://github.com/macrobomaster/cv/blob/main/cv/system/gimbald/gimbald.py): `cv/system/gimbald/gimbald.py`
- [Robot state machine](https://github.com/macrobomaster/cv/blob/main/cv/system/stated/stated.py): `cv/system/stated/stated.py`
- [Device communications](https://github.com/macrobomaster/cv/blob/main/cv/system/commsd/commsd.py): `cv/system/commsd/commsd.py`

### Runtime Infrastructure

- [Service supervisor](https://github.com/macrobomaster/cv/blob/main/cv/system/core/supervisor.py): `cv/system/core/supervisor.py`
- [Message bus](https://github.com/macrobomaster/cv/blob/main/cv/system/core/messaging.py): `cv/system/core/messaging.py`
- [Shared frame ring](https://github.com/macrobomaster/cv/blob/main/cv/system/common/frame_ring.py): `cv/system/common/frame_ring.py`

### Model Training

- [Auto-aim model](https://github.com/macrobomaster/cv/blob/main/cv/autoaim/model.py): `cv/autoaim/model.py`
- [Auto-aim training](https://github.com/macrobomaster/cv/blob/main/cv/autoaim/train.py): `cv/autoaim/train.py`
- [Synthetic scenes](https://github.com/macrobomaster/cv/blob/main/cv/autoaim/syndata/__init__.py): `cv/autoaim/syndata/__init__.py`

### Other components

- **Camera hardware**
- **Robot sensors**
- **Robot actuators**
- **Operator**

## Connections

- Camera hardware → Camera daemon: captures
- Camera daemon → Shared frame ring: writes frames
- Camera daemon → Auto-aim inference: publishes frames
- Auto-aim inference → Auto-aim model: runs inference
- Auto-aim inference → Plate tracking: publishes detections
- Camera daemon → Camera occupancy: publishes frames
- Camera daemon → AprilTag detection: provides frames
- AprilTag detection → Field localization: provides tag detections
- Robot sensors → Field localization: provides motion data
- Field localization → Pose filter: updates pose
- Field localization → Plate tracking: publishes pose
- Field localization → Camera occupancy: publishes pose
- Camera occupancy → Ground projection: projects contacts
- Camera occupancy → Path planning: publishes occupancy
- Plate tracking → Aim and fire: publishes target
- Plate tracking → Path planning: provides obstacles
- Operator → Robot state machine: sets mode
- Robot state machine → Path planning: sends goals
- Path planning → Grid planner: plans route
- Path planning → Occupancy grid: updates grid
- Path planning → Robot actuators: commands chassis
- Aim and fire → Gimbal control: sends setpoints
- Aim and fire → Robot actuators: commands firing
- Gimbal control → Robot actuators: commands gimbal
- Gimbal control → Aim and fire: publishes state
- Device communications → Robot actuators: dispatches commands
- Service supervisor → Message bus: starts services
- Synthetic scenes → Auto-aim training: generates samples
- Auto-aim training → Auto-aim model: trains weights