# zz1ww/triniscan architecture

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

- Interactive diagram: https://gitdiagram.com/zz1ww/triniscan
- Repository: https://github.com/zz1ww/triniscan

## Overview

TriniScan is a laser-line triangulation scanner that turns rotating-table camera captures into a closed 3D mesh and volume measurement. The main workflow is configured and launched through the CLI or Tkinter UI; the pipeline loads camera, laser, and axis calibration, scans views, extracts laser centers, triangulates and registers point clouds, then reconstructs and closes a mesh before computing volume. Calibration tools and single-frame preview are supporting workflows. The firmware has two documented alternative MCU implementations for the serial-controlled turntable. Relationships among unsampled subsystems follow README descriptions; source excerpts show only selected calls.

Main entry points: [`software/triniscan/core/pipeline.py`](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/core/pipeline.py) (Scan pipeline), [`software/triniscan/ui/app.py`](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/app.py) (GUI), [`software/triniscan/extraction/centerline.py`](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/extraction/centerline.py) (Centerline extraction), [`software/triniscan/core/main.py`](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/core/main.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_ui["GUI<br/>[app.py]"]
  node_ui_panels["Config panels<br/>[panels.py]"]
  node_ui_preview["Preview panel<br/>[preview.py]"]
  node_ui_worker["Background worker<br/>[worker.py]"]
end

subgraph group_calib["Calibration"]
  node_camera_calib["Camera calibration<br/>[camera_calib.py]"]
  node_laser_calib["Laser calibration<br/>[laser_calib.py]"]
  node_axis_calib["Axis calibration<br/>[axis_calib.py]"]
end

subgraph group_scan["Capture and extraction"]
  node_pipeline["Scan pipeline<br/>[pipeline.py]"]
  node_camera["Camera capture<br/>[capture.py]"]
  node_turntable["Turntable controller<br/>[controller.py]"]
  node_centerline["Centerline extraction<br/>[centerline.py]"]
  node_steger["Steger method<br/>[_steger.py]"]
end

subgraph group_recon["Reconstruction and volume"]
  node_triangulate["Triangulation<br/>[triangulate.py]"]
  node_register["View registration<br/>[register.py]"]
  node_mesh["Mesh reconstruction<br/>[mesh.py]"]
  node_close_mesh["Mesh closure<br/>[close_mesh.py]"]
  node_volume["Volume calculation<br/>[volume.py]"]
  node_measurement["Measurement result"]
end

subgraph group_mcu["Turntable firmware"]
  node_hal_main["HAL firmware main<br/>[main.c]"]
  node_hal_cmd["HAL command handler<br/>[cmd.c]"]
  node_hal_motor["HAL motor driver<br/>[motor.c]"]
  node_spl_main["SPL firmware main<br/>[main.c]"]
  node_spl_cmd["SPL command handler<br/>[cmd.c]"]
  node_spl_motor["SPL motor driver<br/>[motor.c]"]
end

node_operator(("Operator"))

node_operator -->|"runs scan"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"starts measurement"| node_pipeline
node_operator -->|"uses interface"| node_ui
node_ui -->|"renders"| node_ui_panels
node_ui -->|"renders"| node_ui_preview
node_ui -->|"dispatches tasks"| node_ui_worker
node_ui -->|"starts measurement"| node_pipeline
node_ui -->|"captures preview"| node_camera
node_ui -->|"extracts preview"| node_centerline
node_pipeline -->|"loads calibration"| node_camera_calib
node_pipeline -->|"loads calibration"| node_laser_calib
node_pipeline -->|"loads calibration"| node_axis_calib
node_pipeline -->|"controls rotation"| node_turntable
node_pipeline -->|"captures views"| node_camera
node_pipeline -->|"extracts centers"| node_centerline
node_centerline -->|"delegates method"| node_steger
node_pipeline -->|"triangulates pixels"| node_triangulate
node_pipeline -->|"registers views"| node_register
node_pipeline -->|"reconstructs mesh"| node_mesh
node_pipeline -->|"closes mesh"| node_close_mesh
node_pipeline -->|"computes volume"| node_volume
node_pipeline -->|"produces result"| node_measurement
node_laser_calib -->|"extracts calibration line"| node_centerline
node_turntable -->|"serial protocol"| node_hal_cmd
node_hal_main -.->|"runs command handling"| node_hal_cmd
node_hal_cmd -.->|"controls motor"| node_hal_motor
node_turntable -->|"serial protocol"| node_spl_cmd
node_spl_main -.->|"runs command handling"| node_spl_cmd
node_spl_cmd -->|"controls motor"| node_spl_motor

click node_cli "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/core/main.py"
click node_config "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/core/config.py"
click node_ui "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/app.py"
click node_ui_panels "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/panels.py"
click node_ui_preview "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/preview.py"
click node_ui_worker "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/worker.py"
click node_pipeline "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/core/pipeline.py"
click node_camera "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/camera/capture.py"
click node_turntable "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/turntable/controller.py"
click node_centerline "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/extraction/centerline.py"
click node_steger "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/extraction/_steger.py"
click node_camera_calib "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/calibration/camera_calib.py"
click node_laser_calib "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/calibration/laser_calib.py"
click node_axis_calib "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/calibration/axis_calib.py"
click node_triangulate "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/reconstruction/triangulate.py"
click node_register "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/reconstruction/register.py"
click node_mesh "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/reconstruction/mesh.py"
click node_close_mesh "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/volume/close_mesh.py"
click node_volume "https://github.com/zz1ww/triniscan/blob/main/software/triniscan/volume/volume.py"
click node_hal_main "https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_cubeide/Core/Src/main.c"
click node_hal_cmd "https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_cubeide/Core/Src/cmd.c"
click node_hal_motor "https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_cubeide/Core/Src/motor.c"
click node_spl_main "https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_spl/User/main.c"
click node_spl_cmd "https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_spl/User/cmd.c"
click node_spl_motor "https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_spl/User/motor.c"

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_cli,node_config,node_ui,node_ui_panels,node_ui_preview,node_ui_worker toneBlue
class node_camera_calib,node_laser_calib,node_axis_calib toneAmber
class node_pipeline,node_camera,node_turntable,node_centerline,node_steger toneMint
class node_triangulate,node_register,node_mesh,node_close_mesh,node_volume,node_measurement toneRose
class node_hal_main,node_hal_cmd,node_hal_motor,node_spl_main,node_spl_cmd,node_spl_motor,node_operator toneIndigo
```

## Components

### User entry

- [CLI](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/core/main.py): `software/triniscan/core/main.py`
- [Configuration](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/core/config.py): `software/triniscan/core/config.py`
- [GUI](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/app.py): `software/triniscan/ui/app.py`
- [Config panels](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/panels.py): `software/triniscan/ui/panels.py`
- [Preview panel](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/preview.py): `software/triniscan/ui/preview.py`
- [Background worker](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/ui/worker.py): `software/triniscan/ui/worker.py`

### Calibration

- [Camera calibration](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/calibration/camera_calib.py): `software/triniscan/calibration/camera_calib.py`
- [Laser calibration](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/calibration/laser_calib.py): `software/triniscan/calibration/laser_calib.py`
- [Axis calibration](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/calibration/axis_calib.py): `software/triniscan/calibration/axis_calib.py`

### Capture and extraction

- [Scan pipeline](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/core/pipeline.py): `software/triniscan/core/pipeline.py`
- [Camera capture](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/camera/capture.py): `software/triniscan/camera/capture.py`
- [Turntable controller](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/turntable/controller.py): `software/triniscan/turntable/controller.py`
- [Centerline extraction](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/extraction/centerline.py): `software/triniscan/extraction/centerline.py`
- [Steger method](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/extraction/_steger.py): `software/triniscan/extraction/_steger.py`

### Reconstruction and volume

- [Triangulation](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/reconstruction/triangulate.py): `software/triniscan/reconstruction/triangulate.py`
- [View registration](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/reconstruction/register.py): `software/triniscan/reconstruction/register.py`
- [Mesh reconstruction](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/reconstruction/mesh.py): `software/triniscan/reconstruction/mesh.py`
- [Mesh closure](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/volume/close_mesh.py): `software/triniscan/volume/close_mesh.py`
- [Volume calculation](https://github.com/zz1ww/triniscan/blob/main/software/triniscan/volume/volume.py): `software/triniscan/volume/volume.py`
- **Measurement result**

### Turntable firmware

- [HAL firmware main](https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_cubeide/Core/Src/main.c): `firmware/mcu_stm32_cubeide/Core/Src/main.c`
- [HAL command handler](https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_cubeide/Core/Src/cmd.c): `firmware/mcu_stm32_cubeide/Core/Src/cmd.c`
- [HAL motor driver](https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_cubeide/Core/Src/motor.c): `firmware/mcu_stm32_cubeide/Core/Src/motor.c`
- [SPL firmware main](https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_spl/User/main.c): `firmware/mcu_stm32_spl/User/main.c`
- [SPL command handler](https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_spl/User/cmd.c): `firmware/mcu_stm32_spl/User/cmd.c`
- [SPL motor driver](https://github.com/zz1ww/triniscan/blob/main/firmware/mcu_stm32_spl/User/motor.c): `firmware/mcu_stm32_spl/User/motor.c`

### Other components

- **Operator**

## Connections

- Operator → CLI: runs scan (evidence: `README.md`)
- CLI → Configuration: loads settings (evidence: `software/triniscan/core/main.py`)
- CLI → Scan pipeline: starts measurement (evidence: `software/triniscan/core/main.py`)
- Operator → GUI: uses interface (evidence: `README.md`)
- GUI → Config panels: renders (evidence: `software/triniscan/ui/app.py`)
- GUI → Preview panel: renders (evidence: `software/triniscan/ui/app.py`)
- GUI → Background worker: dispatches tasks (evidence: `software/triniscan/ui/app.py`)
- GUI → Scan pipeline: starts measurement (evidence: `software/triniscan/ui/app.py`)
- GUI → Camera capture: captures preview (evidence: `software/triniscan/ui/app.py`)
- GUI → Centerline extraction: extracts preview (evidence: `software/triniscan/ui/app.py`)
- Scan pipeline → Camera calibration: loads calibration (evidence: `software/triniscan/core/pipeline.py`)
- Scan pipeline → Laser calibration: loads calibration (evidence: `software/triniscan/core/pipeline.py`)
- Scan pipeline → Axis calibration: loads calibration (evidence: `software/triniscan/core/pipeline.py`)
- Scan pipeline → Turntable controller: controls rotation (evidence: `README.md`)
- Scan pipeline → Camera capture: captures views (evidence: `README.md`)
- Scan pipeline → Centerline extraction: extracts centers (evidence: `software/triniscan/core/pipeline.py`)
- Centerline extraction → Steger method: delegates method (evidence: `software/triniscan/extraction/centerline.py`)
- Scan pipeline → Triangulation: triangulates pixels (evidence: `software/triniscan/core/pipeline.py`)
- Scan pipeline → View registration: registers views (evidence: `software/triniscan/core/pipeline.py`)
- Scan pipeline → Mesh reconstruction: reconstructs mesh (evidence: `README.md`)
- Scan pipeline → Mesh closure: closes mesh (evidence: `software/triniscan/core/pipeline.py`)
- Scan pipeline → Volume calculation: computes volume (evidence: `software/triniscan/core/pipeline.py`)
- Scan pipeline → Measurement result: produces result (evidence: `software/triniscan/core/pipeline.py`)
- Laser calibration → Centerline extraction: extracts calibration line (evidence: `software/triniscan/calibration/laser_calib.py`)
- Turntable controller → HAL command handler: serial protocol (evidence: `README.md`)
- HAL firmware main → HAL command handler: runs command handling
- HAL command handler → HAL motor driver: controls motor
- Turntable controller → SPL command handler: serial protocol (evidence: `README.md`)
- SPL firmware main → SPL command handler: runs command handling
- SPL command handler → SPL motor driver: controls motor (evidence: `firmware/mcu_stm32_spl/User/cmd.c`)
