## 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](https://dpird-dma.github.io/blog/S2Mosaic-Creating-Cloud-Free-Sentinel-2-Mosaics/)
## 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 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.
## Note 📝
We use OmniCloudMask for state-of-the-art cloud and cloud shadow masking. OCM will run significantly faster if an available NVIDIA GPU is present.
## Try in Colab
[![Colab_Button]][Link]
[Link]: https://colab.research.google.com/drive/1-vdAAnpzp_VCotTV07cbSC9iQFiD7DcH?usp=sharing 'Try S2Mosaic In Colab'
[Colab_Button]: https://img.shields.io/badge/Try%20in%20Colab-grey?style=for-the-badge&logo=google-colab
## Installation 🛠️
You can install S2Mosaic using pip:
```
pip install s2mosaic
```
## Usage Example 1 🚀
Here's a basic example of how to use S2Mosaic:
```python
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:
```python
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 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").
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/DPIRD-DMA/S2Mosaic",
"name": "s2mosaic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Nick Wright",
"author_email": "nicholas.wright@dpird.wa.gov.au",
"download_url": "https://files.pythonhosted.org/packages/4c/bb/2c1404136a76115d93d7fadd98ad9505063c76c96a905e679e3d19bd602e/s2mosaic-0.2.1.tar.gz",
"platform": null,
"description": "## S2Mosaic \ud83d\udef0\ufe0f\ud83c\udf0d\n\nS2Mosaic 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.\n\n[S2Mosaic blog post here](https://dpird-dma.github.io/blog/S2Mosaic-Creating-Cloud-Free-Sentinel-2-Mosaics/)\n\n\n## Features \ud83c\udf1f\n\n- Create Sentinel-2 mosaics for specific grid areas and time ranges.\n- Flexible scene selection methods: by valid data percentage, oldest, or newest scenes.\n- Multiple mosaic creation methods: mean or first valid pixel.\n- Support for different spectral bands, including visual (RGB) composites.\n- State-of-the-art cloud masking using the OmniCloudMask library.\n- Export mosaics as GeoTIFF files or return as NumPy arrays.\n\n## Changelog \ud83d\udcdd\n### Version 0.1.9:\n * Added a slight dilation to the no data mask to remove diagonal no data pixels from scene edges.\n\n\n## Note \ud83d\udcdd\n\nWe use OmniCloudMask for state-of-the-art cloud and cloud shadow masking. OCM will run significantly faster if an available NVIDIA GPU is present.\n\n## Try in Colab\n\n[![Colab_Button]][Link]\n\n[Link]: https://colab.research.google.com/drive/1-vdAAnpzp_VCotTV07cbSC9iQFiD7DcH?usp=sharing 'Try S2Mosaic In Colab'\n\n[Colab_Button]: https://img.shields.io/badge/Try%20in%20Colab-grey?style=for-the-badge&logo=google-colab\n\n\n\n## Installation \ud83d\udee0\ufe0f\n\nYou can install S2Mosaic using pip:\n```\npip install s2mosaic\n```\n\n## Usage Example 1 \ud83d\ude80\n\nHere's a basic example of how to use S2Mosaic:\n\n```python\nfrom s2mosaic import mosaic\nfrom pathlib import Path\n\n# Create a mosaic for a specific grid area and time range\nresult = mosaic(\n grid_id=\"50HMH\", # Sentinel-2 scene grid ID\n start_year=2022,\n start_month=1,\n start_day=1,\n duration_months=2, # Duration to collect data from\n output_dir=Path(\"output\"), # Output directory for mosaic TIFF files\n sort_method=\"valid_data\", # Method to sort potential scenes before download\n mosaic_method=\"mean\", # Approach used to combine scenes\n required_bands=['visual'], # Required Sentinel-2 bands\n no_data_threshold=0.001 # Threshold for early stopping\n)\n\nprint(f\"Mosaic saved to: {result}\")\n```\n\nThis 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.\n\n## Usage Example 2 \ud83d\udd2c\n\nHere's another example of how to use S2Mosaic:\n\n```python\nfrom s2mosaic import mosaic\n\n# Create a mosaic for a specific grid area and time range\narray, rio_profile = mosaic(\n grid_id=\"50HMH\",\n start_year=2022,\n start_month=1,\n start_day=1,\n duration_months=2,\n sort_method=\"valid_data\",\n mosaic_method=\"mean\",\n required_bands=[\"B04\", \"B03\", \"B02\", \"B08\"],\n no_data_threshold=0.001\n)\n\nprint(f\"Mosaic array shape: {array.shape}\")\n```\n\nSimilar to the example above but with 16-bit red, green, blue, and NIR bands returned as a NumPy array and rasterio profile.\n\n## Advanced Usage \ud83e\udde0\n\nS2Mosaic provides several options for customizing the mosaic creation process:\n\n- `sort_method`: Choose between \"valid_data\", \"oldest\", or \"newest\" to determine scene selection priority.\n- `mosaic_method`: Use \"mean\" for an average of valid pixels or \"first\" to use the first valid pixel.\n- `required_bands`: Specify which spectral bands to include in the mosaic. Use [\"visual\"] for an RGB composite.\n- `no_data_threshold`: Set the threshold for considering a pixel as no-data. Set to None to process all scenes.\n- `ocm_batch_size`: Set the batch size for OmniCloudMask inference (default: 6).\n- `ocm_inference_dtype`: Set the data type for OmniCloudMask inference (default: \"bf16\").\n\nFor more detailed information on these options and additional functionality, please refer to the function docstring in the source code.\n\n## Performance Tips \ud83d\ude80\n- `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.\n- `ocm_inference_dtype`: if the device supports it 'bf16' tends to be the fastest option, failing this try 'fp16' then 'fp32'.\n- `sort_method`: Using \"valid_data\" as the sort method tends to be the fastest option if no_data_threshold is not None.\n- `mosaic_method`: Using 'first' can be a lot faster than 'mean' as only valid, non cloudy, new pixels are downloaded.\n\n## Contributing \ud83e\udd1d\n\nContributions to S2Mosaic are welcome! Please feel free to submit pull requests, create issues, or suggest improvements. \ud83d\ude4c\n\n## License \ud83d\udcc4\n\nThis project is licensed under the MIT License. \u2696\ufe0f\n\n## Acknowledgments \ud83d\ude4f\n\nThis package uses the Planetary Computer STAC API and the OmniCloudMask library for cloud masking.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for making cloud-free Sentinel-2 mosaics",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/DPIRD-DMA/S2Mosaic"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c2c361cb8e9f97cc374af723b4fe3f2027f1ac57d09db712435c7c88ee17ad0a",
"md5": "c6f82844899bd40ead221a5dca787459",
"sha256": "b1ddcae95a86a5130a7ba49aaff7cdf64271d4fb1440dcad05caf8116960eabc"
},
"downloads": -1,
"filename": "s2mosaic-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6f82844899bd40ead221a5dca787459",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 5580809,
"upload_time": "2024-12-22T05:51:31",
"upload_time_iso_8601": "2024-12-22T05:51:31.168880Z",
"url": "https://files.pythonhosted.org/packages/c2/c3/61cb8e9f97cc374af723b4fe3f2027f1ac57d09db712435c7c88ee17ad0a/s2mosaic-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4cbb2c1404136a76115d93d7fadd98ad9505063c76c96a905e679e3d19bd602e",
"md5": "afb4cd31c5ccba41f066e2a3fd63a7a1",
"sha256": "85e93a79f6ab30807adfd6e87fbdd870204202c5c0d85ce194eeadd7b6fae7cb"
},
"downloads": -1,
"filename": "s2mosaic-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "afb4cd31c5ccba41f066e2a3fd63a7a1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 5618952,
"upload_time": "2024-12-22T05:51:41",
"upload_time_iso_8601": "2024-12-22T05:51:41.033270Z",
"url": "https://files.pythonhosted.org/packages/4c/bb/2c1404136a76115d93d7fadd98ad9505063c76c96a905e679e3d19bd602e/s2mosaic-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-22 05:51:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DPIRD-DMA",
"github_project": "S2Mosaic",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "s2mosaic"
}
JSON
