Python Fmask


A set of command line utilities and Python modules that implement the ‘fmask’ algorithm as published in:

Zhu, Z. and Woodcock, C.E. (2012). Object-based cloud and cloud shadow detection in Landsat imagery Remote Sensing of Environment 118 (2012) 83-94.


Zhu, Z., Wang, S. and Woodcock, C.E. (2015). 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 159 (2015) 269-277.

Installation requires Python, numpy, scipy, GDAL and RIOS and the ability to compile C extensions for Python. It is licensed under GPL 3.

Originally developed by Neil Flood at DSITI and additional work funded by Landcare Research.


This package implements the Fmask algorithm as a Python module. It is intended that this can be wrapped in a variety of main programs which can handle the local details of how the image files are named and organised, and is intended to provide maximum flexibility. It should not be tied to expecting the imagery to be layed out in a particular manner.

This modular design also simplifies the use of the same core algorithm on either Landsat and Sentinel imagery. The wrapper programs take care of differences in file organisation and metadata formats, while the core algorithm is the same for both.

However, we have also supplied some example wrapper scripts, based around the image organisation as supplied by the usual distributors of the imagery. In the case of Landsat, we have supplied main programs which can cope with the data as it comes from USGS, while in the case of Sentinel-2 we have supplied wrappers to deal with the data as supplied by ESA.

It is expected that some users will use these directly, while larger organisations will wish to create their own wrappers specific to their own file naming and layout conventions.

The output from the core algorithm module is a single thematic raster, with integer codes representing null, clear, cloud, shadow, snow, water respectively.

The examples shown below use the given example wrappers.

Command Line Examples

All the commandline programs given use argparse to handle commandline arguments, and hence will respond sensibly to the -h option by printing their own help. Some have options to modify their behaviour.

Please note that the output format used is defined by RIOS. This defaults to HFA (.img). See RIOS documentation for more information and how to change this using the environment variable $RIOS_DFLT_DRIVER.

Note: these examples are for use in a Unix/Linux shell so that the filename wildcards get expanded properly. Windows users should prefix these commands with “fmask_expandWildcards” so that the commands get run with the wildcards expanded as they do in Unix/Linux.

USGS Landsat

The command line scripts supplied can process an untarred USGS Landsat scene. Firstly, the reflective and thermal bands must be stacked separately. This needs to be done in a different manner depending on the sensor. (Note: The wild cards shown here are for the more modern form of the USGS naming convention. Older forms would require slightly different wild card patterns. )

Landsat 4&5: -separate -of HFA -co COMPRESSED=YES -o ref.img L*_B[1,2,3,4,5,7].TIF -separate -of HFA -co COMPRESSED=YES -o thermal.img L*_B6.TIF

Landsat 7: -separate -of HFA -co COMPRESSED=YES -o ref.img L*_B[1,2,3,4,5,7].TIF -separate -of HFA -co COMPRESSED=YES -o thermal.img L*_B6_VCID_?.TIF

Landsat 8: -separate -of HFA -co COMPRESSED=YES -o ref.img LC8*_B[1-7,9].TIF -separate -of HFA -co COMPRESSED=YES -o thermal.img LC8*_B1[0,1].TIF

The next step is to create an image of the relevant angles, per-pixel, for use in subsequent steps. For Landsat, this can be done using: -m *_MTL.txt -t ref.img -o angles.img

Then mask and Top of Atmosphere reflectance must be calculated and finally the cloud mask itself: -i ref.img -m *_MTL.txt -o saturationmask.img -i ref.img -m *_MTL.txt -z angles.img -o toa.img -t thermal.img -a toa.img -m *_MTL.txt -z angles.img -s saturationmask.img -o cloud.img

If the thermal band is empty (for Landsat-8 with the SSM anomaly, after 2015-11-01) then it is ignored gracefully.


The command line scripts supplied can process a Sentinel2 Level C granule from the image directory. Here is an example of how to do this. This example works at 20m resolution, but the recipe can be varied as required. Be warned, processing at 10m resolution would be considerably slower, and is unlikely to be any more accurate.

This makes a stack of ALL the bands, at the 20m resolution (a compromise between speed and detail). Bands are in order of numeric band number:

gdalbuildvrt -resolution user -tr 20 20 -separate allbands.vrt *_B0[1-8].jp2 *_B8A.jp2 *_B09.jp2 *_B1[0-2].jp2

Make a separate image of the per-pixel sun and satellite angles. -i ../*.xml -o angles.img

Now create the cloud mask output image. Note that this assumes the bands are in a particular order (as created in the vrt, above): -a allbands.vrt -z angles.img -o cloud.img

Note that the wild card patterns used in the above example commands are quite simple. This is mainly so that they will work with both the old and the new file naming conventions which ESA are using. Feel free to be more restrictive.

Re-wrapping and Re-configuring

To build a different set of wrappers, and configure things differently, the default wrappers are a good place to start. The configuration is mainly handled by the fmask.config.FmaskConfig class. For example, one would call fmask.config.FmaskConfig.setReflectiveBand() to change which layer of the stack corresponds to which wavelength band.


Get the source as a bundle from BitBucket. Release notes for each version can be read in Release Notes. To install from source, read the INSTALL.txt file included inside the source bundle.

Pre-built binary Conda packages are available under the ‘conda-forge’ channel. Once you have installed Conda, run the following commands on the command line to install python-fmask:

conda config --add channels conda-forge
conda create -n myenv python-fmask
source activate myenv # omit 'source' on Windows


Please log bugs encountered with the Issue Tracker.