CalculateCloudMaskUsingFmask Task

This task calculates a cloud mask for the following sensors: Landsat 4-5 TM, Landsat 7 ETM+, Landsat 8, and Sentinel-2.

This task requires extra steps to calibrate and layer-stack the imagery before creating a cloud mask. Consider using the simpler CalculateCloudMaskForProduct task.

You must supply an input raster containing multispectral bands that have been calibrated to top-of-atmosphere (TOA) reflectance. The following inputs are optional:

A thermal-band raster calibrated to brightness temperatures, in Kelvins.
Landsat-8 only and Sentinel-2 only: A cirrus-band raster, calibated to TOA reflectance.

If you are working with Landsat 8 data, you can optionally create a layer stack that contains the TOA reflectance and TOA cirrus bands.

ENVI uses the Fmask algorithm cited in the following references:

Zhu, Z., S. Wang, and C. E. Woodcock. "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, doi:10.1016/j.rse.2014.12.014 (paper for Fmask version 3.2).

Zhu, Z., and C. E. Woodcock. "Object-Based Cloud and Cloud Shadow Detection in Landsat Imagery." Remote Sensing of Environment 118 (2012): 83-94, doi:10.1016/j.rse.2011.10.028 (paper for Fmask version 1.6).

Example

This example calculates a cloud mask for a Landsat-8 file. Update the file name and location with your own data. This example assumes that the pixel sizes for all rasters are 30 meters. No layer stacking is required.

; Start the application

e = ENVI()

; Open a Landsat-8 file

File = 'LC80410302013213LGN00_MTL.txt'

Raster = e.OpenRaster(File)

; Landsat-8 images are stored in a five-element array.

; Get the bands needed for this task.

OLIBands = Raster[0]

CirrusBand = Raster[2]

ThermalBands = Raster[3]; Thermal infrared 1 and 2

; Calibrate OLI bands to TOA reflectance

RadTask = ENVITask('RadiometricCalibration')

RadTask.INPUT_RASTER = OLIBands

RadTask.CALIBRATION_TYPE = 'Top-of-Atmosphere Reflectance'

RadTask.Execute

; Calibrate Cirrus band to TOA reflectance

CirrusRadTask = ENVITask('RadiometricCalibration')

CirrusRadTask.INPUT_RASTER = CirrusBand

CirrusRadTask.CALIBRATION_TYPE = 'Top-of-Atmosphere Reflectance'

CirrusRadTask.Execute

; Calibrate thermal bands to brightness temperature

BTTask = ENVITask('RadiometricCalibration')

BTTask.INPUT_RASTER = ThermalBands

BTTask.CALIBRATION_TYPE = 'Brightness Temperature'

BTTask.Execute

; Calculate cloud mask

CloudTask = ENVITask('CalculateCloudMaskUsingFmask')

CloudTask.INPUT_BRIGHTNESS_TEMPERATURE_RASTER = BTTask.OUTPUT_RASTER

CloudTask.INPUT_CIRRUS_RASTER = CirrusRadTask.OUTPUT_RASTER

CloudTask.INPUT_REFLECTANCE_RASTER = RadTask.OUTPUT_RASTER

CloudTask.Execute

; Get the collection of data objects currently available in the Data Manager

DataColl = e.Data

; Add the output to the Data Manager

DataColl.Add, CloudTask.OUTPUT_RASTER

; Display the result

View = e.GetView()

Layer = View.CreateLayer(CloudTask.OUTPUT_RASTER)

View.Zoom, /FULL_EXTENT

The result of this process is a binary image where cloud (masked) pixels have values of 0 and non-cloud (non-masked) pixels have values of 1. To apply the mask to the input reflectance raster, add the following steps. The masked pixels will have NoData values.

rasterWithMask = ENVIMaskRaster( $

  RadTask.OUTPUT_RASTER, $

  CloudTask.OUTPUT_RASTER)

DataColl.Add, rasterWithMask

Layer2 = View.CreateLayer(rasterWithMask)

You can use the rasterWithMask raster for any subsequent image processing now that you calibrated it to top-of-atmosphere reflectance and applied a cloud mask. If you will perform spectral analysis on the data, you should correct for atmospheric effects next by using the ENVIQUACTask routine.

Syntax

Result = ENVITask('CalculateCloudMaskUsingFmask')

Input parameters (Set, Get): INPUT_BRIGHTNESS_TEMPERATURE_RASTER, INPUT_CIRRUS_RASTER, KERNEL_SIZE, CLOUD_THRESHOLD, OUTPUT_RASTER_URI, INPUT_REFLECTANCE_RASTER

Output parameters (Get only): OUTPUT_RASTER

Parameters marked as "Set" are those that you can set to specific values. You can also retrieve their current values any time. Parameters marked as "Get" are those whose values you can retrieve but not set.

Input Parameters

KERNEL_SIZE (optional)

Specify the number of pixels along one side of a square kernel. The default value is 7 (to create a 7 x 7 array). Cloud regions are dilated by this kernel size before output.

CLOUD_THRESHOLD (optional)

Specify a floating-point threshold for cloud probability over clear-land and clear-water regions. The default value is 22.5.

INPUT_BRIGHTNESS_TEMPERATURE_RASTER (optional)

Specify a thermal band raster, calibrated to brightness temperatures. The input wavelengths must range from 10.4 to 12.5 µm. First execute the RadiometricCalibration task with the CALIBRATION_TYPE parameter set to Brightness Temperature, then pass its output to INPUT_BRIGHTNESS_TEMPERATURE_RASTER.

Landsat 4-5 TM: Band 6
Landsat-7 ETM+: Band 61. See Frequently Asked Questions about the Landsat Missions for more information about the difference between Band 61 and 62.
Landsat-8 TIRS: Thermal Infrared 1.

See Metaspectral Datasets for instructions on specifying the correct array element for the thermal bands.

INPUT_CIRRUS_RASTER (optional)

Specify a Landsat-8 cirrus band raster, calibrated to top-of-atmosphere reflectance. The input wavelengths must range from 1.36 to 1.385 µm. First execute the RadiometricCalibration task with the CALIBRATION_TYPE parameter set to Top-of-atmosphere Reflectance, then pass its output to INPUT_CIRRUS_RASTER. See Metaspectral Datasets for instructions on specifying the correct array element for the cirrus band.

INPUT_REFLECTANCE_RASTER (required)

Specify a raster containing the Landsat multispectral bands, calibrated to top-of-atmosphere (TOA) reflectance. First execute the RadiometricCalibration task with the CALIBRATION_TYPE parameter set to Top-of-atmosphere Reflectance, then pass its output to INPUT_REFLECTANCE_RASTER.

Landsat 4-5 TM: Bands 1-5, 7
Landsat-7 ETM+: Bands 1-7
Landsat-8 OLI: Coastal aerosol, Blue, Green, Red, NIR, SWIR1, SWIR2

See Metaspectral Datasets for instructions on specifying the correct array element for the multispectral bands.

The input wavelengths must be within the following ranges:

Blue: 0.45 - 0.523 µm
Green: 0.52 - 0.605 µm
Red: 0.63 - 0.69 µm
NIR: 0.75 - 0.9 µm
SWIR1: 1.55 - 1.75 µm
SWIR2: 2.05 - 2.380 µm

OUTPUT_RASTER_URI (optional)

Specify a string with the fully qualified filename and path of the associated OUTPUT_RASTER.

If you do not specify this parameter, or set it to an exclamation symbol (!), ENVI creates a temporary file.
If you set it to the hash symbol (#), ENVI creates a file in the temporary directory, but this file will not be deleted when ENVI closes.