# OmniWaterMask
OmniWaterMask is a Python library for high accuracy water segmentation in high to moderate resolution satellite imagery, supporting a wide range of resolutions, sensors, and processing levels.
## Features
- Process imagery resolutions from 0.2 m to 50 m.
- Any imagery processing level
- Only requires Red, Green, Blue and NIR bands
- Known to work well with Sentinel-2, Landsat 8, PlanetScope, Maxar and NAIP
## Try in Colab
[![Colab_Button]][Link]
[Link]: https://colab.research.google.com/drive/15qgTgk4XiWcSzllNt4CtFU7pDSNrKLHk?usp=sharing 'Try OmniWaterMask In Colab'
[Colab_Button]: https://img.shields.io/badge/Try%20in%20Colab-grey?style=for-the-badge&logo=google-colab
## How it works
OmniWaterMask integrates a sensor agnostic deep learning segmentation model with NDWI and vector datasets to detect water bodies within remote sensing products.
Paper coming soon...
## Installation
To install the package, use one of the following commands:
Make sure you are running Python 3.9 or above and
```bash
conda create -n owm python=3.12
conda activate owm
pip install omniwatermask
```
```bash
conda create -n owm python=3.12
conda activate owm
pip install git+https://github.com/DPIRD-DMA/OmniWaterMask.git
```
## Usage
To predict a water mask for a list of scenes simply pass a list of geotiff files to the make_water_mask function along with the band order for the Red, Green, Blue and NIR bands. Predictions are saved to disk along side the input as geotiffs, a list of predictions file paths is returned:
```python
from pathlib import Path
from omniwatermask import make_water_mask
scene_paths = [Path("path/to/scene1.tif"), Path("path/to/scene2.tif")]
# Predict water masks for scenes
water_mask_path = make_water_mask(
scene_paths=[scene_paths], # you can pass a list of images
band_order=[1, 2, 3, 4], # band order of the input images, expects RGB+NIR
)
```
## Output
- Output classes are:
- 0 = Non-water
- 1 = water
## Usage tips
- OWM requires an active internet connection to function properly, as it needs to download OpenStreetMap (OSM) data.
- Hardware acceleration is strongly recommended:
- NVIDIA GPU
- Apple Silicon Mac
- Other PyTorch-compatible accelerators
- Consider enabling "bf16" inference_dtype on compatible hardware - this typically results in faster processing speeds.
- If experiencing VRAM limitations even with batch_size=1, switching the 'mosaic_device' parameter to 'cpu' can help.
- Improve accuracy by providing known water body locations as 'aux_vector_sources' - simply pass a list of file paths pointing to your water polygon datasets.
- Reduce false positives by including vector data for common misidentification sources (buildings, roads) through the 'aux_negative_vector_sources' parameter.
- When working with scenes containing no-data regions, explicitly set the 'no_data_value' parameter to ensure proper handling of these areas.
## Parameters
- `scene_paths`: List of paths or single path (supports both Path and string types) to the input satellite/aerial imagery
- `band_order`: List of integers specifying the band order for input imagery (e.g., [1,2,3,4] if your input image is stored with band order red, green, blue then NIR data). This tells OWM which bands correspond to Red, Green, Blue, and Near-Infrared channels
- `batch_size`: Number of patches processed simultaneously during inference. Default is 1, increase for better GPU utilization
- `version`: Version identifier for the output files. Defaults to current OmniWaterMask version
- `output_dir`: Optional path for output files. If not specified, outputs are saved alongside input files
- `mosaic_device`: Device for mosaic operations ("cpu", "cuda" or "mps"). Defaults to system's default device
- `inference_device`: Device for model inference ("cpu", "cuda" or "mps"). Defaults to system's default device
- `aux_vector_sources`: List of paths to supplementary water body vector data to aid detection
- `aux_negative_vector_sources`: List of paths to vector data marking areas commonly misidentified as water
- `inference_dtype`: Data type for inference operations. Defaults to torch.float32
- `no_data_value`: Value indicating no-data regions in the input imagery. Defaults to 0
- `inference_patch_size`: Size of image patches for inference. Defaults to 1000 pixels
- `inference_overlap_size`: Overlap between adjacent patches during inference. Defaults to 300 pixels
- `overwrite`: Whether to overwrite existing output files. Defaults to True
- `use_cache`: Whether to cache vector data processing results. Defaults to True
- `use_osm_building`: Whether to use OpenStreetMap building data to reduce false positives. Defaults to True
- `use_osm_roads`: Whether to use OpenStreetMap road data to reduce false positives. Defaults to True
- `cache_dir`: Directory for storing cached vector data. Defaults to "OWM_cache" in current directory
## Contributing
Contributions are welcome! Please submit a pull request or open an issue to discuss any changes.
## License
This project is licensed under the MIT License
## Acknowledgements
Special thanks to the [S1S2-Water dataset authors ](https://github.com/MWieland/s1s2_water) and [The FLAIR #1 dataset authors](https://ignf.github.io/FLAIR/) for providing the valuable training datasets.
Raw data
{
"_id": null,
"home_page": "https://github.com/DPIRD-DMA/OmniWaterMask",
"name": "omniwatermask",
"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/66/97/f007e7c7329c909b1626743ec2386af773f7fff47ce8a25cd6539cf76ed8/omniwatermask-0.2.7.tar.gz",
"platform": null,
"description": "# OmniWaterMask\n\nOmniWaterMask is a Python library for high accuracy water segmentation in high to moderate resolution satellite imagery, supporting a wide range of resolutions, sensors, and processing levels.\n\n## Features\n\n- Process imagery resolutions from 0.2 m to 50 m.\n- Any imagery processing level\n- Only requires Red, Green, Blue and NIR bands\n- Known to work well with Sentinel-2, Landsat 8, PlanetScope, Maxar and NAIP\n\n## Try in Colab\n\n[![Colab_Button]][Link]\n\n[Link]: https://colab.research.google.com/drive/15qgTgk4XiWcSzllNt4CtFU7pDSNrKLHk?usp=sharing 'Try OmniWaterMask In Colab'\n\n[Colab_Button]: https://img.shields.io/badge/Try%20in%20Colab-grey?style=for-the-badge&logo=google-colab\n\n## How it works\nOmniWaterMask integrates a sensor agnostic deep learning segmentation model with NDWI and vector datasets to detect water bodies within remote sensing products.\n\nPaper coming soon...\n\n## Installation\n\nTo install the package, use one of the following commands:\n\nMake sure you are running Python 3.9 or above and \n\n```bash\nconda create -n owm python=3.12\nconda activate owm\n\npip install omniwatermask\n```\n\n```bash\nconda create -n owm python=3.12\nconda activate owm\n\npip install git+https://github.com/DPIRD-DMA/OmniWaterMask.git\n```\n\n## Usage\n\nTo predict a water mask for a list of scenes simply pass a list of geotiff files to the make_water_mask function along with the band order for the Red, Green, Blue and NIR bands. Predictions are saved to disk along side the input as geotiffs, a list of predictions file paths is returned:\n\n```python\nfrom pathlib import Path\nfrom omniwatermask import make_water_mask\n\nscene_paths = [Path(\"path/to/scene1.tif\"), Path(\"path/to/scene2.tif\")]\n\n# Predict water masks for scenes\nwater_mask_path = make_water_mask(\n scene_paths=[scene_paths], # you can pass a list of images\n band_order=[1, 2, 3, 4], # band order of the input images, expects RGB+NIR\n)\n```\n## Output\n- Output classes are:\n- 0 = Non-water\n- 1 = water\n\n## Usage tips\n\n- OWM requires an active internet connection to function properly, as it needs to download OpenStreetMap (OSM) data.\n- Hardware acceleration is strongly recommended:\n - NVIDIA GPU\n - Apple Silicon Mac\n - Other PyTorch-compatible accelerators\n- Consider enabling \"bf16\" inference_dtype on compatible hardware - this typically results in faster processing speeds.\n- If experiencing VRAM limitations even with batch_size=1, switching the 'mosaic_device' parameter to 'cpu' can help.\n- Improve accuracy by providing known water body locations as 'aux_vector_sources' - simply pass a list of file paths pointing to your water polygon datasets.\n- Reduce false positives by including vector data for common misidentification sources (buildings, roads) through the 'aux_negative_vector_sources' parameter.\n\n- When working with scenes containing no-data regions, explicitly set the 'no_data_value' parameter to ensure proper handling of these areas.\n\n\n## Parameters\n\n- `scene_paths`: List of paths or single path (supports both Path and string types) to the input satellite/aerial imagery\n\n- `band_order`: List of integers specifying the band order for input imagery (e.g., [1,2,3,4] if your input image is stored with band order red, green, blue then NIR data). This tells OWM which bands correspond to Red, Green, Blue, and Near-Infrared channels\n\n- `batch_size`: Number of patches processed simultaneously during inference. Default is 1, increase for better GPU utilization\n\n- `version`: Version identifier for the output files. Defaults to current OmniWaterMask version\n\n- `output_dir`: Optional path for output files. If not specified, outputs are saved alongside input files\n\n- `mosaic_device`: Device for mosaic operations (\"cpu\", \"cuda\" or \"mps\"). Defaults to system's default device\n\n- `inference_device`: Device for model inference (\"cpu\", \"cuda\" or \"mps\"). Defaults to system's default device\n\n- `aux_vector_sources`: List of paths to supplementary water body vector data to aid detection\n\n- `aux_negative_vector_sources`: List of paths to vector data marking areas commonly misidentified as water\n\n- `inference_dtype`: Data type for inference operations. Defaults to torch.float32\n\n- `no_data_value`: Value indicating no-data regions in the input imagery. Defaults to 0\n\n- `inference_patch_size`: Size of image patches for inference. Defaults to 1000 pixels\n\n- `inference_overlap_size`: Overlap between adjacent patches during inference. Defaults to 300 pixels\n\n- `overwrite`: Whether to overwrite existing output files. Defaults to True\n\n- `use_cache`: Whether to cache vector data processing results. Defaults to True\n\n- `use_osm_building`: Whether to use OpenStreetMap building data to reduce false positives. Defaults to True\n\n- `use_osm_roads`: Whether to use OpenStreetMap road data to reduce false positives. Defaults to True\n\n- `cache_dir`: Directory for storing cached vector data. Defaults to \"OWM_cache\" in current directory\n\n\n## Contributing\n\nContributions are welcome! Please submit a pull request or open an issue to discuss any changes.\n\n## License\n\nThis project is licensed under the MIT License\n\n## Acknowledgements\n\nSpecial thanks to the [S1S2-Water dataset authors ](https://github.com/MWieland/s1s2_water) and [The FLAIR #1 dataset authors](https://ignf.github.io/FLAIR/) for providing the valuable training datasets.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for water segmentation in high to moderate resolution remotely sensed imagery",
"version": "0.2.7",
"project_urls": {
"Homepage": "https://github.com/DPIRD-DMA/OmniWaterMask"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d621ca93cd9da797de8cf45f6040e210571d8f72321b9d307b646c32e51c7a20",
"md5": "e58e051342c71fa9cc678f901610c9b0",
"sha256": "a11beb650825654d0d26d6cbbd68c232cd931eba71e952d8eff03b0aaa5094cd"
},
"downloads": -1,
"filename": "omniwatermask-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e58e051342c71fa9cc678f901610c9b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17882,
"upload_time": "2024-12-22T05:53:13",
"upload_time_iso_8601": "2024-12-22T05:53:13.112762Z",
"url": "https://files.pythonhosted.org/packages/d6/21/ca93cd9da797de8cf45f6040e210571d8f72321b9d307b646c32e51c7a20/omniwatermask-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6697f007e7c7329c909b1626743ec2386af773f7fff47ce8a25cd6539cf76ed8",
"md5": "2aed25f655b3cd54c02ca9de07ceb648",
"sha256": "be0fcefd52e1a32fde58ce282de334ee6614c4cb31b13d8f53c6d70497b33efe"
},
"downloads": -1,
"filename": "omniwatermask-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "2aed25f655b3cd54c02ca9de07ceb648",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17960,
"upload_time": "2024-12-22T05:53:15",
"upload_time_iso_8601": "2024-12-22T05:53:15.547082Z",
"url": "https://files.pythonhosted.org/packages/66/97/f007e7c7329c909b1626743ec2386af773f7fff47ce8a25cd6539cf76ed8/omniwatermask-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-22 05:53:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DPIRD-DMA",
"github_project": "OmniWaterMask",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "omniwatermask"
}
JSON
