# oceam/deepsorghumhead architecture

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

- Interactive diagram: https://gitdiagram.com/oceam/deepsorghumhead
- Repository: https://github.com/oceam/deepsorghumhead

## Overview

##### Project Type & Purpose
- This is an open-source deep‐learning tool (built on top of Keras and the “keras-retinanet” base) for sorghum head detection and counting.
- It provides training, inference conversion, evaluation and debugging pipelines, plus support for multiple backends (TensorFlow, Theano, CNTK).

##### High-Level Architectural Components
a. Data Ingestion & Storage
- CSV Annotation Files (e.g., annotations_map.csv, train/test CSVs)
- Image Dataset (downloaded separately via provided form)
b. Preprocessing Layer
- DeepSorghumHead_Keras/preprocessing (Generator, CSVGenerator)
- Tools: resize_img.py, csv_generator logic
c. Model Definition & Backends
- Models (ResNet, VGG, MobileNet, DenseNet, RetinaNet) under DeepSorghumHead_Keras/models
- Custom Layers & Losses under DeepSorghumHead_Keras/layers & losses.py
- Initializers & Callbacks (common operations, evaluation callbacks)
- Backend abstraction in DeepSorghumHead_Keras/backend (tensorflow_backend, theano_backend, cntk_backend)
d. Training Pipeline
- Entry script: train.py / train_SorghumHead.py
- Training loop invoking data generators → model → loss → callbacks → snapshot saving
e. Inference Conversion
- Script: convert_model.py transforms training‐time model to inference model (merges anchors, detection logic)
- Output: “inference model” weights in bin/inf_models/
f. Evaluation & Debugging
- evaluate.py: loads inference model + test data → runs detections → writes result files
- debug.py: visualizes annotations vs. anchor availability
g. Utilities & Visualization
- DeepSorghumHead_Keras/utils (anchors, image ops, visualization)
- FM_Vis.py: feature map visualization

##### Relationships & Data Flow
- Data Ingestion → Preprocessing → Model Building → Training Loop → Checkpointed Models
- Checkpointed Models → convert_model.py → Inference Model
- Inference Model + Test Data → evaluate.py → Quantitative Results
- Data + Inference Model → debug.py / FM_Vis.py → Visual Diagnostics

##### Key Architectural Patterns & Principles
- Modular layering: clear separation of data generators, model definition, training logic, callbacks, backend abstraction.
- Strategy pattern for backends: interchangeable TensorFlow/Theano/CNTK implementations.
- Pipeline scripts orchestrate workflows without embedding core logic.
- Reuse of base keras-retinanet patterns: anchor generation, filter_detections, CSVGenerator.

##### Elements
- From data → preprocessing → training
- From training → model conversion
- From inference model → evaluation/debug
- External service blocks: GPU/CUDA, TensorBoard logs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        A1["annotations_map.csv"]:::data
        click A1 "https://github.com/oceam/deepsorghumhead/blob/master/annotations_map.csv"
        A2["Image Dataset"]:::data
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        P1["generator.py"]:::modules
        click P1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/preprocessing/generator.py"
        P2["csv_generator.py"]:::modules
        click P2 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/preprocessing/csv_generator.py"
        P3["resize_img.py"]:::scripts
        click P3 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/bin/resize_img.py"
    end

    %% Model Definition & Custom Layers
    subgraph "Model Definition & Custom Layers"
        M1["retinanet.py"]:::modules
        click M1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/models/retinanet.py"
        M2["resnet.py"]:::modules
        click M2 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/models/resnet.py"
        M3["vgg.py"]:::modules
        click M3 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/models/vgg.py"
        M4["mobilenet.py"]:::modules
        click M4 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/models/mobilenet.py"
        M5["densenet.py"]:::modules
        click M5 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/models/densenet.py"
        L1["losses.py"]:::modules
        click L1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/losses.py"
        L2["_misc.py"]:::modules
        click L2 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/layers/_misc.py"
        L3["filter_detections.py"]:::modules
        click L3 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/layers/filter_detections.py"
        I1["initializers.py"]:::modules
        click I1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/initializers.py"
    end

    %% Backend Abstraction
    subgraph "Backend Abstraction"
        B1["tensorflow_backend.py"]:::modules
        click B1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/backend/tensorflow_backend.py"
        B2["theano_backend.py"]:::modules
        click B2 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/backend/theano_backend.py"
        B3["cntk_backend.py"]:::modules
        click B3 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/backend/cntk_backend.py"
        B4["common.py"]:::modules
        click B4 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/backend/common.py"
        B5["dynamic.py"]:::modules
        click B5 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/backend/dynamic.py"
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        T1["train.py"]:::scripts
        click T1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/bin/train.py"
        T2["train_SorghumHead.py"]:::scripts
        click T2 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/bin/train_SorghumHead.py"
        T3["test_custom_model.py"]:::scripts
        click T3 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/bin/test_custom_model.py"
        C1["callbacks/common.py"]:::modules
        click C1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/callbacks/common.py"
        C2["callbacks/eval.py"]:::modules
        click C2 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/callbacks/eval.py"
    end

    %% Checkpoint Store
    CS[(Checkpoint Store)]:::store

    %% Model Converter
    MC["convert_model.py"]:::scripts
    click MC "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/bin/convert_model.py"

    %% Inference Model Store
    IS[(Inference Model Store)]:::store

    %% Evaluation & Debugging
    subgraph "Evaluation & Debugging"
        E1["evaluate.py"]:::scripts
        click E1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/bin/evaluate.py"
        E2["debug.py"]:::scripts
        click E2 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/bin/debug.py"
        E3["FM_Vis.py"]:::scripts
        click E3 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/bin/FM_Vis.py"
    end

    %% Utilities & Visualization
    subgraph "Utilities & Visualization"
        U1["anchors.py"]:::modules
        click U1 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/anchors.py"
        U2["image.py"]:::modules
        click U2 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/image.py"
        U3["model.py"]:::modules
        click U3 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/model.py"
        U4["eval.py"]:::modules
        click U4 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/eval.py"
        U5["eval_x.py"]:::modules
        click U5 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/eval_x.py"
        U6["visualization.py"]:::modules
        click U6 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/visualization.py"
        U7["colors.py"]:::modules
        click U7 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/colors.py"
        U8["keras_version.py"]:::modules
        click U8 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/keras_version.py"
        U9["transform.py"]:::modules
        click U9 "https://github.com/oceam/deepsorghumhead/blob/master/DeepSorghumHead_Keras/utils/transform.py"
    end

    %% Data Flow
    A1 -->|"CSV → generator"| P2
    A2 -->|"Images → generator"| P1
    P1 -->|"batches → model builder"| M1
    P2 -->|"batches → model builder"| M1
    P3 -->|"resized images"| P1

    M1 & M2 & M3 & M4 & M5 & L1 & L2 & L3 & I1 -->|"model definitions"| B1
    B1 & B2 & B3 & B4 & B5 -->|"backend API"| T1
    T1 & T2 -->|"training loop"| CS
    C1 & C2 -->|"callbacks"| T1

    CS -->|"HDF5 weights"| MC
    MC -->|"converted model"| IS

    IS -->|"inference model + data"| E1
    E1 -->|"results"| U4
    IS -->|"inference model + data"| E2
    E2 -->|"debug visuals"| U6
    IS -->|"inference model + data"| E3
    E3 -->|"feature maps"| U6

    %% Styles
    classDef scripts fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef modules fill:#d4edda,stroke:#333,stroke-width:1px
    classDef data fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef store fill:#f0f0f0,stroke:#333,stroke-width:1px
```
