MASKING

Create cloud, haze, and water masks from satellite imagery


EnvironmentsPYTHON :: EASI :: MODELER
Quick linksDescription :: Parameters :: Parameter descriptions :: Details :: Example :: References :: Related

Back to top

Description


MASKING calculates haze, cloud, saturated pixels, and water masks for use in haze removal, color balancing, and atmospheric correction.
Back to top

Parameters


masking(fili, srcbgd, asensor, visirchn, cfile, znangle, hazecov, clthresh, wuthresh, filo)

Name Type Caption Length Value range
FILI * str Input file name 1 -    
SRCBGD str Source background value 0 -   Default: FILE
ASENSOR str Sensor name 0 - 24
VISIRCHN List[int] Input visible and infrared bands 0 - 4  
CFILE str Calibration file (*.cal) 0 -    
ZNANGLE List[float] Solar zenith angle (deg) 0 - 1 0.0 - 90.0
HAZECOV List[float] Percentage of haze cover 0 - 1 Default: 50
CLTHRESH List[float] Cloud reflectance threshold 0 - 8  
WUTHRESH List[int] Upper water reflectance thresholds (NIR, SWIR) 0 - 2 Default: 5,3
FILO * str Bitmap masks 1 -    

* Required parameter
Back to top

Parameter descriptions

FILI

The name of the input file that contains multispectral imagery from one of the supported sensors (see ASENSOR).

SRCBGD

This parameter specifies which pixels in the source image are to be considered as background (NoData) pixels. In general, if a pixel is considered NoData, the application handles the pixel in a specific manner.

Available options are:
Note: To specify multiple values, use a comma-delimited list. The first value is applied to the first channel, the second value to the second channel, and so on. If fewer values are specified than the number of input channels, the last value is repeated for all remaining channels. If more values are specified than the number of input channels, the extra values are ignored.

ASENSOR

The name of the sensor used to capture the input image.

If no value is specified for this parameter, MASKING checks for the metadata tag PlatformName at the file level. If the aforementioned metadata tag is not found, an error will occur.

For a list of supported sensors, see Details.

This parameter is optional.

VISIRCHN

The channel in which the blue, red, NIR, and SWIR bands are held. This information must be specified correctly to ensure that the masks are properly computed. If the blue band is not available, the green band may be used as a substitute.

This parameter is defined as follows: 
<blue or green>,<red>,<nir>,<swir>

If no value is specified for this parameter, the MASKING checks for the metadata tags MinWavelength, MaxWavelength, and WavelengthUnits at the channel level to properly associate each channel with the correct band.

If the metadata tags are missing for any of the required channels and no value is specified for VISIRCHN, MASKING checks that the file contains as many channels as multispectral bands for the specified sensor (as specified for ASENSOR); if it does not, an error occurs.

For example, if the sensor is specified as SPOT-5 MS, and channel 1 contains the NIR band, channel 2 contains the red band, channel 3 contains the green band, and channel 4 contains the SWIR band, the value of VISIRCHN must be defined as follows: 
VISIRCHN = 3,2,1,4
If the sensor is specified as Worldview-2 MS, and channel 1 contains the coastal (violet) band, channel 2 contains the blue band, channel three contains the green band, channel 3 contains the green band, channel 5 contains the red band, and channel 7 contains the NIR-1 band, VISIRCHN must be defined as follows: 
VISIRCHN = 2,5,7
If one of the required bands is missing, a 0 (zero) must be provided for the position of the missing band in the VISIRCHN list. For example, in the preceding example referring to SPOT-5, if the NIR band is missing from the input file (FILE), but the green, red, and SWIR bands are available, the value of VISIRCHN must be specified as follows: 
VISIRCHN = 3,2,0,4

If the blue (or green) and red bands are missing, an error will occur on running MASKING.

Both the NIR and SWIR bands must be specified. If only one is specifed, MASKING will execute using only the blue (or green) and the red band.

Note the NIR band and the SWIR band (~1.6um) is used to identify water pixels.

This parameter is optional.

CFILE

The path and file name of the text file that contains, for each band, the calibration coefficients used to transform the values from the image to absolute radiance values. Typically, this information is provided with the data set as an offset and a gain for each channel. The specified text file should contain the band number, offset and gain, and the units for each. The following shows an example of a calibration file for SPOT Landsat-7 images:

7          c0       c1         [mW/cm2 sr micron]
1   	-0.6200   0.0776000
2   	-0.6400   0.0796000  
3   	-0.5000   0.0619000
4   	-0.5100   0.0637000
5   	-0.1002   0.0126000 
6   	 0.0000   0.00670866
7   	-0.0350   0.00437000
The folder atcor\cal in your installation folder contains sample calibration files for each supported sensor. In a calibration file, each row lists the calibration coefficients for each sensor band; the bands are listed in increasing order. You must ensure that the offset (c0) and gain (c1) values correspond to the scene. These values must be provided in the expected units for the specific sensor (shown at the top right of the calibration file). If no value is specified for this parameter, the following metadata tags for each channel in the input file are used:

Also, if no value is specified for Calibration File, or if the coefficients cannot be derived from the metadata, an error message will be displayed.

Important: Do not modify the calibration files, because they indicate the nominal bands for each sensor.

ZNANGLE

The solar zenith angle (0-90 degrees) at the time of image acquisition.

If no value is specified for this parameter, MASKING derives the solar zenith from any one of the following combination of metadata tags found at the file level of the input file (FILI):

If no value is specified for this parameter, and none of the combinations of metadata tags are found in full, an error occurs.

HAZECOV

The approximate percentage of coverage of hazy pixels in the image.

The value of this parameter is used to determine the size of the haze mask generated to identify haze pixels. This percentage value should be based on the total number of pixels in the image, excluding saturated pixels. By default, haze coverage is assumed to be close to 50 percent.

This parameter is optional.

CLTHRESH

The minimum and maximum top of the atmosphere (TOA) reflectance value, in percentage, of the blue band (or green, if blue is not available) used to identify cloud pixels. Lower thresholds will tend to identify more pixels as cloud, but may also misclassify more urban features with unnaturally high reflectance as clouds.

The cloud reflectance threshold is specified as follows: 
<low_thr>,<seed_thr>,<dilation_in_pixels>
For example, the thresholds can be set per sensor as:

The high threshold is used to identify the brightest pixels in the cloud. The low threshold is used to identify the remaining cloud pixels.

To use the enhanced cloud detection algorithm, a series of values can be specified for CLTHRESH, described as follows:

This parameter is optional.

WUTHRESH

The maximum TOA reflectance value, in percentage, in the NIR band and the SWIR band (~1.6um), used to identify water pixels.

The Water Upper Reflectance Threshold is specified as follows: 
<NIR_THRESH>,<SWIR_THRESH>

The first value is the upper TOA reflectance value of water for the NIR band; the second value is the upper TOA reflectance value of water for the SWIR band. If the input file does not contain a NIR and SWIR band, this parameter is ignored and the water mask is not produced.

This parameter is optional.

FILO

The name of the PCIDSK file to receive the output masks. The specified output file can be the image file specified in FILI or any other file with the exact same georeferencing (the bitmap masks will be appended). If the specified output file does not exist, a new PCIDSK file is created.

The output file will contain the following masks:

Each bitmap segment is identified from the metadata tags LayerType. The metadata values will be Haze, Cloud, Saturated, and Water for each of the preceding output bitmaps listed. The first three masks are always created, even if they are empty. The water mask is created only if both the NIR and SWIR bands are available.

Back to top

Details

MASKING generates coarse classification masks used for classification, mosaicking, haze removal, and atmospheric correction.

The coarse classification masks provide a quick and simple method of identifying general ground features (clouds, haze) and ground features (water). These masks are used to facilitate haze removal (HAZEREM), atmospheric correction (ATCOR), and mosaicking operations. They may be used as exclusion masks for color balancing.

The output masks from this program are generally used as input into HAZEREM (haze removal) or ATCOR (atmospheric correction). HAZEREM uses the coarse classification masks to clarify non-hazy pixels and to appropriately compute the statistics of the influence of haze. ATCOR uses the haze mask to determine the candidate pixels for Dark Vegetation, when computing a visibility map under varying atmospheric conditions.

With the parameter ZNANGLE (Solar Zenith Angle), you can specify the zenith angle for the scene. If sufficient metadata exists to extract or compute the solar zenith angle, you need not specify a value for this parameter. If sufficient metadata is not found, a value must be specified. If the input image contains the metadata tag Acquisition_DateTime, this parameter can be defaulted; the angle will be computed based on the date from the image metadata and scene center. The solar zenith and azimuth angles can also be computed using SOLARZAZ.

Supported sensors

The following sensors are supported:
  • ALI
  • ALOS Avnir-2
  • Aster
  • Cartosat PAN
  • CBERS-4
  • CBERS-4A
  • Deimos-1
  • Deimos-2
  • DMC
  • Dragonette
  • DS-EO
  • FASat-Charlie
  • Formosat-2
  • FORMOSAT-5
  • Geoeye-1
  • GF1
  • GF2
  • GF4
  • GF6
  • GF7
  • Gokturk1
  • IRS-1A
  • IRS-1B
  • IRS-1C
  • IRS-1D
  • IRS-P6
  • Ikonos-2
  • Jilin-1
  • KazEOSat-2
  • KOMPSAT-2
  • KOMPSAT-3
  • KOMPSAT-3A
  • Landsat-4 MSS
  • Landsat-5 MSS
  • Landsat-4 TM
  • Landsat-5 TM
  • Landsat-7 ETM+
  • Landsat-8
  • Maxar-Legion
  • OrbView-3
  • PeruSAT-1
  • PlanetScope
  • Pleiades
  • QuickBird
  • PlanetScope
  • RapidEye
  • Resourcesat-2
  • SAC-C
  • Sentinel-2
  • SPOT-1
  • SPOT-2
  • SPOT-3
  • SPOT-4
  • SPOT-5
  • SPOT-6
  • SPOT-7
  • SuperView
  • Thaichote (THEOS)
  • TripleSat
  • WorldView-2
  • WorldView-3
  • WorldView-4
  • ZY1E
  • ZY3
  • ZY3-2
Note: When specifying a sensor, use the exact syntax, as shown in the preceding list.
Back to top

Example

This example calculates the haze, cloud, and water bitmap masks based on the image, irvine.pix, where the channels are as follows:
  • Channel 1 is blue
  • Channel 2 is green
  • Channel 3 is red
  • Channel 4 is NIR
  • Channel 5 is SWIR (~1.6 ㎛)
The result will be written to the newly created PCIDSK file, HazeCloudWater.pix.
from pci.masking import masking

fili	=	"irvine.pix"
filo	=	"HotIrvine.pix"
visirchn	=	[1,3,4,5]
asensor	=	" Landsat-7 ETM+"
cfile	=	r"/atcor/cal/landsat7/etm_standard.cal"

znangle	=	[43.0]
hazecov	=	[30]
clthresh	=	[]
wuthresh	=	[]
srcbgd	=	""

masking(fili, srcbgd, asensor, visirchn, cfile, znangle, hazecov, clthresh, wuthresh, filo)
Back to top

References

Zhang, Y, B Guindon, and J Cihlar, An image transform to characterize and compensate for spatial variations, Remote Sensing of Environment 82 (2002): 173-87.

Parent topic: M
Previous topic: MAS
Next topic: MATCH
Related functions
ATCOR
HAZEREM
MOSPREP

© PCI Geomatics Enterprises, Inc.®, 2026. All rights reserved.