Fmask 4.

0 Handbook

Shi Qiu (qsly09@hotmail.com)

Zhe Zhu (zhe.zhu@ttu.edu)
Binbin He (binbinhe@uestc.edu.cn)

May 22, 2018

ABSTRACT

Fmask 4.0 is developed based on 3.3 version of Fmask algorithm (Zhu et al.,
2015) and the MFmask algorithm (Qiu et al., 2017). This 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-8. This software can be used for
Landsats 4-8 Collection 1 Level 1 product and Sentinel 2 Level-1C product
at the same time. This temporary document provides guide to use this new
Fmask tool with GUI and the command-line based tool (without GUI).

ALGORITHM INPUTS
Besides Top of Atmosphere (TOA) reflectances and Brightness Temperature
(BT), this new Fmask uses several auxiliary data, including Digital Elevation
Models (DEMs), DEM-derived slope, DEM-derived aspect, and Global Surface
Water Occurrence (GSWO) data. Note that the auxiliary data in the package is
only available for the images between 84°N and 80°S. For these regions, the
corresponding DEM data for each image needs to be manually downloaded,
mosaicked, projected, and resampled to image's resolution and extent (save it as
‘image name_DEM.tif’ at the scene folder) as following examples. NOTE you
can also manually prepare better DEM data (e.g., 30 meters STRM), that would
provide slightly better results.
Landsat data:

Sentinel 2 data:
S2A_OPER_PRD_MSIL1C_T28PDC_2016351A.SAFE
- GRANULE
- L1C_T28PDC_A007756_20161216T113355
- FMASK_DATA (Fmask tool automatically creates this folder)
HOW TO INSTALL

1. Download the setup files and run Fmask4.0 InstallerMac for MAC (Fmask
4.0 installer.exe for Windows).

2. During the installation, a brief introduction is illustrated.

3. The setup program provides an option for installation, which allows you to
choose specific installation components.
4. The MATLAB Runtime will be installed, which also allows you to choose
specific installation components.

5. During the installation for MATLAB RUNTIME, read the license agreement
and accept it.

6. More than 1 G disk space will be used.

7. The MATLAB Runtime will be downloaded.

8. Installation completed.
HOW TO USE
It needs approximately 5G memory to run this algorithm, that means a machine
with 8G+ memory are recommended.

Quick use: Start > Select Image(s) > Set parameters (skippable) > Run

1. Start application
Launch the Fmask 4.0 tool, of which interface will be illustrated.

2. Select image(s)
Click ‘Select’ to choose the directory of images. This tool will process one image
if an image directory is selected. Multi images will be automatically processed in
sequence if a directory containing numbers of images is selected.
3. Set parameters (skip this if you do not want to use default parameters)
The dilation (buffer) sizes for cloud, cloud shadow, and snow are 3, 3, and 0
pixels. The cloud probability threshold is 10% for Landsats 4-7, 17.5% for
Landsat 8, and 20% for Sentinel 2A/B (Table 1).

These parameters also can be manually changed in this tool to get optimal cloud,
cloud shadow, and snow detection results. The most critical parameter is cloud
probability threshold. The default cloud probability thresholds has the best
overall accuracies across our global test sites. If you want less commission error,
higher probability is recommended (50% for instance), and if you want less
omission error, lower probability is recommended (7.5% for instance). Note that
the two-way switch at ‘Custom’ activates the adjustment of the cloud probability
threshold, otherwise default threshold will be used.

Table 1 Input parameters of Fmask 4.0.

Input Arguments Descriptions Default Values (Pixels)

Cloud Number of dilated pixels for cloud 3 (0 for accuracy assessment)

Shadow Number of dilated pixels for cloud 3

shadow

snow Number of dilated pixels for snow 0

10.0 % for Landsats 4~7,

Cloud Probability Cloud probability threshold for
17.5 % for Landsat 8,
Threshold creating potential cloud layer
and 20.0 % for Sentinel 2
4. Run
Click ‘Run’ and wait for the new Fmask results. If everything is going well, the
status light will be GREEN; If something is incorrect, the status light’s color will
be changed to YELLOW or RED, and error information can be found at the end
of the information board.
It normally takes 0.5 to 10 minutes for processing one Landsat or Sentinel 2 image
with one CPU.

5. Fmask results
After running Fmask, there will be an image called ‘XXX_Fmask.tif’. Note that
a folder called ‘FMASK_DATA’ will be created to save Fmask results for
Sentinel 2 data. The image values are presenting the following classes:

0 => clear land pixel

1 => clear water pixel

2 => cloud shadow

3 => snow

4 => cloud

255 => no observation

6. Exit
After finishing all processes, we can click ‘Exit’ to close the tool. Additionally,
you can also cancel all tasks during their running using the ‘Exit’ button but need
to notice that you would wait some seconds or minutes before canceling the
processing task.
Standalone without GUI
Sometimes a standalone without GUI is also useful especially for batch
processing in parallel model. Users can temporarily refer the instructions for the
Fmask 3.3 to use this new Fmask
(https://www.dropbox.com/s/gx7x7htynxk5ulp/Fmask_Windows_Standalone_Instructi

ons_Website.pdf?dl=0).

Note:
In the Command Prompt, cd into the folder where Landsat bands and .MTL
files for Landsats 4-8 data or the folder (as below example) for Sentinel 2, and
run Fmask by entering “Fmask_4_0” (also can change the parameters as the
same as 3.3 version).

cd into the folder for Sentinel 2 as:

Sentinel 2 data:
S2A_OPER_PRD_MSIL1C_T28PDC_2016351A.SAFE
- GRANULE
- L1C_T28PDC_A007756_20161216T113355