# SpectraForge

A premium desktop workstation for **Earth observation processing and visualization** across sensors. Unsupervised segmentation and uncertainty are optional modules inside a much broader EO workflow. Built to run locally on Windows/macOS/Linux.

## Why it exists
- **Multi-sensor preprocessing** (Sentinel‑1/2/3, Landsat, ERA5, ENMAP, hyperspectral, PlanetScope, UAV)
- **Band management and index generation** for fast EO analysis
- **Interactive ROI labeling** for ground‑truthing and validation
- **Optional unsupervised segmentation** with probability maps and uncertainty
- **Designed for patent-ready workflows** (keep private until filing)

## Features (v1)
- Clean, modern studio UI (not a QGIS clone)
- GeoTIFF, NetCDF, ENVI (hyperspectral), Sentinel‑2 folder support
- Sensor presets (Sentinel‑1/2/3, Landsat, PlanetScope, UAV, ERA5, ENMAP, hyperspectral)
- Auto feature selection across multi-band data
- Unsupervised segmentation with probability maps and entropy-based uncertainty (optional)
- Index Builder with curated indices per sensor + custom JSON/YAML recipes
- ROI selection + cluster labeling workflow
- Run history saved to `runs/`
- Copernicus + Planet API panels (offline stub in this build)

## Install

From PyPI:

```bash
python -m pip install spectraforce
```

From source:

```bash
python -m pip install -r requirements.txt
```

## Run

```bash
spectraforge
```

Alternative:

```bash
python -m spectraforge
```

## Data formats
- **GeoTIFF**: `.tif`, `.tiff`
- **NetCDF**: `.nc` (ERA5 and other gridded products)
- **ENVI**: `.hdr` + `.img` (hyperspectral)
- **Sentinel‑2**: SAFE folder with `.jp2` band files
- **NumPy**: `.npy` arrays (2D or 3D)
- **Tabular**: `.csv`, `.xlsx`

## Indices
SpectraForge ships with curated indices (NDVI, NDWI, etc.) per sensor. You can add your own:

- JSON/YAML recipe files (see `samples/` for examples)
- Index layers appear in the layer stack like any other band
Example custom indices file: `samples/indices_example.json`

## NPY export
Export data to `.npy` directly from the UI:

- All bands in one file
- Selected bands in one file
- Individual band files
- Optional index layer exports
## Offline samples
Synthetic samples live in `samples/` so the repo runs without downloads.
Real cropped samples live in `samples/real/`.
Manipur example outputs live in `samples/manipur/`.

## API keys (stored locally)
API keys are stored in `~/.spectraforge/config.json` on your machine.

## Why I Use SpectraForge
I use SpectraForge when I want a fast, repeatable path from raw EO images to clean indices, analysis layers, and exportable outputs. I need it because I do not want to rebuild custom scripts for every dataset. It saves me time because I can run the same workflow across sensors and get consistent results. I use it easily by loading a folder, letting the app auto detect bands, choosing indices, and optionally running unsupervised segmentation with ROI labeling when I need it.

## Step by Step Outputs for Manipur Sentinel‑2
I ran the full pipeline on real Sentinel‑2 data from Manipur and saved the outputs below.

**Step 1 — Load bands and true color**
<p align="center"><img src="docs/screenshots/manipur_full/manipur_full_truecolor.png" alt="Manipur True Color" width="520"></p>

**Step 2 — NDVI and NDWI indices**
<table>
  <tr>
    <td><img src="docs/screenshots/manipur_full/manipur_full_ndvi.png" alt="Manipur NDVI" width="400"><br><em>NDVI</em></td>
    <td><img src="docs/screenshots/manipur_full/manipur_full_ndwi.png" alt="Manipur NDWI" width="400"><br><em>NDWI</em></td>
  </tr>
</table>

**Step 3 — Unsupervised segmentation with 8 clusters**
<p align="center"><img src="docs/screenshots/manipur_full/manipur_full_seg_labels.png" alt="Manipur Segmentation Labels" width="480"></p>

**Step 4 — ROI selection and labeling**
<table>
  <tr>
    <td><img src="docs/screenshots/manipur_full/manipur_full_roi_overlay.png" alt="Manipur ROI Overlay" width="400"><br><em>ROI overlay</em></td>
    <td><img src="docs/screenshots/manipur_full/manipur_full_roi_labels.png" alt="Manipur ROI Labels" width="400"><br><em>ROI labels</em></td>
  </tr>
</table>

**Step 5 — Uncertainty and confidence**
I use the same color rule for both maps: blue means low, red means high.  
For uncertainty, blue means low uncertainty and red means high uncertainty.  
For confidence, blue means low confidence and red means high confidence.
<table>
  <tr>
    <td><img src="docs/screenshots/manipur_full/manipur_full_seg_uncertainty.png" alt="Manipur Segmentation Uncertainty" width="400"><br><em>Uncertainty</em></td>
    <td><img src="docs/screenshots/manipur_full/manipur_full_seg_confidence.png" alt="Manipur Segmentation Confidence" width="400"><br><em>Confidence</em></td>
  </tr>
</table>

**Saved outputs full resolution**
- `samples/manipur_full/manipur_full_stack.npy`
- `samples/manipur_full/manipur_full_stack_preview.tif`
- `samples/manipur_full/manipur_full_<index>.npy`
- `samples/manipur_full/manipur_full_<index>.tif`

## Color Legend for segmentation labels
Clusters are **unsupervised**. Colors map to cluster IDs in order:

- `0` → maroon `#800000`
- `1` → darkblue `#00008B`
- `2` → darkgreen `#006400`
- `3` → cyan `#00FFFF`
- `4` → darkcyan `#008B8B`
- `5` → magenta `#FF00FF`
- `6` → indigo `#4B0082`
- `7` → grey `#808080`
- `8` → peru `#CD853F`
- `9` → slateblue `#6A5ACD`
- `10` → mediumspringgreen `#00FA9A`
- `11` → orangered `#FF4500`

If you run fewer than 12 clusters, only the first N colors are used.

## Color Notes for indices
Index quicklooks use a **viridis** scale:
brighter colors indicate higher values.

## Uncertainty calibration made easy
- Run segmentation → get probability maps (`predict_proba`)
- Use entropy + confidence to visualize uncertain regions
- Assign labels with ROI selections (no labeled data required)

## Segmentation engine
If your environment has scientific stack conflicts, switch the engine to **Safe mode** in the UI.  
Fast mode uses scikit‑learn when available.

## SpectraForge vs QGIS (Pros & Cons)
| Aspect | SpectraForge | QGIS |
| --- | --- | --- |
| Focus | EO segmentation + indices + uncertainty | Full GIS for all domains |
| Setup | One command local run | Heavier install + plugins |
| Unsupervised segmentation + uncertainty | Built‑in, turnkey | Requires plugins/workflows |
| Indices | Curated EO indices + custom recipes | Many tools, but more manual setup |
| UI style | Modern studio layout (not QGIS style) | Traditional GIS layout |
| Extensibility | Focused feature set | Huge plugin ecosystem |
| Geoprocessing breadth | Focused EO analytics | Broad GIS toolbox |
| Best for | Fast EO segmentation + research demos | Full GIS analysis & cartography |

**Pros of SpectraForge:** fast EO‑first workflow, built‑in uncertainty, simple NPY export, easy to demo.  
**Cons vs QGIS:** fewer GIS tools, smaller plugin ecosystem, less advanced cartography.

## Contributions
See `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md`.

## Credits
Arnab Bhowmik

## How to cite
If you use SpectraForge in academic work, please cite it like this:

```
Arnab Bhowmik. SpectraForge: Earth Observation Processing and Visualization Toolkit. Version 0.1.3, 2026. https://github.com/ArnaBannonymus/SpectraForge
```

BibTeX:

```bibtex
@software{spectraforge_2026,
  author = {Bhowmik, Arnab},
  title = {SpectraForge: Earth Observation Processing and Visualization Toolkit},
  year = {2026},
  version = {0.1.3},
  url = {https://github.com/ArnaBannonymus/SpectraForge}
}
```

## Privacy note
Runs locally. No data leaves your machine.

## License
Proprietary (permission required for any use)
