How bcschofield/hpatr works
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: save_and_analyse.py Analysis pipeline · Windows_Experiment_GUI.py Experiment GUI · train_detectron2.py Training tools · config_loader.py Config loader
Components 23
Runtime package
Reusable application code under src/
- Config loader · Loads shared paths and environment settings
src/config_loader.py - Run processor · Coordinates AI-side run processing and workflow execution
src/ai/process_run.py - Experiment GUI · Operator GUI for experiment setup and device orchestration
src/gui/Windows_Experiment_GUI.py - Portenta firmware · Arduino Portenta motor and pressure control firmware
src/gui/Pressure_Motor_Portenta.cpp - Camera settings · JSON camera and acquisition settings
src/gui/camera_settings.json - Analysis pipeline · Primary droplet and expansion analysis workflow
src/imaging/save_and_analyse.py - Expansion detect · Detection logic for expansion and droplet structures
src/imaging/expansion_detection.py - Video convert · Converts MP4 video into TIFF frames for analysis
src/imaging/mp4_to_tiff.py - Still capture · Captures a single image from the camera source
src/imaging/capture_still_image.py - Webcam preview · Live preview loop for camera framing and inspection
src/imaging/webcam_preview.py
AI workspace
Training, inference, and synthetic data tooling
- Train model · Root-level Detectron2 training launcher
train_detectron2.py - Run inference · Root-level Detectron2 inference launcher
inference_detectron2.py - Build dataset · Root-level training dataset setup script
setup_training_dataset.py - Evaluate model · Root-level model evaluation script
AI/evaluate_model.py - Training tools · AI training, inference, and visualization utilities
AI/Training_Analysis/train_detectron2.py - Synthetic data · Generates spray and blur datasets with annotations
AI/synthetic_data/spray_dataset_generator.py - Validation set · Curated validation images, annotations, and results
AI/Validation_100/blur_annotations.json
Trials sandbox
Ad hoc prototyping and experiment outputs
- Cone trials · Sandbox scripts for cone and spray experimentation
Trials/Cone_Tester.py - Trial GUI · Experimental GUI for cone and spray tuning
Trials/cone_GUI.py
Support assets
Configuration, shared data, and docs
- Path config · Repository-wide filesystem path definitions
config/paths.yaml - Example paths · Example configuration used as fallback or template
config/paths_example.yaml - Sample output · Example output artifacts and placeholder data
data/sample_output/.gitkeep - Docs · Process and algorithm documentation
docs/CODE_SOP.md
Connections 23
- 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