# weecology/deepforest architecture

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

- Interactive diagram: https://gitdiagram.com/weecology/deepforest
- Repository: https://github.com/weecology/deepforest

## Overview

##### Project type and purpose
- DeepForest is an open-source Python package (library/CLI tool) for object-detection in aerial imagery, built on PyTorch/torchvision. Its core functionality is training and running tree-crown and bird detection models on RGB images, plus evaluation and visualization tools.

##### File structure
- Top-level:
- src/deepforest/… – core library code (data handling, models, training, prediction, evaluation, visualization, CLI).
- src/deepforest/models/… – model definitions (FasterRCNN, RetinaNet).
- src/deepforest/datasets/… – dataset builders for training and prediction.
- scripts/cli.py & main.py – command-line interface entrypoints.
- conf/config.yaml – default configuration.
- download.py – fetching pretrained weights.
- tests/… – unit tests for each component.
- docs/, README.md, CI workflows – documentation & deployment assets.

##### README
- Confirms: DeepForest uses torchvision object-detection modules.
- Key features: model loading, custom training, prediction, evaluation, visualization.
- Dependencies: Python ≥3.8, PyTorch, torchvision.

##### Detail
- Config file feeding into both data and model modules.
- Cache/download service for pretrained weights.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        CLI["CLI"]:::frontend
        API["Python API"]:::frontend
    end

    %% Configuration
    CONFIG["Configuration\n(config.yaml + CLI args)"]:::config

    %% Data Layer
    subgraph "Data Layer"
        Preproc["Preprocessing"]:::data
        TrainDS["Training Dataset"]:::data
        PredDS["Prediction Dataset"]:::data
        CropDS["Crop-Model Dataset"]:::data
        Utils["Utilities"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        FRCNN["Faster R-CNN"]:::model
        Retina["RetinaNet"]:::model
        Wrapper["Model Wrapper"]:::model
        TV["TorchVision Detectors"]:::external
    end

    %% Training & Evaluation
    subgraph "Training & Evaluation"
        Main["Training Pipeline"]:::training
        Callbacks["Callbacks"]:::training
        Eval["Evaluation Module"]:::training
        IoU["IoU Calculations"]:::training
    end

    %% Prediction & Visualization
    subgraph "Prediction & Visualization"
        Predict["Prediction Module"]:::prediction
        Visual["Visualization Module"]:::prediction
    end

    %% Persistence & Outputs
    subgraph "Persistence & Outputs"
        Download["Download Service"]:::storage
        Weights["Pretrained Weights (Cache)"]:::storage
        Outputs["Output Files (CSV/GeoJSON)"]:::storage
        Plots["Plots/Images"]:::storage
    end

    %% External Dependencies
    subgraph "External Dependencies"
        PyTorch["PyTorch & TorchVision"]:::external
        GeoIO["GDAL / Rasterio"]:::external
        YAML["PyYAML"]:::external
    end

    %% Relationships
    CLI -->|runs| CONFIG
    API -->|imports| CONFIG

    CONFIG -->|configures| Preproc
    CONFIG -->|configures| Wrapper

    Preproc -->|prepares| TrainDS
    Preproc -->|prepares| PredDS
    Preproc -->|prepares| CropDS
    Utils -->|supports| Preproc

    TrainDS -->|batches| Main
    Wrapper -->|model| Main
    Callbacks -->|hooks| Main

    Main -->|saves| Weights
    Download -->|fetches| Weights

    Main -->|evaluates| Eval
    Eval -->|uses| IoU
    Eval -->|outputs metrics| Outputs

    Weights -->|loaded by| Predict
    PredDS -->|provides data| Predict
    Predict -->|results| Outputs
    Predict -->|passes to| Visual
    Visual -->|generates| Plots

    Wrapper -->|uses| TV

    Preproc -->|uses| GeoIO
    Predict -->|uses| GeoIO

    CONFIG -->|uses| YAML

    Main -->|uses| PyTorch
    Wrapper -->|uses| PyTorch
    Predict -->|uses| PyTorch

    %% Click Events
    click CLI "https://github.com/weecology/deepforest/blob/main/src/deepforest/scripts/cli.py"
    click API "https://github.com/weecology/deepforest/blob/main/src/deepforest/__init__.py"
    click CONFIG "https://github.com/weecology/deepforest/blob/main/src/deepforest/conf/config.yaml"
    click Preproc "https://github.com/weecology/deepforest/blob/main/src/deepforest/preprocess.py"
    click Utils "https://github.com/weecology/deepforest/blob/main/src/deepforest/utilities.py"
    click TrainDS "https://github.com/weecology/deepforest/blob/main/src/deepforest/datasets/training.py"
    click PredDS "https://github.com/weecology/deepforest/blob/main/src/deepforest/datasets/prediction.py"
    click CropDS "https://github.com/weecology/deepforest/blob/main/src/deepforest/datasets/cropmodel.py"
    click FRCNN "https://github.com/weecology/deepforest/blob/main/src/deepforest/models/FasterRCNN.py"
    click Retina "https://github.com/weecology/deepforest/blob/main/src/deepforest/models/retinanet.py"
    click Wrapper "https://github.com/weecology/deepforest/blob/main/src/deepforest/model.py"
    click Main "https://github.com/weecology/deepforest/blob/main/src/deepforest/main.py"
    click Callbacks "https://github.com/weecology/deepforest/blob/main/src/deepforest/callbacks.py"
    click Eval "https://github.com/weecology/deepforest/blob/main/src/deepforest/evaluate.py"
    click IoU "https://github.com/weecology/deepforest/blob/main/src/deepforest/IoU.py"
    click Predict "https://github.com/weecology/deepforest/blob/main/src/deepforest/predict.py"
    click Visual "https://github.com/weecology/deepforest/blob/main/src/deepforest/visualize.py"
    click Download "https://github.com/weecology/deepforest/blob/main/src/deepforest/download.py"

    %% Styles
    classDef frontend fill:#aecbfa,stroke:#0366d6,stroke-width:1px
    classDef config fill:#e8f0fe,stroke:#8ab4f8,stroke-width:1px
    classDef data fill:#ccffcc,stroke:#33aa33,stroke-width:1px
    classDef model fill:#ffdab9,stroke:#ff8c00,stroke-width:1px
    classDef training fill:#ffebcd,stroke:#ff7700,stroke-width:1px
    classDef prediction fill:#ffe4b5,stroke:#ffaa00,stroke-width:1px
    classDef storage fill:#d3d3d3,stroke:#999,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#666,stroke-width:1px
```
