# saintbridgethefirst/imageraster architecture

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

- Interactive diagram: https://gitdiagram.com/saintbridgethefirst/imageraster
- Repository: https://github.com/saintbridgethefirst/imageraster

## Overview

ImageRaster is a 3Pi+ robot scanning system with a live browser dashboard and a Processing Digital Twin. The main workflow is to prepare a printed sheet, start a raster scan from the dashboard or robot button, collect pose and surface readings, and view or download the reconstructed image and scan data. The graph also preserves documented analysis and simulation capabilities. Firmware call details are limited to the supplied excerpts and source index; Digital Twin internals are represented at the directory level where source was not sampled.

Main entry points: [`Controller.cpp`](https://github.com/saintbridgethefirst/imageraster/blob/main/Controller.cpp) (Raster controller), [`WebDashboard.cpp`](https://github.com/saintbridgethefirst/imageraster/blob/main/WebDashboard.cpp) (Dashboard server), [`DigitalTwin`](https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin) (Scan simulator), [`ImageRaster.ino`](https://github.com/saintbridgethefirst/imageraster/blob/main/ImageRaster.ino) (Firmware entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Sheet preparation"]
  node_sheet_tool["Sheet generator<br/>[make_sheet.py]"]
  node_sheet_assets["Sheet assets"]
end

subgraph group_firmware["Robot firmware"]
  node_entry["Firmware entry<br/>[ImageRaster.ino]"]
  node_controller["Raster controller<br/>[Controller.cpp]"]
  node_robot_io["Robot I/O<br/>[Robot.cpp]"]
  node_odometry["Odometry model<br/>[OdometryModel.cpp]"]
  node_scan_log[("Scan ring buffer<br/>[ScanLog.cpp]")]
  node_timer["Polling timer<br/>[TaskTimer.cpp]"]
  node_wifi["WiFi access point<br/>[RobotWifiAP.cpp]"]
  node_telemetry["TCP telemetry<br/>[Controller.cpp]"]
end

subgraph group_dashboard["Live dashboard"]
  node_web_server["Dashboard server<br/>[WebDashboard.cpp]"]
  node_web_ui["Browser dashboard<br/>[dashboard.html]"]
end

subgraph group_twin["Digital Twin"]
  node_twin["Scan simulator"]
  node_twin_views["Twin views"]
  node_twin_models["Twin models"]
end

node_engineer(("Operator"))
node_robot["3Pi+ robot"]

node_engineer -->|"prepares artwork"| node_sheet_tool
node_sheet_tool -->|"creates sheets"| node_sheet_assets
node_engineer -->|"starts scan"| node_robot
node_robot -->|"runs firmware"| node_entry
node_entry -.->|"updates"| node_controller
node_controller -->|"reads sensors"| node_robot_io
node_controller -->|"updates pose"| node_odometry
node_controller -->|"appends samples"| node_scan_log
node_controller -.->|"schedules work"| node_timer
node_entry -.->|"starts access point"| node_wifi
node_web_server -->|"reads robot state"| node_robot_io
node_web_server -->|"controls scans"| node_controller
node_web_server -.->|"serves over WiFi"| node_wifi
node_web_ui -->|"requests status and data"| node_web_server
node_scan_log -->|"provides samples"| node_web_server
node_controller -->|"emits scan telemetry"| node_telemetry
node_telemetry -->|"feeds twin"| node_twin
node_twin -.->|"uses models"| node_twin_models
node_twin -.->|"renders views"| node_twin_views
node_sheet_assets -.->|"supplies scan surface"| node_twin

click node_sheet_tool "https://github.com/saintbridgethefirst/imageraster/blob/main/tools/make_sheet.py"
click node_entry "https://github.com/saintbridgethefirst/imageraster/blob/main/ImageRaster.ino"
click node_controller "https://github.com/saintbridgethefirst/imageraster/blob/main/Controller.cpp"
click node_robot_io "https://github.com/saintbridgethefirst/imageraster/blob/main/Robot.cpp"
click node_odometry "https://github.com/saintbridgethefirst/imageraster/blob/main/OdometryModel.cpp"
click node_scan_log "https://github.com/saintbridgethefirst/imageraster/blob/main/ScanLog.cpp"
click node_timer "https://github.com/saintbridgethefirst/imageraster/blob/main/TaskTimer.cpp"
click node_wifi "https://github.com/saintbridgethefirst/imageraster/blob/main/RobotWifiAP.cpp"
click node_web_server "https://github.com/saintbridgethefirst/imageraster/blob/main/WebDashboard.cpp"
click node_web_ui "https://github.com/saintbridgethefirst/imageraster/blob/main/dashboard/dashboard.html"
click node_telemetry "https://github.com/saintbridgethefirst/imageraster/blob/main/Controller.cpp"
click node_twin "https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin"
click node_twin_views "https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin"
click node_twin_models "https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin"
click node_sheet_assets "https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin/sheets"

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_sheet_tool,node_sheet_assets toneBlue
class node_entry,node_controller,node_robot_io,node_odometry,node_scan_log,node_timer,node_wifi,node_telemetry toneAmber
class node_web_server,node_web_ui toneMint
class node_twin,node_twin_views,node_twin_models toneRose
class node_engineer,node_robot toneIndigo
```

## Components

### Sheet preparation

- [Sheet generator](https://github.com/saintbridgethefirst/imageraster/blob/main/tools/make_sheet.py): `tools/make_sheet.py`
- [Sheet assets](https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin/sheets): `DigitalTwin/sheets`

### Robot firmware

- [Firmware entry](https://github.com/saintbridgethefirst/imageraster/blob/main/ImageRaster.ino): `ImageRaster.ino`
- [Raster controller](https://github.com/saintbridgethefirst/imageraster/blob/main/Controller.cpp): `Controller.cpp`
- [Robot I/O](https://github.com/saintbridgethefirst/imageraster/blob/main/Robot.cpp): `Robot.cpp`
- [Odometry model](https://github.com/saintbridgethefirst/imageraster/blob/main/OdometryModel.cpp): `OdometryModel.cpp`
- [Scan ring buffer](https://github.com/saintbridgethefirst/imageraster/blob/main/ScanLog.cpp): `ScanLog.cpp`
- [Polling timer](https://github.com/saintbridgethefirst/imageraster/blob/main/TaskTimer.cpp): `TaskTimer.cpp`
- [WiFi access point](https://github.com/saintbridgethefirst/imageraster/blob/main/RobotWifiAP.cpp): `RobotWifiAP.cpp`
- [TCP telemetry](https://github.com/saintbridgethefirst/imageraster/blob/main/Controller.cpp): `Controller.cpp`

### Live dashboard

- [Dashboard server](https://github.com/saintbridgethefirst/imageraster/blob/main/WebDashboard.cpp): `WebDashboard.cpp`
- [Browser dashboard](https://github.com/saintbridgethefirst/imageraster/blob/main/dashboard/dashboard.html): `dashboard/dashboard.html`

### Digital Twin

- [Scan simulator](https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin): `DigitalTwin`
- [Twin views](https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin): `DigitalTwin`
- [Twin models](https://github.com/saintbridgethefirst/imageraster/tree/main/DigitalTwin): `DigitalTwin`

### Other components

- **Operator**
- **3Pi+ robot**

## Connections

- Operator → Sheet generator: prepares artwork (evidence: `tools/make_sheet.py`)
- Sheet generator → Sheet assets: creates sheets (evidence: `tools/make_sheet.py`)
- Operator → 3Pi+ robot: starts scan (evidence: `README.md`)
- 3Pi+ robot → Firmware entry: runs firmware (evidence: `README.md`)
- Firmware entry → Raster controller: updates
- Raster controller → Robot I/O: reads sensors (evidence: `Controller.cpp`)
- Raster controller → Odometry model: updates pose (evidence: `Controller.cpp`)
- Raster controller → Scan ring buffer: appends samples (evidence: `Controller.cpp`)
- Raster controller → Polling timer: schedules work
- Firmware entry → WiFi access point: starts access point
- Dashboard server → Robot I/O: reads robot state
- Dashboard server → Raster controller: controls scans
- Dashboard server → WiFi access point: serves over WiFi
- Browser dashboard → Dashboard server: requests status and data
- Scan ring buffer → Dashboard server: provides samples
- Raster controller → TCP telemetry: emits scan telemetry (evidence: `README.md`)
- TCP telemetry → Scan simulator: feeds twin (evidence: `README.md`)
- Scan simulator → Twin models: uses models
- Scan simulator → Twin views: renders views
- Sheet assets → Scan simulator: supplies scan surface
