🌍 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):

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

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)

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

---

🤝 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

---