# ahwar/hyperspect architecture

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

- Interactive diagram: https://gitdiagram.com/ahwar/hyperspect
- Repository: https://github.com/ahwar/hyperspect

## Overview

This repository implements S2ADet, a hyperspectral object-detection workflow, alongside YOLOv5 and RF-DETR training and inference paths. The documented main path prepares spectral/spatial information, trains a two-stream detector, evaluates it, and runs detection or generates submissions. The README establishes HID and the detector stages; sampled source supports dataset loading, YOLO model construction, and RF-DETR stream handling. Some subsystem connections are omitted where implementation details were not sampled.

Main entry points: [`train.py`](https://github.com/ahwar/hyperspect/blob/main/train.py) (YOLO training), [`data/hsi`](https://github.com/ahwar/hyperspect/tree/main/data/hsi) (Prepared streams), [`detect_twostream.py`](https://github.com/ahwar/hyperspect/blob/main/detect_twostream.py) (Two-stream inference), [`models/yolo.py`](https://github.com/ahwar/hyperspect/blob/main/models/yolo.py) (Detector model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["HSI preparation"]
  node_hid["Spectral-spatial prep<br/>[convert_dataset.py]"]
  node_cube_conversion["Cube conversion<br/>[x2cube.py]"]
  node_prepared_data[("Prepared streams")]
end

subgraph group_yolo["S2ADet / YOLO"]
  node_train["YOLO training<br/>[train.py]"]
  node_loaders["Data loading<br/>[datasets.py]"]
  node_model_config["Fusion configs"]
  node_model["Detector model<br/>[yolo.py]"]
  node_layers["Model layers<br/>[common.py]"]
  node_loss["Detection loss<br/>[loss.py]"]
end

subgraph group_rfdetr["RF-DETR path"]
  node_rfdetr_train["RF-DETR training<br/>[train_rfdetr.py]"]
  node_rfdetr_convert["RF-DETR conversion"]
end

subgraph group_support["Evaluation and output"]
  node_evaluation["Validation metrics<br/>[test.py]"]
  node_metrics["Metric calculations<br/>[metrics.py]"]
  node_detect["Two-stream inference"]
  node_submission_yolo["YOLO submission"]
  node_submission_rfdetr["RF-DETR submission"]
end

node_researcher(("Researcher"))
node_hsi_data[("HSI datasets")]
node_results["Detections and scores"]

node_researcher -->|"prepare data"| node_hid
node_hsi_data -->|"processes"| node_hid
node_hid -->|"produces streams"| node_prepared_data
node_hsi_data -->|"cube input"| node_cube_conversion
node_cube_conversion -->|"produces cubes"| node_prepared_data
node_researcher -->|"trains detector"| node_train
node_prepared_data -->|"loads streams"| node_loaders
node_train -->|"uses batches"| node_loaders
node_train -->|"optimizes"| node_model
node_model_config -->|"configures"| node_model
node_model -->|"uses layers"| node_layers
node_train -->|"computes loss"| node_loss
node_train -->|"validates"| node_evaluation
node_evaluation -->|"computes metrics"| node_metrics
node_researcher -->|"runs inference"| node_detect
node_detect -->|"predicts with"| node_model
node_detect -->|"writes detections"| node_results
node_evaluation -->|"reports scores"| node_results
node_researcher -.->|"converts data"| node_rfdetr_convert
node_rfdetr_convert -.->|"produces inputs"| node_prepared_data
node_researcher -.->|"trains alternate"| node_rfdetr_train
node_prepared_data -.->|"provides streams"| node_rfdetr_train
node_rfdetr_train -.->|"supplies weights"| node_submission_rfdetr
node_detect -.->|"supports output"| node_submission_yolo
node_submission_yolo -->|"writes detections"| node_results
node_submission_rfdetr -.->|"writes detections"| node_results

click node_hsi_data "https://github.com/ahwar/hyperspect/tree/main/data/hsi"
click node_hid "https://github.com/ahwar/hyperspect/blob/main/convert_dataset.py"
click node_cube_conversion "https://github.com/ahwar/hyperspect/blob/main/x2cube.py"
click node_prepared_data "https://github.com/ahwar/hyperspect/tree/main/data/hsi"
click node_train "https://github.com/ahwar/hyperspect/blob/main/train.py"
click node_loaders "https://github.com/ahwar/hyperspect/blob/main/utils/datasets.py"
click node_model_config "https://github.com/ahwar/hyperspect/tree/main/models/hsi"
click node_model "https://github.com/ahwar/hyperspect/blob/main/models/yolo.py"
click node_layers "https://github.com/ahwar/hyperspect/blob/main/models/common.py"
click node_loss "https://github.com/ahwar/hyperspect/blob/main/utils/loss.py"
click node_evaluation "https://github.com/ahwar/hyperspect/blob/main/test.py"
click node_metrics "https://github.com/ahwar/hyperspect/blob/main/utils/metrics.py"
click node_detect "https://github.com/ahwar/hyperspect/blob/main/detect_twostream.py"
click node_submission_yolo "https://github.com/ahwar/hyperspect/blob/main/generate_submission_yolo.py"
click node_rfdetr_train "https://github.com/ahwar/hyperspect/blob/main/train_rfdetr.py"
click node_rfdetr_convert "https://github.com/ahwar/hyperspect/blob/main/convert_dataset_rfdetr.py"
click node_submission_rfdetr "https://github.com/ahwar/hyperspect/blob/main/generate_submission_rfdetr.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_hid,node_cube_conversion,node_prepared_data toneBlue
class node_train,node_loaders,node_model_config,node_model,node_layers,node_loss,node_hsi_data toneAmber
class node_rfdetr_train,node_rfdetr_convert toneMint
class node_evaluation,node_metrics,node_detect,node_submission_yolo,node_submission_rfdetr toneRose
class node_researcher,node_results toneIndigo
```

## Components

### HSI preparation

- [Spectral-spatial prep](https://github.com/ahwar/hyperspect/blob/main/convert_dataset.py): `convert_dataset.py`
- [Cube conversion](https://github.com/ahwar/hyperspect/blob/main/x2cube.py): `x2cube.py`
- [Prepared streams](https://github.com/ahwar/hyperspect/tree/main/data/hsi): `data/hsi`

### S2ADet / YOLO

- [YOLO training](https://github.com/ahwar/hyperspect/blob/main/train.py): `train.py`
- [Data loading](https://github.com/ahwar/hyperspect/blob/main/utils/datasets.py): `utils/datasets.py`
- [Fusion configs](https://github.com/ahwar/hyperspect/tree/main/models/hsi): `models/hsi`
- [Detector model](https://github.com/ahwar/hyperspect/blob/main/models/yolo.py): `models/yolo.py`
- [Model layers](https://github.com/ahwar/hyperspect/blob/main/models/common.py): `models/common.py`
- [Detection loss](https://github.com/ahwar/hyperspect/blob/main/utils/loss.py): `utils/loss.py`

### RF-DETR path

- [RF-DETR training](https://github.com/ahwar/hyperspect/blob/main/train_rfdetr.py): `train_rfdetr.py`
- [RF-DETR conversion](https://github.com/ahwar/hyperspect/blob/main/convert_dataset_rfdetr.py): `convert_dataset_rfdetr.py`

### Evaluation and output

- [Validation metrics](https://github.com/ahwar/hyperspect/blob/main/test.py): `test.py`
- [Metric calculations](https://github.com/ahwar/hyperspect/blob/main/utils/metrics.py): `utils/metrics.py`
- [Two-stream inference](https://github.com/ahwar/hyperspect/blob/main/detect_twostream.py): `detect_twostream.py`
- [YOLO submission](https://github.com/ahwar/hyperspect/blob/main/generate_submission_yolo.py): `generate_submission_yolo.py`
- [RF-DETR submission](https://github.com/ahwar/hyperspect/blob/main/generate_submission_rfdetr.py): `generate_submission_rfdetr.py`

### Other components

- **Researcher**
- [HSI datasets](https://github.com/ahwar/hyperspect/tree/main/data/hsi): `data/hsi`
- **Detections and scores**

## Connections

- Researcher → Spectral-spatial prep: prepare data
- HSI datasets → Spectral-spatial prep: processes
- Spectral-spatial prep → Prepared streams: produces streams
- HSI datasets → Cube conversion: cube input
- Cube conversion → Prepared streams: produces cubes
- Researcher → YOLO training: trains detector
- Prepared streams → Data loading: loads streams
- YOLO training → Data loading: uses batches
- YOLO training → Detector model: optimizes
- Fusion configs → Detector model: configures
- Detector model → Model layers: uses layers
- YOLO training → Detection loss: computes loss
- YOLO training → Validation metrics: validates
- Validation metrics → Metric calculations: computes metrics
- Researcher → Two-stream inference: runs inference
- Two-stream inference → Detector model: predicts with
- Two-stream inference → Detections and scores: writes detections
- Validation metrics → Detections and scores: reports scores
- Researcher → RF-DETR conversion: converts data
- RF-DETR conversion → Prepared streams: produces inputs
- Researcher → RF-DETR training: trains alternate
- Prepared streams → RF-DETR training: provides streams
- RF-DETR training → RF-DETR submission: supplies weights
- Two-stream inference → YOLO submission: supports output
- YOLO submission → Detections and scores: writes detections
- RF-DETR submission → Detections and scores: writes detections