| 1 | <?xml version="1.0" encoding="utf-8"?> |
|---|
| 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 3 | <html xmlns="http://www.w3.org/1999/xhtml"><head><link rel="stylesheet" type="text/css" href="81help.css?format=raw" /><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Cayula-Cornillon Fronts in CoastWatch Image as Binary Raster</title></head><body><table style="margin-top:-1em; margin-bottom:0; padding:0; margin-left:-1em"><tr><td style="background:white"><img width="875" height="70" alt="ArcToolbox banner" src="AHBanner_ArcToolbox.gif?format=raw" /></td></tr></table><h1>Cayula-Cornillon Fronts in CoastWatch Image as Binary Raster</h1><p></p><p>Finds fronts in a CoastWatch POES AVHRR image using the Cayula-Cornillon (1992) single-image edge detection algorithm and outputs them to a binary raster.</p><br /><p><h2><img width="11" height="11" border="0" src="sm_arrow_down.gif?format=raw" /> Command line syntax</h2></p><div Class="expand" id="id103137">CoastWatchAVHRRFindFrontsAsBinaryRaster_GeoEco <imageFile> <variable> <outputFrontsFile> {cloudMaskFile} {cloudVariable} {sunZenithFile} {sunZenithVariable} {useDayCloudTest1} {useDayCloudTest2} {useDayCloudTest3} {useDayCloudTest4} {useDayCloudTest5} {useDayCloudTest6} {useDayCloudTest7} {maskWhenDayCloudMaskExceeds} {useNightCloudTest1} {useNightCloudTest2} {useNightCloudTest3} {useNightCloudTest4} {useNightCloudTest5} {useNightCloudTest6} {useNightCloudTest7} {maskWhenNightCloudMaskExceeds} {minCloudyNeighbors} {medianFilterWindowSize} {histogramWindowSize} {histogramWindowStride} {minPropNonMaskedCells} {minPopProp} {minPopMeanDifference} {minTheta} {minSinglePopCohesion} {minGlobalPopCohesion} {threads} {outputMaskFile} {outputFilteredImageFile} {outputCandidateCountsFile} {outputFrontCountsFile} {outputWindowStatusCodesFile} {outputWindowStatusValuesFile} <br /><br /><b>Parameters</b><br /><table width="100%" border="0" cellpadding="5"><tbody><tr><th width="40%"><b>Expression</b></th><th width="60%"><b>Explanation</b></th></tr><tr><td class="info"><imageFile></td><td class="info" align="left"><p>CoastWatch POES AVHRR CWF or HDF file in which fronts should be |
|---|
| 4 | detected.</p><p>Only CoastWatch POES AVHRR files are supported. An error will be raise |
|---|
| 5 | for other CoastWatch files, such as those for the GOES satellite |
|---|
| 6 | series.</p><p>If you provide a compressed file in a supported compression format, it |
|---|
| 7 | will be automatically decompressed. If it is an archive (e.g. .zip or |
|---|
| 8 | .tar), it must contain exactly one file, which must not be in a |
|---|
| 9 | subdirectory.</p></td></tr><tr><td class="info"><variable></td><td class="info" align="left"><p>Name of the CoastWatch variable to in which fronts should be |
|---|
| 10 | detected. At the time of this writing, the CoastWatch program was |
|---|
| 11 | known to have published files with these variables:</p><dl><dt></dt><dd><pre>avhrr_ch1 |
|---|
| 12 | avhrr_ch2 |
|---|
| 13 | avhrr_ch3 |
|---|
| 14 | avhrr_ch3a |
|---|
| 15 | avhrr_ch4 |
|---|
| 16 | avhrr_ch5 |
|---|
| 17 | cloud |
|---|
| 18 | cloudx |
|---|
| 19 | graphics |
|---|
| 20 | sst |
|---|
| 21 | rel_azimuth |
|---|
| 22 | sat_zenith |
|---|
| 23 | sun_zenith</pre></dd></dl><p>Almost all users will want to detect fronts in the sst variable, but |
|---|
| 24 | you may specify one of the others, if appropriate for your project. |
|---|
| 25 | Please see the CoastWatch documentation for more information about the |
|---|
| 26 | variables.</p></td></tr><tr><td class="info"><outputFrontsFile></td><td class="info" align="left"><p>Output binary raster that shows the fronts detected in the input |
|---|
| 27 | image.</p><p>The file will have the same dimensions as the input image and contain |
|---|
| 28 | 8-bit signed integers with three possible values:</p><ul><li><p>-128 - the pixel was never a candidate for containing a front, |
|---|
| 29 | either because it was masked or because because it did not appear in |
|---|
| 30 | any histogram windows that had sufficiently large numbers of |
|---|
| 31 | non-masked pixels to proceed with the histogramming step of the |
|---|
| 32 | Cayula-Cornillon algorithm.</p></li></ul><ul><li><p>0 - The pixel was a candidate for containing a front -- it was not |
|---|
| 33 | masked and it appeared in at least one histogram window with a |
|---|
| 34 | sufficient number of non-masked pixels to proceed with the |
|---|
| 35 | histogramming step -- but it was never marked as a front pixel in |
|---|
| 36 | any of the histogram windows it appeared in.</p></li></ul><ul><li><p>1 - The pixel was a candidate for containing a front and it was marked |
|---|
| 37 | as a front pixel in at least one of the histogram windows it |
|---|
| 38 | appeared in.</p></li></ul></td></tr><tr><td class="info">{cloudMaskFile}</td><td class="info" align="left"><p>CoastWatch POES AVHRR CWF or HDF file that contains the CoastWatch |
|---|
| 39 | cloud mask.</p><p>A value need only be provided for this parameter when the cloud mask |
|---|
| 40 | is not stored in the input CoastWatch file. This will usually be the |
|---|
| 41 | case for CWF files, because they usually do not contain more than one |
|---|
| 42 | CoastWatch variable per file. HDF files usually contain all of the |
|---|
| 43 | variables, so you can usually omit this parameter for HDF files.</p><p>If you provide a compressed file in a supported compression format, it |
|---|
| 44 | will be automatically decompressed. If it is an archive (e.g. .zip or |
|---|
| 45 | .tar), it must contain exactly one file, which must not be in a |
|---|
| 46 | subdirectory.</p></td></tr><tr><td class="info">{cloudVariable}</td><td class="info" align="left"><p>Name of the CoastWatch variable to extract from the cloud mask |
|---|
| 47 | file and use as the cloud mask (e.g. "cloud").</p><p>The current implementation of this tool was designed to operate on the |
|---|
| 48 | 8-bit CLAVR cloud mask represented by the "cloud" variable in |
|---|
| 49 | CoastWatch files. It was not designed to operate on the "cloudx" |
|---|
| 50 | variable, which is a new experimental CLAVR-x cloud mask available in |
|---|
| 51 | recent CoastWatch HDF files. Nonetheless, if you wish to operate on |
|---|
| 52 | the cloudx variable, you can specify it instead of cloud, and pick |
|---|
| 53 | mask options appropriate for it instead.</p></td></tr><tr><td class="info">{sunZenithFile}</td><td class="info" align="left"><p>CoastWatch POES AVHRR CWF or HDF file that contains the solar |
|---|
| 54 | zenith image, typically represented by the sun_zenith variable.</p><p>A value need only be provided for this parameter when the solar zenith |
|---|
| 55 | is not stored in the input CoastWatch file. This will usually be the |
|---|
| 56 | case for CWF files, because they usually do not contain more than one |
|---|
| 57 | CoastWatch variable per file. HDF files usually contain all of the |
|---|
| 58 | variables, so you can usually omit this parameter for HDF files.</p><p>If you provide a compressed file in a supported compression format, it |
|---|
| 59 | will be automatically decompressed. If it is an archive (e.g. .zip or |
|---|
| 60 | .tar), it must contain exactly one file, which must not be in a |
|---|
| 61 | subdirectory.</p><p>According to CoastWatch researcher Peter Hollemans, when an image's |
|---|
| 62 | scene time is "day", all pixels of the cloud mask use daytime cloud |
|---|
| 63 | tests, and when it is "night", all pixels use nighttime cloud tests. |
|---|
| 64 | When the scene time is "day/night", the decision of which tests to use |
|---|
| 65 | is based on the solar zenith for that pixel.</p><p>According to Peter, for CoastWatch HDF files, pixels with a solar |
|---|
| 66 | zenith > 80 degrees use the nighttime cloud tests, and <= 80 use the |
|---|
| 67 | daytime cloud tests. This tool implements that logic. If you specify |
|---|
| 68 | that cloud masking should be performed for a day/night image but no |
|---|
| 69 | solar zenith image is available, this tool will assume that nighttime |
|---|
| 70 | cloud tests were used for every pixel and a warning will be issued. |
|---|
| 71 | For some reason, CoastWatch occasionally produces day/night images |
|---|
| 72 | with no sun_zenith or other variables that are present in day images. |
|---|
| 73 | My recollection is that Peter said it is safe to assume for these |
|---|
| 74 | images that all pixels are nighttime.</p><p>The solar zenith image is ignored for scene times other than |
|---|
| 75 | "day/night" (e.g. "day" or "night").</p><p>After some investigation, I find that the cloud mask pixels near the |
|---|
| 76 | 80 degree solar zenith line are problematic, for two reasons:</p><ul><li><p>According to Peter, the solar zenith <= 80 cutoff line is not going |
|---|
| 77 | to line up perfectly with the switch from daytime to nighttime cloud |
|---|
| 78 | tests because the solar zenith angles are rounded to the nearest |
|---|
| 79 | 0.01 when written to the HDF file so a few pixels with values of say |
|---|
| 80 | 80.003 will get rounded to 80 even though they underwent processing |
|---|
| 81 | with the nighttime cloud tests. Peter said, "I guess that's the flaw |
|---|
| 82 | with storing angle data in HDF as scaled integers (that decision was |
|---|
| 83 | mainly due to file size concerns)."</p></li></ul><ul><li><p>The switch between daytime tests and nighttime tests does not |
|---|
| 84 | manifest as a clean transition in the cloud mask pixels. The daytime |
|---|
| 85 | pixels do not seem to cleanly abut the nighttime pixels. Rather, a |
|---|
| 86 | strip of pixels with strange values raggedly separates the two. |
|---|
| 87 | Peter said: "The apparent unclean transition between day and night |
|---|
| 88 | tests is related to neighborhood functions. The uniformity tests |
|---|
| 89 | use a 2x2 box of data values to the right and below a given value in |
|---|
| 90 | the array to check for a condition being true, and the results of |
|---|
| 91 | the uniformity test flag all pixels in the 2x2 box with the test |
|---|
| 92 | results, regardless of whether all those pixels are day or |
|---|
| 93 | nighttime. Both day and nighttime have uniformity tests, so the |
|---|
| 94 | results of uniformity tests at the day/night boundary are mixed. The |
|---|
| 95 | mixing is generally acceptable because the results are intended to |
|---|
| 96 | be used for SST masking not cloud type evaluation and the mixing |
|---|
| 97 | only occurs in cloudy conditions, not clear SST conditions."</p></li></ul><p>Peter said he did not know what was done for CoastWatch day/night CWF |
|---|
| 98 | files. I examined a few of these from the North East region, and it |
|---|
| 99 | appeared that they also switched from daytime to nighttime cloud tests |
|---|
| 100 | in the middle of the image. But the NOAA distribution site |
|---|
| 101 | (<a href="http://www.class.noaa.gov">http://www.class.noaa.gov</a>) only appeared to have CWFs containing the |
|---|
| 102 | sun_zenith variable for dates after late 1999.</p><p>Peter mentioned that the cwangles program from the CoastWatch |
|---|
| 103 | Utilities could compute the solar zenith, but the values would only be |
|---|
| 104 | approximate beacuse the program assumed that all pixels were obtained |
|---|
| 105 | by the sensor at the same moment in time. I tried this approach but |
|---|
| 106 | the 80 degree solar zenith line did not line up with the line where |
|---|
| 107 | the cloud tests appeared to switch. Because of this, I do not believe |
|---|
| 108 | that day/night CWF files will be useable for users who want to use |
|---|
| 109 | some cloud tests and ignore others.</p></td></tr><tr><td class="info">{sunZenithVariable}</td><td class="info" align="left"><p>Name of the CoastWatch variable to extract from the solar zenith |
|---|
| 110 | file and use as the solar zenith image (e.g. "sun_zenith").</p></td></tr><tr><td class="info">{useDayCloudTest1}</td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Reflective Gross |
|---|
| 111 | Cloud Test (bit 1 of the cloud mask) will be masked. If False, this |
|---|
| 112 | cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 |
|---|
| 113 | test is used for both CWF and HDF files, but for HDF files, the |
|---|
| 114 | CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 115 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 116 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 117 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 118 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 119 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useDayCloudTest2}</td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Reflectance |
|---|
| 120 | Uniformity Test (bit 2 of the cloud mask) will be masked. If False, |
|---|
| 121 | this cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 |
|---|
| 122 | test is used for both CWF and HDF files, but for HDF files, the |
|---|
| 123 | CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 124 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 125 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 126 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 127 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 128 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useDayCloudTest3}</td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Reflectance Ratio |
|---|
| 129 | Cloud Test (bit 3 of the cloud mask) will be masked. If False, this |
|---|
| 130 | cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 |
|---|
| 131 | test is used for both CWF and HDF files, but for HDF files, the |
|---|
| 132 | CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 133 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 134 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 135 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 136 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 137 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useDayCloudTest4}</td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Channel 3 Albedo |
|---|
| 138 | Test (bit 4 of the cloud mask) will be masked. If False, this cloud |
|---|
| 139 | test will be ignored.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 140 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 141 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 142 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 143 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 144 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useDayCloudTest5}</td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Thermal Uniformity |
|---|
| 145 | Test (bit 5 of the cloud mask) will be masked. If False, this cloud |
|---|
| 146 | test will be ignored.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 147 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 148 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 149 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 150 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 151 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useDayCloudTest6}</td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Four Minus Five |
|---|
| 152 | Test (bit 6 of the cloud mask) will be masked. If False, this cloud |
|---|
| 153 | test will be ignored.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 154 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 155 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 156 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 157 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 158 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useDayCloudTest7}</td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Thermal Gross |
|---|
| 159 | Cloud Test (bit 7 of the cloud mask) will be masked. If False, this |
|---|
| 160 | cloud test will be ignored.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 161 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 162 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 163 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 164 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 165 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{maskWhenDayCloudMaskExceeds}</td><td class="info" align="left"><p>If a value is provided, daytime pixels with a cloud mask value |
|---|
| 166 | greater than this value will be masked.</p><p>The CoastWatch cloud mask is a bitmask, where each bit represents the |
|---|
| 167 | success (0) or failure (1) of a given CLAVR cloud test. Thus the cloud |
|---|
| 168 | mask values are NOT intended to be interpreted as range, like a |
|---|
| 169 | spectrum, where 0 represents "very clear" and 255 represents "very |
|---|
| 170 | cloudy". Nevertheless, some users of this tool determined that for |
|---|
| 171 | their study the best tradeoff between minimizing SST error and |
|---|
| 172 | minimizing the number of pixels masked by clouds was obtained by |
|---|
| 173 | masking all pixels where the cloud mask exceeded a certain value. This |
|---|
| 174 | option was implemented specifically for those users and is not |
|---|
| 175 | recommended for general use. If you do use this option, be sure to |
|---|
| 176 | study many cloud mask images before selecting a value.</p><p>If a value is provided both for this parameter and for the cloud test |
|---|
| 177 | bits specified by the previous parameters, all of these parameters |
|---|
| 178 | will be effective. In other words, a cloudy pixel can be masked by |
|---|
| 179 | failing a specific cloud test, or by exceeding the minimum cloud mask |
|---|
| 180 | value, or both. .</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 181 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 182 | documentation for the cloud mask file parameter. For more information |
|---|
| 183 | about the cloud tests, please see the CoastWatch and CLAVR |
|---|
| 184 | documentation.</p></td></tr><tr><td class="info">{useNightCloudTest1}</td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Thermal Gross |
|---|
| 185 | Cloud Test (bit 1 of the cloud mask) will be masked. If False, this |
|---|
| 186 | cloud test will be ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 187 | pixels are classified as daytime or nighttime, please see the |
|---|
| 188 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 189 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 190 | indicates it failed. For more details about the cloud tests, please |
|---|
| 191 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useNightCloudTest2}</td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Thermal |
|---|
| 192 | Uniformity Test (bit 2 of the cloud mask) will be masked. If False, |
|---|
| 193 | this cloud test will be ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 194 | pixels are classified as daytime or nighttime, please see the |
|---|
| 195 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 196 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 197 | indicates it failed. For more details about the cloud tests, please |
|---|
| 198 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useNightCloudTest3}</td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Uniform Low |
|---|
| 199 | Stratus Test (bit 3 of the cloud mask) will be masked. If False, this |
|---|
| 200 | cloud test will be ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 201 | pixels are classified as daytime or nighttime, please see the |
|---|
| 202 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 203 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 204 | indicates it failed. For more details about the cloud tests, please |
|---|
| 205 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useNightCloudTest4}</td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Four Minus Five |
|---|
| 206 | Test (bit 4 of the cloud mask) will be masked. If False, this cloud |
|---|
| 207 | test will be ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 208 | pixels are classified as daytime or nighttime, please see the |
|---|
| 209 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 210 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 211 | indicates it failed. For more details about the cloud tests, please |
|---|
| 212 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useNightCloudTest5}</td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Cirrus Test (bit |
|---|
| 213 | 5 of the cloud mask) will be masked. If False, this cloud test will be |
|---|
| 214 | ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 215 | pixels are classified as daytime or nighttime, please see the |
|---|
| 216 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 217 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 218 | indicates it failed. For more details about the cloud tests, please |
|---|
| 219 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useNightCloudTest6}</td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-x Channel 3B |
|---|
| 220 | Albedo Test (bit 6 of the cloud mask) will be masked. If False, this |
|---|
| 221 | cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, this test was not |
|---|
| 222 | used for CoastWatch CWF files and thus bit 6 will always be 0, |
|---|
| 223 | indicating success, for CWF nighttime cloud mask pixels.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 224 | pixels are classified as daytime or nighttime, please see the |
|---|
| 225 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 226 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 227 | indicates it failed. For more details about the cloud tests, please |
|---|
| 228 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{useNightCloudTest7}</td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-x Channel 3B |
|---|
| 229 | Albedo Uniformity Test (bit 7 of the cloud mask) will be masked. If |
|---|
| 230 | False, this cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, this test was not |
|---|
| 231 | used for CoastWatch CWF files and thus bit 7 will always be 0, |
|---|
| 232 | indicating success, for CWF nighttime cloud mask pixels.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 233 | pixels are classified as daytime or nighttime, please see the |
|---|
| 234 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 235 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 236 | indicates it failed. For more details about the cloud tests, please |
|---|
| 237 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">{maskWhenNightCloudMaskExceeds}</td><td class="info" align="left"><p>If a value is provided, nighttime pixels with a cloud mask value |
|---|
| 238 | greater than this value will be masked.</p><p>The CoastWatch cloud mask is a bitmask, where each bit represents the |
|---|
| 239 | success (0) or failure (1) of a given CLAVR cloud test. Thus the cloud |
|---|
| 240 | mask values are NOT intended to be interpreted as range, like a |
|---|
| 241 | spectrum, where 0 represents "very clear" and 255 represents "very |
|---|
| 242 | cloudy". Nevertheless, some users of this tool determined that for |
|---|
| 243 | their study the best tradeoff between minimizing SST error and |
|---|
| 244 | minimizing the number of pixels masked by clouds was obtained by |
|---|
| 245 | masking all pixels where the cloud mask exceeded a certain value. This |
|---|
| 246 | option was implemented specifically for those users and is not |
|---|
| 247 | recommended for general use. If you do use this option, be sure to |
|---|
| 248 | study many cloud mask images before selecting a value.</p><p>If a value is provided both for this parameter and for the cloud test |
|---|
| 249 | bits specified by the previous parameters, all of these parameters |
|---|
| 250 | will be effective. In other words, a cloudy pixel can be masked by |
|---|
| 251 | failing a specific cloud test, or by exceeding the minimum cloud mask |
|---|
| 252 | value, or both. .</p><p>This parameter is ignored for daytime pixels. For a discussion of |
|---|
| 253 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 254 | documentation for the cloud mask file parameter. For more information |
|---|
| 255 | about the cloud tests, please see the CoastWatch and CLAVR |
|---|
| 256 | documentation.</p></td></tr><tr><td class="info">{minCloudyNeighbors}</td><td class="info" align="left"><p>Minimum number of neighbors that a cloudy pixel must have in order |
|---|
| 257 | for that pixel to be masked.</p><p>You can use this option to ignore isolated cloudy pixels that are not |
|---|
| 258 | clumped together. For example, if you specify the value 1, cloudy |
|---|
| 259 | pixels will be ignored and not used in the masking process unless at |
|---|
| 260 | least one of their eight neighbors is also cloudy.</p><p>If a neighbor is not cloudy but it is masked for some other reason |
|---|
| 261 | (e.g. it is land), it does not count as being cloudy.</p><p>This option is ignored when cloud masking is not performed.</p></td></tr><tr><td class="info">{medianFilterWindowSize}</td><td class="info" align="left"><p>Window size, in pixels, of the median filter to apply to the input |
|---|
| 262 | image prior to running the histogram analysis step of the |
|---|
| 263 | Cayula-Cornillon algorithm. If not provided, median filtering will not |
|---|
| 264 | be performed.</p><p>If you provide a value, it must be an odd integer greater than or |
|---|
| 265 | equal to 3. The filter window is square and advances across the image |
|---|
| 266 | 1 pixel at a time. The center pixel, if it is not masked, is replaced |
|---|
| 267 | with the median value of the non-masked pixels in the surrounding |
|---|
| 268 | window. All masks are applied before the median filter is executed.</p><p>Median filtering is a traditional first step for certain classes of |
|---|
| 269 | edge detection algorithms. The original Cayula-Cornillon paper used a |
|---|
| 270 | window size of 3.</p></td></tr><tr><td class="info">{histogramWindowSize}</td><td class="info" align="left"><p>Size of the histogram window to use for the Cayula-Cornillon |
|---|
| 271 | algorithm.</p><p>The window is square. The original paper used a window size of 32. |
|---|
| 272 | Although the algorithm is claimed to obtain similar results regardless |
|---|
| 273 | of window size, I have noticed that some fronts may only be detected |
|---|
| 274 | by using a smaller window size such as 16. I highly recommend you read |
|---|
| 275 | the paper carefully before experimenting with different window |
|---|
| 276 | sizes.</p></td></tr><tr><td class="info">{histogramWindowStride}</td><td class="info" align="left"><p>Number of pixels to move the histogram window after each iteration |
|---|
| 277 | of the Cayula-Cornillon algorithm.</p><p>The original paper used a 32x32 window and a stride of 16, to minimize |
|---|
| 278 | the CPU time required to execute the algorithm. Cutting the stride in |
|---|
| 279 | half increases the CPU time by a factor of about four. For example, a |
|---|
| 280 | stride of 1 requires about 256 times more CPU time than a stride of |
|---|
| 281 | 16.</p><p>In my experience, smaller stride values identify more fronts, and the |
|---|
| 282 | resulting fronts are longer and thicker. If you have a powerful |
|---|
| 283 | computer, want to find more fronts, and are comfortable deviating from |
|---|
| 284 | the published method, you can use a smaller value. If you do this, you |
|---|
| 285 | may want to apply a thinning algorithm after running this tool, to |
|---|
| 286 | reduce the widths of the resulting fronts.</p></td></tr><tr><td class="info">{minPropNonMaskedCells}</td><td class="info" align="left"><p>Minimum proportion of pixels in a histogram window that must not |
|---|
| 287 | be masked for the algorithm to proceed with histogram analysis on that |
|---|
| 288 | window.</p><p>For example, if the value 0.75 is used and the histogram window is |
|---|
| 289 | 20x20, at least 300 out of the 400 pixels must not be masked for |
|---|
| 290 | analysis to proceed on that window. If more than 100 pixels are |
|---|
| 291 | masked, the algorithm discards the current window, advances to next |
|---|
| 292 | one, and starts over.</p><p>The Fortran code I obtained from Dave Ullman used the value 0.65.</p></td></tr><tr><td class="info">{minPopProp}</td><td class="info" align="left"><p>Minimum proportional size of the smaller population.</p><p>If the histogram algorithm determines that the values of the |
|---|
| 293 | non-masked pixels in the window have a bimodal distribution, it then |
|---|
| 294 | selects the value that optimally separates them into two populations. |
|---|
| 295 | As described on page 73 of the 1992 paper, if the proportion of |
|---|
| 296 | non-masked pixels allocated to the smaller population is smaller than |
|---|
| 297 | 0.25, the subsequent statistical tests will not be accurate. In this |
|---|
| 298 | case, and the algorithm discards the current window, advances to next |
|---|
| 299 | one, and starts over.</p><p>I do not recommend selecting a value other than 0.25 unless you |
|---|
| 300 | understand the statistical analysis presented in the 1992 paper.</p></td></tr><tr><td class="info">{minPopMeanDifference}</td><td class="info" align="left"><p>Minimum difference in population means.</p><p>After the histogram algorithm separates the non-masked pixels into two |
|---|
| 301 | populations, it computes the means of the two populations. If the |
|---|
| 302 | means differ by less than this parameter value, the algorithm discards |
|---|
| 303 | the current window, advances to next one, and starts over.</p><p>The original intent of this parameter is obscure. The Fortran code I |
|---|
| 304 | obtained from Dave Ullman used the value 3 and contained the |
|---|
| 305 | explanation "a temperature difference of less than three digital |
|---|
| 306 | counts between the 2 populations is likely to be a result of the |
|---|
| 307 | discrete nature of the data."</p><p>You can use this parameter to eliminate weak fronts by selecting a |
|---|
| 308 | value that corresponds to a desired minimum mean temperature |
|---|
| 309 | difference. For example, the NOAA NODC 4km AVHRR Pathfinder Project |
|---|
| 310 | (<a href="http://www.nodc.noaa.gov/SatelliteData/pathfinder4km/">http://www.nodc.noaa.gov/SatelliteData/pathfinder4km/</a>) publishes SST |
|---|
| 311 | data as 16-bit unsigned integers where each integer represents 0.075 |
|---|
| 312 | degrees. To eliminate fronts where the mean temperature difference is |
|---|
| 313 | less than 0.5 degrees, set this parameter to 0.5 / 0.075 = |
|---|
| 314 | 6.666667.</p></td></tr><tr><td class="info">{minTheta}</td><td class="info" align="left"><p>Minimum criterion function, theta(Topt), as described on pages |
|---|
| 315 | 71-72 of the 1992 paper.</p><p>The criterion function is used to determine whether the histogram |
|---|
| 316 | window contains a bimodal distribution. Cayula and Cornillon performed |
|---|
| 317 | an extensive analysis to determine that the value 0.76 produced |
|---|
| 318 | optimal results for the SST data they worked with. Selecting a smaller |
|---|
| 319 | value will allow windows with more homogenous, less bimodal |
|---|
| 320 | distributions to be considered by the algorithm. If the window yields |
|---|
| 321 | a value less than this parameter, the algorithm discards the current |
|---|
| 322 | window, advances to next one, and starts over.</p><p>I do not recommend selecting a value other than 0.76 unless you |
|---|
| 323 | understand the statistics presented in the original paper.</p></td></tr><tr><td class="info">{minSinglePopCohesion}</td><td class="info" align="left"><p>Minimum cohesion of a single population.</p><p>If the histogram window is found to have a sufficiently bimodal |
|---|
| 324 | distribution of values, the cohesion algorithm is executed to check |
|---|
| 325 | whether the pixels of the two populations are sufficiently spatially |
|---|
| 326 | separated. High values indicate that they are separated, suggesting |
|---|
| 327 | that two distinct populations (e.g. water masses) are present in the |
|---|
| 328 | window. Low values indicate the populations are all mixed up, like a |
|---|
| 329 | checkerboard, and suggest that the pattern results from clouds, noise |
|---|
| 330 | or other random processes.</p><p>The first part of the cohesion algorithm checks the cohesion of each |
|---|
| 331 | population by itself (equations 19 and 20 in the 1992 paper). As |
|---|
| 332 | described in Appendix B of the 1992 paper, the optimal cohesion |
|---|
| 333 | coefficients depend on the size of the histogram window. Cayula and |
|---|
| 334 | Cornillon used the value 0.90 for a 32x32 window, which was |
|---|
| 335 | calculated:</p><dl><dt></dt><dd><pre>C = 1.0 - 0.02 - 1/winsize - 2*P(error) = 0.98 - 1/32 - 2(0.025) = 0.90</pre></dd></dl><p>For a 16x16 window, the equation evaluates to 0.8675.</p></td></tr><tr><td class="info">{minGlobalPopCohesion}</td><td class="info" align="left"><p>Minimum cohesion of both populations.</p><p>The second part of the cohesion algorithm checks the cohesion of both |
|---|
| 336 | populations together (equation 21 in the 1992 paper). As described in |
|---|
| 337 | Appendix B of the 1992 paper, the optimal cohesion coefficients depend |
|---|
| 338 | on the size of the histogram window. Cayula and Cornillon used the |
|---|
| 339 | value 0.92 for a 32x32 window, which was calculated:</p><dl><dt></dt><dd><pre>C = 1.0 - 1/winsize - 2*P(error) = 1.0 - 1/32 - 2(0.025) = 0.92</pre></dd></dl><p>For a 16x16 window, the equation evaluates to 0.8875.</p></td></tr><tr><td class="info">{threads}</td><td class="info" align="left"><p>Number of threads to start for parallel processing.</p><p>The histogram and cohesion algorithms are CPU intensive but are |
|---|
| 340 | designed to run in parallel on machines that have multiple processors. |
|---|
| 341 | To maximize utilization of your machine's processors and shorten the |
|---|
| 342 | time required to execute the algorithms, set the number of threads to |
|---|
| 343 | the number of processors you wish to utilize. Do not set the number of |
|---|
| 344 | threads to more than the number of processors you have; this will |
|---|
| 345 | reduce performance.</p><p>For this option to have any effect, your version of Python must |
|---|
| 346 | include the threading module. Most recent versions of Python include |
|---|
| 347 | this module.</p></td></tr><tr><td class="info">{outputMaskFile}</td><td class="info" align="left"><p>Output binary raster that shows the pixels of the input image that |
|---|
| 348 | were masked prior to executing the Cayula-Cornillon algorithm.</p><p>The file will have the same dimensions as the input image and contain |
|---|
| 349 | 8-bit unsigned integers. The value 1 indicates that the corresponding |
|---|
| 350 | pixel of the input image was masked; 0 indicates the pixel was not |
|---|
| 351 | masked.</p></td></tr><tr><td class="info">{outputFilteredImageFile}</td><td class="info" align="left"><p>Output binary raster that shows the median-filtered input image.</p><p>The file will have the same data type and dimensions as the input |
|---|
| 352 | image. Non-masked pixels will have the median value of the non-masked |
|---|
| 353 | pixels in the surrounding window (the center pixel is included in the |
|---|
| 354 | median selection). Masked pixels will be marked with the smallest |
|---|
| 355 | possible value for the pixel data type. For example, if the pixel data |
|---|
| 356 | type is 16-bit signed integer, the masked pixels will be marked with |
|---|
| 357 | the value -32768.</p></td></tr><tr><td class="info">{outputCandidateCountsFile}</td><td class="info" align="left"><p>Output binary raster that indicates how many times the |
|---|
| 358 | corresponding pixel of the input image was a candidate for containing |
|---|
| 359 | a front, i.e. the number of times it appeared in a histogram window |
|---|
| 360 | that had a sufficiently large number of non-masked pixels to proceed |
|---|
| 361 | to the histogram algorithm.</p><p>The file will contain 16-bit signed integers and have the same |
|---|
| 362 | dimensions as the input image. If the histogram window stride is less |
|---|
| 363 | than the window size, successive histogram windows will overlap, and |
|---|
| 364 | many pixels will have candidate counts greater than 1. Masked pixels |
|---|
| 365 | can never be candidates for containing a front and will have the value |
|---|
| 366 | -32768.</p></td></tr><tr><td class="info">{outputFrontCountsFile}</td><td class="info" align="left"><p>Output binary raster that indicates how many times a front was |
|---|
| 367 | detected at the corresponding pixel of the input image.</p><p>The file will contain 16-bit signed integers and have the same |
|---|
| 368 | dimensions as the input image. The value will range from 0 (the input |
|---|
| 369 | image pixel never contained a front) to the candidate count value for |
|---|
| 370 | the pixel (it always contained a front in every histogram window that |
|---|
| 371 | contained it). Masked pixels can never be candidates for containing a |
|---|
| 372 | front and will have the value -32768.</p></td></tr><tr><td class="info">{outputWindowStatusCodesFile}</td><td class="info" align="left"><p>Output binary raster that indicates the result of the algorithm |
|---|
| 373 | for the histogram window centered on the pixel. You can use this image |
|---|
| 374 | to diagnose why the algorithm did not find fronts in a particular |
|---|
| 375 | region of your image.</p><p>The file will contain 8-bit signed integers and have the same |
|---|
| 376 | dimensions as the input image. The pixel values will be one of these |
|---|
| 377 | code numbers:</p><ul><li><p>Code 0 - The algorithm was not executed for the window because the |
|---|
| 378 | histogram window stride was greater than 1, causing the algorithm to |
|---|
| 379 | skip over this window.</p></li></ul><ul><li><p>Code 1 - The proportion of the window's pixels that had data was |
|---|
| 380 | found to be too small. This typically occurs when the window occurs |
|---|
| 381 | in a region where many of the pixels are masked due to land, clouds, |
|---|
| 382 | or insufficient satellite coverage.</p></li></ul><ul><li><p>Code 2 - After the histogram algorithm optimally separated the |
|---|
| 383 | window's pixels into two populations, the proportion of pixels |
|---|
| 384 | allocated to the smaller population was found to be too small. This |
|---|
| 385 | can occur when a front occurs in the window, but the window is not |
|---|
| 386 | centered on the front, causing it to contain a disproportionate |
|---|
| 387 | number of pixels from one population. This is usually not a problem. |
|---|
| 388 | As long as the histogram window stride is sufficiently small, the |
|---|
| 389 | histogram window will eventually pass over the front and proceed to |
|---|
| 390 | the next step of the algorithm.</p></li></ul><ul><li><p>Code 3 - After the histogram algorithm optimally separated the |
|---|
| 391 | window's pixels into two populations, the difference between the |
|---|
| 392 | mean values of the two populations was found to be too small. This |
|---|
| 393 | typically happens when the window does not contain a front or when |
|---|
| 394 | the gradient along the front is small (i.e. it is a weak front).</p></li></ul><ul><li><p>Code 4 - After the histogram algorithm optimally separated the |
|---|
| 395 | window's pixels into two populations, the criterion function that |
|---|
| 396 | was calculated was found to be too small (the criterion function is |
|---|
| 397 | theta(Topt) described on pages 71-72 of the 1992 paper). This means |
|---|
| 398 | that the two populations are not sufficiently bimodal to indicate |
|---|
| 399 | that a front exists in the window.</p></li></ul><ul><li><p>Code 5 - The window was found to have two populations that were |
|---|
| 400 | sufficiently proportional, different in their means, and bimodal, |
|---|
| 401 | but the cohesion of one or the other population was insufficient (as |
|---|
| 402 | described by equations 19 and 20 in the 1992 paper). This indicates |
|---|
| 403 | that the cells of the two populations are spatially intermixed like |
|---|
| 404 | a checkerboard, rather than being spatially separate, as occurs when |
|---|
| 405 | a front is present.</p></li></ul><ul><li><p>Code 6 - The window was found to have two populations that were |
|---|
| 406 | sufficiently proportional, different in their means, and bimodal, |
|---|
| 407 | and each population was found to be sufficiently cohesive, but the |
|---|
| 408 | cohesion of the two populations together was insufficient (as |
|---|
| 409 | described by equation 21 of the 1992 paper). As with code 5, this |
|---|
| 410 | indicates that the cells of the two populations are spatially |
|---|
| 411 | intermixed like a checkerboard, rather than being spatially |
|---|
| 412 | separate, as occurs when a front is present.</p></li></ul><ul><li><p>Code 7 - The window passed all of the algorithm's tests and was |
|---|
| 413 | classified as containing a front.</p></li></ul><p>When the width and height of histogram window is an even number, the |
|---|
| 414 | center pixel is the one to the lower right of the exact center of the |
|---|
| 415 | window, which falls at the intersection of four pixels. For example, |
|---|
| 416 | in a 6x6 window, the center pixel is the fourth from the left and |
|---|
| 417 | fourth from the top.</p></td></tr><tr><td class="info">{outputWindowStatusValuesFile}</td><td class="info" align="left"><p>Output binary raster to be used in conjunction with the window |
|---|
| 418 | status codes when diagnosing the results of the algorithm.</p><p>The file will contain 32-bit floating point numbers and have the same |
|---|
| 419 | dimensions as the input image. The value of each pixel depends on the |
|---|
| 420 | window status code for that pixel:</p><ul><li><p>Codes 0, 1, 7 - The pixel value is always 0.0.</p></li></ul><ul><li><p>Code 2 - The pixel value is the proportion of the window's pixels |
|---|
| 421 | that were allocated to the smaller population.</p></li></ul><ul><li><p>Code 3 - The pixel value is the difference in the mean values of |
|---|
| 422 | the window's two populations.</p></li></ul><ul><li><p>Code 4 - The pixel value is the criterion function that was |
|---|
| 423 | calculated for the window.</p></li></ul><ul><li><p>Code 5 - The pixel value is the cohesion of the window's population |
|---|
| 424 | that was found to be insufficiently cohesive. If both populations |
|---|
| 425 | were insufficiently cohesive, it is the cohesion of the "cold" |
|---|
| 426 | population.</p></li></ul><ul><li><p>Code 6 - The pixel value is the cohesion of the window's two |
|---|
| 427 | populations together.</p></li></ul><p>By examining the pixel values, you can determine how to adjust the |
|---|
| 428 | algorithm's parameters to cause more or fewer windows to pass the |
|---|
| 429 | algorithm's tests, increasing or decreasing the number of fronts |
|---|
| 430 | identified in the image. You should only adjust the parameters if you |
|---|
| 431 | feel comfortable deviating from their published values.</p></td></tr></tbody></table></div><p><h2><img width="11" height="11" border="0" src="sm_arrow_down.gif?format=raw" /> Scripting syntax</h2></p><div Class="expand" id="TEST">CoastWatchAVHRRFindFrontsAsBinaryRaster_GeoEco (imageFile, variable, outputFrontsFile, cloudMaskFile, cloudVariable, sunZenithFile, sunZenithVariable, useDayCloudTest1, useDayCloudTest2, useDayCloudTest3, useDayCloudTest4, useDayCloudTest5, useDayCloudTest6, useDayCloudTest7, maskWhenDayCloudMaskExceeds, useNightCloudTest1, useNightCloudTest2, useNightCloudTest3, useNightCloudTest4, useNightCloudTest5, useNightCloudTest6, useNightCloudTest7, maskWhenNightCloudMaskExceeds, minCloudyNeighbors, medianFilterWindowSize, histogramWindowSize, histogramWindowStride, minPropNonMaskedCells, minPopProp, minPopMeanDifference, minTheta, minSinglePopCohesion, minGlobalPopCohesion, threads, outputMaskFile, outputFilteredImageFile, outputCandidateCountsFile, outputFrontCountsFile, outputWindowStatusCodesFile, outputWindowStatusValuesFile) <br /><br /><b>Parameters</b><br /><table width="100%" border="0" cellpadding="5"><tbody><tr><th width="40%"><b>Expression</b></th><th width="60%"><b>Explanation</b></th></tr><tr><td class="info">CoastWatch file (Required) </td><td class="info" align="left"><p>CoastWatch POES AVHRR CWF or HDF file in which fronts should be |
|---|
| 432 | detected.</p><p>Only CoastWatch POES AVHRR files are supported. An error will be raise |
|---|
| 433 | for other CoastWatch files, such as those for the GOES satellite |
|---|
| 434 | series.</p><p>If you provide a compressed file in a supported compression format, it |
|---|
| 435 | will be automatically decompressed. If it is an archive (e.g. .zip or |
|---|
| 436 | .tar), it must contain exactly one file, which must not be in a |
|---|
| 437 | subdirectory.</p></td></tr><tr><td class="info">Variable (Required) </td><td class="info" align="left"><p>Name of the CoastWatch variable to in which fronts should be |
|---|
| 438 | detected. At the time of this writing, the CoastWatch program was |
|---|
| 439 | known to have published files with these variables:</p><dl><dt></dt><dd><pre>avhrr_ch1 |
|---|
| 440 | avhrr_ch2 |
|---|
| 441 | avhrr_ch3 |
|---|
| 442 | avhrr_ch3a |
|---|
| 443 | avhrr_ch4 |
|---|
| 444 | avhrr_ch5 |
|---|
| 445 | cloud |
|---|
| 446 | cloudx |
|---|
| 447 | graphics |
|---|
| 448 | sst |
|---|
| 449 | rel_azimuth |
|---|
| 450 | sat_zenith |
|---|
| 451 | sun_zenith</pre></dd></dl><p>Almost all users will want to detect fronts in the sst variable, but |
|---|
| 452 | you may specify one of the others, if appropriate for your project. |
|---|
| 453 | Please see the CoastWatch documentation for more information about the |
|---|
| 454 | variables.</p></td></tr><tr><td class="info">Output fronts image (Required) </td><td class="info" align="left"><p>Output binary raster that shows the fronts detected in the input |
|---|
| 455 | image.</p><p>The file will have the same dimensions as the input image and contain |
|---|
| 456 | 8-bit signed integers with three possible values:</p><ul><li><p>-128 - the pixel was never a candidate for containing a front, |
|---|
| 457 | either because it was masked or because because it did not appear in |
|---|
| 458 | any histogram windows that had sufficiently large numbers of |
|---|
| 459 | non-masked pixels to proceed with the histogramming step of the |
|---|
| 460 | Cayula-Cornillon algorithm.</p></li></ul><ul><li><p>0 - The pixel was a candidate for containing a front -- it was not |
|---|
| 461 | masked and it appeared in at least one histogram window with a |
|---|
| 462 | sufficient number of non-masked pixels to proceed with the |
|---|
| 463 | histogramming step -- but it was never marked as a front pixel in |
|---|
| 464 | any of the histogram windows it appeared in.</p></li></ul><ul><li><p>1 - The pixel was a candidate for containing a front and it was marked |
|---|
| 465 | as a front pixel in at least one of the histogram windows it |
|---|
| 466 | appeared in.</p></li></ul></td></tr><tr><td class="info">CoastWatch cloud mask file (Optional) </td><td class="info" align="left"><p>CoastWatch POES AVHRR CWF or HDF file that contains the CoastWatch |
|---|
| 467 | cloud mask.</p><p>A value need only be provided for this parameter when the cloud mask |
|---|
| 468 | is not stored in the input CoastWatch file. This will usually be the |
|---|
| 469 | case for CWF files, because they usually do not contain more than one |
|---|
| 470 | CoastWatch variable per file. HDF files usually contain all of the |
|---|
| 471 | variables, so you can usually omit this parameter for HDF files.</p><p>If you provide a compressed file in a supported compression format, it |
|---|
| 472 | will be automatically decompressed. If it is an archive (e.g. .zip or |
|---|
| 473 | .tar), it must contain exactly one file, which must not be in a |
|---|
| 474 | subdirectory.</p></td></tr><tr><td class="info">Cloud mask variable (Optional) </td><td class="info" align="left"><p>Name of the CoastWatch variable to extract from the cloud mask |
|---|
| 475 | file and use as the cloud mask (e.g. "cloud").</p><p>The current implementation of this tool was designed to operate on the |
|---|
| 476 | 8-bit CLAVR cloud mask represented by the "cloud" variable in |
|---|
| 477 | CoastWatch files. It was not designed to operate on the "cloudx" |
|---|
| 478 | variable, which is a new experimental CLAVR-x cloud mask available in |
|---|
| 479 | recent CoastWatch HDF files. Nonetheless, if you wish to operate on |
|---|
| 480 | the cloudx variable, you can specify it instead of cloud, and pick |
|---|
| 481 | mask options appropriate for it instead.</p></td></tr><tr><td class="info">CoastWatch solar zenith file (Optional) </td><td class="info" align="left"><p>CoastWatch POES AVHRR CWF or HDF file that contains the solar |
|---|
| 482 | zenith image, typically represented by the sun_zenith variable.</p><p>A value need only be provided for this parameter when the solar zenith |
|---|
| 483 | is not stored in the input CoastWatch file. This will usually be the |
|---|
| 484 | case for CWF files, because they usually do not contain more than one |
|---|
| 485 | CoastWatch variable per file. HDF files usually contain all of the |
|---|
| 486 | variables, so you can usually omit this parameter for HDF files.</p><p>If you provide a compressed file in a supported compression format, it |
|---|
| 487 | will be automatically decompressed. If it is an archive (e.g. .zip or |
|---|
| 488 | .tar), it must contain exactly one file, which must not be in a |
|---|
| 489 | subdirectory.</p><p>According to CoastWatch researcher Peter Hollemans, when an image's |
|---|
| 490 | scene time is "day", all pixels of the cloud mask use daytime cloud |
|---|
| 491 | tests, and when it is "night", all pixels use nighttime cloud tests. |
|---|
| 492 | When the scene time is "day/night", the decision of which tests to use |
|---|
| 493 | is based on the solar zenith for that pixel.</p><p>According to Peter, for CoastWatch HDF files, pixels with a solar |
|---|
| 494 | zenith > 80 degrees use the nighttime cloud tests, and <= 80 use the |
|---|
| 495 | daytime cloud tests. This tool implements that logic. If you specify |
|---|
| 496 | that cloud masking should be performed for a day/night image but no |
|---|
| 497 | solar zenith image is available, this tool will assume that nighttime |
|---|
| 498 | cloud tests were used for every pixel and a warning will be issued. |
|---|
| 499 | For some reason, CoastWatch occasionally produces day/night images |
|---|
| 500 | with no sun_zenith or other variables that are present in day images. |
|---|
| 501 | My recollection is that Peter said it is safe to assume for these |
|---|
| 502 | images that all pixels are nighttime.</p><p>The solar zenith image is ignored for scene times other than |
|---|
| 503 | "day/night" (e.g. "day" or "night").</p><p>After some investigation, I find that the cloud mask pixels near the |
|---|
| 504 | 80 degree solar zenith line are problematic, for two reasons:</p><ul><li><p>According to Peter, the solar zenith <= 80 cutoff line is not going |
|---|
| 505 | to line up perfectly with the switch from daytime to nighttime cloud |
|---|
| 506 | tests because the solar zenith angles are rounded to the nearest |
|---|
| 507 | 0.01 when written to the HDF file so a few pixels with values of say |
|---|
| 508 | 80.003 will get rounded to 80 even though they underwent processing |
|---|
| 509 | with the nighttime cloud tests. Peter said, "I guess that's the flaw |
|---|
| 510 | with storing angle data in HDF as scaled integers (that decision was |
|---|
| 511 | mainly due to file size concerns)."</p></li></ul><ul><li><p>The switch between daytime tests and nighttime tests does not |
|---|
| 512 | manifest as a clean transition in the cloud mask pixels. The daytime |
|---|
| 513 | pixels do not seem to cleanly abut the nighttime pixels. Rather, a |
|---|
| 514 | strip of pixels with strange values raggedly separates the two. |
|---|
| 515 | Peter said: "The apparent unclean transition between day and night |
|---|
| 516 | tests is related to neighborhood functions. The uniformity tests |
|---|
| 517 | use a 2x2 box of data values to the right and below a given value in |
|---|
| 518 | the array to check for a condition being true, and the results of |
|---|
| 519 | the uniformity test flag all pixels in the 2x2 box with the test |
|---|
| 520 | results, regardless of whether all those pixels are day or |
|---|
| 521 | nighttime. Both day and nighttime have uniformity tests, so the |
|---|
| 522 | results of uniformity tests at the day/night boundary are mixed. The |
|---|
| 523 | mixing is generally acceptable because the results are intended to |
|---|
| 524 | be used for SST masking not cloud type evaluation and the mixing |
|---|
| 525 | only occurs in cloudy conditions, not clear SST conditions."</p></li></ul><p>Peter said he did not know what was done for CoastWatch day/night CWF |
|---|
| 526 | files. I examined a few of these from the North East region, and it |
|---|
| 527 | appeared that they also switched from daytime to nighttime cloud tests |
|---|
| 528 | in the middle of the image. But the NOAA distribution site |
|---|
| 529 | (<a href="http://www.class.noaa.gov">http://www.class.noaa.gov</a>) only appeared to have CWFs containing the |
|---|
| 530 | sun_zenith variable for dates after late 1999.</p><p>Peter mentioned that the cwangles program from the CoastWatch |
|---|
| 531 | Utilities could compute the solar zenith, but the values would only be |
|---|
| 532 | approximate beacuse the program assumed that all pixels were obtained |
|---|
| 533 | by the sensor at the same moment in time. I tried this approach but |
|---|
| 534 | the 80 degree solar zenith line did not line up with the line where |
|---|
| 535 | the cloud tests appeared to switch. Because of this, I do not believe |
|---|
| 536 | that day/night CWF files will be useable for users who want to use |
|---|
| 537 | some cloud tests and ignore others.</p></td></tr><tr><td class="info">Solar zenith variable (Optional) </td><td class="info" align="left"><p>Name of the CoastWatch variable to extract from the solar zenith |
|---|
| 538 | file and use as the solar zenith image (e.g. "sun_zenith").</p></td></tr><tr><td class="info">Use daytime Reflective Gross Cloud Test (bit 1) (Optional) </td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Reflective Gross |
|---|
| 539 | Cloud Test (bit 1 of the cloud mask) will be masked. If False, this |
|---|
| 540 | cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 |
|---|
| 541 | test is used for both CWF and HDF files, but for HDF files, the |
|---|
| 542 | CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 543 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 544 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 545 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 546 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 547 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use daytime Reflectance Uniformity Test (bit 2) (Optional) </td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Reflectance |
|---|
| 548 | Uniformity Test (bit 2 of the cloud mask) will be masked. If False, |
|---|
| 549 | this cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 |
|---|
| 550 | test is used for both CWF and HDF files, but for HDF files, the |
|---|
| 551 | CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 552 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 553 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 554 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 555 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 556 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use daytime Reflectance Ratio Cloud Test (bit 3) (Optional) </td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Reflectance Ratio |
|---|
| 557 | Cloud Test (bit 3 of the cloud mask) will be masked. If False, this |
|---|
| 558 | cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 |
|---|
| 559 | test is used for both CWF and HDF files, but for HDF files, the |
|---|
| 560 | CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 561 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 562 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 563 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 564 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 565 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use daytime Channel 3 Albedo Test (bit 4) (Optional) </td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Channel 3 Albedo |
|---|
| 566 | Test (bit 4 of the cloud mask) will be masked. If False, this cloud |
|---|
| 567 | test will be ignored.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 568 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 569 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 570 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 571 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 572 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use daytime Thermal Uniformity Test (bit 5) (Optional) </td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Thermal Uniformity |
|---|
| 573 | Test (bit 5 of the cloud mask) will be masked. If False, this cloud |
|---|
| 574 | test will be ignored.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 575 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 576 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 577 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 578 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 579 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use daytime Four Minus Five Test (bit 6) (Optional) </td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Four Minus Five |
|---|
| 580 | Test (bit 6 of the cloud mask) will be masked. If False, this cloud |
|---|
| 581 | test will be ignored.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 582 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 583 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 584 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 585 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 586 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use daytime Thermal Gross Cloud Test (bit 7) (Optional) </td><td class="info" align="left"><p>If True, daytime pixels that failed the CLAVR-1 Thermal Gross |
|---|
| 587 | Cloud Test (bit 7 of the cloud mask) will be masked. If False, this |
|---|
| 588 | cloud test will be ignored.</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 589 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 590 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 591 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 592 | indicates it failed. For more details about the cloud tests, please see the |
|---|
| 593 | CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Mask when daytime cloud mask exceeds value (Optional) </td><td class="info" align="left"><p>If a value is provided, daytime pixels with a cloud mask value |
|---|
| 594 | greater than this value will be masked.</p><p>The CoastWatch cloud mask is a bitmask, where each bit represents the |
|---|
| 595 | success (0) or failure (1) of a given CLAVR cloud test. Thus the cloud |
|---|
| 596 | mask values are NOT intended to be interpreted as range, like a |
|---|
| 597 | spectrum, where 0 represents "very clear" and 255 represents "very |
|---|
| 598 | cloudy". Nevertheless, some users of this tool determined that for |
|---|
| 599 | their study the best tradeoff between minimizing SST error and |
|---|
| 600 | minimizing the number of pixels masked by clouds was obtained by |
|---|
| 601 | masking all pixels where the cloud mask exceeded a certain value. This |
|---|
| 602 | option was implemented specifically for those users and is not |
|---|
| 603 | recommended for general use. If you do use this option, be sure to |
|---|
| 604 | study many cloud mask images before selecting a value.</p><p>If a value is provided both for this parameter and for the cloud test |
|---|
| 605 | bits specified by the previous parameters, all of these parameters |
|---|
| 606 | will be effective. In other words, a cloudy pixel can be masked by |
|---|
| 607 | failing a specific cloud test, or by exceeding the minimum cloud mask |
|---|
| 608 | value, or both. .</p><p>This parameter is ignored for nighttime pixels. For a discussion of |
|---|
| 609 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 610 | documentation for the cloud mask file parameter. For more information |
|---|
| 611 | about the cloud tests, please see the CoastWatch and CLAVR |
|---|
| 612 | documentation.</p></td></tr><tr><td class="info">Use nighttime Thermal Gross Cloud Test (bit 1) (Optional) </td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Thermal Gross |
|---|
| 613 | Cloud Test (bit 1 of the cloud mask) will be masked. If False, this |
|---|
| 614 | cloud test will be ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 615 | pixels are classified as daytime or nighttime, please see the |
|---|
| 616 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 617 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 618 | indicates it failed. For more details about the cloud tests, please |
|---|
| 619 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use nighttime Thermal Uniformity Test (bit 2) (Optional) </td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Thermal |
|---|
| 620 | Uniformity Test (bit 2 of the cloud mask) will be masked. If False, |
|---|
| 621 | this cloud test will be ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 622 | pixels are classified as daytime or nighttime, please see the |
|---|
| 623 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 624 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 625 | indicates it failed. For more details about the cloud tests, please |
|---|
| 626 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use nighttime Uniform Low Stratus Test (bit 3) (Optional) </td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Uniform Low |
|---|
| 627 | Stratus Test (bit 3 of the cloud mask) will be masked. If False, this |
|---|
| 628 | cloud test will be ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 629 | pixels are classified as daytime or nighttime, please see the |
|---|
| 630 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 631 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 632 | indicates it failed. For more details about the cloud tests, please |
|---|
| 633 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use nighttime Four Minus Five Test (bit 4) (Optional) </td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Four Minus Five |
|---|
| 634 | Test (bit 4 of the cloud mask) will be masked. If False, this cloud |
|---|
| 635 | test will be ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 636 | pixels are classified as daytime or nighttime, please see the |
|---|
| 637 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 638 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 639 | indicates it failed. For more details about the cloud tests, please |
|---|
| 640 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use nighttime Cirrus Test (bit 5) (Optional) </td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-1 Cirrus Test (bit |
|---|
| 641 | 5 of the cloud mask) will be masked. If False, this cloud test will be |
|---|
| 642 | ignored.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 643 | pixels are classified as daytime or nighttime, please see the |
|---|
| 644 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 645 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 646 | indicates it failed. For more details about the cloud tests, please |
|---|
| 647 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use nighttime Channel 3B Albedo Test (bit 6) (Optional) </td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-x Channel 3B |
|---|
| 648 | Albedo Test (bit 6 of the cloud mask) will be masked. If False, this |
|---|
| 649 | cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, this test was not |
|---|
| 650 | used for CoastWatch CWF files and thus bit 6 will always be 0, |
|---|
| 651 | indicating success, for CWF nighttime cloud mask pixels.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 652 | pixels are classified as daytime or nighttime, please see the |
|---|
| 653 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 654 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 655 | indicates it failed. For more details about the cloud tests, please |
|---|
| 656 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Use nighttime Channel 3B Albedo Uniformity Test (bit 7) (Optional) </td><td class="info" align="left"><p>If True, nighttime pixels that failed the CLAVR-x Channel 3B |
|---|
| 657 | Albedo Uniformity Test (bit 7 of the cloud mask) will be masked. If |
|---|
| 658 | False, this cloud test will be ignored.</p><p>According to CoastWatch researcher Peter Hollemans, this test was not |
|---|
| 659 | used for CoastWatch CWF files and thus bit 7 will always be 0, |
|---|
| 660 | indicating success, for CWF nighttime cloud mask pixels.</p><p>This parameter is ignored for daytime pixels. For a discussion of how |
|---|
| 661 | pixels are classified as daytime or nighttime, please see the |
|---|
| 662 | documentation for the cloud mask file parameter.</p><p>In CoastWatch cloud masks, bit 1 is the least significant bit, and a |
|---|
| 663 | value of 0 for a bit indicates that the cloud test passed, while 1 |
|---|
| 664 | indicates it failed. For more details about the cloud tests, please |
|---|
| 665 | see the CoastWatch and CLAVR documentation.</p></td></tr><tr><td class="info">Mask when nighttime cloud mask exceeds value (Optional) </td><td class="info" align="left"><p>If a value is provided, nighttime pixels with a cloud mask value |
|---|
| 666 | greater than this value will be masked.</p><p>The CoastWatch cloud mask is a bitmask, where each bit represents the |
|---|
| 667 | success (0) or failure (1) of a given CLAVR cloud test. Thus the cloud |
|---|
| 668 | mask values are NOT intended to be interpreted as range, like a |
|---|
| 669 | spectrum, where 0 represents "very clear" and 255 represents "very |
|---|
| 670 | cloudy". Nevertheless, some users of this tool determined that for |
|---|
| 671 | their study the best tradeoff between minimizing SST error and |
|---|
| 672 | minimizing the number of pixels masked by clouds was obtained by |
|---|
| 673 | masking all pixels where the cloud mask exceeded a certain value. This |
|---|
| 674 | option was implemented specifically for those users and is not |
|---|
| 675 | recommended for general use. If you do use this option, be sure to |
|---|
| 676 | study many cloud mask images before selecting a value.</p><p>If a value is provided both for this parameter and for the cloud test |
|---|
| 677 | bits specified by the previous parameters, all of these parameters |
|---|
| 678 | will be effective. In other words, a cloudy pixel can be masked by |
|---|
| 679 | failing a specific cloud test, or by exceeding the minimum cloud mask |
|---|
| 680 | value, or both. .</p><p>This parameter is ignored for daytime pixels. For a discussion of |
|---|
| 681 | how pixels are classified as daytime or nighttime, please see the |
|---|
| 682 | documentation for the cloud mask file parameter. For more information |
|---|
| 683 | about the cloud tests, please see the CoastWatch and CLAVR |
|---|
| 684 | documentation.</p></td></tr><tr><td class="info">Minimum number of cloudy neighbors (Optional) </td><td class="info" align="left"><p>Minimum number of neighbors that a cloudy pixel must have in order |
|---|
| 685 | for that pixel to be masked.</p><p>You can use this option to ignore isolated cloudy pixels that are not |
|---|
| 686 | clumped together. For example, if you specify the value 1, cloudy |
|---|
| 687 | pixels will be ignored and not used in the masking process unless at |
|---|
| 688 | least one of their eight neighbors is also cloudy.</p><p>If a neighbor is not cloudy but it is masked for some other reason |
|---|
| 689 | (e.g. it is land), it does not count as being cloudy.</p><p>This option is ignored when cloud masking is not performed.</p></td></tr><tr><td class="info">Median filter window size (Optional) </td><td class="info" align="left"><p>Window size, in pixels, of the median filter to apply to the input |
|---|
| 690 | image prior to running the histogram analysis step of the |
|---|
| 691 | Cayula-Cornillon algorithm. If not provided, median filtering will not |
|---|
| 692 | be performed.</p><p>If you provide a value, it must be an odd integer greater than or |
|---|
| 693 | equal to 3. The filter window is square and advances across the image |
|---|
| 694 | 1 pixel at a time. The center pixel, if it is not masked, is replaced |
|---|
| 695 | with the median value of the non-masked pixels in the surrounding |
|---|
| 696 | window. All masks are applied before the median filter is executed.</p><p>Median filtering is a traditional first step for certain classes of |
|---|
| 697 | edge detection algorithms. The original Cayula-Cornillon paper used a |
|---|
| 698 | window size of 3.</p></td></tr><tr><td class="info">Histogram window size (Optional) </td><td class="info" align="left"><p>Size of the histogram window to use for the Cayula-Cornillon |
|---|
| 699 | algorithm.</p><p>The window is square. The original paper used a window size of 32. |
|---|
| 700 | Although the algorithm is claimed to obtain similar results regardless |
|---|
| 701 | of window size, I have noticed that some fronts may only be detected |
|---|
| 702 | by using a smaller window size such as 16. I highly recommend you read |
|---|
| 703 | the paper carefully before experimenting with different window |
|---|
| 704 | sizes.</p></td></tr><tr><td class="info">Histogram window stride (Optional) </td><td class="info" align="left"><p>Number of pixels to move the histogram window after each iteration |
|---|
| 705 | of the Cayula-Cornillon algorithm.</p><p>The original paper used a 32x32 window and a stride of 16, to minimize |
|---|
| 706 | the CPU time required to execute the algorithm. Cutting the stride in |
|---|
| 707 | half increases the CPU time by a factor of about four. For example, a |
|---|
| 708 | stride of 1 requires about 256 times more CPU time than a stride of |
|---|
| 709 | 16.</p><p>In my experience, smaller stride values identify more fronts, and the |
|---|
| 710 | resulting fronts are longer and thicker. If you have a powerful |
|---|
| 711 | computer, want to find more fronts, and are comfortable deviating from |
|---|
| 712 | the published method, you can use a smaller value. If you do this, you |
|---|
| 713 | may want to apply a thinning algorithm after running this tool, to |
|---|
| 714 | reduce the widths of the resulting fronts.</p></td></tr><tr><td class="info">Minimum proportion of non-masked pixels (Optional) </td><td class="info" align="left"><p>Minimum proportion of pixels in a histogram window that must not |
|---|
| 715 | be masked for the algorithm to proceed with histogram analysis on that |
|---|
| 716 | window.</p><p>For example, if the value 0.75 is used and the histogram window is |
|---|
| 717 | 20x20, at least 300 out of the 400 pixels must not be masked for |
|---|
| 718 | analysis to proceed on that window. If more than 100 pixels are |
|---|
| 719 | masked, the algorithm discards the current window, advances to next |
|---|
| 720 | one, and starts over.</p><p>The Fortran code I obtained from Dave Ullman used the value 0.65.</p></td></tr><tr><td class="info">Minimum proportion of smaller population (Optional) </td><td class="info" align="left"><p>Minimum proportional size of the smaller population.</p><p>If the histogram algorithm determines that the values of the |
|---|
| 721 | non-masked pixels in the window have a bimodal distribution, it then |
|---|
| 722 | selects the value that optimally separates them into two populations. |
|---|
| 723 | As described on page 73 of the 1992 paper, if the proportion of |
|---|
| 724 | non-masked pixels allocated to the smaller population is smaller than |
|---|
| 725 | 0.25, the subsequent statistical tests will not be accurate. In this |
|---|
| 726 | case, and the algorithm discards the current window, advances to next |
|---|
| 727 | one, and starts over.</p><p>I do not recommend selecting a value other than 0.25 unless you |
|---|
| 728 | understand the statistical analysis presented in the 1992 paper.</p></td></tr><tr><td class="info">Minimum population mean difference (Optional) </td><td class="info" align="left"><p>Minimum difference in population means.</p><p>After the histogram algorithm separates the non-masked pixels into two |
|---|
| 729 | populations, it computes the means of the two populations. If the |
|---|
| 730 | means differ by less than this parameter value, the algorithm discards |
|---|
| 731 | the current window, advances to next one, and starts over.</p><p>The original intent of this parameter is obscure. The Fortran code I |
|---|
| 732 | obtained from Dave Ullman used the value 3 and contained the |
|---|
| 733 | explanation "a temperature difference of less than three digital |
|---|
| 734 | counts between the 2 populations is likely to be a result of the |
|---|
| 735 | discrete nature of the data."</p><p>You can use this parameter to eliminate weak fronts by selecting a |
|---|
| 736 | value that corresponds to a desired minimum mean temperature |
|---|
| 737 | difference. For example, the NOAA NODC 4km AVHRR Pathfinder Project |
|---|
| 738 | (<a href="http://www.nodc.noaa.gov/SatelliteData/pathfinder4km/">http://www.nodc.noaa.gov/SatelliteData/pathfinder4km/</a>) publishes SST |
|---|
| 739 | data as 16-bit unsigned integers where each integer represents 0.075 |
|---|
| 740 | degrees. To eliminate fronts where the mean temperature difference is |
|---|
| 741 | less than 0.5 degrees, set this parameter to 0.5 / 0.075 = |
|---|
| 742 | 6.666667.</p></td></tr><tr><td class="info">Minimum value for criterion function (Optional) </td><td class="info" align="left"><p>Minimum criterion function, theta(Topt), as described on pages |
|---|
| 743 | 71-72 of the 1992 paper.</p><p>The criterion function is used to determine whether the histogram |
|---|
| 744 | window contains a bimodal distribution. Cayula and Cornillon performed |
|---|
| 745 | an extensive analysis to determine that the value 0.76 produced |
|---|
| 746 | optimal results for the SST data they worked with. Selecting a smaller |
|---|
| 747 | value will allow windows with more homogenous, less bimodal |
|---|
| 748 | distributions to be considered by the algorithm. If the window yields |
|---|
| 749 | a value less than this parameter, the algorithm discards the current |
|---|
| 750 | window, advances to next one, and starts over.</p><p>I do not recommend selecting a value other than 0.76 unless you |
|---|
| 751 | understand the statistics presented in the original paper.</p></td></tr><tr><td class="info">Minimum single-population cohesion (Optional) </td><td class="info" align="left"><p>Minimum cohesion of a single population.</p><p>If the histogram window is found to have a sufficiently bimodal |
|---|
| 752 | distribution of values, the cohesion algorithm is executed to check |
|---|
| 753 | whether the pixels of the two populations are sufficiently spatially |
|---|
| 754 | separated. High values indicate that they are separated, suggesting |
|---|
| 755 | that two distinct populations (e.g. water masses) are present in the |
|---|
| 756 | window. Low values indicate the populations are all mixed up, like a |
|---|
| 757 | checkerboard, and suggest that the pattern results from clouds, noise |
|---|
| 758 | or other random processes.</p><p>The first part of the cohesion algorithm checks the cohesion of each |
|---|
| 759 | population by itself (equations 19 and 20 in the 1992 paper). As |
|---|
| 760 | described in Appendix B of the 1992 paper, the optimal cohesion |
|---|
| 761 | coefficients depend on the size of the histogram window. Cayula and |
|---|
| 762 | Cornillon used the value 0.90 for a 32x32 window, which was |
|---|
| 763 | calculated:</p><dl><dt></dt><dd><pre>C = 1.0 - 0.02 - 1/winsize - 2*P(error) = 0.98 - 1/32 - 2(0.025) = 0.90</pre></dd></dl><p>For a 16x16 window, the equation evaluates to 0.8675.</p></td></tr><tr><td class="info">Minimum global-population cohesion (Optional) </td><td class="info" align="left"><p>Minimum cohesion of both populations.</p><p>The second part of the cohesion algorithm checks the cohesion of both |
|---|
| 764 | populations together (equation 21 in the 1992 paper). As described in |
|---|
| 765 | Appendix B of the 1992 paper, the optimal cohesion coefficients depend |
|---|
| 766 | on the size of the histogram window. Cayula and Cornillon used the |
|---|
| 767 | value 0.92 for a 32x32 window, which was calculated:</p><dl><dt></dt><dd><pre>C = 1.0 - 1/winsize - 2*P(error) = 1.0 - 1/32 - 2(0.025) = 0.92</pre></dd></dl><p>For a 16x16 window, the equation evaluates to 0.8875.</p></td></tr><tr><td class="info">Processing threads (Optional) </td><td class="info" align="left"><p>Number of threads to start for parallel processing.</p><p>The histogram and cohesion algorithms are CPU intensive but are |
|---|
| 768 | designed to run in parallel on machines that have multiple processors. |
|---|
| 769 | To maximize utilization of your machine's processors and shorten the |
|---|
| 770 | time required to execute the algorithms, set the number of threads to |
|---|
| 771 | the number of processors you wish to utilize. Do not set the number of |
|---|
| 772 | threads to more than the number of processors you have; this will |
|---|
| 773 | reduce performance.</p><p>For this option to have any effect, your version of Python must |
|---|
| 774 | include the threading module. Most recent versions of Python include |
|---|
| 775 | this module.</p></td></tr><tr><td class="info">Output mask image (Optional) </td><td class="info" align="left"><p>Output binary raster that shows the pixels of the input image that |
|---|
| 776 | were masked prior to executing the Cayula-Cornillon algorithm.</p><p>The file will have the same dimensions as the input image and contain |
|---|
| 777 | 8-bit unsigned integers. The value 1 indicates that the corresponding |
|---|
| 778 | pixel of the input image was masked; 0 indicates the pixel was not |
|---|
| 779 | masked.</p></td></tr><tr><td class="info">Output median filtered image (Optional) </td><td class="info" align="left"><p>Output binary raster that shows the median-filtered input image.</p><p>The file will have the same data type and dimensions as the input |
|---|
| 780 | image. Non-masked pixels will have the median value of the non-masked |
|---|
| 781 | pixels in the surrounding window (the center pixel is included in the |
|---|
| 782 | median selection). Masked pixels will be marked with the smallest |
|---|
| 783 | possible value for the pixel data type. For example, if the pixel data |
|---|
| 784 | type is 16-bit signed integer, the masked pixels will be marked with |
|---|
| 785 | the value -32768.</p></td></tr><tr><td class="info">Output candidate count image (Optional) </td><td class="info" align="left"><p>Output binary raster that indicates how many times the |
|---|
| 786 | corresponding pixel of the input image was a candidate for containing |
|---|
| 787 | a front, i.e. the number of times it appeared in a histogram window |
|---|
| 788 | that had a sufficiently large number of non-masked pixels to proceed |
|---|
| 789 | to the histogram algorithm.</p><p>The file will contain 16-bit signed integers and have the same |
|---|
| 790 | dimensions as the input image. If the histogram window stride is less |
|---|
| 791 | than the window size, successive histogram windows will overlap, and |
|---|
| 792 | many pixels will have candidate counts greater than 1. Masked pixels |
|---|
| 793 | can never be candidates for containing a front and will have the value |
|---|
| 794 | -32768.</p></td></tr><tr><td class="info">Output front count image (Optional) </td><td class="info" align="left"><p>Output binary raster that indicates how many times a front was |
|---|
| 795 | detected at the corresponding pixel of the input image.</p><p>The file will contain 16-bit signed integers and have the same |
|---|
| 796 | dimensions as the input image. The value will range from 0 (the input |
|---|
| 797 | image pixel never contained a front) to the candidate count value for |
|---|
| 798 | the pixel (it always contained a front in every histogram window that |
|---|
| 799 | contained it). Masked pixels can never be candidates for containing a |
|---|
| 800 | front and will have the value -32768.</p></td></tr><tr><td class="info">Output window status codes image (Optional) </td><td class="info" align="left"><p>Output binary raster that indicates the result of the algorithm |
|---|
| 801 | for the histogram window centered on the pixel. You can use this image |
|---|
| 802 | to diagnose why the algorithm did not find fronts in a particular |
|---|
| 803 | region of your image.</p><p>The file will contain 8-bit signed integers and have the same |
|---|
| 804 | dimensions as the input image. The pixel values will be one of these |
|---|
| 805 | code numbers:</p><ul><li><p>Code 0 - The algorithm was not executed for the window because the |
|---|
| 806 | histogram window stride was greater than 1, causing the algorithm to |
|---|
| 807 | skip over this window.</p></li></ul><ul><li><p>Code 1 - The proportion of the window's pixels that had data was |
|---|
| 808 | found to be too small. This typically occurs when the window occurs |
|---|
| 809 | in a region where many of the pixels are masked due to land, clouds, |
|---|
| 810 | or insufficient satellite coverage.</p></li></ul><ul><li><p>Code 2 - After the histogram algorithm optimally separated the |
|---|
| 811 | window's pixels into two populations, the proportion of pixels |
|---|
| 812 | allocated to the smaller population was found to be too small. This |
|---|
| 813 | can occur when a front occurs in the window, but the window is not |
|---|
| 814 | centered on the front, causing it to contain a disproportionate |
|---|
| 815 | number of pixels from one population. This is usually not a problem. |
|---|
| 816 | As long as the histogram window stride is sufficiently small, the |
|---|
| 817 | histogram window will eventually pass over the front and proceed to |
|---|
| 818 | the next step of the algorithm.</p></li></ul><ul><li><p>Code 3 - After the histogram algorithm optimally separated the |
|---|
| 819 | window's pixels into two populations, the difference between the |
|---|
| 820 | mean values of the two populations was found to be too small. This |
|---|
| 821 | typically happens when the window does not contain a front or when |
|---|
| 822 | the gradient along the front is small (i.e. it is a weak front).</p></li></ul><ul><li><p>Code 4 - After the histogram algorithm optimally separated the |
|---|
| 823 | window's pixels into two populations, the criterion function that |
|---|
| 824 | was calculated was found to be too small (the criterion function is |
|---|
| 825 | theta(Topt) described on pages 71-72 of the 1992 paper). This means |
|---|
| 826 | that the two populations are not sufficiently bimodal to indicate |
|---|
| 827 | that a front exists in the window.</p></li></ul><ul><li><p>Code 5 - The window was found to have two populations that were |
|---|
| 828 | sufficiently proportional, different in their means, and bimodal, |
|---|
| 829 | but the cohesion of one or the other population was insufficient (as |
|---|
| 830 | described by equations 19 and 20 in the 1992 paper). This indicates |
|---|
| 831 | that the cells of the two populations are spatially intermixed like |
|---|
| 832 | a checkerboard, rather than being spatially separate, as occurs when |
|---|
| 833 | a front is present.</p></li></ul><ul><li><p>Code 6 - The window was found to have two populations that were |
|---|
| 834 | sufficiently proportional, different in their means, and bimodal, |
|---|
| 835 | and each population was found to be sufficiently cohesive, but the |
|---|
| 836 | cohesion of the two populations together was insufficient (as |
|---|
| 837 | described by equation 21 of the 1992 paper). As with code 5, this |
|---|
| 838 | indicates that the cells of the two populations are spatially |
|---|
| 839 | intermixed like a checkerboard, rather than being spatially |
|---|
| 840 | separate, as occurs when a front is present.</p></li></ul><ul><li><p>Code 7 - The window passed all of the algorithm's tests and was |
|---|
| 841 | classified as containing a front.</p></li></ul><p>When the width and height of histogram window is an even number, the |
|---|
| 842 | center pixel is the one to the lower right of the exact center of the |
|---|
| 843 | window, which falls at the intersection of four pixels. For example, |
|---|
| 844 | in a 6x6 window, the center pixel is the fourth from the left and |
|---|
| 845 | fourth from the top.</p></td></tr><tr><td class="info">Output window status values image (Optional) </td><td class="info" align="left"><p>Output binary raster to be used in conjunction with the window |
|---|
| 846 | status codes when diagnosing the results of the algorithm.</p><p>The file will contain 32-bit floating point numbers and have the same |
|---|
| 847 | dimensions as the input image. The value of each pixel depends on the |
|---|
| 848 | window status code for that pixel:</p><ul><li><p>Codes 0, 1, 7 - The pixel value is always 0.0.</p></li></ul><ul><li><p>Code 2 - The pixel value is the proportion of the window's pixels |
|---|
| 849 | that were allocated to the smaller population.</p></li></ul><ul><li><p>Code 3 - The pixel value is the difference in the mean values of |
|---|
| 850 | the window's two populations.</p></li></ul><ul><li><p>Code 4 - The pixel value is the criterion function that was |
|---|
| 851 | calculated for the window.</p></li></ul><ul><li><p>Code 5 - The pixel value is the cohesion of the window's population |
|---|
| 852 | that was found to be insufficiently cohesive. If both populations |
|---|
| 853 | were insufficiently cohesive, it is the cohesion of the "cold" |
|---|
| 854 | population.</p></li></ul><ul><li><p>Code 6 - The pixel value is the cohesion of the window's two |
|---|
| 855 | populations together.</p></li></ul><p>By examining the pixel values, you can determine how to adjust the |
|---|
| 856 | algorithm's parameters to cause more or fewer windows to pass the |
|---|
| 857 | algorithm's tests, increasing or decreasing the number of fronts |
|---|
| 858 | identified in the image. You should only adjust the parameters if you |
|---|
| 859 | feel comfortable deviating from their published values.</p></td></tr></tbody></table></div></body></html> |
|---|
