Metadata-Version: 2.4
Name: spectraforce
Version: 0.1.0
Summary: Premium desktop workstation for Earth observation segmentation.
Author: SpectraForge
License: SpectraForge Proprietary License
        
        Copyright (c) 2026 ArnaBannonymus
        All rights reserved.
        
        This software and associated documentation files (the "Software") are
        proprietary and confidential. No part of the Software may be used, copied,
        modified, merged, published, distributed, sublicensed, or sold without
        explicit prior written permission from the copyright holder.
        
        Any unauthorized use of the Software is strictly prohibited.
        
        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.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6
Requires-Dist: numpy<2.2,>=1.23
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: pillow
Requires-Dist: rasterio
Requires-Dist: xarray
Requires-Dist: rioxarray
Requires-Dist: netCDF4
Requires-Dist: spectral
Requires-Dist: pyyaml
Dynamic: license-file

# SpectraForge

A premium desktop workstation for Earth observation segmentation with **GMM + uncertainty**, multi-sensor feature selection, and interactive ROI labeling. Built to run locally on Windows/macOS/Linux.

## Why it exists
- **Multi-sensor preprocessing** (Sentinel‑1/2/3, Landsat, ERA5, ENMAP, hyperspectral, PlanetScope, UAV)
- **GMM segmentation** with `predict_proba` and uncertainty maps
- **Interactive ROI labeling** to refine clusters or assign human labels
- **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
- GMM segmentation with probability maps and entropy-based uncertainty
- 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 satellite data to clean indices, segmentation, and uncertainty maps. 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, running GMM, and labeling ROIs in one place.

## 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 — GMM segmentation with 8 clusters**
<p align="center"><img src="docs/screenshots/manipur_full/manipur_full_gmm_labels.png" alt="Manipur GMM 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_gmm_uncertainty.png" alt="Manipur GMM Uncertainty" width="400"><br><em>Uncertainty</em></td>
    <td><img src="docs/screenshots/manipur_full/manipur_full_gmm_confidence.png" alt="Manipur GMM 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 GMM 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 GMM → get `predict_proba`
- Use entropy + confidence to visualize uncertain regions
- Assign labels with ROI selections (no labeled data required)

## GMM 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 |
| GMM + 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`.

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

## License
Proprietary (permission required for any use)
