Skip to main content

masks clouds and cloud shadows in Sentinel-2, Landsat-8, Landsat-7 and Landsat-5 images

Project description

UKIS ukis-csmask

ukis-csmask codecov Upload Python Package PyPI version GitHub license Code Style DOI

UKIS Cloud Shadow MASK (ukis-csmask) package masks clouds and cloud shadows in Sentinel-2, Landsat-8, Landsat-7 and Landsat-5 images. Masking is performed with a pre-trained convolution neural network. It is fast and works directly on Level-1C data (no atmospheric correction required). Images just need to be in Top Of Atmosphere (TOA) reflectance and include at least the "Blue", "Green", "Red", "NIR", "SWIR1" and "SWIR2" spectral bands. Best performance (in terms of accuracy and speed) is achieved when images are resampled to approximately 30 m spatial resolution.

This publication provides further insight into the underlying algorithm and compares it to the widely used Fmask algorithm across a heterogeneous test dataset. If you use ukis-csmask in your work, please consider citing us as follows.

Wieland, M.; Li, Y.; Martinis, S. Multi-sensor cloud and cloud shadow segmentation with a convolutional neural network. Remote Sensing of Environment, 2019, 230, 1-12. https://doi.org/10.1016/j.rse.2019.05.022

Examples

Example

Here's an example on how to compute a cloud and cloud shadow mask from an image. Please note that here we use ukis-pysat for convencience image handling, but you can also work directly with numpy arrays.

from ukis_csmask.mask import CSmask
from ukis_pysat.raster import Image, Platform

# read Level-1C image from file, convert digital numbers to TOA reflectance
# and make sure resolution is 30 m to get best performance
img = Image(data="sentinel2.tif", dimorder="last")
img.dn2toa(platform=Platform.Sentinel2)
img.warp(
    resampling_method=0,
    resolution=30,
    dst_crs=img.dataset.crs
)

# compute cloud and cloud shadow mask
# NOTE: band_order must match the order of bands in the input image. it does not have to be in this explicit order,
# but needs to include these six spectral bands.
csmask = CSmask(
    img=img.arr,
    band_order=["Blue", "Green", "Red", "NIR", "SWIR1", "SWIR2"],
    nodata_value=0,
)

# access cloud and cloud shadow mask
csmask_csm = csmask.csm

# access valid mask
csmask_valid = csmask.valid

# convert results to UKIS-pysat Image
csmask_csm = Image(csmask.csm, transform=img.dataset.transform, crs=img.dataset.crs, dimorder="last")
csmask_valid = Image(csmask.valid, transform=img.dataset.transform, crs=img.dataset.crs, dimorder="last")

# write results back to file
csmask_csm.write_to_file("sentinel2_csm.tif", dtype="uint8", compress="PACKBITS")
csmask_valid.write_to_file("sentinel2_valid.tif", dtype="uint8", compress="PACKBITS", kwargs={"nbits":2})

Installation

The easiest way to install ukis-csmask is through pip. The default installation supports CPU computation.

pip install ukis-csmask

To install ukis-csmask with GPU support run the following instead. This requires that you have a GPU with CUDA runtime libraries (CUDA 10.2 and cuDNN 8.0.3) installed on the system.

pip install ukis-csmask[gpu]

For a list of dependencies check the requirements.

Contributors

The UKIS team creates and adapts libraries which simplify the usage of satellite data. Our team includes (in alphabetical order):

  • Boehnke, Christian
  • Fichtner, Florian
  • Mandery, Nico
  • Martinis, Sandro
  • Riedlinger, Torsten
  • Wieland, Marc

German Aerospace Center (DLR)

Licenses

This software is licensed under the Apache 2.0 License.

Copyright (c) 2020 German Aerospace Center (DLR) * German Remote Sensing Data Center * Department: Geo-Risks and Civil Security

Changelog

See changelog.

Contributing

The UKIS team welcomes contributions from the community. For more detailed information, see our guide on contributing if you're interested in getting involved.

What is UKIS?

The DLR project Environmental and Crisis Information System (the German abbreviation is UKIS, standing for Umwelt- und Kriseninformationssysteme aims at harmonizing the development of information systems at the German Remote Sensing Data Center (DFD) and setting up a framework of modularized and generalized software components.

UKIS is intended to ease and standardize the process of setting up specific information systems and thus bridging the gap from EO product generation and information fusion to the delivery of products and information to end users.

Furthermore the intention is to save and broaden know-how that was and is invested and earned in the development of information systems and components in several ongoing and future DFD projects.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ukis-csmask-0.1.4.tar.gz (28.9 MB view details)

Uploaded Source

Built Distribution

ukis_csmask-0.1.4-py3-none-any.whl (28.9 MB view details)

Uploaded Python 3

File details

Details for the file ukis-csmask-0.1.4.tar.gz.

File metadata

  • Download URL: ukis-csmask-0.1.4.tar.gz
  • Upload date:
  • Size: 28.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.2 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.10.2

File hashes

Hashes for ukis-csmask-0.1.4.tar.gz
Algorithm Hash digest
SHA256 a4dc5a0aae72a0f2d344f7704804911de99175f2c5f525ad044557716e7b6685
MD5 ab6b5ea04a2836bb881429a79ee4bd1d
BLAKE2b-256 599a9dfff249cb4d550d5f92f0891d8b91b4206141347e0fdb3fb78f3aa84446

See more details on using hashes here.

File details

Details for the file ukis_csmask-0.1.4-py3-none-any.whl.

File metadata

  • Download URL: ukis_csmask-0.1.4-py3-none-any.whl
  • Upload date:
  • Size: 28.9 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.2 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.10.2

File hashes

Hashes for ukis_csmask-0.1.4-py3-none-any.whl
Algorithm Hash digest
SHA256 1804724d530aa134052be2ef452e7f8fa1304222e2a828468a0bab8ea4b97e28
MD5 243bd68a74f79477e11607ad6fa5323c
BLAKE2b-256 f620fbc4c1bc3456d6da1b2eb0ffa6b37556cb9e062dea1b45a3e64eb821ace6

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page