Metadata-Version: 2.4
Name: spectraforce
Version: 0.1.1
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 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, Chandrabali Karmakar

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

## License
Proprietary (permission required for any use)
