# bcschofield/hpatr architecture

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

- Interactive diagram: https://gitdiagram.com/bcschofield/hpatr
- Repository: https://github.com/bcschofield/hpatr

## Overview

HPATR is organized as a set of loosely coupled tools around one domain: aerosol / droplet experimentation, imaging analysis, and model-based analysis. The repository is not a single monolithic application; it has three main functional areas with a shared configuration layer and shared data directories.

#### 1) Core architecture at a glance

The repo splits into:

- **`src/` runtime package**: the main reusable code for imaging, GUI control, and configuration.
- **Root-level entry scripts**: convenience launchers for training/inference and imaging workflows.
- **`AI/` workspace**: Detectron2-based training, evaluation, synthetic data generation, and validation assets.
- **`Trials/` sandbox**: ad hoc experiments, cone/spray prototyping, and generated outputs.
- **`config/`**: path and environment configuration.
- **`data/`**: sample inputs/outputs and example artifacts.
- **`docs/`**: process and algorithm documentation.

A key architectural pattern is that most runtime code depends on **path configuration loaded from `config/paths.yaml`** rather than hard-coded locations. The system is designed to run with local file-based inputs and outputs, and it emits timestamped result folders for traceability.

#### 2) Main runtime subsystems in `src/`

##### A. Imaging / analysis pipeline (`src/imaging/`)
This is the main image-processing subsystem.

Relevant modules:
- `save_and_analyse.py`
- `expansion_detection.py`
- `mp4_to_tiff.py`
- `capture_still_image.py`
- `webcam_preview.py`
- `save_and_analyse.py` is described in the README as the primary pipeline.

###### Responsibilities
- Accept an input image or frame set.
- Run droplet/expansion detection using computer vision techniques.
- Produce analysis artifacts and debug imagery.
- Optionally convert Phantom video files into TIFF frames before analysis.

###### Processing flow
The README indicates the analysis core uses:
- **Canny edge detection**
- **Watershed segmentation**
- **Hough circle detection**
- **Optimization** for size and position

This implies a staged pipeline where intermediate detections are refined into a final, optimized result.

###### Outputs
The pipeline writes to a timestamped directory structure under a configured output root, typically including:
- copied input
- `FINAL_OPTIMIZED_RESULT.png`
- `FINAL_ANALYSIS.csv`
- intermediate detection images like `CANNY_DETECTION.png` and `WATERSHED_DETECTION.png`
- a `debug_images/` subfolder

###### Boundaries
This subsystem is file-driven and self-contained:
- Input boundary: image files, TIFFs, or extracted video frames
- Output boundary: analysis images, CSVs, debug artifacts
- It does not directly control hardware

##### B. Experiment control GUI (`src/gui/`)
This is the hardware orchestration and experiment-logging subsystem.

Relevant modules:
- `Windows_Experiment_GUI.py`
- `Pressure_Motor_Portenta.cpp`
- `camera_settings.json`

###### Responsibilities
- Provide a unified GUI for experiment setup and execution.
- Control:
  - an **Arduino Portenta H7** running the provided firmware
  - a **motor driver (TMC5160)**
  - a **pressure controller**
  - a **Phantom camera** via SDK if available
- Capture experiment metadata and logs.

###### Hardware / external boundaries
This layer is hardware-facing and communicates across serial and SDK boundaries:
- **Arduino / Portenta** over serial
- **pressure controller** over serial
- **Phantom camera** through `pyphantom` if installed
- If `pyphantom` is unavailable, the GUI degrades gracefully and camera features are limited

###### Data/logging flow
The GUI likely acts as an experiment coordinator:
- operator inputs settings
- GUI sends control commands to hardware
- camera captures data
- logs and metadata are written to disk in configured locations

The `serial_log.txt` at repo root suggests serial communication is logged centrally or during testing.

###### Boundaries
The GUI is a control plane, not an analysis plane:
- it orchestrates devices and records metadata
- it does not appear to contain the core image analysis logic
- camera settings are externalized into JSON for reproducibility and operator tuning

##### C. Configuration loader (`src/config_loader.py`)
This is the shared configuration boundary for the runtime system.

###### Responsibilities
- Load path and environment settings from YAML
- Fall back to example/default configuration when needed
- Avoid hard-coded paths in analysis and GUI code

###### Why it matters architecturally
This module is the glue that lets imaging, GUI, and file-processing components share a consistent view of:
- input directories
- output roots
- experiment log locations
- camera/video paths

The repo is clearly designed around configurable local paths rather than an external database or service.

#### 3) Root-level scripts and entry points

There are root-level scripts that mirror or expose major workflows:

- `train_detectron2.py`
- `inference_detectron2.py`
- `setup_training_dataset.py`
- `evaluate_model.py`

These suggest top-level entry points for training and running model inference outside the `src/` package structure.

The presence of near-duplicate tooling under `AI/Training_Analysis/` indicates the repo contains both:
- current or consolidated entry points at the root
- older or more specialized analysis scripts under the AI workspace

From an architecture perspective, these are not separate runtime services; they are command-line utilities that sit beside the main package.

#### 4) AI / ML subsystem (`AI/`)

This is a distinct but related subsystem for model training, evaluation, inference, and synthetic data generation.

##### A. Training and inference tools (`AI/Training_Analysis/`)
Files include:
- `train_detectron2.py`
- `inference_detectron2.py`
- `evaluate_model.py`
- `setup_training_dataset.py`
- `plot_from_metrics.py`
- `visualize_coco_results.py`
- `visualize_model_predictions.py`
- `test_inference_debug.py`
- `verify_installation.py`
- `check_image_identity.py`

###### Responsibilities
- Prepare datasets
- Train a **Detectron2** model
- Run inference
- Evaluate model performance
- Visualize results and metrics
- Verify environment setup and debug inference issues

This area strongly implies a classical object-detection training workflow built around Detectron2 and COCO-style annotations.

###### Data flow
1. Raw or synthetic annotated images are assembled into a training dataset.
2. `setup_training_dataset.py` structures the data for training.
3. `train_detectron2.py` trains a model.
4. `evaluate_model.py` and visualization scripts analyze outputs and metrics.
5. `inference_detectron2.py` runs the trained model on new images.

##### B. Synthetic data generation (`AI/synthetic_data/`)
Files include:
- `spray_dataset_generator.py`
- `blur_spray_dataset_generator.py`
- `conjoined_blur_spray_dataset_generator.py`

Folders under `AI/synthetic_data/` contain timestamped dataset generations with:
- `annotations.json` or `blur_annotations.json`
- images
- visualizations

###### Responsibilities
- Generate synthetic spray / blur datasets
- Emit annotations alongside images
- Create visualizations for review

###### Architectural role
This is a data-production subsystem feeding the ML pipeline. It is separate from runtime experiment control and separate from the hand-built image-processing pipeline.

##### C. Validation data (`AI/Validation_100/`)
Contains:
- `blur_annotations.json`
- images
- `evaluation_results.xlsx`
- side-by-side comparisons
- visualizations

This looks like a curated validation set used to benchmark the model or detection approach.

##### D. AI workspace boundaries
The AI area is file-based, like the rest of the repository:
- datasets live on disk
- annotations are JSON
- evaluation outputs are images or spreadsheets
- no central model registry or cloud pipeline is visible

#### 5) Trials / prototyping area

The `Trials/` folder is a sandbox for experimental work and iterative development.

Contents include:
- `Cone_2.py`, `Cone_3.py`, `Cone_4.py`, `Cone_Tester.py`
- `cone_GUI.py`
- sample TIFFs and outputs
- debug directories and parameter CSVs

This suggests an experimental branch of the problem domain focused on cone/spray behavior and interactive tuning.

Architecturally, this folder should be viewed as:
- prototyping code
- manual experimentation
- non-production outputs

It is likely not part of the stable runtime path, but it informs the algorithms and GUI behavior.

#### 6) Shared data and artifacts

##### `data/sample_output/`
A placeholder for output examples and probably documentation-oriented artifacts.

##### `AI/synthetic_data/...`
Timestamped runs show the repo favors immutable experiment folders:
- each run gets its own namespace
- inputs, annotations, and visualizations stay together

##### `serial_log.txt`
A repository-root log of serial communication or device testing, reinforcing the hardware-control aspect.

#### 7) Important technical boundaries and dependencies

##### File-system centric architecture
The dominant boundary is the filesystem:
- inputs are image/video files
- outputs are analysis folders
- annotations are JSON
- metrics may be CSV/XLSX
- configuration is YAML/JSON

There is no evidence of a web backend, message broker, or database service in the core architecture.

##### Hardware integration boundaries
The system interacts with:
- **Arduino / Portenta firmware** compiled from C++
- **motor and pressure hardware**
- **Phantom camera SDK (`pyphantom`)**

These are optional or environment-dependent integrations, especially the camera SDK.

##### ML framework boundary
The AI layer depends on **Detectron2** and related computer vision tooling. This is a separate dependency stack from the GUI/hardware control path, even though both operate on the same general domain of spray/droplet imagery.

#### 8) How the pieces fit together

A practical end-to-end view:

1. **Experiment setup**
   - User launches the GUI.
   - GUI loads configuration and hardware settings.
   - GUI connects to serial devices and optionally the Phantom camera.

2. **Data acquisition**
   - Camera captures images or videos.
   - Frames may be converted from MP4 to TIFF.
   - Still images may be captured directly.

3. **Image analysis**
   - The imaging pipeline processes the captured files.
   - Detection/segmentation/optimization steps produce final analysis outputs and debug artifacts.

4. **ML workflow**
   - Synthetic or validation datasets are generated or curated.
   - Detectron2 training/inference scripts operate on those datasets.
   - Predictions and metrics are visualized and evaluated.

5. **Experiment record keeping**
   - Logs, outputs, and datasets are written into timestamped folders for traceability.

#### 9) Diagramming guidance

If you draw this repository as an architecture diagram, the clearest separation is:

- **Control plane**: GUI + serial/SDK hardware integrations
- **Analysis plane**: imaging pipeline and post-processing
- **ML pipeline**: synthetic data generation, training, inference, evaluation
- **Configuration layer**: YAML/JSON-based path and camera settings
- **Filesystem as the integration bus**: nearly all subsystems exchange data through files and folders

The repo is best understood as a local, operator-driven research toolchain rather than a client-server system.

Main entry points: [`src/imaging/save_and_analyse.py`](https://github.com/bcschofield/hpatr/blob/HEAD/src/imaging/save_and_analyse.py) (Analysis pipeline), [`src/gui/Windows_Experiment_GUI.py`](https://github.com/bcschofield/hpatr/blob/HEAD/src/gui/Windows_Experiment_GUI.py) (Experiment GUI), [`AI/Training_Analysis/train_detectron2.py`](https://github.com/bcschofield/hpatr/blob/HEAD/AI/Training_Analysis/train_detectron2.py) (Training tools), [`src/config_loader.py`](https://github.com/bcschofield/hpatr/blob/HEAD/src/config_loader.py) (Config loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Runtime package"
  n_config_loader["Config loader<br/>yaml path config<br/>[config_loader.py]"]
  n_process_run["Run processor<br/>ai run coordination<br/>[process_run.py]"]
  n_gui["Experiment GUI<br/>hardware control"]
  n_portenta{{"Portenta firmware<br/>embedded controller"}}
  n_camera_settings["Camera settings<br/>runtime config"]
  n_imaging_pipeline["Analysis pipeline<br/>image analysis"]
  n_expansion_detection["Expansion detect<br/>vision stage"]
  n_video_convert["Video convert<br/>frame extraction<br/>[mp4_to_tiff.py]"]
  n_capture_still["Still capture<br/>acquisition"]
  n_webcam_preview["Webcam preview<br/>preview utility<br/>[webcam_preview.py]"]
end

subgraph "AI workspace"
  n_train_root["Train model<br/>cli entrypoint"]
  n_infer_root["Run inference<br/>cli entrypoint"]
  n_dataset_root["Build dataset<br/>cli entrypoint"]
  n_eval_root["Evaluate model<br/>cli entrypoint<br/>[evaluate_model.py]"]
  n_ai_train["Training tools<br/>detectron2 workflow"]
  n_ai_synth["Synthetic data<br/>data generation"]
  n_ai_validation[("Validation set<br/>benchmark data")]
end

subgraph "Trials sandbox"
  n_trials["Cone trials<br/>prototype experiments<br/>[Cone_Tester.py]"]
  n_trials_gui["Trial GUI<br/>prototype gui<br/>[cone_GUI.py]"]
end

subgraph "Support assets"
  n_paths["Path config<br/>shared config<br/>[paths.yaml]"]
  n_paths_example["Example paths<br/>config template<br/>[paths_example.yaml]"]
  n_data[("Sample output<br/>shared data<br/>[.gitkeep]")]
  n_docs["Docs<br/>[CODE_SOP.md]"]
end

n_paths -->|"loads"| n_config_loader
n_paths_example -->|"template"| n_paths
n_config_loader -->|"configures"| n_gui
n_config_loader -->|"configures"| n_imaging_pipeline
n_config_loader -->|"configures"| n_process_run
n_gui -->|"controls"| n_portenta
n_gui -->|"uses"| n_camera_settings
n_gui -->|"launches"| n_capture_still
n_gui -->|"launches"| n_webcam_preview
n_capture_still -->|"feeds"| n_imaging_pipeline
n_video_convert -->|"feeds"| n_imaging_pipeline
n_expansion_detection -->|"part of"| n_imaging_pipeline
n_imaging_pipeline -->|"writes"| n_data
n_ai_synth -->|"feeds"| n_ai_train
n_ai_validation -->|"benchmarks"| n_ai_train
n_dataset_root -->|"prepares"| n_ai_train
n_train_root -->|"delegates"| n_ai_train
n_infer_root -->|"delegates"| n_ai_train
n_eval_root -->|"delegates"| n_ai_train
n_trials_gui -->|"orchestrates"| n_trials
n_trials -.->|"informs"| n_imaging_pipeline
n_docs -.->|"documents"| n_imaging_pipeline
n_docs -.->|"documents"| n_gui

click n_config_loader "https://github.com/bcschofield/hpatr/blob/Main/src/config_loader.py"
click n_process_run "https://github.com/bcschofield/hpatr/blob/Main/src/ai/process_run.py"
click n_gui "https://github.com/bcschofield/hpatr/blob/Main/src/gui/Windows_Experiment_GUI.py"
click n_portenta "https://github.com/bcschofield/hpatr/blob/Main/src/gui/Pressure_Motor_Portenta.cpp"
click n_camera_settings "https://github.com/bcschofield/hpatr/blob/Main/src/gui/camera_settings.json"
click n_imaging_pipeline "https://github.com/bcschofield/hpatr/blob/Main/src/imaging/save_and_analyse.py"
click n_expansion_detection "https://github.com/bcschofield/hpatr/blob/Main/src/imaging/expansion_detection.py"
click n_video_convert "https://github.com/bcschofield/hpatr/blob/Main/src/imaging/mp4_to_tiff.py"
click n_capture_still "https://github.com/bcschofield/hpatr/blob/Main/src/imaging/capture_still_image.py"
click n_webcam_preview "https://github.com/bcschofield/hpatr/blob/Main/src/imaging/webcam_preview.py"
click n_train_root "https://github.com/bcschofield/hpatr/blob/Main/train_detectron2.py"
click n_infer_root "https://github.com/bcschofield/hpatr/blob/Main/inference_detectron2.py"
click n_dataset_root "https://github.com/bcschofield/hpatr/blob/Main/setup_training_dataset.py"
click n_eval_root "https://github.com/bcschofield/hpatr/blob/Main/AI/evaluate_model.py"
click n_ai_train "https://github.com/bcschofield/hpatr/blob/Main/AI/Training_Analysis/train_detectron2.py"
click n_ai_synth "https://github.com/bcschofield/hpatr/blob/Main/AI/synthetic_data/spray_dataset_generator.py"
click n_ai_validation "https://github.com/bcschofield/hpatr/blob/Main/AI/Validation_100/blur_annotations.json"
click n_trials "https://github.com/bcschofield/hpatr/blob/Main/Trials/Cone_Tester.py"
click n_trials_gui "https://github.com/bcschofield/hpatr/blob/Main/Trials/cone_GUI.py"
click n_paths "https://github.com/bcschofield/hpatr/blob/Main/config/paths.yaml"
click n_paths_example "https://github.com/bcschofield/hpatr/blob/Main/config/paths_example.yaml"
click n_data "https://github.com/bcschofield/hpatr/blob/Main/data/sample_output/.gitkeep"
click n_docs "https://github.com/bcschofield/hpatr/blob/Main/docs/CODE_SOP.md"

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 n_config_loader,n_process_run,n_gui,n_portenta,n_camera_settings,n_imaging_pipeline,n_expansion_detection,n_video_convert,n_capture_still,n_webcam_preview toneBlue
class n_train_root,n_infer_root,n_dataset_root,n_eval_root,n_ai_train,n_ai_synth,n_ai_validation toneAmber
class n_trials,n_trials_gui toneMint
class n_paths,n_paths_example,n_data,n_docs toneRose
```

## Components

### Runtime package

Reusable application code under src/

- [Config loader](https://github.com/bcschofield/hpatr/blob/HEAD/src/config_loader.py): yaml path config · Loads shared paths and environment settings · `src/config_loader.py`
- [Run processor](https://github.com/bcschofield/hpatr/blob/HEAD/src/ai/process_run.py): ai run coordination · Coordinates AI-side run processing and workflow execution · `src/ai/process_run.py`
- [Experiment GUI](https://github.com/bcschofield/hpatr/blob/HEAD/src/gui/Windows_Experiment_GUI.py): hardware control · Operator GUI for experiment setup and device orchestration · `src/gui/Windows_Experiment_GUI.py`
- [Portenta firmware](https://github.com/bcschofield/hpatr/blob/HEAD/src/gui/Pressure_Motor_Portenta.cpp): embedded controller · Arduino Portenta motor and pressure control firmware · `src/gui/Pressure_Motor_Portenta.cpp`
- [Camera settings](https://github.com/bcschofield/hpatr/blob/HEAD/src/gui/camera_settings.json): runtime config · JSON camera and acquisition settings · `src/gui/camera_settings.json`
- [Analysis pipeline](https://github.com/bcschofield/hpatr/blob/HEAD/src/imaging/save_and_analyse.py): image analysis · Primary droplet and expansion analysis workflow · `src/imaging/save_and_analyse.py`
- [Expansion detect](https://github.com/bcschofield/hpatr/blob/HEAD/src/imaging/expansion_detection.py): vision stage · Detection logic for expansion and droplet structures · `src/imaging/expansion_detection.py`
- [Video convert](https://github.com/bcschofield/hpatr/blob/HEAD/src/imaging/mp4_to_tiff.py): frame extraction · Converts MP4 video into TIFF frames for analysis · `src/imaging/mp4_to_tiff.py`
- [Still capture](https://github.com/bcschofield/hpatr/blob/HEAD/src/imaging/capture_still_image.py): acquisition · Captures a single image from the camera source · `src/imaging/capture_still_image.py`
- [Webcam preview](https://github.com/bcschofield/hpatr/blob/HEAD/src/imaging/webcam_preview.py): preview utility · Live preview loop for camera framing and inspection · `src/imaging/webcam_preview.py`

### AI workspace

Training, inference, and synthetic data tooling

- [Train model](https://github.com/bcschofield/hpatr/blob/HEAD/train_detectron2.py): cli entrypoint · Root-level Detectron2 training launcher · `train_detectron2.py`
- [Run inference](https://github.com/bcschofield/hpatr/blob/HEAD/inference_detectron2.py): cli entrypoint · Root-level Detectron2 inference launcher · `inference_detectron2.py`
- [Build dataset](https://github.com/bcschofield/hpatr/blob/HEAD/setup_training_dataset.py): cli entrypoint · Root-level training dataset setup script · `setup_training_dataset.py`
- [Evaluate model](https://github.com/bcschofield/hpatr/blob/HEAD/AI/evaluate_model.py): cli entrypoint · Root-level model evaluation script · `AI/evaluate_model.py`
- [Training tools](https://github.com/bcschofield/hpatr/blob/HEAD/AI/Training_Analysis/train_detectron2.py): detectron2 workflow · AI training, inference, and visualization utilities · `AI/Training_Analysis/train_detectron2.py`
- [Synthetic data](https://github.com/bcschofield/hpatr/blob/HEAD/AI/synthetic_data/spray_dataset_generator.py): data generation · Generates spray and blur datasets with annotations · `AI/synthetic_data/spray_dataset_generator.py`
- [Validation set](https://github.com/bcschofield/hpatr/blob/HEAD/AI/Validation_100/blur_annotations.json): benchmark data · Curated validation images, annotations, and results · `AI/Validation_100/blur_annotations.json`

### Trials sandbox

Ad hoc prototyping and experiment outputs

- [Cone trials](https://github.com/bcschofield/hpatr/blob/HEAD/Trials/Cone_Tester.py): prototype experiments · Sandbox scripts for cone and spray experimentation · `Trials/Cone_Tester.py`
- [Trial GUI](https://github.com/bcschofield/hpatr/blob/HEAD/Trials/cone_GUI.py): prototype gui · Experimental GUI for cone and spray tuning · `Trials/cone_GUI.py`

### Support assets

Configuration, shared data, and docs

- [Path config](https://github.com/bcschofield/hpatr/blob/HEAD/config/paths.yaml): shared config · Repository-wide filesystem path definitions · `config/paths.yaml`
- [Example paths](https://github.com/bcschofield/hpatr/blob/HEAD/config/paths_example.yaml): config template · Example configuration used as fallback or template · `config/paths_example.yaml`
- [Sample output](https://github.com/bcschofield/hpatr/blob/HEAD/data/sample_output/.gitkeep): shared data · Example output artifacts and placeholder data · `data/sample_output/.gitkeep`
- [Docs](https://github.com/bcschofield/hpatr/blob/HEAD/docs/CODE_SOP.md): reference docs · Process and algorithm documentation · `docs/CODE_SOP.md`

## Connections

- Path config → Config loader: loads · Shared path configuration is read by runtime code
- Example paths → Path config: template · Example configuration supports local setup
- Config loader → Experiment GUI: configures · GUI uses shared paths and environment settings
- Config loader → Analysis pipeline: configures · Analysis outputs and inputs follow configured paths
- Config loader → Run processor: configures · AI-side orchestration uses shared filesystem locations
- Experiment GUI → Portenta firmware: controls · GUI sends commands to embedded motor and pressure firmware
- Experiment GUI → Camera settings: uses · Camera behavior is externalized in JSON
- Experiment GUI → Still capture: launches · GUI can trigger still image acquisition
- Experiment GUI → Webcam preview: launches · GUI can open live preview for framing
- Still capture → Analysis pipeline: feeds · Captured stills are analyzed downstream
- Video convert → Analysis pipeline: feeds · Converted frames become analysis input
- Expansion detect → Analysis pipeline: part of · Detection stage inside the main analysis pipeline
- Analysis pipeline → Sample output: writes · Analysis outputs are stored as traceable artifacts
- Synthetic data → Training tools: feeds · Synthetic annotated datasets support training
- Validation set → Training tools: benchmarks · Validation set supports evaluation and comparison
- Build dataset → Training tools: prepares · Training data is structured before model fitting
- Train model → Training tools: delegates · Root launcher mirrors the AI training workflow
- Run inference → Training tools: delegates · Root launcher mirrors the AI inference workflow
- Evaluate model → Training tools: delegates · Root launcher mirrors the AI evaluation workflow
- Trial GUI → Cone trials: orchestrates · Prototype GUI drives trial scripts and outputs
- Cone trials → Analysis pipeline: informs · Trial outputs and prototyping shape analysis work
- Docs → Analysis pipeline: documents · Documentation explains analysis and optimization behavior
- Docs → Experiment GUI: documents · Documentation also covers operator workflow and control flow
