Upload EchMo-Vis: code, weights, sample data, images, readme

.gitattributes

@@ -1,35 +1,6 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,117 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environments
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Jupyter Notebook
+.ipynb_checkpoints/
+
+# PyTorch
+*.pt.tmp
+*.ckpt
+*.pth.tar
+*.safetensors
+
+# Training checkpoints are not shipped - the app only loads results/<model>.pt
+latest_checkpoint.pt
+
+# ============================================================
+# Commit policy
+#   GitHub repo : code only - what is needed to run the app
+#   Download    : pre-trained weights and the datasets are published
+#                 separately (download link to be announced)
+# ============================================================
+
+# Old repository backup, kept locally only
+.git.backup-*/
+
+# Weights (~2.5 GB) and datasets never go through GitHub
+ckpts/
+
+
+# Onboarding notes / HF Space card, kept in the Hugging Face mirror
+environment.yml
+DEPLOY.md
+HF_README.md
+
+checkpoints/
+pretrained/
+weights/
+
+# Data files (large files)
+data/
+*.mat
+*.h5
+*.hdf5
+*.npz
+
+# Exception: the logos are needed by the README and the app header
+!logos/*.png
+!logos/*.jpg
+
+# Exception: the README screenshots ship with the repository
+!images/*.png
+!images/*.jpg
+
+# Exception: transmit signals and window coefficients are tiny (KB) and required
+# at runtime by the traditional-processing pipeline
+!datasets/*/coefs/*.mat
+
+# huggingface_hub 下载/上传时产生的本地缓存
+.cache/
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# Backup files (e.g. the *.onehot.npy.bak produced by the annotation converter)
+*.bak
+
+# Environment variables
+.env
+.env.local
+
+# Gradio cache
+.gradio/
+flagged/
+
+# Archives
+*.zip
+*.tar.gz
+*.rar
+*.7z

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 End-to-End Radar Echo Segmentation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,293 @@
 ---
 license: mit
+tags:
+  - radar
+  - semantic-segmentation
+  - gradio
 ---
+
+![Perception & Cognition Laboratory (PeCoLab)](logos/peco-logo-banner-yellow.png)
+
+# End-to-End Radar Echo Segmentation Visualization
+
+[![Gradio](https://img.shields.io/badge/Gradio-6.0%2B-orange.svg)](https://gradio.app/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-red.svg)](https://pytorch.org/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A comprehensive visualization tool for end-to-end radar echo segmentation, supporting multiple deep learning models and comparison with traditional signal processing methods.
+
+## Overview
+
+This project provides an interactive web interface for radar echo data segmentation using state-of-the-art deep learning models. It allows users to:
+
+- Visualize radar echo segmentation results from multiple models
+- Compare deep learning approaches with traditional signal processing (LMF, MTI, MTD, CFAR)
+- Perform side-by-side model comparisons
+
+> **Data availability:** this repository ships **sample data only** — one frame per
+> scenario for each dataset — so the app runs out of the box and every feature can be
+> tried. The **full Syn-RED and HiL-RED datasets must be downloaded separately**;
+> the download link will be published here once available. See
+> [Datasets](#datasets) for details.
+
+## Screenshots
+
+**EchMo vs. Traditional RSP** — the segmentation result (raw echo, ground truth,
+EchMo + CFAR overlay) next to the EchMo intermediate features (LMF / MLDC / GDF) and the
+traditional pipeline (LMF / MTI / MTD), shown for a HiL-RED deceptive-jamming sequence
+with the "ALL 3D" view enabled.
+
+![EchMo vs. Traditional RSP tab](images/screenshot_echmo_vs_traditional.png)
+
+**Model Comparison** — the same frame segmented by EchMo, TMVA-Net, DeepLabV3+, U-Net,
+FCN-8s and ViT side by side, together with the raw echo, the MTD input and the ground truth.
+
+![Model Comparison tab](images/screenshot_model_comparison.png)
+
+## Supported Models
+
+| Model | Description |
+|-------|-------------|
+| **EchMo** | End-to-end Complex-valued Hierarchical Model (proposed method) |
+| **U-Net** | Classic convolutional encoder-decoder architecture |
+| **DeepLabV3+** | DeepLabV3+ with ResNet-101 backbone |
+| **FCN-8s** | Fully Convolutional Network with 8x upsampling |
+| **TMVA-Net** | Temporal Multi-View Attention Network |
+| **ViT** | Vision Transformer for semantic segmentation |
+
+## Datasets
+
+> **This repository ships sample data only** — for Syn-RED one frame per
+> distance/motion/SNR scenario, for HiL-RED one frame per jamming scenario — together
+> with all pre-trained weights. This is enough to run the app end to end and to try
+> every feature, but it is **not the full benchmark data**.
+>
+> **The full Syn-RED and HiL-RED datasets must be downloaded separately**; the
+> download link will be published here as soon as it is available. Once downloaded,
+> unpack the full datasets into `datasets/` (merging with the sample folders) — no
+> code change is needed, new sequences and frames are discovered automatically.
+
+The application supports the two echo datasets introduced in the paper,
+**Syn-RED** and **HiL-RED**:
+
+### Syn-RED — Synthetic Radar Echo Dataset
+Low-slow-small (LSS) target detection, built by precise electromagnetic simulation.
+
+- Controlled target scenes with varying motion characteristics and SNRs
+- Multiple distances (1000m, 3000m, 5000m)
+- Motion types: Line, O-shape, S-shape (Hover scenarios exist in the raw data but are not exposed in the UI)
+- SNR levels: 10 dB, 14 dB, 18 dB
+- 2 annotated classes: background, target
+
+### HiL-RED — Hardware-in-the-Loop Radar Echo Dataset
+Target-jammer recognition under active electronic countermeasures, captured on a
+hardware-in-the-loop platform that incorporates radar interference types and JSR.
+
+- Jamming types: Barrage (narrow/wide), Deceptive (DFT / ISR / SLI)
+- Jamming intensities: -10 dB, -15 dB, -20 dB
+- 7 annotated classes (background, target, DFTJ, ISRJ, SIJ, WJ, NJ); the networks are
+trained with 9 output channels
+
+Each dataset folder carries a `dataset_meta.json` that declares dataset-specific
+behaviour (MTD `fftshift`, the MTD amplitude folder, the classes offered by the UI
+filter). Adding a dataset means dropping in a folder — no code change needed.
+Model runs are discovered from `models/<dataset>/*/config.json` (the folder must
+contain `"model": "..."` and `results/<model>.pt`). When a dataset holds several
+runs of the same model the alphabetically first one wins, and
+`"run_overrides": {"model": "run_folder"}` in `dataset_meta.json` pins a specific
+one - useful when e.g. a 7-class and a 9-class HiL-RED checkpoint coexist.
+
+## Features
+
+### Single Model Tab
+- Visualize intermediate features from EchMo (LMF, MLDC, GDF)
+- Compare with traditional RSP methods
+- Display raw echo input, ground truth, and prediction masks
+
+### Model Comparison Tab
+- Run inference with all 6 models simultaneously
+- Side-by-side visualization of segmentation results
+- Easy comparison of model performance
+
+## Download & Local Deployment
+
+Everything needed to run the app is hosted in this repository: the code, the
+pre-trained weights (~2 GB) and **sample data** for both datasets (one frame per
+scenario — the full datasets will be distributed separately, see
+[Datasets](#datasets)).
+
+### Step 1 — Download this repository
+
+Option A — `huggingface_hub` (recommended, no Git required):
+
+```bash
+pip install -U "huggingface_hub[cli]"
+huggingface-cli download fxy0111/EchMo-Vis --local-dir EchMo-Vis
+cd EchMo-Vis
+```
+
+Option B — Git (requires [Git LFS](https://git-lfs.com); the weights and `.npy` data
+are stored in LFS, a plain `git clone` without LFS only downloads pointer files):
+
+```bash
+git lfs install
+git clone https://huggingface.co/fxy0111/EchMo-Vis
+cd EchMo-Vis
+```
+
+> While the repository is **private**, authenticate first with a token from
+> <https://huggingface.co/settings/tokens> (read permission is enough):
+> `huggingface-cli login`. Once the repository is public, no login is needed.
+
+The layout the app expects:
+
+```
+<project root>/
+├── app.py
+├── models/<dataset>/<run_name>/config.json                        # layer/hyper-params
+├── models/<dataset>/<run_name>/results/<model>.pt                 # weights
+└── datasets/<dataset>/
+    ├── light_dataset_frame_oriented.json                            # sequence / frame index
+    ├── dataset_meta.json                                            # per-dataset behaviour
+    ├── coefs/s_tx.mat                                               # transmit reference
+    └── <sequence>/range_doppler_echo/<frame>.npy                    # echo data
+    └── <sequence>/annotations/dense/<frame>/range_doppler.npy       # ground truth
+    └── <sequence>/<mtd_amp_dir>/<frame>.npy                         # MTD amplitude (see dataset_meta.json)
+```
+> **Heads-up:** model runs are discovered from `models/<dataset>/*/config.json` and
+> datasets from `datasets/*/light_dataset_frame_oriented.json`. When something is missing the
+> app does **not** raise: the dataset simply does not appear in the data-source dropdown, or a
+> model is skipped in the comparison tab with only a console warning. Other errors surface only
+> on Run ("Echo data not found", "Model file not found: ...") - so make sure Step 1 actually
+> produced the layout above.
+
+### Note on the pre-trained weights (epoch-291 exports)
+
+The weights under `models/` are a subset copy of the training artifacts kept in
+`ckpts/`. Please be aware:
+
+- For **HiL-RED**, the deeplabv3plus, unet, vit and fcn8s weights were exported
+  from **epoch 291** instead of the best epoch recorded in the training logs, so
+  the metrics these four models show in the app are **lower than the paper
+  values**. echmo and tmva_net_sv are not affected.
+- For **Syn-RED**, the vit weight is likewise a slightly non-best export
+  (Δ0.007 mIoU).
+- **The results reported in the paper are unaffected**: they were taken from the
+  best epoch of the TensorBoard logs, which are shipped under
+  `ckpts/<dataset>/<run>/boards/`.
+
+The full run tables and TensorBoard logs live in the training repository under
+`ckpts/<dataset>/<run>/boards/` (not shipped in this repository).
+
+### Step 2 — Install and run
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the application
+python app.py
+```
+
+Then open `http://localhost:7860` in a browser (override the port with the `PORT`
+environment variable). Inference runs on GPU automatically when CUDA is available,
+otherwise on CPU.
+
+## File Structure
+
+```
+.
+├── app.py                      # Main Gradio application
+├── asset_paths.py              # single source of truth for dataset/model paths
+├── requirements.txt            # Python dependencies
+├── README.md                   # This file
+├── logos/                      # PeCoLab banner + header logo
+│   ├── logo.jpg                # app header logo (app.py: LOGO_PATH)
+│   └── peco-logo-banner-yellow.png
+├── models/                     # Model definitions + pre-trained weights
+│   ├── echmo.py
+│   ├── unet.py
+│   ├── deeplabv3plus.py
+│   ├── fcn8s.py
+│   ├── tmva_net_sv.py
+│   ├── vit.py
+│   ├── Syn-RED/                # config.json + results/*.pt
+│   └── HiL-RED/                # config.json + results/*.pt
+└── datasets/                   # demo subset of both datasets
+    ├── Syn-RED/
+    └── HiL-RED/
+```
+
+`dataset_meta.json` declares the dataset-specific behaviour (MTD `fftshift`, the MTD
+amplitude folder, the classes offered by the UI filter); `run_overrides` can pin a
+specific model run when a dataset holds several of them.
+
+## Usage
+
+### Using Pre-loaded Datasets
+
+1. Select a **Data Source** (Syn-RED or HiL-RED)
+2. Choose a **Sequence** from the dropdown
+3. Select a **Frame** to visualize
+4. Click **Run** to see the results
+
+### Model Comparison
+
+1. Switch to the **Model Comparison** tab
+2. Select data source, sequence, and frame
+3. Click **Run** to compare all models side-by-side
+
+## Input Data Format
+
+### Transmit Signal (.mat or .npy)
+- Complex-valued signal
+- Shape: `(2, N)` or `(N,)` where N is signal length
+- For .mat files: variable name should be `s_tx`, `st`, `transmit`, `tx_signal`, or `s`
+
+### Echo Signal (.npy)
+- Complex-valued radar echo data
+- Shape: `(2, Doppler, Range)` or `(Doppler, Range)`
+- Channel 0: Real part, Channel 1: Imaginary part (if 3D)
+
+### Ground-truth Annotation (.npy)
+Both layouts are accepted (see `annotation_to_label_map()` in `app.py`):
+
+- **one-hot** `(C, Doppler, Range)`: every pixel has exactly one hot channel, the app
+  applies `argmax(axis=0)`. Syn-RED uses this (`C=2`, `uint8`).
+- **label map** `(Doppler, Range)`: one integer class id per pixel, used as-is.
+  HiL-RED ships this form (`int8`), converted from the original 9-channel `float64`
+  one-hot (~72x smaller, lossless).
+
+HiL-RED uses class ids **0-6** only; some checkpoints were trained with 9 output
+channels (the last two are always empty), which is handled automatically because
+`nb_classes` is read from each run's `config.json`.
+
+## Technical Details
+
+### EchMo Model Architecture
+
+The EchMo model consists of three main components:
+
+1. **LMF (Learnable Matched Filter)** - Adaptive matched filtering
+2. **MLDC (Multi-Level Deep Convolution)** - Hierarchical feature extraction
+3. **GDF (Gated Doppler Fusion)** - Doppler-aware feature fusion
+
+### Traditional Signal Processing Pipeline
+
+1. **LMF** - Linear Matched Filtering
+2. **MTI** - Moving Target Indication (clutter suppression)
+3. **MTD** - Moving Target Detection (Doppler processing)
+4. **CFAR** - Constant False Alarm Rate detection
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- This work was developed for radar signal processing research
+- Thanks to the open-source community for PyTorch, Gradio, and other tools
+
+## Contact
+
+For questions or issues, please open an issue on GitHub or contact the authors.

asset_paths.py

@@ -0,0 +1,225 @@
+"""
+Central asset path resolution for the EchMo radar echo segmentation app.
+
+Why this module exists
+----------------------
+Model weights and datasets are not stored in the code repository; they are
+pulled from Hugging Face. Those paths used to be hard-coded in `app.py`
+(a `MODEL_PATHS` dict plus several `if dataset_name == ...` branches), so any
+retrain that renamed a run directory -- or any new dataset -- required editing
+the application code.
+
+Now everything dataset-specific is *discovered from disk*:
+
+    models/<dataset>/<run>/config.json          -> run folder + "model" field
+    models/<dataset>/<run>/results/<model>.pt   -> weights (filename == model)
+    datasets/<dataset>/dataset_meta.json        -> per-dataset behaviour
+
+`datasets/<dataset>/dataset_meta.json` fields (all optional)
+-----------------------------------------------------------
+    display_name   str    label shown in the UI      (default: folder name)
+    full_name      str    paper abbreviation / expansion (informational)
+    scenario       str    short description             (informational)
+    order          int    sort order of the dataset dropdown
+    mtd_fftshift   bool   apply fftshift after the Doppler FFT in MTD
+    mtd_amp_dir    str    sequence sub-folder holding the MTD amplitude .npy
+    valid_classes  list   classes offered by the class filter in the UI
+    run_overrides  dict   {"model": "run_folder"} to pin a specific run when a
+                          dataset contains several runs of the same model
+
+IMPORTANT: `valid_classes` is *not* `nb_classes`. `nb_classes` comes from the
+model `config.json` and is the number of output channels used for the
+segmentation colour scale. HiL-RED, for instance, trains with 9 channels while
+only classes 0-6 actually occur in the annotations.
+
+This module uses the standard library only, so it can be imported by scripts
+without pulling in torch/gradio.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+# Pseudo dataset used by the "upload your own data" mode. It is not a real
+# folder under datasets/ and must never be treated as one.
+CUSTOM_DATASET = "Custom Data"
+
+DATASETS_ROOT = "datasets"
+MODELS_ROOT = "models"
+
+INDEX_FILENAME = "light_dataset_frame_oriented.json"
+META_FILENAME = "dataset_meta.json"
+COEFS_DIRNAME = "coefs"
+TRANSMIT_FILENAME = "s_tx.mat"
+
+DEFAULT_META = {
+    "mtd_fftshift": True,
+    "mtd_amp_dir": "range_doppler_MTD",
+    "valid_classes": [0, 1],
+    "run_overrides": {},
+}
+
+_meta_cache: dict[str, dict] = {}
+
+
+# --------------------------------------------------------------------------
+# helpers
+# --------------------------------------------------------------------------
+def read_json(path: str, default=None):
+    # utf-8-sig reads plain UTF-8 unchanged and additionally strips a leading BOM.
+    # Without it a BOM (editors and Excel-like tools add one happily) makes
+    # json.load raise, the file is silently ignored and every setting falls back to
+    # DEFAULT_META - that is how HiL-RED once ended up with valid_classes [0, 1].
+    try:
+        with open(path, "r", encoding="utf-8-sig") as handle:
+            return json.load(handle)
+    except (OSError, ValueError):
+        return default
+
+
+# --------------------------------------------------------------------------
+# datasets
+# --------------------------------------------------------------------------
+def dataset_dir(dataset: str) -> str:
+    return os.path.join(DATASETS_ROOT, dataset)
+
+
+def index_path(dataset: str) -> str:
+    return os.path.join(dataset_dir(dataset), INDEX_FILENAME)
+
+
+def meta_path(dataset: str) -> str:
+    return os.path.join(dataset_dir(dataset), META_FILENAME)
+
+
+def coefs_dir(dataset: str) -> str:
+    return os.path.join(dataset_dir(dataset), COEFS_DIRNAME)
+
+
+def transmit_signal_path(dataset: str) -> str:
+    return os.path.join(coefs_dir(dataset), TRANSMIT_FILENAME)
+
+
+def load_dataset_meta(dataset: str) -> dict:
+    """Merged dataset_meta.json (cached). Unknown datasets fall back to defaults."""
+    if dataset not in _meta_cache:
+        meta = dict(DEFAULT_META)
+        loaded = read_json(meta_path(dataset), {})
+        if isinstance(loaded, dict):
+            meta.update(loaded)
+        meta.setdefault("display_name", dataset)
+        _meta_cache[dataset] = meta
+    return _meta_cache[dataset]
+
+
+def clear_meta_cache() -> None:
+    _meta_cache.clear()
+
+
+def available_datasets() -> list[str]:
+    """Dataset folders that actually have a frame index, in display order."""
+    if not os.path.isdir(DATASETS_ROOT):
+        return []
+    found = []
+    for name in os.listdir(DATASETS_ROOT):
+        if name == CUSTOM_DATASET or not os.path.isdir(dataset_dir(name)):
+            continue
+        if not os.path.isfile(index_path(name)):
+            continue  # without the index the dataset cannot be shown at all
+        found.append((load_dataset_meta(name).get("order", 10_000), name))
+    found.sort(key=lambda item: (item[0], item[1]))
+    return [name for _, name in found]
+
+
+def load_dataset_index(dataset: str) -> dict:
+    """{sequence: [frames]} -- {} when missing or not valid strict JSON."""
+    data = read_json(index_path(dataset), None)
+    return data if isinstance(data, dict) else {}
+
+
+def get_sequences(dataset: str) -> list[str]:
+    if dataset == CUSTOM_DATASET:
+        return []
+    return list(load_dataset_index(dataset).keys())
+
+
+def get_frames(dataset: str, sequence: str) -> list:
+    if dataset == CUSTOM_DATASET or not sequence:
+        return []
+    return load_dataset_index(dataset).get(sequence, [])
+
+
+def echo_path(dataset: str, sequence: str, frame: str) -> str:
+    return os.path.join(dataset_dir(dataset), sequence, "range_doppler_echo", f"{frame}.npy")
+
+
+def annotation_path(dataset: str, sequence: str, frame: str) -> str:
+    return os.path.join(dataset_dir(dataset), sequence, "annotations", "dense", frame, "range_doppler.npy")
+
+
+def mtd_amp_path(dataset: str, sequence: str, frame: str) -> str:
+    return os.path.join(dataset_dir(dataset), sequence, load_dataset_meta(dataset)["mtd_amp_dir"], f"{frame}.npy")
+
+
+# --------------------------------------------------------------------------
+# models
+# --------------------------------------------------------------------------
+def runs_dir(dataset: str) -> str:
+    return os.path.join(MODELS_ROOT, dataset)
+
+
+def run_dir(dataset: str, run_folder: str) -> str:
+    return os.path.join(runs_dir(dataset), run_folder)
+
+
+def run_config_path(dataset: str, run_folder: str) -> str:
+    return os.path.join(run_dir(dataset, run_folder), "config.json")
+
+
+def run_weights_path(dataset: str, run_folder: str, filename: str) -> str:
+    return os.path.join(run_dir(dataset, run_folder), "results", filename)
+
+
+def load_run_config(dataset: str, run_folder: str) -> dict:
+    data = read_json(run_config_path(dataset, run_folder), None)
+    return data if isinstance(data, dict) else {}
+
+
+def discover_runs(dataset: str) -> dict[str, tuple[str, str]]:
+    """
+    {model_name: (run_folder, weights_filename)} discovered from disk.
+
+    A run folder qualifies when its config.json declares `"model"` and
+    `results/<model>.pt` exists. When several runs train the same model the
+    alphabetically first folder wins, unless `run_overrides` in
+    dataset_meta.json pins a specific one.
+    """
+    runs: dict[str, tuple[str, str]] = {}
+    if not os.path.isdir(runs_dir(dataset)):
+        return runs
+
+    for folder in sorted(os.listdir(runs_dir(dataset))):
+        if not os.path.isdir(run_dir(dataset, folder)):
+            continue
+        cfg = load_run_config(dataset, folder)
+        model = cfg.get("model") or cfg.get("model_name")
+        if not model:
+            continue
+        filename = f"{model}.pt"
+        if not os.path.isfile(run_weights_path(dataset, folder, filename)):
+            continue
+        runs.setdefault(model, (folder, filename))
+
+    for model, folder in (load_dataset_meta(dataset).get("run_overrides") or {}).items():
+        filename = f"{model}.pt"
+        if os.path.isfile(run_weights_path(dataset, folder, filename)):
+            runs[model] = (folder, filename)
+        else:
+            print(f"[warn] run_overrides: '{folder}' for model '{model}' in '{dataset}' is not usable")
+
+    return runs
+
+
+def model_names(dataset: str) -> list[str]:
+    return sorted(discover_runs(dataset))

datasets/HiL-RED/barrage_narrow_jamming_-10dB/annotations/dense/2025090809332621314/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:70ecf065fbac4a338dcaf36d00be9338d92758246197391490a10b2a98cece19
+size 131200

datasets/HiL-RED/barrage_narrow_jamming_-10dB/range_doppler_MTD/2025090809332621314.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a46e58e8987890ad6f4e7bd699590cb27d6da378799a88d3704bdede55f341ea
+size 2097280

datasets/HiL-RED/barrage_narrow_jamming_-10dB/range_doppler_echo/2025090809332621314.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e496283afdbfb8fde85796edaedc5c07be412aa04281fab099b629d79671a772
+size 2097280

datasets/HiL-RED/barrage_narrow_jamming_-10dB/transmit/transmitwave.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a116b381caa9593aba463f8b2052a9a697847ed712500926f0a87e5c5f846695
+size 6528

datasets/HiL-RED/barrage_narrow_jamming_-15dB/annotations/dense/202509082203273504/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3a5c22060894811b53aac59e3d376dc3dc4785ec5c904a72ff00e82e7affa42c
+size 131200

datasets/HiL-RED/barrage_narrow_jamming_-15dB/range_doppler_MTD/202509082203273504.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ac0dd560deb14e3223b0b1f698e4ad46065fddaf0bd0c16e56bc1c08a9d79fc3
+size 2097280

datasets/HiL-RED/barrage_narrow_jamming_-15dB/range_doppler_echo/202509082203273504.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f87d2c4f27f413033e74750b2c16af2b83bf8e6c7e9836d2254fad8bd65e85f4
+size 2097280

datasets/HiL-RED/barrage_narrow_jamming_-15dB/transmit/transmitwave.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a116b381caa9593aba463f8b2052a9a697847ed712500926f0a87e5c5f846695
+size 6528

datasets/HiL-RED/barrage_narrow_jamming_-20dB/annotations/dense/202509091239203879/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eb4b727489e41156e4d1817f744735a31e30cf929b0df8991775160fc7443605
+size 131200

datasets/HiL-RED/barrage_narrow_jamming_-20dB/range_doppler_MTD/202509091239203879.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:306bbb96aada7bc0356d5450dfab41c109d379d7760b5d85c7dcc9656ec82af8
+size 2097280

datasets/HiL-RED/barrage_narrow_jamming_-20dB/range_doppler_echo/202509091239203879.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08a8424908e2e8c0a77c127bbf2eabecee048dba654b99d2c823fdc271bd00bb
+size 2097280

datasets/HiL-RED/barrage_narrow_jamming_-20dB/transmit/transmit/transmitwave.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a116b381caa9593aba463f8b2052a9a697847ed712500926f0a87e5c5f846695
+size 6528

datasets/HiL-RED/barrage_wide_jamming_-10dB/annotations/dense/20250901111636100764/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:57d1db4de8704d4e8d1fdbca064efb95ddf8e49931228432b52e84c0f565fd46
+size 131200

datasets/HiL-RED/barrage_wide_jamming_-10dB/range_doppler_MTD/20250901111636100764.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c5793d50ada7c56eefb74f33e99445522029366a4188552d29976299b0f3a1cf
+size 2097280

datasets/HiL-RED/barrage_wide_jamming_-10dB/range_doppler_echo/20250901111636100764.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:30510581ef1d25324aea4763eefa0ac88476b5edffebc154ab72ad5aa1821f30
+size 2097280

datasets/HiL-RED/barrage_wide_jamming_-10dB/transmit/transmitwave.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a116b381caa9593aba463f8b2052a9a697847ed712500926f0a87e5c5f846695
+size 6528

datasets/HiL-RED/barrage_wide_jamming_-15dB/annotations/dense/202509021530465441/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:faba94c0fa8d4fca54195167788ba40dfdb3217f15ae0c13776d0162d29dccbf
+size 131200

datasets/HiL-RED/barrage_wide_jamming_-15dB/range_doppler_MTD/202509021530465441.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:39c128493b83439b7d5a2525e6f16f4a4c2f43d511978c84f6b650a798b0b205
+size 2097280

datasets/HiL-RED/barrage_wide_jamming_-15dB/range_doppler_echo/202509021530465441.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1052c81c1985ed7f272c091bf3b5077f2f0351d3c54499af5b0163087097cf30
+size 2097280

datasets/HiL-RED/barrage_wide_jamming_-15dB/transmit/transmitwave.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a116b381caa9593aba463f8b2052a9a697847ed712500926f0a87e5c5f846695
+size 6528

datasets/HiL-RED/barrage_wide_jamming_-20dB/annotations/dense/202509031652503690/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:86285a424c8d6fc828c492c7d6ae3a04f9ab9c224543207756a0a3cf03362135
+size 131200

datasets/HiL-RED/barrage_wide_jamming_-20dB/range_doppler_MTD/202509031652503690.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:99fdb906b04ba369c849b1ff75d6888b912fe19fac37a6c8065f667584337fba
+size 2097280

datasets/HiL-RED/barrage_wide_jamming_-20dB/range_doppler_echo/202509031652503690.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7a7259c589bdb9fc075a2374bf6b38317e64d96210d9737add52f97f127ff61e
+size 2097280

datasets/HiL-RED/barrage_wide_jamming_-20dB/transmit/transmitwave.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a116b381caa9593aba463f8b2052a9a697847ed712500926f0a87e5c5f846695
+size 6528

datasets/HiL-RED/data_seq_ref.json

@@ -0,0 +1,107 @@
+{
+    "deceptive_sli_jammer_-15dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "deceptive_sli_jammer_-20dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "deceptive_dft_jammer_-10dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "deceptive_isr_jammer_-15dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "barrage_wide_jamming_-10dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "deceptive_isr_jammer_-20dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "deceptive_dft_jammer_-15dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "barrage_narrow_jamming_-10dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "barrage_narrow_jamming_-15dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "barrage_wide_jamming_-20dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "deceptive_dft_jammer_-20dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "barrage_narrow_jamming_-20dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "deceptive_sli_jammer_-10dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "barrage_wide_jamming_-15dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    },
+    "deceptive_isr_jammer_-10dB": {
+        "split": [
+            "Train",
+            "Validation",
+            "Test"
+        ]
+    }
+}

datasets/HiL-RED/dataset_meta.json

@@ -0,0 +1,9 @@
+{
+  "display_name": "HiL-RED",
+  "full_name": "Hardware-in-the-Loop Radar Echo Dataset",
+  "scenario": "Target-jammer recognition under active electronic countermeasures",
+  "order": 2,
+  "mtd_fftshift": true,
+  "mtd_amp_dir": "range_doppler_MTD",
+  "valid_classes": [0, 1, 2, 3, 4, 5, 6]
+}

datasets/HiL-RED/deceptive_dft_jammer_-10dB/annotations/dense/202509092208275264/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b7b4beedcd2f094ca06da5f5834f47024358a3ad10e7f13216d3c702314afd36
+size 131200

datasets/HiL-RED/deceptive_dft_jammer_-10dB/range_doppler_MTD/202509092208275264.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1fc43c56366f3e99a3891d9e5e1939211cfecbf9a393db7acc1e5011f921546c
+size 2097280

datasets/HiL-RED/deceptive_dft_jammer_-10dB/range_doppler_echo/202509092208275264.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:983852934cdd8eeafe1b1653d35e51f2745fdf835ef33b42816b9625f5fc2b5b
+size 2097280

datasets/HiL-RED/deceptive_dft_jammer_-10dB/transmit/transmitwave.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a116b381caa9593aba463f8b2052a9a697847ed712500926f0a87e5c5f846695
+size 6528

datasets/HiL-RED/deceptive_dft_jammer_-15dB/annotations/dense/202509102013124057/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:52a1e70875b5d32ed657ea0414a4cb2736136b7837cf919c51dbfb58fbe36937
+size 131200

datasets/HiL-RED/deceptive_dft_jammer_-15dB/range_doppler_MTD/202509102013124057.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a020d43a63d006c93a472a7217a6a21591002c57fca058decc3ea530e6dfd8e4
+size 2097280

datasets/HiL-RED/deceptive_dft_jammer_-15dB/range_doppler_echo/202509102013124057.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:84fd1398de71cdce4cd8ca65d2c7acd8055eb62c9a0a5fa85b59328b53c8bb4d
+size 2097280

datasets/HiL-RED/deceptive_dft_jammer_-15dB/transmit/transmitwave.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a116b381caa9593aba463f8b2052a9a697847ed712500926f0a87e5c5f846695
+size 6528

datasets/HiL-RED/deceptive_dft_jammer_-20dB/annotations/dense/202509112218344171/range_doppler.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:721dad995d4d8bd62abf8b30ed566546b90d24016c70fb99ffb37724871395bc
+size 131200

datasets/HiL-RED/deceptive_dft_jammer_-20dB/range_doppler_MTD/202509112218344171.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:81f258c2b7d3a184882af14848de3d7c22edddeef07ee9f60e6b185bd39ef1c3
+size 2097280