Welcome to the Harris Geospatial documentation center. Here you will find reference guides and help documents.


  >  Docs Center  >  ENVI API  >  Processing  >  ENVICalculateCloudMaskUsingFmaskTask

ENVICalculateCloudMaskUsingFmaskTask

ENVICalculateCloudMaskUsingFmaskTask

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 ENVICalculateCloudMaskForProductTask routine.

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 properties (Set, Get): INPUT_BRIGHTNESS_TEMPERATURE_RASTER, INPUT_CIRRUS_RASTER, KERNEL_SIZE, CLOUD_THRESHOLD, OUTPUT_RASTER_URI, INPUT_REFLECTANCE_RASTER

Output properties (Get only): OUTPUT_RASTER

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

Methods


This task inherits the following methods from ENVITask:

AddParameter

Execute

Parameter

ParameterNames

RemoveParameter

Properties


This task inherits the following properties from ENVITask:

COMMUTE_ON_DOWNSAMPLE

COMMUTE_ON_SUBSET

DESCRIPTION

DISPLAY_NAME

NAME

REVISION

TAGS

This task also contains the following properties:

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 ENVIRadiometricCalibrationTask with the CALIBRATION_TYPE property set to Brightness Temperature, then pass its output to INPUT_BRIGHTNESS_TEMPERATURE_RASTER.

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 ENVIRadiometricCalibrationTask with the CALIBRATION_TYPE property 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 ENVIRadiometricCalibrationTask with the CALIBRATION_TYPE property 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

This is a reference to the output raster of filetype ENVI.

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 property, or set it to an exclamation symbol (!), a temporary file will be created.

Version History


ENVI 5.3, Service Pack 1

Introduced

API Version


3.3

See Also


ENVITask, ENVITask::Parameter, ENVICalculateCloudMaskForProductTask, ENVIRadiometricCalibrationTask, ENVIQUACTask, ENVILayerStackRaster



© 2019 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us