# jordan-pierce/coralnet-toolbox architecture

> Architecture diagram of the GitHub repository jordan-pierce/coralnet-toolbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jordan-pierce/coralnet-toolbox
- Repository: https://github.com/jordan-pierce/coralnet-toolbox

## Overview

##### Project type and purpose
- This is a full-stack, desktop-based annotation and ML toolkit built in Python using PyQt for the GUI.
- Purpose: Provide an end-to-end pipeline for coral reef image/video annotation and analysis, integrating manual tools, AI-assisted models (SAM, YOLO family, AutoDistill, etc.), dataset management, model training, inference, and export to multiple formats (CoralNet, Viscore, GeoJSON, TagLab).

##### File structure
- Top-level entry point: `coralnet_toolbox/main.py`
- GUI layer: Qt windows, widgets, and tools under `coralnet_toolbox/` (e.g., `QtMainWindow.py`, `QtImageWindow.py`, `Annotations/…`, `Tools/…`, `Explorer/…`)
- IO layer: Import/export handlers under `IO/` (`QtImport*.py`, `QtExport*.py`, Open/Save project)
- Core utilities: `Common/`, `utilities.py`
- Raster management: `Rasters/`
- Machine-Learning modules: grouped under `MachineLearning/` with subpackages for BatchInference, TrainModel, EvaluateModel, DeployModel, AutoDistill, SAM, SeeAnything, Tile, etc.
- Results processing: `Results/`
- Scripts, notebooks, docs and CI pipelines are auxiliary and support development/testing.

##### README
- Confirms architecture: “From data collection to deployment,” lists stages: Data Input → Annotation & Labeling → Machine Learning → Analysis & Export
- Enumerates core components: Manual tools, AI models (SAM, YOLO, OWLViT…), dataset & project management, training/tuning, batch/video inference, export.

##### Elements
- Rectangles for components

##### Final advice
- Shared utilities (Common, RasterManager) as a central library used by both GUI and ML.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    subgraph "Entry Point"
        main["main.py"]:::entry
    end

    %% GUI Layer
    subgraph "GUI Layer" 
        QtMain["QtMainWindow"]:::frontend
        QtImage["QtImageWindow"]:::frontend
        Annotations["Annotations"]:::frontend
        Tools["Tools"]:::frontend
        Explorer["Explorer"]:::frontend
    end

    %% Application Logic & Core Utilities
    subgraph "Application Logic & Core Utilities"
        GraphicsUtil["QtGraphicsUtility"]:::logic
        UpdatePaths["QtUpdateImagePaths"]:::logic
        Utilities["utilities.py"]:::logic

        subgraph "Raster Management"
            RasterMgr["RasterManager"]:::logic
            QtRaster["QtRaster"]:::logic
            ImageFilter["ImageFilter"]:::logic
        end

        subgraph "Results Processing"
            ResultsProc["ResultsProcessor"]:::logic
            CombineRes["CombineResults"]:::logic
            ConvertRes["ConvertResults"]:::logic
        end
    end

    %% ML Engine
    subgraph "ML Engine"
        subgraph "Batch Inference"
            BI_Base["QtBase"]:::ml
            BI_Detect["QtDetect"]:::ml
            BI_Segment["QtSegment"]:::ml
        end
        subgraph "TrainModel"
            TM_Base["QtBase"]:::ml
            TM_Classify["QtClassify"]:::ml
            TM_Detect["QtDetect"]:::ml
        end
        subgraph "EvaluateModel"
            EM_Base["QtBase"]:::ml
            EM_Detect["QtDetect"]:::ml
        end
        subgraph "DeployModel"
            DM_Base["QtBase"]:::ml
            DM_Segment["QtSegment"]:::ml
        end
        subgraph "AutoDistill"
            AD_Base["QtBase"]:::ml
            AD_GDINO["GroundingDINO"]:::ml
            AD_Batch["QtBatchInference"]:::ml
        end
        subgraph "SAM Integration"
            SAM_Batch["QtBatchInference"]:::ml
            SAM_Deploy["QtDeployPredictor"]:::ml
        end
        subgraph "SeeAnything"
            SA_Train["QtTrainModel"]:::ml
            SA_Deploy["QtDeployGenerator"]:::ml
        end
        subgraph "Tiling Utilities"
            Tile_Create["QtTileCreation"]:::ml
            Tile_Classify["QtClassify"]:::ml
        end
        subgraph "Video Inference"
            Vid_Widget["QtVideoWidget"]:::ml
            Vid_Infer["QtInference"]:::ml
        end
    end

    %% IO Layer
    subgraph "IO Layer"
        OpenProj["QtOpenProject"]:::data
        SaveProj["QtSaveProject"]:::data
        ImportImg["QtImportImages"]:::data
        ExportCN["QtExportCoralNetAnnotations"]:::data
        ExportVS["QtExportViscoreAnnotations"]:::data
    end

    %% External Services
    subgraph "External Services"
        CN_Auth["QtAuthenticate"]:::external
        CN_Download["QtDownload"]:::external
        ModelRepo["Model Repos"]:::external
        ExtExport["Export Targets"]:::external
    end

    %% Connections
    main --> QtMain
    QtMain --> GraphicsUtil
    QtMain --> UpdatePaths
    QtMain --> Utilities
    QtImage --> RasterMgr
    QtImage --> ImageFilter
    Tools --> RasterMgr
    Annotations --> ResultsProc
    ResultsProc --> CombineRes
    ResultsProc --> ConvertRes

    GraphicsUtil --> BI_Base
    Utilities --> TM_Base
    RasterMgr --> EM_Base
    CombineRes --> DM_Base

    BI_Base --> OpenProj
    BI_Base --> ImportImg
    TM_Base --> SaveProj
    EM_Base --> ImportImg
    DM_Base --> SaveProj

    AD_Batch --> BI_Base
    SAM_Batch --> BI_Base
    SA_Train --> TM_Base
    Tile_Create --> BI_Base
    Vid_Infer --> BI_Base

    OpenProj --> CN_Auth
    CN_Auth --> CN_Download
    ExportCN --> CN_Auth
    ExportVS --> ExtExport

    %% Click Events
    click QtMain "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/QtMainWindow.py"
    click QtImage "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/QtImageWindow.py"
    click Annotations "https://github.com/jordan-pierce/coralnet-toolbox/tree/main/coralnet_toolbox/Annotations/"
    click Tools "https://github.com/jordan-pierce/coralnet-toolbox/tree/main/coralnet_toolbox/Tools/"
    click Explorer "https://github.com/jordan-pierce/coralnet-toolbox/tree/main/coralnet_toolbox/Explorer/"
    click GraphicsUtil "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Common/QtGraphicsUtility.py"
    click UpdatePaths "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Common/QtUpdateImagePaths.py"
    click Utilities "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/utilities.py"
    click RasterMgr "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Rasters/RasterManager.py"
    click QtRaster "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Rasters/QtRaster.py"
    click ImageFilter "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Rasters/ImageFilter.py"
    click ResultsProc "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Results/ResultsProcessor.py"
    click CombineRes "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Results/CombineResults.py"
    click ConvertRes "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Results/ConvertResults.py"
    click OpenProj "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/IO/QtOpenProject.py"
    click SaveProj "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/IO/QtSaveProject.py"
    click ImportImg "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/IO/QtImportImages.py"
    click ExportCN "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/IO/QtExportCoralNetAnnotations.py"
    click ExportVS "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/IO/QtExportViscoreAnnotations.py"
    click BI_Base "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/BatchInference/QtBase.py"
    click BI_Detect "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/BatchInference/QtDetect.py"
    click BI_Segment "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/BatchInference/QtSegment.py"
    click TM_Base "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/TrainModel/QtBase.py"
    click TM_Classify "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/TrainModel/QtClassify.py"
    click TM_Detect "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/TrainModel/QtDetect.py"
    click EM_Base "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/EvaluateModel/QtBase.py"
    click EM_Detect "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/EvaluateModel/QtDetect.py"
    click DM_Base "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/DeployModel/QtBase.py"
    click DM_Segment "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/DeployModel/QtSegment.py"
    click AD_Base "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/AutoDistill/Models/QtBase.py"
    click AD_GDINO "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/AutoDistill/Models/GroundingDINO.py"
    click AD_Batch "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/AutoDistill/QtBatchInference.py"
    click SAM_Batch "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/SAM/QtBatchInference.py"
    click SAM_Deploy "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/SAM/QtDeployPredictor.py"
    click SA_Train "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/SeeAnything/QtTrainModel.py"
    click SA_Deploy "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/SeeAnything/QtDeployGenerator.py"
    click Tile_Create "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Tile/QtTileCreation.py"
    click Tile_Classify "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/Tile/TileDataset/QtClassify.py"
    click Vid_Widget "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/VideoInference/QtVideoWidget.py"
    click Vid_Infer "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/MachineLearning/VideoInference/QtInference.py"
    click CN_Auth "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/CoralNet/QtAuthenticate.py"
    click CN_Download "https://github.com/jordan-pierce/coralnet-toolbox/blob/main/coralnet_toolbox/CoralNet/QtDownload.py"

    %% Styles
    classDef entry fill:#D3C0EB,stroke:#6B46C1,color:#000;
    classDef frontend fill:#BEE3F8,stroke:#3182CE,color:#000;
    classDef logic fill:#C6F6D5,stroke:#2F855A,color:#000;
    classDef ml fill:#F0FFF4,stroke:#38A169,color:#000;
    classDef data fill:#FEFCBF,stroke:#D69E2E,color:#000;
    classDef external fill:#FED7D7,stroke:#C53030,color:#000;
```
