ukis-csmask 1.0.0

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

ukis-csmask

UKIS Cloud Shadow MASK (ukis-csmask) package masks clouds and cloud shadows in Sentinel-2, Landsat-9, Landsat-8, Landsat-7 and Landsat-5 images. Masking is performed with a pre-trained convolution neural network. It is fast and works with both Level-1C (no atmospheric correction) and Level-2A (atmospherically corrected) data. Images just need to be in reflectance and include at least the "blue", "green", "red" and "nir" spectral bands. Best performance (in terms of accuracy and speed) is achieved when images also include "swir16" and "swir22" spectral bands and 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.

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

This publication introduces the Python package, performs additional evaluation on recent cloud and cloud shadow benchmark datasets and tests the applicability of ukis-csmask on Landsat-9 imagery.

Wieland, M.; Fichtner, F.; Martinis, S. UKIS-CSMASK: A Python package for multi-sensor cloud and cloud shadow segmentation. Int. Arch. Photogramm. Remote Sens. Spatial Inf. Sci., 2022, XLIII-B3-2022, 217–222. https://doi.org/10.5194/isprs-archives-XLIII-B3-2022-217-2022

If you use ukis-csmask in your work, please consider citing one of the above publications.

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. Further examples can be found here.

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
# NOTE: band_order must match the order of bands in the input image. it does not have to be in this explicit order.
band_order = ["blue", "green", "red", "nir", "swir16", "swir22"]
img = Image(data="sentinel2.tif", dimorder="last")
img.dn2toa(platform=Platform.Sentinel2, wavelength=band_order)
img.warp(resampling_method=0,resolution=30,dst_crs=img.dataset.crs)

# compute cloud and cloud shadow mask
csmask = CSmask(img=img.arr, product_level="l1c", band_order=band_order, 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})

Accuracy assessment

The original ukis-csmask models, which are available in ukis-csmask<=v0.2.2 and are described in this publication, have been trained and tested on a custom reference dataset specifically for Level-1C data.

From ukis-csmask>=v1.0.0 on, we provide new models for Level-1C (L1C) and Level-2A (L2A) data, which have been trained on a much larger reference dataset (consisting of SPARCS, CloudSEN12+ and some additional custom samples). Both datasets natively only provide L1C images. Therefore, we have compiled corresponding L2A images for each sample.

Above barplot compares the new ukis-csmask>=v1.0.0 models against the previous ukis-csmask<=v0.2.2 models on CloudSEN12+ and SPARCS test splits for both L1C and L2A images. The results indicate the superior performance of the new ukis-csmask>=v1.0.0 models against the previous ukis-csmask<=v0.2.2 models across all tested datasets and product levels. Providing separate models for each product level provides further improvements and enables greater flexibiliy.

Installation

The easiest way to install ukis-csmask is through pip. To install ukis-csmask with default CPU provider run the following.

pip install ukis-csmask[cpu]

To install ukis-csmask with OpenVino support for enhanced CPU inference run the following instead.

pip install ukis-csmask[openvino]

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

pip install ukis-csmask[gpu]

ukis-csmask depends on onnxruntime. For a list of additional 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.