Upload 4 files

.gitattributes

@@ -66,3 +66,4 @@ single/spot_1dpwunet.pt2 filter=lfs diff=lfs merge=lfs -text
 single/spot_1dpwunetpp.pt2 filter=lfs diff=lfs merge=lfs -text
 single/spot_segformer.pt2 filter=lfs diff=lfs merge=lfs -text
 single/spot_unetpp.pt2 filter=lfs diff=lfs merge=lfs -text
+ensemble/ensemble_4.pt2 filter=lfs diff=lfs merge=lfs -text

ensemble/ensemble_4.json

@@ -0,0 +1,281 @@
+{
+  "type": "Feature",
+  "stac_version": "1.1.0",
+  "stac_extensions": [
+    "https://stac-extensions.github.io/mlm/v1.5.0/schema.json",
+    "https://stac-extensions.github.io/file/v2.1.0/schema.json"
+  ],
+  "id": "ENSEMBLE_4MODELS_MEAN_UNCERTAINTY_2025-10-27",
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+      [
+        [
+          -180.0,
+          -90.0
+        ],
+        [
+          -180.0,
+          90.0
+        ],
+        [
+          180.0,
+          90.0
+        ],
+        [
+          180.0,
+          -90.0
+        ],
+        [
+          -180.0,
+          -90.0
+        ]
+      ]
+    ]
+  },
+  "bbox": [
+    -180,
+    -90,
+    180,
+    90
+  ],
+  "properties": {
+    "datetime": "2025-10-27T11:08:23Z",
+    "created": "2025-10-27T11:08:23Z",
+    "updated": "2025-12-01T10:57:16.283159Z",
+    "description": "Ensemble of 4 models (1dpwdeeplabv3, 1dpwunetpp, 1dpwseg, unet) with Mean aggregation and uncertainty quantification for cloud detection in VGT-1, VGT-2, and PROBA-V satellite imagery.",
+    "title": "Ensemble Cloud Detection Model (4 Models + Uncertainty) - VGT1/VGT2/Proba-V",
+    "mlm:name": "ensemble_4models_mean_uncertainty_fdr4vgt_cloudmask",
+    "mlm:architecture": "Ensemble (Mean+Uncertainty): DeepLabV3+PW, UNet+++PW, SegFormer+PW, UNet",
+    "mlm:tasks": [
+      "semantic-segmentation",
+      "uncertainty-quantification"
+    ],
+    "mlm:framework": "pytorch",
+    "mlm:framework_version": "2.5.1+cu121",
+    "mlm:accelerator": "cuda",
+    "mlm:accelerator_constrained": false,
+    "mlm:accelerator_summary": "NVIDIA GPU with CUDA support (compute capability >= 7.0)",
+    "mlm:accelerator_count": 1,
+    "mlm:memory_size": 187574737,
+    "mlm:batch_size_suggestion": 4,
+    "mlm:total_parameters": 29030983,
+    "mlm:pretrained": true,
+    "mlm:pretrained_source": "Global VGT-1/VGT-2/PROBA-V cloud detection models (100k+ training samples)",
+    "mlm:input": [
+      {
+        "name": "VGT_PROBA_TOC_reflectance",
+        "bands": [
+          "Blue (B0, ~450nm)",
+          "Red (B2, ~645nm)",
+          "Near-Infrared (B3, ~835nm)",
+          "SWIR (MIR, ~1665nm)"
+        ],
+        "input": {
+          "shape": [
+            -1,
+            4,
+            512,
+            512
+          ],
+          "dim_order": [
+            "batch",
+            "channel",
+            "height",
+            "width"
+          ],
+          "data_type": "float32"
+        },
+        "norm": {
+          "type": "raw_toc_reflectance",
+          "range": [
+            0,
+            10000
+          ],
+          "description": "Raw Top-of-Canopy reflectance values scaled by 10000"
+        },
+        "pre_processing_function": null
+      }
+    ],
+    "mlm:output": [
+      {
+        "name": "cloud_probability",
+        "tasks": [
+          "semantic-segmentation"
+        ],
+        "result": {
+          "shape": [
+            -1,
+            1,
+            512,
+            512
+          ],
+          "dim_order": [
+            "batch",
+            "channel",
+            "height",
+            "width"
+          ],
+          "data_type": "float32"
+        },
+        "classification:classes": [
+          {
+            "value": 0.0,
+            "name": "clear",
+            "description": "Clear sky (may contain cloud shadows)",
+            "color_hint": "00000000"
+          },
+          {
+            "value": 1.0,
+            "name": "cloud",
+            "description": "Cloud present",
+            "color_hint": "FFFF00"
+          }
+        ],
+        "post_processing_function": "Apply threshold to get binary mask. Recommended threshold: 0.4. Returns tuple: (probabilities, uncertainty)",
+        "standard_threshold": 0.5,
+        "recommended_threshold": 0.4,
+        "value_range": [
+          0.0,
+          1.0
+        ],
+        "description": "Per-pixel mean probability across ensemble models. Built-in sigmoid activation. Values close to 1.0 indicate high confidence of cloud."
+      },
+      {
+        "name": "prediction_uncertainty",
+        "tasks": [
+          "uncertainty-quantification"
+        ],
+        "result": {
+          "shape": [
+            -1,
+            1,
+            512,
+            512
+          ],
+          "dim_order": [
+            "batch",
+            "channel",
+            "height",
+            "width"
+          ],
+          "data_type": "float32"
+        },
+        "value_range": [
+          0.0,
+          1.0
+        ],
+        "description": "Normalized standard deviation across 4 ensemble members. Values close to 1.0 indicate high disagreement between models (high uncertainty). Automatically returned as second element of output tuple."
+      }
+    ],
+    "mlm:hyperparameters": {
+      "ensemble_size": 4,
+      "ensemble_members": [
+        "1dpwdeeplabv3",
+        "1dpwunetpp",
+        "1dpwseg",
+        "unet"
+      ],
+      "aggregation_method": "mean",
+      "uncertainty_method": "normalized_std",
+      "avg_val_loss": 0.0616,
+      "member_details": [
+        {
+          "model": "1dpwdeeplabv3",
+          "epoch": 25,
+          "val_loss": 0.0611
+        },
+        {
+          "model": "1dpwunetpp",
+          "epoch": 22,
+          "val_loss": 0.0625
+        },
+        {
+          "model": "1dpwseg",
+          "epoch": 23,
+          "val_loss": 0.0622
+        },
+        {
+          "model": "unet",
+          "epoch": 20,
+          "val_loss": 0.0606
+        }
+      ]
+    },
+    "file:size": 125049825,
+    "custom:export_format": "torch.export.pt2",
+    "custom:has_sigmoid": true,
+    "custom:sigmoid_location": "built-in per-model wrapper",
+    "custom:export_datetime": "2025-12-01T10:57:16.283159Z",
+    "custom:training_stage": "ensemble-mean-uncertainty",
+    "custom:project": "FDR4VGT",
+    "custom:project_url": "https://fdr4vgt.eu/",
+    "custom:sensors": [
+      "VGT-1",
+      "VGT-2",
+      "PROBA-V"
+    ],
+    "custom:sensor_notes": "Model applicable to SPOT-VGT1, SPOT-VGT2, and PROBA-V imagery",
+    "custom:spatial_resolution": "1km",
+    "custom:tile_size": 512,
+    "custom:recommended_overlap": 64,
+    "custom:applicable_start": "1998-03-01T00:00:00Z",
+    "custom:applicable_end": null,
+    "custom:returns_tuple": true,
+    "custom:tuple_format": "(probabilities, uncertainty)",
+    "dependencies": [
+      "torch>=2.0.0",
+      "segmentation-models-pytorch>=0.3.0",
+      "pytorch-lightning>=2.0.0",
+      "numpy>=1.20.0"
+    ]
+  },
+  "links": [
+    {
+      "rel": "about",
+      "href": "https://fdr4vgt.eu/",
+      "type": "text/html",
+      "title": "FDR4VGT Project - Harmonized VGT Data Record"
+    },
+    {
+      "rel": "license",
+      "href": "https://creativecommons.org/licenses/by/4.0/",
+      "type": "text/html",
+      "title": "CC-BY-4.0 License"
+    }
+  ],
+  "assets": {
+    "model": {
+      "href": "https://huggingface.co/isp-uv-es/FDR4VGT-CLOUD/resolve/main/ensemble/ensemble_4.pt2",
+      "type": "application/octet-stream; application=pytorch",
+      "title": "PyTorch ensemble model weights",
+      "description": "Ensemble of 4 models in torch.export .pt2 format. Returns tuple: (probabilities, uncertainty).",
+      "mlm:artifact_type": "torch.export.pt2",
+      "roles": [
+        "mlm:model",
+        "mlm:weights",
+        "data"
+      ]
+    },
+    "example_data": {
+      "href": "https://huggingface.co/isp-uv-es/FDR4VGT-CLOUD/resolve/main/ensemble/example_data.safetensor",
+      "type": "application/octet-stream; application=safetensors",
+      "title": "Example VGT/PROBA-V image",
+      "description": "Example VGT/PROBA-V Top-of-Canopy reflectance image for model inference.",
+      "roles": [
+        "mlm:example_data",
+        "data"
+      ]
+    },
+    "load": {
+      "href": "https://huggingface.co/isp-uv-es/FDR4VGT-CLOUD/resolve/main/ensemble/load.py",
+      "type": "application/x-python-code",
+      "title": "PyTorch Ensemble Loader",
+      "description": "Python helper code to load the exported .pt2 ensemble model. Includes predict_large() function for large images.",
+      "roles": [
+        "code"
+      ]
+    }
+  },
+  "collection": "ENSEMBLE_4MODELS_FDR4VGT_CloudMask_MeanUncertainty"
+}

ensemble/ensemble_4.pt2

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ca47822614547e57b105edee92cda3f8fd080c0139523e7febd47fce809d69a2
+size 125049825

ensemble/example_data.safetensor

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a66d52bb558f756d105b41ead9386cdd6f04b4ac9cdc0173b5632aa00f35b244
+size 524504

ensemble/load.py

@@ -0,0 +1,316 @@
+import torch
+import torch.nn
+import pathlib
+import pystac
+from typing import Literal, Tuple
+import numpy as np
+import itertools
+from tqdm import tqdm
+import math
+
+# Ensemble model for combining multiple models' outputs
+class EnsembleModel(torch.nn.Module):
+    def __init__(self, *models, mode="max"):
+        super(EnsembleModel, self).__init__()
+        self.models = torch.nn.ModuleList(models)
+        self.mode = mode
+        if mode not in ["min", "mean", "median", "max", "none"]:
+            raise ValueError("Mode must be 'none', 'min', 'mean', 'median', or 'max'.")
+
+    def forward(self, x) -> Tuple[torch.Tensor, torch.Tensor]:
+        """
+        Forward pass for ensemble.
+        
+        Returns:
+            Tuple of (probabilities, uncertainty):
+            - probabilities: (B, 1, H, W) - aggregated predictions
+            - uncertainty: (B, 1, H, W) - normalized std deviation
+        """
+        outputs = []
+        for model in self.models:
+            output = model(x)
+            outputs.append(output)
+        
+        if not outputs:
+            return None, None
+        
+        # Stack all model outputs: (B, N, H, W) where N = number of models
+        stacked_outputs = torch.stack(outputs, dim=1)  # (B, N, 1, H, W)
+        stacked_outputs = stacked_outputs.squeeze(2)   # (B, N, H, W)
+        
+        # Calculate aggregated probabilities
+        if self.mode == "max":
+            output_probs = torch.max(stacked_outputs, dim=1, keepdim=True)[0]
+        elif self.mode == "mean":
+            output_probs = torch.mean(stacked_outputs, dim=1, keepdim=True)
+        elif self.mode == "median":
+            output_probs = torch.median(stacked_outputs, dim=1, keepdim=True)[0]
+        elif self.mode == "min":
+            output_probs = torch.min(stacked_outputs, dim=1, keepdim=True)[0]
+        elif self.mode == "none":
+            # Return all predictions without aggregation
+            return stacked_outputs, None
+        else:
+            raise ValueError("Mode must be 'min', 'mean', 'median', or 'max'.")
+        
+        # Calculate uncertainty (normalized standard deviation)
+        N = len(outputs)
+        if N > 1:
+            # Calculate std across models (dim=1)
+            std_output = torch.std(stacked_outputs, dim=1, keepdim=True)
+            
+            # Normalize the standard deviation [0 - 1]
+            # Formula: std_max = sqrt(0.25 * N / (N - 1))
+            std_max = math.sqrt(0.25 * N / (N - 1))
+            uncertainty = std_output / std_max
+            
+            # Clamp to [0, 1] to avoid numerical issues
+            uncertainty = torch.clamp(uncertainty, 0.0, 1.0)
+        else:
+            # Single model: no uncertainty
+            uncertainty = torch.zeros_like(output_probs)
+        
+        return output_probs, uncertainty  # Both (B, 1, H, W)
+
+def compiled_model(
+    path: pathlib.Path, 
+    stac_item: pystac.Item,
+    mode: Literal["min", "mean", "median", "max"] = "max",
+    *args, **kwargs
+):
+    """
+    Loads model(s) dynamically based on STAC metadata.
+    
+    - If single .pt2 → returns single model
+    - If multiple .pt2 → returns EnsembleModel
+    
+    Args:
+        mode: Aggregation mode for ensembles (ignored for single models)
+    
+    Returns:
+        Single model or EnsembleModel
+    """
+    model_paths = []
+    for asset_key, asset in stac_item.assets.items():
+        if asset.href.endswith(".pt2"):
+            model_paths.append(asset.href) 
+    
+    if not model_paths:
+        raise ValueError("No .pt2 files found in STAC item assets.")
+    
+    model_paths.sort()
+    
+    if len(model_paths) == 1:
+        # Single model
+        return torch.export.load(model_paths[0]).module()
+    else:
+        # Ensemble model
+        models = [torch.export.load(p).module() for p in model_paths]
+        return EnsembleModel(*models, mode=mode)
+
+def define_iteration(dimension: tuple, chunk_size: int, overlap: int = 0):
+    """
+    Defines iteration strategy to traverse the image with overlap.
+    """
+    dimy, dimx = dimension
+    if chunk_size > max(dimx, dimy):
+        return [(0, 0)]
+    y_step = chunk_size - overlap
+    x_step = chunk_size - overlap
+    iterchunks = list(itertools.product(range(0, dimy, y_step), range(0, dimx, x_step)))
+    iterchunks_fixed = fix_lastchunk(
+        iterchunks=iterchunks, s2dim=dimension, chunk_size=chunk_size
+    )
+    return iterchunks_fixed
+
+
+def fix_lastchunk(iterchunks, s2dim, chunk_size):
+    """
+    Adjusts last chunks to prevent them from exceeding boundaries.
+    """
+    itercontainer = []
+    for index_i, index_j in iterchunks:
+        if index_i + chunk_size > s2dim[0]:
+            index_i = max(s2dim[0] - chunk_size, 0)
+        if index_j + chunk_size > s2dim[1]:
+            index_j = max(s2dim[1] - chunk_size, 0)
+        itercontainer.append((index_i, index_j))
+    return list(set(itercontainer)) # Returns unique values just in case
+
+
+def predict_large(
+    image: np.ndarray,
+    model: torch.nn.Module,
+    chunk_size: int = 512,
+    overlap: int = 64,
+    device: str = "cpu",
+    nodata: float = 0.0
+) -> Tuple[np.ndarray, np.ndarray] | np.ndarray:
+    """
+    Predict a full 'image' (C, H, W) using overlapping patches.
+    
+    Args:
+        image: Input array (C, H, W)
+        model: Compiled PyTorch model
+        chunk_size: Tile size for inference
+        overlap: Overlap between tiles
+        device: 'cpu' or 'cuda'
+        nodata: No-data value
+        
+    Returns:
+        - For ensembles: Tuple of (probabilities, uncertainty), both (1, H, W)
+        - For single models: probabilities array (1, H, W)
+    
+    Compatible with:
+    - Normal models (with .eval()) - returns probabilities only
+    - Exported models (.pt2) - returns probabilities only
+    - Ensembles (EnsembleModel) - returns (probabilities, uncertainty)
+    """
+    
+    # Validate input array dimensions
+    if image.ndim != 3:
+        raise ValueError(f"Input array must be (C, H, W). Received {image.shape}")
+    
+    bands, height, width = image.shape
+    
+    # Prepare model (compatibility logic for .pt2 models)
+    try:
+        model.eval()
+        for p in model.parameters():
+            p.requires_grad = False
+        model = model.to(device)
+    except (NotImplementedError, AttributeError):
+        # Exported model (.pt2) or EnsembleModel
+        model = model.to(device)
+        
+    test_input = torch.zeros(1, bands, chunk_size, chunk_size).to(device)
+    with torch.no_grad():
+        test_output = model(test_input)
+    
+    is_ensemble = isinstance(test_output, tuple) and len(test_output) == 2
+    
+    # Initialize output arrays
+    output_probs = np.full((1, height, width), nodata, dtype=np.float32)
+    
+    if is_ensemble:
+        output_uncertainty = np.full((1, height, width), nodata, dtype=np.float32)
+
+    # Get the list of tile offsets
+    coords = define_iteration(
+        dimension=(height, width),
+        chunk_size=chunk_size,
+        overlap=overlap
+    )
+
+    # Iterate over tiles
+    for idx, (row_off, col_off) in enumerate(tqdm(coords, desc="Inference")):
+        
+        # Read chunk (numpy slicing)
+        patch = image[
+            :,
+            row_off : row_off + chunk_size,
+            col_off : col_off + chunk_size
+        ]
+
+        # Convert to tensor and handle padding if tile is smaller than chunk_size
+        patch_tensor = torch.from_numpy(patch).float().unsqueeze(0).to(device)
+        _, _, h_tile, w_tile = patch_tensor.shape
+        
+        # Calculate padding needed
+        pad_h = chunk_size - h_tile
+        pad_w = chunk_size - w_tile
+        
+        # Apply padding if necessary
+        if pad_h > 0 or pad_w > 0:
+            patch_tensor = torch.nn.functional.pad(
+                patch_tensor, (0, pad_w, 0, pad_h), "constant", nodata
+            )
+        
+        # Create mask for nodata areas (all bands are nodata)
+        mask_all = (patch_tensor == nodata).all(dim=1, keepdim=True)
+        
+        # Forward pass
+        with torch.no_grad():
+            model_output = model(patch_tensor)
+            
+            if is_ensemble:
+                probs, uncertainty = model_output
+                probs = probs.masked_fill(mask_all, nodata)
+                uncertainty = uncertainty.masked_fill(mask_all, nodata)
+            else:
+                probs = model_output
+                probs = probs.masked_fill(mask_all, nodata)
+        
+        # Remove batch dimension and ensure (1, H, W)
+        if probs.ndim == 4:
+            probs = probs.squeeze(0)  # (1, H, W)
+        
+        # Convert to numpy
+        result_probs = probs.cpu().numpy()  # (1, H, W)
+        
+        if is_ensemble:
+            if uncertainty.ndim == 4:
+                uncertainty = uncertainty.squeeze(0)
+            result_uncertainty = uncertainty.cpu().numpy()
+
+        # Logic for partial writing
+        if col_off == 0:
+            offset_x = 0
+        else:
+            offset_x = col_off + overlap // 2
+
+        if row_off == 0:
+            offset_y = 0
+        else:
+            offset_y = row_off + overlap // 2
+
+        if (offset_x + chunk_size) == width:
+            length_x = chunk_size
+            sub_x_start = 0
+        else:
+            length_x = chunk_size - (overlap // 2)
+            sub_x_start = overlap // 2 if col_off != 0 else 0
+
+        if (offset_y + chunk_size) == height:
+            length_y = chunk_size
+            sub_y_start = 0
+        else:
+            length_y = chunk_size - (overlap // 2)
+            sub_y_start = overlap // 2 if row_off != 0 else 0
+
+        # Ensure we don't exceed array bounds
+        if offset_y + length_y > height:
+            length_y = height - offset_y
+        if offset_x + length_x > width:
+            length_x = width - offset_x
+
+        # Extract the valid region from the result
+        to_write_probs = result_probs[
+            :,
+            sub_y_start : sub_y_start + length_y,
+            sub_x_start : sub_x_start + length_x
+        ]
+
+        # Write to the output numpy array
+        output_probs[
+            :,
+            offset_y : offset_y + length_y,
+            offset_x : offset_x + length_x
+        ] = to_write_probs
+        
+        if is_ensemble:
+            to_write_uncertainty = result_uncertainty[
+                :,
+                sub_y_start : sub_y_start + length_y,
+                sub_x_start : sub_x_start + length_x
+            ]
+            output_uncertainty[
+                :,
+                offset_y : offset_y + length_y,
+                offset_x : offset_x + length_x
+            ] = to_write_uncertainty
+            
+    if is_ensemble:
+        return output_probs, output_uncertainty
+    else:
+        return output_probs