Add English Hugging Face model card and configuration

.gitattributes

@@ -1,35 +1,13 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
 *.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
 *.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
 *.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
 *.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,177 @@
+---
+frameworks: PyTorch
+language:
+- en
+license: apache-2.0
+tags:
+- OneScience
+- Earth Science
+- Remote Sensing
+- Multi-Modal Remote Sensing
+- Semantic Segmentation
+- SkySense
+- arxiv:2312.10115
+tasks: []
+datasets: []
+---
+<p align="center">
+  <strong>
+    <span style="font-size: 30px;">SkySense</span>
+  </strong>
+</p>
+
+# Model Introduction
+
+SkySense is a multi-modal and temporal remote sensing foundation model for universal Earth observation interpretation. It jointly models high-resolution optical imagery, Sentinel-2 multispectral time series, Sentinel-1 SAR time series, and geographic context to provide unified representations for remote sensing classification, segmentation, detection, and change detection.
+
+Paper: SkySense: A Multi-Modal Remote Sensing Foundation Model Towards Universal Interpretation for Earth Observation Imagery
+
+https://arxiv.org/abs/2312.10115
+
+# Model Description
+
+SkySense was proposed by Ant Group, Wuhan University, and MYbank. The original model was trained on 21.5 million groups of high-resolution optical, Sentinel-2 multispectral, and Sentinel-1 SAR temporal samples, and is suitable for single-modal or multi-modal, static or temporal remote sensing classification and localization tasks.
+
+# Use Cases
+
+| Scenario | Description |
+| :---: | :--- |
+| Multi-modal remote sensing representation training | Train SkySense with multi-modal temporal remote sensing image data. |
+| Remote sensing image semantic segmentation | Fuse optical, multispectral, and SAR features to predict land-cover classes for image pixels. |
+| Local quick validation | Use synthetic data to validate data loading, training, inference, evaluation, and visualization. |
+| Hugging Face / OneCode execution | Download the standalone model package, install dependencies, and run the scripts directly. |
+| Multi-GPU training | Launch distributed multi-process training with `torchrun`. |
+
+# Usage Guide
+
+## 1. OneCode Usage
+
+Experience intelligent one-click AI4S programming through the OneCode online environment:
+
+[Click to Experience Intelligent One-Click AI4S Programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)
+
+## 2. Manual Installation and Usage
+
+**Hardware Requirements**
+
+- A GPU or DCU is recommended.
+- CPU can be used for import and small-scale connectivity verification; full training and inference will be slower.
+- DCU users must install DTK in advance. DTK 25.04.2 or above, or the OneScience recommended version matching the cluster, is recommended.
+
+### Download the Model Package
+
+```bash
+hf download OneScience-Group/SkySense --local-dir ./SkySense
+cd SkySense
+```
+
+### Install the Runtime Environment
+
+**DCU Environment**
+
+```bash
+# Please activate DTK and CONDA first
+conda create -n onescience311 python=3.11 -y
+conda activate onescience311
+# uv installation is supported
+pip install onescience[earth-dcu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
+```
+
+**GPU Environment**
+
+```bash
+# Please activate CONDA first
+conda create -n onescience311 python=3.11 -y libstdcxx-ng=12 libgcc-ng=12 gcc_linux-64=12 gxx_linux-64=12
+conda activate onescience311
+# uv installation is supported
+pip install onescience[earth-gpu] -i http://mirrors.onescience.ai:3141/pypi/simple/ --trusted-host mirrors.onescience.ai
+```
+
+### Training Data Introduction
+
+The original SkySense pretraining collection contains about 21.5 million spatially registered multi-modal remote sensing samples. It includes high-resolution optical imagery, Sentinel-2 multispectral temporal imagery, Sentinel-1 SAR temporal imagery, acquisition dates, geographic region information, and downstream task labels. The complete registered pretraining collection is not publicly available from the authors, and it is not included in this model repository.
+
+Original data sources include Sentinel-1 and Sentinel-2 products available through Copernicus Data Space and commercial high-resolution imagery such as WorldView. Users must follow the applicable data licenses and independently complete cloud filtering, radiometric processing, spatial registration, resampling, cropping, normalization, and label preparation.
+
+The default local validation uses synthetic NPZ data:
+
+```bash
+python scripts/fake_data.py
+```
+
+The command creates 24 training samples and 8 test samples. Synthetic data is used only to validate the complete training, inference, evaluation, and visualization pipeline. Synthetic results are not reported as model performance and do not reproduce the paper experiments.
+
+For real-data training, prepare the corresponding multi-modal samples in the format expected by the scripts, save them under `data/`, update the data and model settings in `conf/config.yaml`, and use the same `scripts/train.py`. Do not run `scripts/fake_data.py` when using real data.
+
+### Training
+
+Synthetic-data quick validation:
+
+```bash
+python scripts/fake_data.py
+python scripts/train.py
+```
+
+Single GPU or CPU:
+
+```bash
+python scripts/train.py
+```
+
+Multi-GPU:
+
+```bash
+torchrun --nproc_per_node=8 --nnodes=1 --rdzv_id=1000 --rdzv_backend=c10d --max_restarts=0 --master_addr="localhost" --master_port=29500 scripts/train.py
+```
+
+Training outputs:
+
+```text
+result/checkpoints/skysense.pt
+result/training/metrics.json
+```
+
+### Training Weights
+
+Pretrained weights based on multi-modal temporal remote sensing data will be provided under `weight/`. The weight file will be uploaded in a future update. Checkpoints generated from synthetic data are only for pipeline validation and do not provide real remote sensing interpretation capability.
+
+### Inference
+
+```bash
+python scripts/inference.py
+```
+
+Inference reads `data/test.npz` and `result/checkpoints/skysense.pt`. Test data must use the same channel order, normalization, spatial size, region mapping, and class definition as the training data.
+
+Prediction output:
+
+```text
+result/output/
+```
+
+### Evaluation and Visualization
+
+```bash
+python scripts/result.py
+```
+
+Evaluation and visualization outputs:
+
+```text
+result/evaluation/metrics.json
+result/evaluation/comparison.png
+```
+
+For synthetic data, evaluation outputs only confirm that the evaluation and visualization pipeline can run successfully. They are not reported as model performance. For real data, the metrics represent supervised semantic segmentation performance on the user-provided test set and are not equivalent to the complete 21.5-million-sample pretraining evaluation in the paper.
+
+# Official OneScience Resources
+
+| Platform | OneScience Main Repository | Skills Repository |
+| --- | --- | --- |
+| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
+| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |
+
+# Citation and License
+
+- This repository is a reproduction of the original SkySense paper.
+- The reproduction code is released under Apache License 2.0. The original datasets and official model weights remain subject to their respective source licenses.

conf/config.yaml

@@ -0,0 +1,32 @@
+seed: 42
+data:
+  root: data
+  protocol: synthetic_skysense_npz
+  train_samples: 24
+  test_samples: 8
+  image_size: 32
+  num_classes: 6
+  hr_channels: 3
+  s2_channels: 10
+  s1_channels: 2
+  s2_timesteps: 4
+  s1_timesteps: 3
+model:
+  embed_dim: 32
+  patch_size: 4
+  temporal_depth: 2
+  temporal_heads: 4
+  num_regions: 16
+  prototypes_per_region: 4
+train:
+  epochs: 3
+  batch_size: 4
+  learning_rate: 0.001
+  weight_decay: 0.0001
+  alignment_weight: 0.05
+  num_workers: 0
+paths:
+  checkpoint: result/checkpoints/skysense.pt
+  training_metrics: result/training/metrics.json
+  inference_dir: result/output
+  evaluation_dir: result/evaluation

config.json

@@ -0,0 +1,45 @@
+{
+  "model_name": "SkySense",
+  "model_type": "skysense",
+  "architectures": [
+    "SkySense"
+  ],
+  "framework": "PyTorch",
+  "domain": "earth-science",
+  "task": "remote-sensing-multimodal-semantic-segmentation",
+  "implementation": {
+    "entry_point": "model/skysense.py",
+    "scope": "compact multi-modal temporal SkySense reproduction"
+  },
+  "architecture": {
+    "family": "multi-modal temporal remote sensing encoder",
+    "input_format": "NPZ multimodal temporal arrays",
+    "modalities": [
+      "high-resolution RGB",
+      "Sentinel-2 multispectral",
+      "Sentinel-1 SAR"
+    ],
+    "image_size": 32,
+    "embed_dim": 32,
+    "patch_size": 4,
+    "temporal_depth": 2,
+    "temporal_heads": 4,
+    "task": "semantic segmentation"
+  },
+  "data": {
+    "dataset": "SkySense pretraining data",
+    "official_paper": "https://arxiv.org/abs/2312.10115",
+    "protocol": "synthetic_skysense_npz",
+    "synthetic_train_samples": 24,
+    "synthetic_test_samples": 8
+  },
+  "metrics": [
+    "pixel_accuracy",
+    "mean_iou",
+    "per_class_iou"
+  ],
+  "configuration_sources": [
+    "conf/config.yaml",
+    "model/skysense.py"
+  ]
+}

configuration.json

@@ -0,0 +1,12 @@
+{
+  "framework": "PyTorch",
+  "task": "remote_sensing_semantic_segmentation",
+  "model": "SkySense",
+  "input_format": "multimodal_npz",
+  "protocol": "synthetic_skysense_npz",
+  "default_config": "conf/config.yaml",
+  "train": "scripts/train.py",
+  "inference": "scripts/inference.py",
+  "evaluation": "scripts/result.py",
+  "visualization": "scripts/result.py"
+}

model/skysense.py

@@ -0,0 +1,107 @@
+"""Compact, trainable SkySense reproduction for multi-modal remote sensing data."""
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+
+class SpatialEncoder(nn.Module):
+    def __init__(self, in_channels, embed_dim, patch_size):
+        super().__init__()
+        self.projection = nn.Sequential(
+            nn.Conv2d(in_channels, embed_dim, patch_size, patch_size),
+            nn.GELU(),
+            nn.Conv2d(embed_dim, embed_dim, 3, padding=1),
+            nn.GELU(),
+        )
+
+    def forward(self, images):
+        batch, time, channels, height, width = images.shape
+        features = self.projection(images.reshape(batch * time, channels, height, width))
+        _, dim, out_height, out_width = features.shape
+        return features.reshape(batch, time, dim, out_height, out_width)
+
+
+class SkySense(nn.Module):
+    """Factorized spatial-temporal encoder with geo-context prototypes."""
+
+    def __init__(
+        self,
+        hr_channels=3,
+        s2_channels=10,
+        s1_channels=2,
+        embed_dim=32,
+        patch_size=4,
+        temporal_depth=2,
+        temporal_heads=4,
+        num_regions=16,
+        prototypes_per_region=4,
+        num_classes=6,
+    ):
+        super().__init__()
+        self.patch_size = patch_size
+        self.num_regions = num_regions
+        self.hr_encoder = SpatialEncoder(hr_channels, embed_dim, patch_size)
+        self.s2_encoder = SpatialEncoder(s2_channels, embed_dim, patch_size)
+        self.s1_encoder = SpatialEncoder(s1_channels, embed_dim, patch_size)
+        self.date_embedding = nn.Embedding(366, embed_dim)
+        self.modality_embedding = nn.Parameter(torch.zeros(3, embed_dim))
+        self.fusion_token = nn.Parameter(torch.zeros(1, 1, embed_dim))
+        layer = nn.TransformerEncoderLayer(
+            d_model=embed_dim,
+            nhead=temporal_heads,
+            dim_feedforward=embed_dim * 4,
+            dropout=0.0,
+            activation="gelu",
+            batch_first=True,
+            norm_first=True,
+        )
+        self.temporal_fusion = nn.TransformerEncoder(layer, temporal_depth)
+        self.prototypes = nn.Parameter(
+            torch.randn(num_regions, prototypes_per_region, embed_dim) * 0.02
+        )
+        self.decoder = nn.Sequential(
+            nn.Conv2d(embed_dim * 2, embed_dim, 3, padding=1),
+            nn.GELU(),
+            nn.Conv2d(embed_dim, num_classes, 1),
+        )
+        nn.init.normal_(self.date_embedding.weight, std=0.02)
+        nn.init.normal_(self.modality_embedding, std=0.02)
+        nn.init.normal_(self.fusion_token, std=0.02)
+
+    def _add_context(self, features, dates, modality_index):
+        date_context = self.date_embedding(dates.clamp(0, 365)).unsqueeze(-1).unsqueeze(-1)
+        modality = self.modality_embedding[modality_index].view(1, 1, -1, 1, 1)
+        return features + date_context + modality
+
+    def encode_modalities(self, hr, s2, s1, dates_hr, dates_s2, dates_s1):
+        return (
+            self._add_context(self.hr_encoder(hr), dates_hr, 0),
+            self._add_context(self.s2_encoder(s2), dates_s2, 1),
+            self._add_context(self.s1_encoder(s1), dates_s1, 2),
+        )
+
+    def forward(self, hr, s2, s1, dates_hr, dates_s2, dates_s1, region):
+        modality_features = self.encode_modalities(hr, s2, s1, dates_hr, dates_s2, dates_s1)
+        temporal = torch.cat(modality_features, dim=1)
+        batch, time, dim, out_height, out_width = temporal.shape
+        temporal = temporal.permute(0, 3, 4, 1, 2).reshape(-1, time, dim)
+        token = self.fusion_token.expand(temporal.shape[0], -1, -1)
+        fused = self.temporal_fusion(torch.cat([token, temporal], dim=1))[:, 0]
+        fused = fused.reshape(batch, out_height, out_width, dim)
+
+        regional_prototypes = self.prototypes[region.remainder(self.num_regions)]
+        query = F.normalize(fused, dim=-1)
+        keys = F.normalize(regional_prototypes, dim=-1)
+        attention = torch.einsum("bhwd,bpd->bhwp", query, keys).softmax(dim=-1)
+        geo_context = torch.einsum("bhwp,bpd->bhwd", attention, regional_prototypes)
+        output = torch.cat([fused, geo_context], dim=-1).permute(0, 3, 1, 2)
+        logits = self.decoder(output)
+        logits = F.interpolate(logits, size=hr.shape[-2:], mode="bilinear", align_corners=False)
+        return {"logits": logits, "features": modality_features, "fused": fused}
+
+    @staticmethod
+    def cross_modal_alignment_loss(features):
+        pooled = [F.normalize(feature.mean(dim=(1, 3, 4)), dim=-1) for feature in features]
+        losses = [1.0 - (pooled[i] * pooled[j]).sum(dim=-1).mean() for i in range(3) for j in range(i + 1, 3)]
+        return torch.stack(losses).mean()

scripts/fake_data.py

@@ -0,0 +1,66 @@
+"""Generate deterministic SkySense-format data for connectivity tests."""
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_config():
+    with (ROOT / "conf" / "config.yaml").open(encoding="utf-8") as handle:
+        return yaml.safe_load(handle)
+
+
+def make_split(path, count, config, seed):
+    rng = np.random.default_rng(seed)
+    data = config["data"]
+    size = data["image_size"]
+    hr = rng.normal(size=(count, 1, data["hr_channels"], size, size)).astype("float32")
+    s2 = rng.normal(size=(count, data["s2_timesteps"], data["s2_channels"], size, size)).astype("float32")
+    s1 = rng.normal(size=(count, data["s1_timesteps"], data["s1_channels"], size, size)).astype("float32")
+    dates_hr = rng.integers(0, 365, size=(count, 1), dtype=np.int64)
+    dates_s2 = rng.integers(0, 365, size=(count, data["s2_timesteps"]), dtype=np.int64)
+    dates_s1 = rng.integers(0, 365, size=(count, data["s1_timesteps"]), dtype=np.int64)
+    region = rng.integers(0, config["model"]["num_regions"], size=count, dtype=np.int64)
+    signal = hr[:, 0, 0] + 0.35 * s2[:, :, 3].mean(axis=1) - 0.2 * s1[:, :, 0].mean(axis=1)
+    bins = np.quantile(signal, np.linspace(0, 1, data["num_classes"] + 1)[1:-1])
+    labels = np.digitize(signal, bins).astype(np.int64)
+    np.savez_compressed(
+        path,
+        hr=hr,
+        s2=s2,
+        s1=s1,
+        dates_hr=dates_hr,
+        dates_s2=dates_s2,
+        dates_s1=dates_s1,
+        region=region,
+        labels=labels,
+        data_source=np.asarray("synthetic"),
+        protocol=np.asarray(config["data"]["protocol"]),
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args()
+    config = load_config()
+    data_dir = ROOT / config["data"]["root"]
+    data_dir.mkdir(parents=True, exist_ok=True)
+    outputs = [("train.npz", config["data"]["train_samples"]), ("test.npz", config["data"]["test_samples"])]
+    for offset, (name, count) in enumerate(outputs):
+        target = data_dir / name
+        if args.force or not target.exists():
+            make_split(target, count, config, config["seed"] + offset)
+        print(
+            f"generated={target.relative_to(ROOT)} samples={count} "
+            f"data_source=synthetic protocol={config['data']['protocol']}"
+        )
+
+
+if __name__ == "__main__":
+    main()

scripts/inference.py

@@ -0,0 +1,69 @@
+"""Run SkySense inference and save arrays for evaluation."""
+
+import importlib.util
+from pathlib import Path
+
+import numpy as np
+import torch
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_model_class():
+    spec = importlib.util.spec_from_file_location("skysense_model", ROOT / "model" / "skysense.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.SkySense
+
+
+def main():
+    with (ROOT / "conf" / "config.yaml").open(encoding="utf-8") as handle:
+        config = yaml.safe_load(handle)
+    checkpoint_path = ROOT / config["paths"]["checkpoint"]
+    if not checkpoint_path.exists():
+        raise FileNotFoundError(
+            f"Missing checkpoint: {checkpoint_path.relative_to(ROOT)}. "
+            "Run `python scripts/train.py` first."
+        )
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    checkpoint = torch.load(checkpoint_path, map_location=device, weights_only=False)
+    SkySense = load_model_class()
+    model = SkySense(
+        **config["model"],
+        hr_channels=config["data"]["hr_channels"],
+        s2_channels=config["data"]["s2_channels"],
+        s1_channels=config["data"]["s1_channels"],
+        num_classes=config["data"]["num_classes"],
+    ).to(device)
+    model.load_state_dict(checkpoint["model"])
+    model.eval()
+    test_path = ROOT / config["data"]["root"] / "test.npz"
+    if not test_path.exists():
+        raise FileNotFoundError(
+            f"Missing inference data: {test_path.relative_to(ROOT)}. "
+            "Run `python scripts/fake_data.py` first."
+        )
+    archive = np.load(test_path)
+    keys = ["hr", "s2", "s1", "dates_hr", "dates_s2", "dates_s1", "region"]
+    tensors = {key: torch.from_numpy(archive[key]).to(device) for key in keys}
+    with torch.inference_mode():
+        output = model(tensors["hr"], tensors["s2"], tensors["s1"], tensors["dates_hr"], tensors["dates_s2"], tensors["dates_s1"], tensors["region"])
+        probabilities = output["logits"].softmax(dim=1)
+    output_dir = ROOT / config["paths"]["inference_dir"]
+    output_dir.mkdir(parents=True, exist_ok=True)
+    np.save(output_dir / "predictions.npy", probabilities.argmax(dim=1).cpu().numpy())
+    np.save(output_dir / "probabilities.npy", probabilities.cpu().numpy())
+    np.save(output_dir / "targets.npy", archive["labels"])
+    data_source = str(archive["data_source"]) if "data_source" in archive.files else "unknown"
+    protocol = str(archive["protocol"]) if "protocol" in archive.files else "unknown"
+    np.savez(output_dir / "metadata.npz", data_source=data_source, protocol=protocol)
+    print(
+        f"output={output_dir.relative_to(ROOT)} samples={len(archive['hr'])} "
+        f"data_source={data_source} protocol={protocol}"
+    )
+
+
+if __name__ == "__main__":
+    main()

scripts/result.py

@@ -0,0 +1,64 @@
+"""Evaluate semantic predictions and render a compact comparison image."""
+
+import json
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def main():
+    with (ROOT / "conf" / "config.yaml").open(encoding="utf-8") as handle:
+        config = yaml.safe_load(handle)
+    input_dir = ROOT / config["paths"]["inference_dir"]
+    required = [input_dir / "predictions.npy", input_dir / "targets.npy"]
+    missing = [str(path.relative_to(ROOT)) for path in required if not path.exists()]
+    if missing:
+        raise FileNotFoundError(
+            f"Missing inference outputs: {missing}. Run `python scripts/inference.py` first."
+        )
+    predictions = np.load(input_dir / "predictions.npy")
+    targets = np.load(input_dir / "targets.npy")
+    classes = config["data"]["num_classes"]
+    intersections = np.zeros(classes, dtype=np.float64)
+    unions = np.zeros(classes, dtype=np.float64)
+    for class_id in range(classes):
+        predicted = predictions == class_id
+        expected = targets == class_id
+        intersections[class_id] = np.logical_and(predicted, expected).sum()
+        unions[class_id] = np.logical_or(predicted, expected).sum()
+    per_class_iou = np.divide(intersections, unions, out=np.zeros_like(intersections), where=unions > 0)
+    metadata_path = input_dir / "metadata.npz"
+    metadata = np.load(metadata_path) if metadata_path.exists() else None
+    metrics = {
+        "pixel_accuracy": float((predictions == targets).mean()),
+        "mean_iou": float(per_class_iou.mean()),
+        "per_class_iou": per_class_iou.tolist(),
+        "samples": int(len(predictions)),
+        "data_source": str(metadata["data_source"]) if metadata is not None else "unknown",
+        "protocol": str(metadata["protocol"]) if metadata is not None else "unknown",
+    }
+    output_dir = ROOT / config["paths"]["evaluation_dir"]
+    output_dir.mkdir(parents=True, exist_ok=True)
+    with (output_dir / "metrics.json").open("w", encoding="utf-8") as handle:
+        json.dump(metrics, handle, indent=2)
+    figure, axes = plt.subplots(2, 2, figsize=(7, 7))
+    for index, axis in enumerate(axes.flat):
+        sample = index // 2
+        image = targets[sample] if index % 2 == 0 else predictions[sample]
+        axis.imshow(image, vmin=0, vmax=classes - 1, cmap="terrain")
+        axis.set_title(("Target" if index % 2 == 0 else "Prediction") + f" {sample}")
+        axis.axis("off")
+    figure.tight_layout()
+    figure.savefig(output_dir / "comparison.png", dpi=120)
+    plt.close(figure)
+    print(f"pixel_accuracy={metrics['pixel_accuracy']:.6f} mean_iou={metrics['mean_iou']:.6f}")
+    print(f"evaluation={output_dir.relative_to(ROOT)}")
+
+
+if __name__ == "__main__":
+    main()

scripts/train.py

@@ -0,0 +1,147 @@
+"""Train compact SkySense on NPZ multi-modal temporal samples."""
+
+import importlib.util
+import json
+import os
+import random
+from pathlib import Path
+
+import numpy as np
+import torch
+import yaml
+from torch import distributed as dist
+from torch.nn.parallel import DistributedDataParallel
+from torch.utils.data import DataLoader, Dataset, DistributedSampler
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def load_model_class():
+    spec = importlib.util.spec_from_file_location("skysense_model", ROOT / "model" / "skysense.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.SkySense
+
+
+def load_config():
+    with (ROOT / "conf" / "config.yaml").open(encoding="utf-8") as handle:
+        return yaml.safe_load(handle)
+
+
+class NPZDataset(Dataset):
+    def __init__(self, path):
+        archive = np.load(path)
+        sample_keys = {"hr", "s2", "s1", "dates_hr", "dates_s2", "dates_s1", "region", "labels"}
+        missing = sample_keys.difference(archive.files)
+        if missing:
+            raise ValueError(f"Dataset {path} is missing arrays: {sorted(missing)}")
+        self.arrays = {key: archive[key] for key in sample_keys}
+        self.data_source = str(archive["data_source"]) if "data_source" in archive.files else "unknown"
+        self.protocol = str(archive["protocol"]) if "protocol" in archive.files else "unknown"
+
+    def __len__(self):
+        return len(self.arrays["hr"])
+
+    def __getitem__(self, index):
+        return {key: torch.as_tensor(value[index]) for key, value in self.arrays.items()}
+
+
+def setup_device():
+    world_size = int(os.environ.get("WORLD_SIZE", "1"))
+    local_rank = int(os.environ.get("LOCAL_RANK", "0"))
+    if world_size > 1:
+        backend = "nccl" if torch.cuda.is_available() else "gloo"
+        dist.init_process_group(backend=backend)
+    if torch.cuda.is_available():
+        torch.cuda.set_device(local_rank)
+        return torch.device("cuda", local_rank), world_size, local_rank
+    return torch.device("cpu"), world_size, local_rank
+
+
+def main():
+    config = load_config()
+    seed = config["seed"]
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    device, world_size, local_rank = setup_device()
+    dataset_path = ROOT / config["data"]["root"] / "train.npz"
+    if not dataset_path.exists():
+        raise FileNotFoundError(
+            f"Missing training data: {dataset_path.relative_to(ROOT)}. "
+            "Run `python scripts/fake_data.py` for a synthetic connectivity test."
+        )
+    dataset = NPZDataset(dataset_path)
+    if local_rank == 0:
+        print(
+            f"data_source={dataset.data_source} protocol={dataset.protocol} "
+            f"samples={len(dataset)} image_size={config['data']['image_size']}x{config['data']['image_size']}"
+        )
+    sampler = DistributedSampler(dataset, shuffle=True) if world_size > 1 else None
+    loader = DataLoader(
+        dataset,
+        batch_size=config["train"]["batch_size"],
+        shuffle=sampler is None,
+        sampler=sampler,
+        num_workers=config["train"]["num_workers"],
+    )
+    SkySense = load_model_class()
+    model = SkySense(
+        **config["model"],
+        hr_channels=config["data"]["hr_channels"],
+        s2_channels=config["data"]["s2_channels"],
+        s1_channels=config["data"]["s1_channels"],
+        num_classes=config["data"]["num_classes"],
+    ).to(device)
+    if world_size > 1:
+        model = DistributedDataParallel(model, device_ids=[local_rank] if device.type == "cuda" else None)
+    optimizer = torch.optim.AdamW(model.parameters(), lr=config["train"]["learning_rate"], weight_decay=config["train"]["weight_decay"])
+    final_loss = float("nan")
+    for epoch in range(config["train"]["epochs"]):
+        if sampler is not None:
+            sampler.set_epoch(epoch)
+        model.train()
+        total = 0.0
+        for batch in loader:
+            batch = {key: value.to(device) for key, value in batch.items()}
+            output = model(batch["hr"], batch["s2"], batch["s1"], batch["dates_hr"], batch["dates_s2"], batch["dates_s1"], batch["region"])
+            base_model = model.module if hasattr(model, "module") else model
+            segmentation = torch.nn.functional.cross_entropy(output["logits"], batch["labels"])
+            alignment = base_model.cross_modal_alignment_loss(output["features"])
+            loss = segmentation + config["train"]["alignment_weight"] * alignment
+            optimizer.zero_grad(set_to_none=True)
+            loss.backward()
+            optimizer.step()
+            total += loss.item()
+        final_loss = total / len(loader)
+        if local_rank == 0:
+            print(f"epoch={epoch + 1} loss={final_loss:.6f}")
+    if local_rank == 0:
+        checkpoint = ROOT / config["paths"]["checkpoint"]
+        checkpoint.parent.mkdir(parents=True, exist_ok=True)
+        base_model = model.module if hasattr(model, "module") else model
+        torch.save({"model": base_model.state_dict(), "config": config, "final_loss": final_loss}, checkpoint)
+        metrics = ROOT / config["paths"]["training_metrics"]
+        metrics.parent.mkdir(parents=True, exist_ok=True)
+        metrics.write_text(
+            json.dumps(
+                {
+                    "final_loss": final_loss,
+                    "epochs": config["train"]["epochs"],
+                    "samples": len(dataset),
+                    "data_source": dataset.data_source,
+                    "protocol": dataset.protocol,
+                },
+                indent=2,
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+        print(f"checkpoint={checkpoint.relative_to(ROOT)} final_loss={final_loss:.6f}")
+    if world_size > 1:
+        dist.destroy_process_group()
+
+
+if __name__ == "__main__":
+    main()