Quantifying the Evidence for Each Class in Unsupervised UAV Hyperspectral Mapping of Coastal Macroalgae

Official repository for the manuscript:

Quantifying the Evidence for Each Class in Unsupervised UAV Hyperspectral Mapping of Coastal Macroalgae
Pedro Orgeira Crespo, Fernando Aguado Agelet, Marcos Quiroga Rodríguez
atlanTTic Research Center & Telecommunication Engineering School / Escola de Enxeñaría Aeroespacial, Universidade de Vigo
Submitted to Remote Sensing (MDPI), 2026.

---

Overview

Unsupervised unmixing provides an automated route to coastal cover mapping when field reference spectra are unavailable. However, standard geometric endmember extractors (such as VCA) return as many classes as requested without providing statistical evidence for their stability or completeness.

This repository provides the complete, self-contained Python pipeline and Typst paper source for:

1. Consensus Endmember Extraction: Evaluating endmember recovery frequency over $R = 30$ half-sample replicates.
2. Model Adequacy & Residual Closure: Using the per-pixel FCLS reconstruction residual to detect and repair incomplete endmember sets (e.g., missing open water).
3. Composition-Resolved Cover: Weighting endmember abundance fractions by internal spectral composition rather than reading raw footprint max-abundance maps.

---

Repository Structure

├── mdpi-report/                # Typst manuscript source & figures
│   ├── main.typ                # Main manuscript document
│   ├── references.bib          # Bibliography database
│   ├── mdpi_template.typ       # MDPI journal layout template
│   └── figures/                # Output directory for generated figures and CSV tables
│
├── scripts/                    # Reproduction pipeline & core algorithms
│   ├── run_all.py              # End-to-end figure and table generator runner
│   ├── 01_overview.py          # Fig. 1: True-colour orthomosaic & spectral profile
│   ├── 02_mnf.py               # Figs. 2–3: MNF scree plot & eigenimages
│   ├── 03_indices.py           # Fig. 4: Radiometric index stack & NDVI reference
│   ├── 04_endmembers.py        # Figs. 5–6 & Table 3: Consensus endmember spectra & angles
│   ├── 05_abundance.py         # Figs. 7–8 & Table 4: FCLS abundance maps
│   ├── 06_classify_areas.py    # Hard classification & per-class area reporting
│   ├── 07_ablation.py          # Synthetic extraction ablation benchmark (Section 4.7)
│   ├── 08_tiles.py             # Spatial extent / tile partitioning analysis (Section 5.1)
│   ├── 09_stratification.py    # Paired index-stratification test (Section 4.8)
│   ├── 10_baseline_sam.py      # SAM baseline classifier comparison (Section 5.2)
│   ├── 11_consensus_rmse.py    # Synthetic mixture FCLS validation (Section 3.6)
│   ├── 12_material_cover.py    # Endmember completeness repair & composition-resolved cover
│   ├── build_field_figure.py   # Field campaign montage generator
│   └── algadron_hsi/           # Core Python package
│       ├── io.py               # Streaming ENVI BIP reader
│       ├── mnf.py              # Shift-difference noise-whitened MNF transform
│       ├── indices.py          # Radiometric index calculations
│       ├── unmixing.py         # VCA & FCLS solvers
│       ├── consensus.py        # Half-sample resample consensus extractor
│       ├── separability.py     # Pairwise spectral angle metrics
│       ├── synthetic.py        # Synthetic scene generator
│       └── viz.py              # Plotting style & display helpers
│
├── pyproject.toml              # Dependencies and package metadata
└── README.md                   # Repository documentation

---

Setup & Requirements

The project uses Python 3.10+ and standard numerical libraries (numpy, scipy, matplotlib, scikit-learn). We recommend using uv for fast environment management:

uv sync

Alternatively, install via standard pip:

pip install numpy scipy matplotlib scikit-learn pillow typst

---

Reproducing Manuscript Results

1. Generating Manuscript Figures and Tables

Run the pipeline against an ENVI Band-Interleaved-by-Pixel (.bip.hdr) orthomosaic cube:

cd scripts
uv run python run_all.py --input path/to/scene.bip.hdr

This sequentially executes stages 01 through 06, rendering figure PNGs and CSV tables directly into mdpi-report/figures/.

2. Endmember Completeness & Material Cover Repair

To evaluate reconstruction residual closure and derive composition-resolved vegetated cover:

uv run python 12_material_cover.py --input path/to/scene.bip.hdr

3. Synthetic Benchmark Experiments

To run the extraction ablation, tile partitioning, stratification, and SAM baseline comparisons reported in the paper (still from scripts/):

uv run python 07_ablation.py
uv run python 08_tiles.py --input path/to/scene.bip.hdr
uv run python 09_stratification.py
uv run python 10_baseline_sam.py --input path/to/scene.bip.hdr
uv run python 11_consensus_rmse.py

4. Compiling the Typst Manuscript

To compile the manuscript PDF using Typst:

cd mdpi-report
typst compile main.typ paper.pdf

---

Data Availability

The processing pipeline streams large ENVI BIP hyperspectral cubes in fixed $O(B^2)$ memory blocks. Hyperspectral orthomosaics analyzed in this study (Praia da Ladeira, Baiona, Spain) are available upon reasonable request from the corresponding author.

---

License

This software and reproducible pipeline are released under the MIT License.