s2mosaic 1.1.0

S2Mosaic 🛰️🌍

S2Mosaic is a Python package for creating cloud-free mosaics from Sentinel-2 satellite imagery. It allows users to generate composite images for specified grid areas and time ranges, with various options for scene selection and mosaic creation.

S2Mosaic blog post here

Features 🌟

• Create Sentinel-2 mosaics for specific grid areas and time ranges.
• Flexible scene selection methods: by valid data percentage, oldest, or newest scenes.
• Multiple mosaic creation methods: mean, arbitrary percentile, median or first valid pixel.
• Support for different spectral bands, including visual (RGB) composites.
• State-of-the-art cloud masking using the OmniCloudMask library.
• Export mosaics as GeoTIFF files or return as NumPy arrays.

Changelog 📝

Version 0.1.9:

* Added a slight dilation to the no data mask to remove diagonal no data pixels from scene edges.

version 1.0.0

* Added support for percentile and median mosaic options and minor optimizations.

Note 📝

We use OmniCloudMask (OCM)for state-of-the-art cloud and cloud shadow masking. OCM will run significantly faster if an available NVIDIA GPU or MPS accelerator is present.

Try in Colab

Installation 🛠️

You can install S2Mosaic using pip:

pip install s2mosaic

Or with uv:

uv add s2mosaic

Usage Example 1 🚀

Here's a basic example of how to use S2Mosaic:

from s2mosaic import mosaic
from pathlib import Path

# Create a mosaic for a specific grid area and time range
result = mosaic(
    grid_id="50HMH", # Sentinel-2 scene grid ID
    start_year=2022,
    start_month=1,
    start_day=1,
    duration_months=2, # Duration to collect data from
    output_dir=Path("output"), # Output directory for mosaic TIFF files
    sort_method="valid_data", # Method to sort potential scenes before download
    mosaic_method="mean", # Approach used to combine scenes
    required_bands=['visual'], # Required Sentinel-2 bands
    no_data_threshold=0.001 # Threshold for early stopping
)

print(f"Mosaic saved to: {result}")

This example creates a mosaic for the grid area "50HMH" for the first two months of 2022, using the visual (TCI) product. The scenes are sorted by valid data percentage, and the mosaic is created using the mean of valid pixels. The process stops iterating through scenes once the no_data_threshold is reached.

Usage Example 2 🔬

Here's another example of how to use S2Mosaic:

from s2mosaic import mosaic

# Create a mosaic for a specific grid area and time range
array, rio_profile = mosaic(
    grid_id="50HMH",
    start_year=2022,
    start_month=1,
    start_day=1,
    duration_months=2,
    sort_method="valid_data",
    mosaic_method="mean",
    required_bands=["B04", "B03", "B02", "B08"],
    no_data_threshold=0.001
)

print(f"Mosaic array shape: {array.shape}")

Similar to the example above but with 16-bit red, green, blue, and NIR bands returned as a NumPy array and rasterio profile.

Advanced Usage 🧠

S2Mosaic provides several options for customizing the mosaic creation process:

• sort_method: Choose between "valid_data", "oldest", or "newest" to determine scene selection priority.
• mosaic_method: Use "mean" for an average of valid pixels, "percentile" with "percentile_value" for more particular merging, or "first" to use the first valid pixel.
• required_bands: Specify which spectral bands to include in the mosaic. Use ["visual"] for an RGB composite.
• no_data_threshold: Set the threshold for considering a pixel as no-data. Set to None to process all scenes.
• ocm_batch_size: Set the batch size for OmniCloudMask inference (default: 6).
• ocm_inference_dtype: Set the data type for OmniCloudMask inference (default: "bf16").
• additional_query: Set additional query filters such as {"eo:cloud_cover": {"lt": 80}}

For more detailed information on these options and additional functionality, please refer to the function docstring in the source code.

Performance Tips 🚀

• ocm_batch_size: If using a GPU, setting this above the default value (1) will speed up cloud masking. In most cases, a value of 4 works well. If you encounter CUDA errors, try using a lower number.
• ocm_inference_dtype: if the device supports it 'bf16' tends to be the fastest option, failing this try 'fp16' then 'fp32'.
• sort_method: Using "valid_data" as the sort method tends to be the fastest option if no_data_threshold is not None.
• mosaic_method: Using 'first' can be a lot faster than 'mean' as only valid, non cloudy, new pixels are downloaded.

Contributing 🤝

Contributions to S2Mosaic are welcome! Please feel free to submit pull requests, create issues, or suggest improvements. 🙌

License 📄

This project is licensed under the MIT License. ⚖️

Acknowledgments 🙏

This package uses the Planetary Computer STAC API and the OmniCloudMask library for cloud masking.