# mintenecha/wildlife_monitor architecture

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

- Interactive diagram: https://gitdiagram.com/mintenecha/wildlife_monitor
- Repository: https://github.com/mintenecha/wildlife_monitor

## Overview

Wildlife Monitor processes camera-trap images for species recognition and animal localisation, saves detections and visual overlays, and presents them for review and comparison. Its three documented detection configurations preserve distinct recognition/localisation approaches; a separate behaviour-modeling branch uses MegaDetector count data to train sequence models. The dashboard also exposes upload, map, settings, and export workflows. Core pipeline internals and most dashboard views were not sampled, so those links reflect documented capabilities and visible routing rather than uninspected call details.

Main entry points: [`wildlife_monitor/pipelines`](https://github.com/mintenecha/wildlife_monitor/tree/main/wildlife_monitor/pipelines) (Pipeline Configurations), [`wildlife_monitor/pipeline2/train.py`](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/train.py) (Training Data Builder), [`wildlife_monitor/pipelines/compare.py`](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipelines/compare.py) (Pipeline Comparator), [`wildlife_monitor/dashboard/app.py`](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/dashboard/app.py) (Dashboard Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data and Configuration"]
  node_loader["Species Loader<br/>[loader.py]"]
  node_settings["Runtime Settings<br/>[settings.py]"]
end

subgraph group_detect["Detection Pipelines"]
  node_pipelines["Pipeline Configurations"]
  node_bioclip["BioCLIP Recognition<br/>[bioclip.py]"]
  node_sam1["SAM 1 Segmentation<br/>[sam1.py]"]
  node_sam3["SAM 3 Segmentation<br/>[sam3.py]"]
  node_yolo["YOLO Detection<br/>[yolo.py]"]
  node_megadetector["MegaDetector Counts<br/>[megadetector.py]"]
end

subgraph group_results["Results and Dashboard"]
  node_records["Detection Records<br/>[records.py]"]
  node_visuals["Overlay Rendering<br/>[visualisation.py]"]
  node_resultfiles["Detection CSVs and Overlays"]
  node_comparator["Pipeline Comparator<br/>[compare.py]"]
  node_dashboard["Dashboard Router<br/>[app.py]"]
  node_views["Dashboard Views"]
  node_dataaccess["Dashboard Data Access<br/>[data_access.py]"]
end

subgraph group_behaviour["Behaviour Modeling"]
  node_training["Training Data Builder<br/>[train.py]"]
  node_features["Sequence Features"]
  node_sequences["Sequence Builder"]
  node_behaviourmodel["Behaviour Models<br/>[models.py]"]
  node_trainer["Model Trainer<br/>[train.py]"]
end

node_operator(("Monitor User"))
node_cli["Pipeline Runner<br/>[run_pipeline.py]"]
node_dataset["Camera Trap Dataset"]
node_externalmodels["Model Checkpoints"]

node_operator -->|"selects run"| node_cli
node_cli -->|"dispatches pipeline"| node_pipelines
node_dataset -->|"provides metadata/images"| node_loader
node_pipelines -->|"loads species images"| node_loader
node_pipelines -->|"recognizes species"| node_bioclip
node_pipelines -->|"segments with SAM 1"| node_sam1
node_pipelines -->|"segments with SAM 3"| node_sam3
node_pipelines -->|"localizes animals"| node_yolo
node_pipelines -.->|"counts animals"| node_megadetector
node_externalmodels -.->|"supplies weights"| node_sam1
node_externalmodels -.->|"supplies gated weights"| node_sam3
node_pipelines -->|"produces detections"| node_records
node_pipelines -->|"renders overlays"| node_visuals
node_pipelines -->|"writes outputs"| node_resultfiles
node_operator -->|"requests comparison"| node_comparator
node_comparator -->|"runs each configuration"| node_pipelines
node_comparator -->|"reads and writes comparison"| node_resultfiles
node_operator -->|"uses dashboard"| node_dashboard
node_dashboard -->|"routes pages"| node_views
node_dashboard -->|"loads selector data"| node_dataaccess
node_views -->|"requests detection data"| node_dataaccess
node_dataaccess -->|"reads results"| node_resultfiles
node_resultfiles -->|"provides count detections"| node_training
node_training -->|"extracts features"| node_features
node_training -->|"builds sequences"| node_sequences
node_training -->|"trains model"| node_behaviourmodel
node_training -->|"evaluates model"| node_trainer
node_settings -->|"configures runs"| node_pipelines

click node_cli "https://github.com/mintenecha/wildlife_monitor/blob/main/scripts/run_pipeline.py"
click node_loader "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/data/loader.py"
click node_settings "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/config/settings.py"
click node_pipelines "https://github.com/mintenecha/wildlife_monitor/tree/main/wildlife_monitor/pipelines"
click node_bioclip "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/bioclip.py"
click node_sam1 "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/sam1.py"
click node_sam3 "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/sam3.py"
click node_yolo "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/yolo.py"
click node_megadetector "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/megadetector.py"
click node_records "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/utils/records.py"
click node_visuals "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/utils/visualisation.py"
click node_comparator "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipelines/compare.py"
click node_dashboard "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/dashboard/app.py"
click node_views "https://github.com/mintenecha/wildlife_monitor/tree/main/wildlife_monitor/dashboard/views"
click node_dataaccess "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/dashboard/data_access.py"
click node_training "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/train.py"
click node_features "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/feature_extractor.py"
click node_sequences "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/sequence_builder.py"
click node_behaviourmodel "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/models.py"
click node_trainer "https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/train.py"

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 node_loader,node_settings,node_operator toneBlue
class node_pipelines,node_bioclip,node_sam1,node_sam3,node_yolo,node_megadetector toneAmber
class node_records,node_visuals,node_resultfiles,node_comparator,node_dashboard,node_views,node_dataaccess toneMint
class node_training,node_features,node_sequences,node_behaviourmodel,node_trainer toneRose
class node_cli toneTeal
class node_dataset,node_externalmodels toneIndigo
```

## Components

### Data and Configuration

- [Species Loader](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/data/loader.py): `wildlife_monitor/data/loader.py`
- [Runtime Settings](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/config/settings.py): `wildlife_monitor/config/settings.py`

### Detection Pipelines

- [Pipeline Configurations](https://github.com/mintenecha/wildlife_monitor/tree/main/wildlife_monitor/pipelines): `wildlife_monitor/pipelines`
- [BioCLIP Recognition](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/bioclip.py): `wildlife_monitor/models/bioclip.py`
- [SAM 1 Segmentation](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/sam1.py): `wildlife_monitor/models/sam1.py`
- [SAM 3 Segmentation](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/sam3.py): `wildlife_monitor/models/sam3.py`
- [YOLO Detection](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/yolo.py): `wildlife_monitor/models/yolo.py`
- [MegaDetector Counts](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/models/megadetector.py): `wildlife_monitor/models/megadetector.py`

### Results and Dashboard

- [Detection Records](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/utils/records.py): `wildlife_monitor/utils/records.py`
- [Overlay Rendering](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/utils/visualisation.py): `wildlife_monitor/utils/visualisation.py`
- **Detection CSVs and Overlays**
- [Pipeline Comparator](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipelines/compare.py): `wildlife_monitor/pipelines/compare.py`
- [Dashboard Router](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/dashboard/app.py): `wildlife_monitor/dashboard/app.py`
- [Dashboard Views](https://github.com/mintenecha/wildlife_monitor/tree/main/wildlife_monitor/dashboard/views): `wildlife_monitor/dashboard/views`
- [Dashboard Data Access](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/dashboard/data_access.py): `wildlife_monitor/dashboard/data_access.py`

### Behaviour Modeling

- [Training Data Builder](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/train.py): `wildlife_monitor/pipeline2/train.py`
- [Sequence Features](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/feature_extractor.py): `wildlife_monitor/pipeline2/feature_extractor.py`
- [Sequence Builder](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/sequence_builder.py): `wildlife_monitor/pipeline2/sequence_builder.py`
- [Behaviour Models](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/models.py): `wildlife_monitor/pipeline2/models.py`
- [Model Trainer](https://github.com/mintenecha/wildlife_monitor/blob/main/wildlife_monitor/pipeline2/train.py): `wildlife_monitor/pipeline2/train.py`

### Other components

- **Monitor User**
- [Pipeline Runner](https://github.com/mintenecha/wildlife_monitor/blob/main/scripts/run_pipeline.py): `scripts/run_pipeline.py`
- **Camera Trap Dataset**
- **Model Checkpoints**

## Connections

- Monitor User → Pipeline Runner: selects run
- Pipeline Runner → Pipeline Configurations: dispatches pipeline
- Camera Trap Dataset → Species Loader: provides metadata/images
- Pipeline Configurations → Species Loader: loads species images
- Pipeline Configurations → BioCLIP Recognition: recognizes species
- Pipeline Configurations → SAM 1 Segmentation: segments with SAM 1
- Pipeline Configurations → SAM 3 Segmentation: segments with SAM 3
- Pipeline Configurations → YOLO Detection: localizes animals
- Pipeline Configurations → MegaDetector Counts: counts animals
- Model Checkpoints → SAM 1 Segmentation: supplies weights
- Model Checkpoints → SAM 3 Segmentation: supplies gated weights
- Pipeline Configurations → Detection Records: produces detections
- Pipeline Configurations → Overlay Rendering: renders overlays
- Pipeline Configurations → Detection CSVs and Overlays: writes outputs
- Monitor User → Pipeline Comparator: requests comparison
- Pipeline Comparator → Pipeline Configurations: runs each configuration
- Pipeline Comparator → Detection CSVs and Overlays: reads and writes comparison
- Monitor User → Dashboard Router: uses dashboard
- Dashboard Router → Dashboard Views: routes pages
- Dashboard Router → Dashboard Data Access: loads selector data
- Dashboard Views → Dashboard Data Access: requests detection data
- Dashboard Data Access → Detection CSVs and Overlays: reads results
- Detection CSVs and Overlays → Training Data Builder: provides count detections
- Training Data Builder → Sequence Features: extracts features
- Training Data Builder → Sequence Builder: builds sequences
- Training Data Builder → Behaviour Models: trains model
- Training Data Builder → Model Trainer: evaluates model
- Runtime Settings → Pipeline Configurations: configures runs