# Welcome to CloudS2Mask ☁️
## 💡 About
CloudS2Mask is an open-source Python library that efficiently segments clouds and cloud shadows in Sentinel-2 imagery using state-of-the-art deep learning techniques. Benchmarks with the CloudSEN12 Dataset show a 17% error reduction compared to the most competent existing methods.
## 🎯 Features
* High-precision cloud and cloud shadow segmentation for Sentinel-2 L1C imagery.
* Rapid processing: Approximately 2.2 seconds per scene at 20m resolution (RTX 4090, AMD Ryzen 9 5950X).
* Compatibility with both GPU and non-GPU systems.
* Supported on Linux, Windows, and macOS.
## 🚀 Installation
**Windows Users with NVIDIA GPUs**: Before installing CloudS2Mask, ensure you've installed [PyTorch with CUDA support](https://pytorch.org/get-started/locally/), then follow the steps below.
**Mac and Linux Users**: You can proceed with the installation commands below.
To install CloudS2Mask, clone this repository and proceed with manual installation.
```console
git clone https://github.com/DPIRD-DMA/CloudS2Mask
cd CloudS2Mask
pip install -q .
cd ..
```
## 💻 Usage
Here's a simple demonstration of how to use CloudS2Mask:
All you need to do is pass a list of Sentinel-2 level 1C 'SAFE' directories to CloudS2Mask.
[![Colab_Button]][Link]
[Link]: https://colab.research.google.com/drive/10zyZWCPaGDUO6PKNsyKyxcXIfvkoP2xK?usp=sharing 'Try CloudS2Mask In Colab'
[Colab_Button]: https://img.shields.io/badge/Try%20in%20Colab-grey?style=for-the-badge&logo=google-colab
```python
from pathlib import Path
from clouds2mask import (
create_settings,
batch_process_scenes,
)
output_dir = Path("./outputs")
l1c_folders_path = Path("/path/to/your/S2_l1c_SAFE/folders")
l1c_folders = list(l1c_folders_path.glob("*.SAFE"))
scene_settings = create_settings(
sent_safe_dirs=l1c_folders,
output_dir=output_dir,
processing_res=20,
)
paths_to_masks = batch_process_scenes(scene_settings)
```
## ⚙️ Performance Tuning
CloudsS2Mask offers a range of performance and accuracy options, here are some examples,
Settings for high accuracy inference:
```python
scene_settings = create_settings(
sent_safe_dirs=l1c_folders,
output_dir=output_dir,
batch_size=32,
tta_max_depth=5,
processing_res=10,
patch_overlap_px=64,
model_ensembling=True,
)
```
Settings for fast inference:
```python
scene_settings = create_settings(
sent_safe_dirs=l1c_folders,
output_dir=output_dir,
batch_size=32,
processing_res=20,
output_compression=None,
)
```
Settings for CPU inference:
```python
scene_settings = create_settings(
sent_safe_dirs=l1c_folders,
output_dir=output_dir,
batch_size=1,
processing_res=20,
)
```
CloudS2Mask will try to auto detect acceleration cards such as NVIDIA GPUs or Apple MPS, but you can also manually specify them like this:
```python
scene_settings = create_settings(
sent_safe_dirs=l1c_folders,
output_dir=output_dir,
pytorch_device='MPS',
)
```
## 👏 Contributing
We welcome all contributions! Feel free to open an issue or submit a pull request.
## 📄 License
This project is licensed under the MIT License - please refer to the LICENSE file for more details.
## 📝 Contact
For support, bug reporting, or to contribute, feel free to reach out at nicholas.wright@dpird.wa.gov.au.
Raw data
{
"_id": null,
"home_page": "https://github.com/DPIRD-DMA/CloudS2Mask",
"name": "CloudS2Mask",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Nick Wright",
"author_email": "nicholas.wright@dpird.wa.gov.au",
"download_url": "https://files.pythonhosted.org/packages/db/dd/69f5696024fafc7e079ee27d05a20ebd880c71e8a7140cacc745016ec47a/CloudS2Mask-0.1.5.tar.gz",
"platform": null,
"description": "# Welcome to CloudS2Mask \u2601\ufe0f\n\n\n\n\n\n## \ud83d\udca1 About \nCloudS2Mask is an open-source Python library that efficiently segments clouds and cloud shadows in Sentinel-2 imagery using state-of-the-art deep learning techniques. Benchmarks with the CloudSEN12 Dataset show a 17% error reduction compared to the most competent existing methods.\n\n## \ud83c\udfaf Features \n* High-precision cloud and cloud shadow segmentation for Sentinel-2 L1C imagery.\n* Rapid processing: Approximately 2.2 seconds per scene at 20m resolution (RTX 4090, AMD Ryzen 9 5950X).\n* Compatibility with both GPU and non-GPU systems.\n* Supported on Linux, Windows, and macOS.\n\n## \ud83d\ude80 Installation \n**Windows Users with NVIDIA GPUs**: Before installing CloudS2Mask, ensure you've installed [PyTorch with CUDA support](https://pytorch.org/get-started/locally/), then follow the steps below.\n\n**Mac and Linux Users**: You can proceed with the installation commands below.\nTo install CloudS2Mask, clone this repository and proceed with manual installation.\n```console\ngit clone https://github.com/DPIRD-DMA/CloudS2Mask\ncd CloudS2Mask\npip install -q .\ncd ..\n```\n\n## \ud83d\udcbb Usage \nHere's a simple demonstration of how to use CloudS2Mask:\n\nAll you need to do is pass a list of Sentinel-2 level 1C 'SAFE' directories to CloudS2Mask. \n\n[![Colab_Button]][Link]\n\n[Link]: https://colab.research.google.com/drive/10zyZWCPaGDUO6PKNsyKyxcXIfvkoP2xK?usp=sharing 'Try CloudS2Mask 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```python\nfrom pathlib import Path\nfrom clouds2mask import (\n create_settings,\n batch_process_scenes,\n)\n\noutput_dir = Path(\"./outputs\")\nl1c_folders_path = Path(\"/path/to/your/S2_l1c_SAFE/folders\")\nl1c_folders = list(l1c_folders_path.glob(\"*.SAFE\"))\n\n\nscene_settings = create_settings(\n sent_safe_dirs=l1c_folders,\n output_dir=output_dir,\n processing_res=20,\n)\n\npaths_to_masks = batch_process_scenes(scene_settings)\n```\n## \u2699\ufe0f Performance Tuning\nCloudsS2Mask offers a range of performance and accuracy options, here are some examples,\n\nSettings for high accuracy inference:\n\n```python\nscene_settings = create_settings(\n sent_safe_dirs=l1c_folders,\n output_dir=output_dir,\n batch_size=32,\n tta_max_depth=5,\n processing_res=10,\n patch_overlap_px=64,\n model_ensembling=True,\n)\n```\nSettings for fast inference:\n```python\nscene_settings = create_settings(\n sent_safe_dirs=l1c_folders,\n output_dir=output_dir,\n batch_size=32,\n processing_res=20,\n output_compression=None,\n)\n```\nSettings for CPU inference:\n```python\nscene_settings = create_settings(\n sent_safe_dirs=l1c_folders,\n output_dir=output_dir,\n batch_size=1,\n processing_res=20,\n)\n```\nCloudS2Mask will try to auto detect acceleration cards such as NVIDIA GPUs or Apple MPS, but you can also manually specify them like this:\n```python\nscene_settings = create_settings(\n sent_safe_dirs=l1c_folders,\n output_dir=output_dir,\n pytorch_device='MPS',\n)\n```\n\n## \ud83d\udc4f Contributing \nWe welcome all contributions! Feel free to open an issue or submit a pull request.\n\n## \ud83d\udcc4 License \nThis project is licensed under the MIT License - please refer to the LICENSE file for more details.\n\n## \ud83d\udcdd Contact \nFor support, bug reporting, or to contribute, feel free to reach out at nicholas.wright@dpird.wa.gov.au.\n",
"bugtrack_url": null,
"license": "",
"summary": "Python library for cloud and cloud shadow segmentation in Sentinel-2",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/DPIRD-DMA/CloudS2Mask"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3d7745856e459012fe1f0a39dfc9f3eb9ec8e650f3ff9b1b5dc71fb99c2e49b6",
"md5": "72e7e9abf1a2ac0095f8989134438b7f",
"sha256": "149b58b12bdd02118eddc903898647e2480d8537a3ab73d6bb1cc08603e81c3b"
},
"downloads": -1,
"filename": "CloudS2Mask-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "72e7e9abf1a2ac0095f8989134438b7f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 28479,
"upload_time": "2023-09-01T03:37:11",
"upload_time_iso_8601": "2023-09-01T03:37:11.651941Z",
"url": "https://files.pythonhosted.org/packages/3d/77/45856e459012fe1f0a39dfc9f3eb9ec8e650f3ff9b1b5dc71fb99c2e49b6/CloudS2Mask-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dbdd69f5696024fafc7e079ee27d05a20ebd880c71e8a7140cacc745016ec47a",
"md5": "f31f665f87fbc1fb24bcf5066670bdd5",
"sha256": "c323a65f7303b16418e180237368037fc5a8dfb1635e5a5e87f1b41dc08530fd"
},
"downloads": -1,
"filename": "CloudS2Mask-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "f31f665f87fbc1fb24bcf5066670bdd5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 23973,
"upload_time": "2023-09-01T03:37:13",
"upload_time_iso_8601": "2023-09-01T03:37:13.814406Z",
"url": "https://files.pythonhosted.org/packages/db/dd/69f5696024fafc7e079ee27d05a20ebd880c71e8a7140cacc745016ec47a/CloudS2Mask-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-01 03:37:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DPIRD-DMA",
"github_project": "CloudS2Mask",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "clouds2mask"
}
JSON
