cloudmask_script [ inputfile clear_reference_file outputfile ] [ parameters ]
Parameters are: IR_var, surface_var, maximum_land_tolerance, maximum_sea_tolerance, minimum_box_range, land_range_scale_factor
cloudmask_script is a UNIX shell script providing cloud detection capability for calculating day or night cloud masks from IR imagery, utilizing an estimated temperature background "reference" image (see topomask) which represents a reference for temperatures and variations thereof, over land and ocean. cloudmask_script performs neighborhood statistics, evaluating mean, min, max,... values and comparing these with the corresponding reference image's statistics to assess likelihood of cloudiness on a per pixel basis, with appropriate thresholds and tolerances as provided by user input parameters. The output consists of a dataset containing a cloud mask variable cloud, of type byte, with 0 or 1 values corresponding to clear and cloudy pixels, respectively.
The basic method in cloudmask_script is to study the neighborhood for each pixel and compare neighborhood statistics with the corresponding surface temperature reference data neighborhood statistics, to categorize each neighborhood either as unambiguously clear/cloudy or as partly cloudy/ambiguous. For the latter case, a pixel's relative place in the neighborhood data distribution (specifically relative to the neighborhood mean) is examined in combination with comparisons to the reference threshold, to provide a less ambiguous clear or cloudy classification.
cloudmask_script relies on emathp for the evaluation of statistics, invoking emathp twice on two passes over the input data: First to process land pixels, then to process ocean pixels. Land and ocean are processed seperately because of different statistical threshold requirements for each. Since each pass results in a separate cloud mask, these are finally merged into a single cloud mask output product, also using emathp.
The basic method used for cloud-detection is as follows (for ocean pixels, substitute "maximum_sea_tolerance" for "maximum_land_tolerance", and replace "land_range_scale_factor" with 1.0):
If (image max < reference min - maximum_land_tolerance) then cloud
else if (image min >= reference min - maximum_land_tolerance) then clear
else if (image [max-min] > reference [max-min]*land_range_scale_factor + minimum_box_range) &&
(image value <= reference min + maximum_land_tolerance) then cloud
else if (image [max-min] > reference [max-min]*land_range_scale_factor + minimum_box_range) &&
(image value > reference min + maximum_land_tolerance) then clear
else if (image mean <= reference min - maximum_land_tolerance) && (image mean >= image value) then cloud
else if (image mean <= reference min - maximum_land_tolerance) && (image mean < image value) then clear
else if (image value <= reference min - maximum_land_tolerance) then cloud
else if (image value > reference min - maximum_land_tolerance) then clear
A graphical representation:
TBB pixel value="x" , mean="*" , min=">" , max="<" , tolerance="~|"
------------------------------------------> decreasing temperature, increasing
height
cloudy pixels
reference: <------->~|
image:
<---------->
<--->
<------x--------------> (wide temperature range, data value less than
threshold)
<-------------x------------>
<-*-x-> (narrow
temperature range, data value less than threshold and mean)
<-*-x-> ( " )
clear pixels
reference: <------->~|
image: <------>
<-------->
<---------->
<------x-----------> (wide temperature range, data value
greater than threshold)
<---x----> (narrow
temperature range, data value greater than threshold)
<-*x-->
(narrow temperature range, data value greater than threshold, less than mean)
<-x-*-> (narrow
temperature range, data value greater than threshold, greater
than mean)
<-x*-> (narrow temperature range, data
value less than threshold, greater than mean)
cloudmask_script does not query for parameters. Parameters must be included on the input command-line in correct sequence, as:
% cloudmask_script inputfile clear_reference_file outputfile IR_var surface_var
maximum_land_tolerance maximum_sea_tolerance minimum_box_range
land_range_scale_factor
Name of the input imagery dataset containing an IR channel variable with brightness temperature values. There is no default.
Name of the input reference temperature dataset containing a surface temperature image variable, with same dimensions and registered to same earth-location as the inputfile IR_var. There is no default.
Name of the output dataset which is to contain the output product cloud mask variable cloud. There is no default.
Name of the input IR channel variable from dataset inputfile. There is no default.
OPTIONAL. Name of the input surface reference temperature variable from the dataset clear_reference_file. The default is "surface_temp".
OPTIONAL. Error tolerance for land temperatures, in degrees celsius, kelvin. This value determines the margin of error applied to reference land surface temperatures provided by surface_var, outside of which values are unambiguously determined to be cloudy. Thus, TBB image temperatures colder than the minimum neighborhood surface_var temperature minus maximum_land_temperature are labeled cloudy unambiguously. The default is 10.0 deg. C.
OPTIONAL. Error tolerance for sea/ocean temperatures, in degrees celsius, kelvin. This value determines the margin of error applied to reference sea surface temperatures provided by surface_var, outside of which values are unambiguously determined to be cloudy. Thus, TBB image temperatures colder than the minimum neighborhood surface_var temperature minus maximum_sea_temperature are labeled cloudy unambiguously. The default is 5.0 deg. C.
OPTIONAL. Error tolerance for neighborhood temperature ranges, in degrees celsius, kelvin. This value determines the margin of error applied to reference surface temperature neighborhood ranges [min - max], as provided by surface_var, outside of which input temperature neighborhood value ranges are usually unambiguously determined to be cloudy, unless the image pixel value is well within the neighborhood surface temperature error margin, in which case the pixel remains ambiguous though labeled clear. TBB image neighborhood temperature ranges wider than the minimum neighborhood surface_var temperature range plus minimum_box_range are otherwise labeled cloudy unambiguously. The default temperature range error tolerance is 1.0 deg. C.
OPTIONAL. The reference surface temperature provided by surface_var is usually merely an estimate, especially because the resolution is usually lower than imagery resolution: Temperatures tend to be smoothed values, so that gradients in temperature can be significantly less than the actual temperature gradients for the scene. This can be rectified by scaling the surface-temperature roughness-gradients (i.e. neighborhood max minus min value) with a scale-factor which is the land_range_scale_factor (sea scale factor = 1.0, i.e. not relevent because ocean temperature gradients are essentially very weak and smooth). This scale factor may improve the accuracy of cloud-detection over land by enhancing reference temperature variations, depending on a scene's requirements. The default is 2.0.
Without parameters, cloudmask_script will provide usage instructions with a listing of required parameters. Notice that the optional parameters are in <brackets> :
% cloudmask_script
useage: cloudmask_script inputfile clear_reference_file outputfile IR_var
<surface_var maximum_land_tolerance maximum_sea_tolerance
minimum_box_range land_range_scale_factor>
Defaults are: surface_var=surface_temp maximum_land_tolerance=10.0
maximum_sea_tolerance=5.0 minimum_box_range=1.0
land_range_scale_factor=2.0
With parameters, cloudmask_script echoes the input parameters before processing. A message notifies final combining of land and sea cloud masks:
% cloudmask_script n14.98343.2225.avhrr n14.98343.ref n14.98343.2225.avhrr.cloudmask
avhrr_ch4 surface_temp 15.0 10.0 1.0 3.0
cloudmask_scriptinputfile = /home/kota/code/reftest/n14.98343.2225.avhrrclear_TBB_file = n14.98343.refoutputfile = n14.98343.2225.avhrr.cloudmaskreferenceTBB_error_land = 15.0referenceTBB_error_sea = 10.0min_cloud_TBBgrad = 1.0referenceTBB_grad_scale_land = 3.0Combining land and sea masks...
NOTES
The tests used in this script comprise an attempt to use surface temperature variations on land, i.e. to account for topography-dependent temperature distributions in IR temperature channel imagery, to facilitate the detection of cloud-defined temperature distributions. They are neither an exhaustive nor unique series of tests, serving instead as an example and possible point of departure for further adaptation.
Last Update: $Date: 2000/12/12 00:57:43 $