# dirac-institute/asteroid_detection_cnn architecture

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

- Interactive diagram: https://gitdiagram.com/dirac-institute/asteroid_detection_cnn
- Repository: https://github.com/dirac-institute/asteroid_detection_cnn

## Overview

ADCNN detects faint asteroid trails by creating labeled image data, training a tiled-image segmentation model, and evaluating predictions at pixel and object levels. Its documented capabilities also include Rubin Butler-compatible data processing and post-processing detections. The graph shows supported calls and documented workflow links; some subsystem implementations were not sampled, so their internal connections are left unspecified.

Main entry points: [`ADCNN/main.py`](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/main.py) (Training workflow), [`ADCNN/train.py`](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/train.py) (Training engine), [`ADCNN/data/dataset_creation`](https://github.com/dirac-institute/asteroid_detection_cnn/tree/master/ADCNN/data/dataset_creation) (Dataset generation), [`ADCNN/evaluation/threshold_scan.py`](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/threshold_scan.py) (Threshold analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_dataset_creation["Dataset generation"]
  node_inject["Trail injection<br/>[simulate_inject.py]"]
  node_inject_deterministic["Deterministic injection"]
  node_rubin_tasks["Rubin processing<br/>[pipetasks.py]"]
  node_h5_dataset[("HDF5 tiled data<br/>[datasets.py]")]
end

subgraph group_learning["Model and training"]
  node_config["Run configuration<br/>[config.py]"]
  node_model["Segmentation network<br/>[model.py]"]
  node_losses["Training losses<br/>[losses.py]"]
  node_training["Training engine<br/>[train.py]"]
  node_ema["EMA weights<br/>[ema.py]"]
  node_distributed["Distributed runtime<br/>[dist_utils.py]"]
  node_main["Training workflow<br/>[main.py]"]
end

subgraph group_inference["Inference and detection"]
  node_predict["Prediction<br/>[predict.py]"]
  node_postprocess["Prediction postprocess<br/>[postprocess.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_geometry["Trail geometry<br/>[geometry.py]"]
  node_detection["Object detection scoring<br/>[detection.py]"]
  node_metrics["Pixel metrics<br/>[metrics.py]"]
  node_threshold["Threshold analysis<br/>[threshold_scan.py]"]
end

node_researcher(("Researcher"))
node_butler[("Rubin Butler")]

node_researcher -->|"configures run"| node_main
node_researcher -->|"creates data"| node_dataset_creation
node_butler -->|"provides products"| node_rubin_tasks
node_dataset_creation -->|"writes labeled data"| node_h5_dataset
node_inject -->|"uses shared helpers"| node_dataset_creation
node_inject_deterministic -->|"uses shared helpers"| node_dataset_creation
node_main -->|"uses settings"| node_config
node_main -->|"loads tiles"| node_h5_dataset
node_main -->|"constructs model"| node_model
node_main -->|"starts training"| node_training
node_training -->|"tracks weights"| node_ema
node_training -->|"validates model"| node_metrics
node_training -->|"coordinates workers"| node_distributed
node_predict -->|"runs model"| node_model
node_postprocess -->|"uses component geometry"| node_geometry
node_detection -->|"labels components"| node_geometry
node_detection -.->|"reports metrics"| node_metrics
node_threshold -->|"scans thresholds"| node_metrics
node_threshold -->|"uses geometry"| node_geometry
node_predict -.->|"postprocesses predictions"| node_postprocess
node_researcher -->|"analyzes detections"| node_threshold

click node_dataset_creation "https://github.com/dirac-institute/asteroid_detection_cnn/tree/master/ADCNN/data/dataset_creation"
click node_inject "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/data/dataset_creation/simulate_inject.py"
click node_inject_deterministic "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/data/dataset_creation/simulate_inject_fill_deterministic.py"
click node_rubin_tasks "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/data/dataset_creation/pipetasks.py"
click node_h5_dataset "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/data/datasets.py"
click node_config "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/core/config.py"
click node_model "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/core/model.py"
click node_losses "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/core/losses.py"
click node_training "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/train.py"
click node_ema "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/training/ema.py"
click node_distributed "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/utils/dist_utils.py"
click node_main "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/main.py"
click node_predict "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/inference/predict.py"
click node_postprocess "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/inference/postprocess.py"
click node_geometry "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/geometry.py"
click node_detection "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/detection.py"
click node_metrics "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/metrics.py"
click node_threshold "https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/threshold_scan.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_dataset_creation,node_inject,node_inject_deterministic,node_rubin_tasks,node_h5_dataset toneBlue
class node_config,node_model,node_losses,node_training,node_ema,node_distributed,node_main,node_butler toneAmber
class node_predict,node_postprocess toneMint
class node_geometry,node_detection,node_metrics,node_threshold toneRose
class node_researcher toneIndigo
```

## Components

### Data preparation

- [Dataset generation](https://github.com/dirac-institute/asteroid_detection_cnn/tree/master/ADCNN/data/dataset_creation): `ADCNN/data/dataset_creation`
- [Trail injection](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/data/dataset_creation/simulate_inject.py): `ADCNN/data/dataset_creation/simulate_inject.py`
- [Deterministic injection](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/data/dataset_creation/simulate_inject_fill_deterministic.py): `ADCNN/data/dataset_creation/simulate_inject_fill_deterministic.py`
- [Rubin processing](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/data/dataset_creation/pipetasks.py): `ADCNN/data/dataset_creation/pipetasks.py`
- [HDF5 tiled data](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/data/datasets.py): `ADCNN/data/datasets.py`

### Model and training

- [Run configuration](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/core/config.py): `ADCNN/core/config.py`
- [Segmentation network](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/core/model.py): `ADCNN/core/model.py`
- [Training losses](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/core/losses.py): `ADCNN/core/losses.py`
- [Training engine](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/train.py): `ADCNN/train.py`
- [EMA weights](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/training/ema.py): `ADCNN/training/ema.py`
- [Distributed runtime](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/utils/dist_utils.py): `ADCNN/utils/dist_utils.py`
- [Training workflow](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/main.py): `ADCNN/main.py`

### Inference and detection

- [Prediction](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/inference/predict.py): `ADCNN/inference/predict.py`
- [Prediction postprocess](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/inference/postprocess.py): `ADCNN/inference/postprocess.py`

### Evaluation

- [Trail geometry](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/geometry.py): `ADCNN/evaluation/geometry.py`
- [Object detection scoring](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/detection.py): `ADCNN/evaluation/detection.py`
- [Pixel metrics](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/metrics.py): `ADCNN/evaluation/metrics.py`
- [Threshold analysis](https://github.com/dirac-institute/asteroid_detection_cnn/blob/master/ADCNN/evaluation/threshold_scan.py): `ADCNN/evaluation/threshold_scan.py`

### Other components

- **Researcher**
- **Rubin Butler**

## Connections

- Researcher → Training workflow: configures run (evidence: `README.md`)
- Researcher → Dataset generation: creates data (evidence: `README.md`)
- Rubin Butler → Rubin processing: provides products (evidence: `ADCNN/data/dataset_creation/pipetasks.py`)
- Dataset generation → HDF5 tiled data: writes labeled data (evidence: `README.md`)
- Trail injection → Dataset generation: uses shared helpers (evidence: `ADCNN/data/dataset_creation/simulate_inject.py`)
- Deterministic injection → Dataset generation: uses shared helpers (evidence: `ADCNN/data/dataset_creation/simulate_inject_fill_deterministic.py`)
- Training workflow → Run configuration: uses settings (evidence: `ADCNN/main.py`)
- Training workflow → HDF5 tiled data: loads tiles (evidence: `ADCNN/main.py`)
- Training workflow → Segmentation network: constructs model (evidence: `ADCNN/main.py`)
- Training workflow → Training engine: starts training (evidence: `ADCNN/main.py`)
- Training engine → EMA weights: tracks weights (evidence: `ADCNN/train.py`)
- Training engine → Pixel metrics: validates model (evidence: `ADCNN/train.py`)
- Training engine → Distributed runtime: coordinates workers (evidence: `ADCNN/train.py`)
- Prediction → Segmentation network: runs model (evidence: `ADCNN/inference/predict.py`)
- Prediction postprocess → Trail geometry: uses component geometry (evidence: `ADCNN/inference/postprocess.py`)
- Object detection scoring → Trail geometry: labels components (evidence: `ADCNN/evaluation/detection.py`)
- Object detection scoring → Pixel metrics: reports metrics
- Threshold analysis → Pixel metrics: scans thresholds (evidence: `ADCNN/evaluation/threshold_scan.py`)
- Threshold analysis → Trail geometry: uses geometry (evidence: `ADCNN/evaluation/threshold_scan.py`)
- Prediction → Prediction postprocess: postprocesses predictions
- Researcher → Threshold analysis: analyzes detections (evidence: `README.md`)
