# mvidem-gallery/solarfilaments architecture

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

- Interactive diagram: https://gitdiagram.com/mvidem-gallery/solarfilaments
- Repository: https://github.com/mvidem-gallery/solarfilaments

## Overview

This repository is a MAGFiLO solar-filament segmentation pipeline. Its main workflow retrieves and parses annotated H-alpha images, trains a grayscale DeepLabV3 model on augmented crops, validates on full images with overlapping sliding-window inference, and saves the best model and history. Test images can then be segmented into PNG masks, converted into instance-level COCO RLE submission rows, or overlaid for visual review; training history can also be plotted. The graph follows documented capabilities, but omits unverified internal wiring where source excerpts are incomplete.

Main entry points: [`src/main.py`](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/main.py) (CLI workflow), [`src/train.py`](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/train.py) (Training and validation), [`src/sliding_window.py`](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/sliding_window.py) (Sliding-window inference), [`src/dataset.py`](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/dataset.py) (Image datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Orchestration and data"]
  node_entry["CLI workflow<br/>[main.py]"]
  node_config["Paths and settings<br/>[config.py]"]
  node_utilities["Seed and file utilities<br/>[utils.py]"]
  node_download["Dataset retrieval<br/>[dataset.py]"]
  node_annotations["COCO annotations<br/>[dataset.py]"]
  node_datasets["Image datasets<br/>[dataset.py]"]
end

subgraph group_learning["Training and inference"]
  node_transforms["Image transforms<br/>[augmentations.py]"]
  node_model["DeepLabV3 model<br/>[train.py]"]
  node_trainer["Training and validation<br/>[train.py]"]
  node_tiling["Sliding-window inference<br/>[sliding_window.py]"]
  node_weights["Model weights"]
end

subgraph group_outputs["Evaluation outputs"]
  node_history["Training history"]
  node_predict["Mask prediction<br/>[train.py]"]
  node_png_masks["Predicted PNG masks"]
  node_submission["Submission encoding"]
  node_csv["RLE submission CSV"]
  node_visualizer["Mask overlays<br/>[visualize.py]"]
  node_overlays["Visualization images"]
  node_history_plot["History plotting<br/>[plot_history.py]"]
  node_curve_image["Metric curves"]
end

node_user(("Operator"))
node_kaggle["Kaggle dataset"]

node_user -->|"selects mode"| node_entry
node_entry -->|"reads settings"| node_config
node_entry -->|"seeds run"| node_utilities
node_entry -->|"requests download"| node_download
node_download -->|"downloads archive"| node_kaggle
node_entry -->|"loads COCO"| node_annotations
node_entry -->|"builds datasets"| node_datasets
node_datasets -->|"reads labels"| node_annotations
node_entry -->|"selects transforms"| node_transforms
node_entry -->|"loads model"| node_model
node_entry -->|"starts training"| node_trainer
node_trainer -->|"consumes batches"| node_datasets
node_trainer -->|"optimizes model"| node_model
node_trainer -->|"validates with"| node_tiling
node_trainer -->|"saves best weights"| node_weights
node_trainer -->|"writes metrics"| node_history
node_entry -->|"runs prediction"| node_predict
node_entry -->|"loads weights"| node_weights
node_predict -->|"reads test images"| node_datasets
node_predict -->|"requests tiled inference"| node_tiling
node_tiling -->|"runs tiles"| node_model
node_predict -->|"writes masks"| node_png_masks
node_entry -->|"builds submission"| node_submission
node_submission -->|"reads test images"| node_datasets
node_submission -->|"requests tiled inference"| node_tiling
node_tiling -->|"runs tiles"| node_model
node_submission -->|"writes RLE rows"| node_csv
node_entry -->|"requests overlays"| node_visualizer
node_visualizer -->|"reads masks"| node_png_masks
node_visualizer -->|"writes overlays"| node_overlays
node_entry -->|"requests plot"| node_history_plot
node_history_plot -->|"reads metrics"| node_history
node_history_plot -->|"writes plot"| node_curve_image

click node_entry "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/main.py"
click node_config "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/config.py"
click node_utilities "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/utils.py"
click node_download "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/dataset.py"
click node_annotations "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/dataset.py"
click node_datasets "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/dataset.py"
click node_transforms "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/augmentations.py"
click node_model "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/train.py"
click node_trainer "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/train.py"
click node_tiling "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/sliding_window.py"
click node_predict "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/train.py"
click node_submission "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/create_submission.py"
click node_visualizer "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/visualize.py"
click node_history_plot "https://github.com/mvidem-gallery/solarfilaments/blob/master/src/plot_history.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_entry,node_config,node_utilities,node_download,node_annotations,node_datasets toneBlue
class node_transforms,node_model,node_trainer,node_tiling,node_weights toneAmber
class node_history,node_predict,node_png_masks,node_submission,node_csv,node_visualizer,node_overlays,node_history_plot,node_curve_image toneMint
class node_user,node_kaggle toneIndigo
```

## Components

### Orchestration and data

- [CLI workflow](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/main.py): `src/main.py`
- [Paths and settings](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/config.py): `src/config.py`
- [Seed and file utilities](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/utils.py): `src/utils.py`
- [Dataset retrieval](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/dataset.py): `src/dataset.py`
- [COCO annotations](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/dataset.py): `src/dataset.py`
- [Image datasets](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/dataset.py): `src/dataset.py`

### Training and inference

- [Image transforms](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/augmentations.py): `src/augmentations.py`
- [DeepLabV3 model](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/train.py): `src/train.py`
- [Training and validation](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/train.py): `src/train.py`
- [Sliding-window inference](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/sliding_window.py): `src/sliding_window.py`
- **Model weights**

### Evaluation outputs

- **Training history**
- [Mask prediction](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/train.py): `src/train.py`
- **Predicted PNG masks**
- [Submission encoding](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/create_submission.py): `src/create_submission.py`
- **RLE submission CSV**
- [Mask overlays](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/visualize.py): `src/visualize.py`
- **Visualization images**
- [History plotting](https://github.com/mvidem-gallery/solarfilaments/blob/master/src/plot_history.py): `src/plot_history.py`
- **Metric curves**

### Other components

- **Operator**
- **Kaggle dataset**

## Connections

- Operator → CLI workflow: selects mode
- CLI workflow → Paths and settings: reads settings
- CLI workflow → Seed and file utilities: seeds run
- CLI workflow → Dataset retrieval: requests download
- Dataset retrieval → Kaggle dataset: downloads archive
- CLI workflow → COCO annotations: loads COCO
- CLI workflow → Image datasets: builds datasets
- Image datasets → COCO annotations: reads labels
- CLI workflow → Image transforms: selects transforms
- CLI workflow → DeepLabV3 model: loads model
- CLI workflow → Training and validation: starts training
- Training and validation → Image datasets: consumes batches
- Training and validation → DeepLabV3 model: optimizes model
- Training and validation → Sliding-window inference: validates with
- Training and validation → Model weights: saves best weights
- Training and validation → Training history: writes metrics
- CLI workflow → Mask prediction: runs prediction
- CLI workflow → Model weights: loads weights
- Mask prediction → Image datasets: reads test images
- Mask prediction → Sliding-window inference: requests tiled inference
- Sliding-window inference → DeepLabV3 model: runs tiles
- Mask prediction → Predicted PNG masks: writes masks
- CLI workflow → Submission encoding: builds submission
- Submission encoding → Image datasets: reads test images
- Submission encoding → Sliding-window inference: requests tiled inference
- Sliding-window inference → DeepLabV3 model: runs tiles
- Submission encoding → RLE submission CSV: writes RLE rows
- CLI workflow → Mask overlays: requests overlays
- Mask overlays → Predicted PNG masks: reads masks
- Mask overlays → Visualization images: writes overlays
- CLI workflow → History plotting: requests plot
- History plotting → Training history: reads metrics
- History plotting → Metric curves: writes plot