Fmask

The software called Fmask (Function of mask) is used for automated clouds, cloud shadows, snow, and water masking for Landsats 4-9 and Sentinel 2 images.

If you have any questions, please contact Zhe Zhu (zhe@uconn.edu) and Shi Qiu (shi.qiu@uconn.edu) at the Department of Natural Resources and the Environment, University of Connecticut.

IMPORTANT: Fmask 5, a novel physics-informed machine learning model programmed in Python, is officially released from this link.

IMPORTANT:

Fmask 4.7 improved the cloud and cloud shadow detection by integrating a global auxiliary data including DEM and water layer, and this GitHub page ONLY provides the Matlab code due to the storage limitation of the repository. The full Matlab code package with GLOBAL AUXILIARY DATA is available at this One Drive, where autoFmask is the main function for processing an image. autoFmaskBacth can process all Landsats 4-9 and Sentinel-2 images into a folder. The folder <AuxiData> includes the auxiliary dataset. Please note that the Mapping Toolbox in MATLAB is required to use the source code, and R2022a is recommended. The standalone can be downloaded for Linux (One Drive) and Windows (One Drive). This link provides the standalone with UI on Windows. The tutorial for using the standalone can be found at this link. Other older versions of Fmask are available upon request.

USE of GLOBAL AUXILIARY DATA: (Matlab code or Windows standalone users can ignore this)

The Matlab code or Windows standalone can automatically locate the package of the global auxiliary data, and there will be a notification regarding the dataset (successfully located or not) when running the Fmask. However, particularly for the Linux standalone, if it fails to locate the auxiliary data, please set up the direct path of the auxiliary data package by using the command, for example, Fmask_4_6 "xxx\xxx\xxx\AuxiData". The directory of the auxiliary data <AuxiData> is usually at the same location as the installed application. Please see an example of how to address this issue from this link.

Note that previous versions do not provide any notifications even when they fail to locate the dataset, and if you have already run the previous versions of Fmask using the Linux standalone, it is highly possible that the dataset has been ignored. In such a case, the detection of cloud and cloud shadows may not be significantly improved for Landsat data compared to the Fmask version 3.3, especially for mountain areas and water regions, where more commission errors may be resulted in, but the outputs will be more like the ones generated using version 3.3, which are also good to use. For Sentinel-2 data, the Fmask 4 can still significantly improve the detection of clouds and cloud shadows even without the auxiliary dataset, due to the new features that nothing about the auxiliary data, such as HOT-based cloud probability.

IMPORTANT:

This 4.7 version has substantial better cloud, cloud shadow, and snow detection results for Sentinel 2 and better results (compared to the 3.3 version that is currently being used by USGS as the Collection 1 QA Band) for Landsats 4-9. This version can be used for Landsats 4-9 Collection 1/2 Level 1 product (Digital Numbers) and Sentinel-2 baseline 3/4 Level-1C product (Top Of Atmosphere reflectance) at the same time.

The majority of the current Collection 1 Landsats 4-9 QA Band provided by USGS are derived form 3.3 Version of Fmask algorithm based on default parameters (cloud probability is 22.5% and buffer pixel size is 3). For example, (1) The Cloud (bit 4) is based on Fmask cloud mask (0 is not cloud and 1 is cloud in Fmask); (2) The Cloud Confidence (bits 5-6) is based on Fmask cloud probability in which >22.5% is high (11), >12.5% is medium (10), and <12.5% is low (01) with 00 kept for future use; (3) Snow/ice Confidence (bits 9-10) and Cloud Shadow Confidence (bits 7-8) has only low confidence (01) and high confidence (11) which correspond to no and yes respectively in snow/ice and cloud shadow mask provided by Fmask.

IMPORTANT:

When making the accuracy assessment for Fmask, please dilate 3 pixels for cloud shadow, but no dilation for cloud, snow, and water.

4.7 Version

1. Updated for Sentintel-2C. (1/16/2025)

4.6 Version

2. Updated for Landsat 9. (2/27/2022)

----- 4.5 Version below ----

3. Implemented a static seed random generator when detecting cloud shadow, which can ensure the reproducibility of the outputs. (Thanks NASA HLS team for this suggestion).

----- 4.4 Version below ----

4. To fix the errors in computing the ID of detector footprints during the view angle generation of the new Sentinel-2 data processing baseline 04.00 (This may result in wrong locations of cloud shadow), and to provide the notifications regarding the global auxiliary data and the input interface of setting the dataset path (particularly for Linux standalone). (Shi Qiu 1/26/2022)

5. To process the new Sentinel-2 data with processing baseline 04.00, to fix bugs in producing the view angles (detectors sorted) and converting the datetime of Sentinel-2 data (irregular format sometimes), and to update the functions of processing Landsat Collection 2 data. (Shi Qiu 12/28/2021)

----- 4.3 version below ----

6. Fixed the bug when GRIDobj reads geotiff with several tiffinfos (see GRIDobj.m). (Shi Qiu 10/15/2020)

----- 4.2 version below ----

7. Update Fmask tool for processing Landsat Collection 2 data; and allow the cloud probability threshold in a larger range such as [-100, 100] in the GUI version. (Shi Qiu 4/8/2020)

----- 4.1 version below ----

8. The cloud shadow mask over water would not be provided at default settings since this will be less meaningful to use and very time-consuming to process. At the same time, fixed the bug that the auxiliary data may not be used for some Sentinel-2 images, of which the extent in the metadata is defined in [0 360] rather than [-180 180]. (Shi Qiu 3/17/2020)

----- 4.0 version below ----

9. Fixed the bug that the cloud shadows in Sentinel-2 imagery would be projected along the wrong direction when solar azimuth angle > 180 degrees. (Shi Qiu 01/19/2019)

10. Integrated Cloud Displacement Index (CDI) into this Fmask 4.0 for better separating clouds from bright surfaces especial for Sentinel-2. The CDI was specially designed to separate clouds from bright surfaces based on the view angle parallax of the three near-infrared bands (band 7, 8, and 8a) (Frantz et al., 2018). (Shi Qiu and Zhe Zhu 06/03/2018)

11. Revised the method to identify the potential false positive cloud pixels. (Shi Qiu and Zhe Zhu 05/23/2018)

12. Restricted the height of the clouds located in the scene boundary into the predicted cloud height derived from its neighboring clouds. (Shi Qiu 04/05/2018)

13. Removed the overlap between the predicted cloud shadow and the potential cloud shadow layer for cloud shadow detection. (Shi Qiu and Zhe Zhu 03/29/2018)

14. Fixed the bug that the reading blue band using GRIDobj may lead to Nan value for Landsat images. (Shi Qiu 03/26/2018)

15. Improved the computational efficiency especially for cloud shadow matching procedure. (Zhe Zhu and Shi Qiu 03/24/2018)

16. Released Fmask 4.0 beta version. (Shi Qiu, Zhe Zhu, and Binbin He 03/22/2018)

Please cite the following papers:

paper 1: Qiu S., et al., Fmask 4.0: Improved cloud and cloud shadow detection in Landsats 4-8 and Sentinel-2 imagery, Remote Sensing of Environment, (2019), doi.org/10.1016/j.rse.2019.05.024 (paper for Fmask 4.0).

paper 2: Zhu, Z. and Woodcock, C. E., Improvement and Expansion of the Fmask Algorithm: Cloud, Cloud Shadow, and Snow Detection for Landsats 4-7, 8, and Sentinel 2 images, Remote Sensing of Environment (2014) doi:10.1016/j.rse.2014.12.014 (paper for Fmask version 3.2).

paper 3: Zhu, Z. and Woodcock, C. E., Object-based cloud and cloud shadow detection in Landsat imagery, Remote Sensing of Environment (2012), doi:10.1016/j.rse.2011.10.028 (paper for Fmask version 1.6).

paper 4: Qiu S., et al. Improving Fmask cloud and cloud shadow detection in mountainous area for Landsats 4–8 images, Remote Sensing of Environment (2017), doi.org/10.1016/j.rse.2017.07.002 (paper for Mountainous Fmask (MFmask), that has been integrated into this Fmask 4.0).

paper 5: Qiu, S., et al., Making Landsat Time Series Consistent: Evaluating and Improving Landsat Analysis Ready Data, Remote Sensing (2019), doi.org/10.3390/rs11010051 (First paper introducing Fmask 4.0 for improving LTS consistency).

After running Fmask 4.0, there will be an image called XXXFmask.tif. The image values are presenting the following classes:

0 => clear l