Metadata-Version: 2.4
Name: muss_dataset
Version: 0.1.5
Summary: MUSS: Multimodal Satellite Dataset Builder (Sentinel-1/2)
Author-email: Yassine Gacha <yassine.crm.tn@gmail.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pyyaml
Requires-Dist: torch
Requires-Dist: torchgeo
Requires-Dist: rasterio
Requires-Dist: rioxarray
Requires-Dist: xarray
Requires-Dist: geopandas
Requires-Dist: shapely
Requires-Dist: pystac-client
Requires-Dist: planetary-computer
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: lightning
Requires-Dist: stackstac
Requires-Dist: zarr
Requires-Dist: matplotlib

# 🌍 MUSS — Multimodal Unified Satellite System

MUSS is a **dynamic dataset builder and modeling framework** for multimodal remote sensing.

It allows users to:

* 📡 Fetch satellite data (Sentinel-1, Sentinel-2, etc.)
* 🧠 Build datasets **on-the-fly**
* ⚡ Train deep learning models directly on generated data
* 🧩 Combine multiple modalities (optical, SAR, indices)

---

## 🚀 Key Features

* ⚡ **Dynamic dataset generation** (no pre-download required)
* 🛰️ Multi-source support (Sentinel-1, Sentinel-2, etc.)
* 🧠 Built-in preprocessing (tiling, reprojection, normalization)
* 📦 Torch-compatible datasets (`NonGeoDataset`)
* 🔄 Lazy / Cache / Prebuild modes
* 📊 Index-based learning (NDVI, NDWI, etc.)
* 🤖 Ready for deep learning (PyTorch + TorchGeo)

---

## 📁 Project Structure

```
.
├── README.md
├── pyproject.toml
├── requirements.txt
├── cache/                  # Generated tiles
├── dist/                   # Build artifacts
├── muss/
│   ├── builder/            # Dataset builder engine
│   ├── providers/          # STAC data providers
│   ├── datasets/           # Torch datasets
│   ├── processing/         # Preprocessing pipeline
│   ├── models/             # Deep learning models
│   ├── tiling/             # Spatial tiling logic
│   ├── storage/            # Cache management
│   ├── configs/            # YAML configs
│   └── test/
└── sample.png
```

---

## ⚙️ Installation

### Install from source

```
pip install -e .
```

### Build package

```
python -m build
```

### Install from PyPI (when published)

```
pip install muss-dataset
```

---

## 🧩 Configuration

Example config (`configs/config.yaml`):

```yaml
data:
  bbox: [lon_min, lat_min, lon_max, lat_max]
  resolution: 10
  time:
    start: "2022-01-01"
    end: "2022-12-31"

processing:
  temporal:
    method: median
  reprojection:
    target_crs: "EPSG:3857"
```

---

## 📡 Supported Providers

* Sentinel-2 (optical)
* Sentinel-1 (SAR)
* (optional) land cover datasets (e.g., WorldCover)

---

## 🏗️ Dataset Usage

```python
from muss.datasets import MussDataset
from torch.utils.data import DataLoader

dataset = MussDataset(
    config_file="configs/config.yaml",
    mode="lazy",  # lazy | cache-only | prebuild
)

loader = DataLoader(dataset, batch_size=8, num_workers=4)

for batch in loader:
    x = batch["image"]
    print(x.shape)
```

---

## 🧠 Training Example (Soft Labels)

```python
for batch in loader:
    x = batch["image"]

    y_soft = build_soft_labels(x)
    y_pred = model(x)

    loss = soft_cross_entropy(y_pred, y_soft)

    optimizer.zero_grad()
    loss.backward()
    optimizer.step()
```

---

## 📊 Indices-Based Learning

MUSS supports **weak supervision via remote sensing indices**:

* NDVI → vegetation
* NDWI → water
* SAR → structure

Soft labels are computed as:

```
Y* = sigmoid((I - μ) / σ)
```

---

## 🧠 Models

Inside `muss/models/`:

* Diffusion Residual Autoencoder (Diff-RAE)
* ResNet-based encoders/decoders

---

## ⚡ Build Dataset CLI

```
muss-build --config configs/config.yaml
```

This will:

* Query STAC API
* Download data
* Build tiles
* Cache results

---

## 📦 Modes

| Mode       | Description             |
| ---------- | ----------------------- |
| lazy       | build on demand         |
| cache-only | use existing tiles only |
| prebuild   | build all tiles first   |

---

## ⚠️ Known Issues

* STAC API rate limits (Planetary Computer)
* CRS missing in some Sentinel-1 items (use sentinel-1-rtc)
* Tile size mismatch (must enforce fixed size)

---

## 🛠️ Requirements

* Python ≥ 3.10
* PyTorch
* TorchGeo
* xarray
* rasterio
* stackstac
* pystac-client

---

## 📸 Example Output

![Sample](sample.png)

---

## 🤝 Contributing

Contributions are welcome:

* new providers
* new models
* performance optimizations

---

## 📜 License

MIT License

---

## 🚀 Roadmap

* [ ] More datasets (Dynamic World, Landsat)
* [ ] Distributed tile building
* [ ] Cloud-native training
* [ ] HuggingFace integration

---

## 👤 Author

Developed as part of a research project DroMUPS.
Dr. Yassine Gacha

---
