GeoEco Python Reference

Previous: FindFrontsAsArcGISRastersArcGISTable Method Up: CoastWatchAVHRR Class Next: FindFrontsAsArcGISRastersTable Method

---

FindFrontsAsArcGISRastersList Method

Finds fronts in a list of CoastWatch POES AVHRR images using the Cayula and Cornillon (1992) single-image edge detection algorithm and outputs them as ArcGIS rasters.

Usage

Arguments

imageFileList

Python type:	list of unicode
Minimum length:	0

List of paths of the CoastWatch POES AVHRR CWF or HDF files.

Only CoastWatch POES AVHRR files are supported. Other CoastWatch files, such as those for the GOES satellite series, will be skipped and a warning will be reported.

Compressed files in a supported compression format will be automatically decompressed. Archives (e.g. .zip or .tar) must contain exactly one file, which must not be in a subdirectory.

variableList

Python type:	list of unicode
Minimum length:	0

List of names of the variables in which fronts should be detected. At the time of this writing, the CoastWatch program was known to have published files with these variables:

avhrr_ch1
avhrr_ch2
avhrr_ch3
avhrr_ch3a
avhrr_ch4
avhrr_ch5
cloud
cloudx
graphics
sst
rel_azimuth
sat_zenith
sun_zenith

Almost all users will want to detect fronts in the sst variable, but you may specify one of the others, if appropriate for your project. Please see the CoastWatch documentation for more information about the variables.

minPopMeanDifference

Python type:	float
Must be greater than:	0.0

Minimum difference, in degrees C, between the mean temperatures of two adjacent populations of pixels for a front to be detected between those two populations.

The Cayula and Cornillon algorithm passes a moving window over the image, checking each window for a bimodal distribution in the temperatures of the pixels within it. When the algorithm detects a bimodal distribution, it computes the mean temperatures of the two populations and compares the difference between the means to this threshold. If the difference is less than this threshold, the algorithm concludes there is no front present and moves on to the next window.

You can use this parameter to eliminate weak fronts by selecting a value that corresponds to a desired minimum mean temperature difference. Bear in mind that Cayula and Cornillon's (1992) study used data from early satellites that contributed to the CoastWatch program. When I examined their Fortran code, I found a commenet suggesting that they believed the minimum allowable threshold given the measurement error of the sensors was 0.45 deg C.

outputFrontsRasterList

Python type:	list of unicode
Minimum length:	0

List of output rasters to create that show the fronts detected in the input images.

The output rasters will have the same dimensions as the input images and contain 8-bit signed integers with three possible values:

• NoData - the pixel was never a candidate for containing a front, either because it was masked or because because it did not appear in any histogram windows that had sufficiently large numbers of non-masked pixels to proceed with the histogramming step of the Cayula and Cornillon algorithm.
• 0 - The pixel was a candidate for containing a front -- it was not masked and it appeared in at least one histogram window with a sufficient number of non-masked pixels to proceed with the histogramming step -- but it was never marked as a front pixel in any of the histogram windows it appeared in.
• 1 - The pixel was a candidate for containing a front and it was marked as a front pixel in at least one of the histogram windows it appeared in.

cloudMaskFileList

Python type:	list of unicode or None, or None
Default value:	None
Minimum length:	0

List of paths of the CoastWatch POES AVHRR CWF or HDF files that contain the cloud masks for the input files.

If you omit this parameter, this tool will try to obtain the cloud mask from the input CoastWatch file instead. This will also occur when you do specify a field for this parameter, but a given row contains NULL for that field. If no cloud mask can be obtained from whichever file is used, cloud masking will not be performed.

If you're processing only HDFs, you can probably omit this parameter. HDFs usually contain all of the variables for a given satellite pass, including the cloud mask, so it is not necessary to obtain it from a different file. If you're processing CWFs, you must specify a field for this parameter if you want cloud masking to be performed. If you're processing both HDFs and CWFs, the field can contain NULL for the HDFs.

Compressed files in a supported compression format will be automatically decompressed. Archives (e.g. .zip or .tar) must contain exactly one file, which must not be in a subdirectory.

cloudVariable

Python type:	unicode or None
Default value:	u'cloud'
Minimum length:	1

Name of the CoastWatch variable to extract from the cloud mask file and use as the cloud mask (e.g. "cloud").

The current implementation of this tool was designed to operate on the 8-bit CLAVR cloud mask represented by the "cloud" variable in CoastWatch files. It was not designed to operate on the "cloudx" variable, which is a new experimental CLAVR-x cloud mask available in recent CoastWatch HDF files. Nonetheless, if you wish to operate on the cloudx variable, you can specify it instead of cloud, and pick mask options appropriate for it instead.

sunZenithFileList

Python type:	list of unicode or None, or None
Default value:	None
Minimum length:	0

List of paths of the CoastWatch POES AVHRR CWF or HDF files that contain the cloud solar zenith images (i.e. the "sun_zenith" variable) for the input files.

If you omit this parameter, this tool will try to obtain the solar zenith image from the input CoastWatch file instead. This will also occur when you do specify a field for this parameter, but a given row contains NULL for that field.

If you're processing only HDFs, you can probably omit this parameter. HDFs usually contain all of the variables for a given satellite pass, including the solar zenith (when sun is above the horizon), so it is not necessary to obtain it from a different file. If you're processing CWFs, you must specify a field for this parameter if you want cloud masking to be performed and you're processing images with a day/night scene time. If you're processing both HDFs and CWFs, the field can contain NULL for the HDFs.

Compressed files in a supported compression format will be automatically decompressed. Archives (e.g. .zip or .tar) must contain exactly one file, which must not be in a subdirectory.

According to CoastWatch researcher Peter Hollemans, when an image's scene time is "day", all pixels of the cloud mask use daytime cloud tests, and when it is "night", all pixels use nighttime cloud tests. When the scene time is "day/night", the decision of which tests to use is based on the solar zenith for that pixel.

According to Peter, for CoastWatch HDF files, pixels with a solar zenith > 80 degrees use the nighttime cloud tests, and <= 80 use the daytime cloud tests. This tool implements that logic. If you specify that cloud masking should be performed for a day/night image but no solar zenith image is available, this tool will assume that nighttime cloud tests were used for every pixel and a warning will be issued. For some reason, CoastWatch occasionally produces day/night images with no sun_zenith or other variables that are present in day images. My recollection is that Peter said it is safe to assume for these images that all pixels are nighttime.

The solar zenith image is ignored for scene times other than "day/night" (e.g. "day" or "night").

After some investigation, I find that the cloud mask pixels near the 80 degree solar zenith line are problematic, for two reasons:

• According to Peter, the solar zenith <= 80 cutoff line is not going to line up perfectly with the switch from daytime to nighttime cloud tests because the solar zenith angles are rounded to the nearest 0.01 when written to the HDF file so a few pixels with values of say 80.003 will get rounded to 80 even though they underwent processing with the nighttime cloud tests. Peter said, "I guess that's the flaw with storing angle data in HDF as scaled integers (that decision was mainly due to file size concerns)."
• The switch between daytime tests and nighttime tests does not manifest as a clean transition in the cloud mask pixels. The daytime pixels do not seem to cleanly abut the nighttime pixels. Rather, a strip of pixels with strange values raggedly separates the two. Peter said: "The apparent unclean transition between day and night tests is related to neighborhood functions. The uniformity tests use a 2x2 box of data values to the right and below a given value in the array to check for a condition being true, and the results of the uniformity test flag all pixels in the 2x2 box with the test results, regardless of whether all those pixels are day or nighttime. Both day and nighttime have uniformity tests, so the results of uniformity tests at the day/night boundary are mixed. The mixing is generally acceptable because the results are intended to be used for SST masking not cloud type evaluation and the mixing only occurs in cloudy conditions, not clear SST conditions."

Peter said he did not know what was done for CoastWatch day/night CWF files. I examined a few of these from the North East region, and it appeared that they also switched from daytime to nighttime cloud tests in the middle of the image. But the NOAA distribution site (http://www.class.noaa.gov) only appeared to have CWFs containing the sun_zenith variable for dates after late 1999.

Peter mentioned that the cwangles program from the CoastWatch Utilities could compute the solar zenith, but the values would only be approximate beacuse the program assumed that all pixels were obtained by the sensor at the same moment in time. I tried this approach but the 80 degree solar zenith line did not line up with the line where the cloud tests appeared to switch. Because of this, I do not believe that day/night CWF files will be useable for users who want to use some cloud tests and ignore others.

sunZenithVariable

Python type:	unicode or None
Default value:	u'sun_zenith'
Minimum length:	1

Name of the CoastWatch variable to extract from the solar zenith file and use as the solar zenith image (e.g. "sun_zenith").

useDayCloudTest1

Python type:	bool
Default value:	False

If True, daytime pixels that failed the CLAVR-1 Reflective Gross Cloud Test (bit 1 of the cloud mask) will be masked. If False, this cloud test will be ignored.

According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 test is used for both CWF and HDF files, but for HDF files, the CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.

This parameter is ignored for nighttime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useDayCloudTest2

Python type:	bool
Default value:	False

If True, daytime pixels that failed the CLAVR-1 Reflectance Uniformity Test (bit 2 of the cloud mask) will be masked. If False, this cloud test will be ignored.

According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 test is used for both CWF and HDF files, but for HDF files, the CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.

This parameter is ignored for nighttime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useDayCloudTest3

Python type:	bool
Default value:	False

If True, daytime pixels that failed the CLAVR-1 Reflectance Ratio Cloud Test (bit 3 of the cloud mask) will be masked. If False, this cloud test will be ignored.

According to CoastWatch researcher Peter Hollemans, the same CLAVR-1 test is used for both CWF and HDF files, but for HDF files, the CLAVR-x thresholds are used instead of than of the CLAVR-1 thresholds.

This parameter is ignored for nighttime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useDayCloudTest4

Python type:	bool
Default value:	False

If True, daytime pixels that failed the CLAVR-1 Channel 3 Albedo Test (bit 4 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for nighttime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useDayCloudTest5

Python type:	bool
Default value:	False

If True, daytime pixels that failed the CLAVR-1 Thermal Uniformity Test (bit 5 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for nighttime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useDayCloudTest6

Python type:	bool
Default value:	False

If True, daytime pixels that failed the CLAVR-1 Four Minus Five Test (bit 6 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for nighttime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useDayCloudTest7

Python type:	bool
Default value:	False

If True, daytime pixels that failed the CLAVR-1 Thermal Gross Cloud Test (bit 7 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for nighttime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

maskWhenDayCloudMaskExceeds

Python type:	int or None
Default value:	None
Minimum value:	0

If a value is provided, daytime pixels with a cloud mask value greater than this value will be masked.

The CoastWatch cloud mask is a bitmask, where each bit represents the success (0) or failure (1) of a given CLAVR cloud test. Thus the cloud mask values are NOT intended to be interpreted as range, like a spectrum, where 0 represents "very clear" and 255 represents "very cloudy". Nevertheless, some users of this tool determined that for their study the best tradeoff between minimizing SST error and minimizing the number of pixels masked by clouds was obtained by masking all pixels where the cloud mask exceeded a certain value. This option was implemented specifically for those users and is not recommended for general use. If you do use this option, be sure to study many cloud mask images before selecting a value.

If a value is provided both for this parameter and for the cloud test bits specified by the previous parameters, all of these parameters will be effective. In other words, a cloudy pixel can be masked by failing a specific cloud test, or by exceeding the minimum cloud mask value, or both. .

This parameter is ignored for nighttime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter. For more information about the cloud tests, please see the CoastWatch and CLAVR documentation.

useNightCloudTest1

Python type:	bool
Default value:	False

If True, nighttime pixels that failed the CLAVR-1 Thermal Gross Cloud Test (bit 1 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for daytime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useNightCloudTest2

Python type:	bool
Default value:	False

If True, nighttime pixels that failed the CLAVR-1 Thermal Uniformity Test (bit 2 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for daytime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useNightCloudTest3

Python type:	bool
Default value:	False

If True, nighttime pixels that failed the CLAVR-1 Uniform Low Stratus Test (bit 3 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for daytime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useNightCloudTest4

Python type:	bool
Default value:	False

If True, nighttime pixels that failed the CLAVR-1 Four Minus Five Test (bit 4 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for daytime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useNightCloudTest5

Python type:	bool
Default value:	False

If True, nighttime pixels that failed the CLAVR-1 Cirrus Test (bit 5 of the cloud mask) will be masked. If False, this cloud test will be ignored.

This parameter is ignored for daytime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useNightCloudTest6

Python type:	bool
Default value:	False

If True, nighttime pixels that failed the CLAVR-x Channel 3B Albedo Test (bit 6 of the cloud mask) will be masked. If False, this cloud test will be ignored.

According to CoastWatch researcher Peter Hollemans, this test was not used for CoastWatch CWF files and thus bit 6 will always be 0, indicating success, for CWF nighttime cloud mask pixels.

This parameter is ignored for daytime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

useNightCloudTest7

Python type:	bool
Default value:	False

If True, nighttime pixels that failed the CLAVR-x Channel 3B Albedo Uniformity Test (bit 7 of the cloud mask) will be masked. If False, this cloud test will be ignored.

According to CoastWatch researcher Peter Hollemans, this test was not used for CoastWatch CWF files and thus bit 7 will always be 0, indicating success, for CWF nighttime cloud mask pixels.

This parameter is ignored for daytime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter.

In CoastWatch cloud masks, bit 1 is the least significant bit, and a value of 0 for a bit indicates that the cloud test passed, while 1 indicates it failed. For more details about the cloud tests, please see the CoastWatch and CLAVR documentation.

maskWhenNightCloudMaskExceeds

Python type:	int or None
Default value:	None
Minimum value:	0

If a value is provided, nighttime pixels with a cloud mask value greater than this value will be masked.

The CoastWatch cloud mask is a bitmask, where each bit represents the success (0) or failure (1) of a given CLAVR cloud test. Thus the cloud mask values are NOT intended to be interpreted as range, like a spectrum, where 0 represents "very clear" and 255 represents "very cloudy". Nevertheless, some users of this tool determined that for their study the best tradeoff between minimizing SST error and minimizing the number of pixels masked by clouds was obtained by masking all pixels where the cloud mask exceeded a certain value. This option was implemented specifically for those users and is not recommended for general use. If you do use this option, be sure to study many cloud mask images before selecting a value.

If a value is provided both for this parameter and for the cloud test bits specified by the previous parameters, all of these parameters will be effective. In other words, a cloudy pixel can be masked by failing a specific cloud test, or by exceeding the minimum cloud mask value, or both. .

This parameter is ignored for daytime pixels. For a discussion of how pixels are classified as daytime or nighttime, please see the documentation for the cloud mask file parameter. For more information about the cloud tests, please see the CoastWatch and CLAVR documentation.

minCloudyNeighbors

Python type:	int or None
Default value:	None
Minimum value:	1

Minimum number of neighbors that a cloudy pixel must have in order for that pixel to be masked.

You can use this option to ignore isolated cloudy pixels that are not clumped together. For example, if you specify the value 1, cloudy pixels will be ignored and not used in the masking process unless at least one of their eight neighbors is also cloudy.

If a neighbor is not cloudy but it is masked for some other reason (e.g. it is land), it does not count as being cloudy.

This option is ignored when cloud masking is not performed.

medianFilterWindowSize

Python type:	int or None
Default value:	3
Minimum value:	3

Window size, in pixels, of the median filter to apply to the input image prior to running the histogram analysis step of the Cayula and Cornillon algorithm. If not provided, median filtering will not be performed.

If you provide a value, it must be an odd integer greater than or equal to 3. The filter window is square and advances across the image 1 pixel at a time. The center pixel, if it is not masked, is replaced with the median value of the non-masked pixels in the surrounding window. All masks are applied before the median filter is executed.

Median filtering is a traditional first step for certain classes of edge detection algorithms. The original Cayula and Cornillon paper used a window size of 3.

histogramWindowSize

Python type:	int
Default value:	32
Minimum value:	8

Size of the histogram window to use for the Cayula and Cornillon algorithm.

The window is square. The original paper used a window size of 32. Although the algorithm is claimed to obtain similar results regardless of window size, I have noticed that some fronts may only be detected by using a smaller window size such as 16. I highly recommend you read the paper carefully before experimenting with different window sizes.

histogramWindowStride

Python type:	int
Default value:	16
Minimum value:	1

Number of pixels to move the histogram window after each iteration of the Cayula and Cornillon algorithm.

The original paper used a 32x32 window and a stride of 16, to minimize the CPU time required to execute the algorithm. Cutting the stride in half increases the CPU time by a factor of about four. For example, a stride of 1 requires about 256 times more CPU time than a stride of 16.

In my experience, smaller stride values identify more fronts, and the resulting fronts are longer and thicker. If you have a powerful computer, want to find more fronts, and are comfortable deviating from the published method, you can use a smaller value. If you do this, I highly recommend you use the Thin Fronts option (under Front Cleanup Options) to thin the fronts back to one pixel wide.

minPropNonMaskedCells

Python type:	float
Default value:	0.65
Minimum value:	0.0

Minimum proportion of pixels in a histogram window that must not be masked for the algorithm to proceed with histogram analysis on that window.

For example, if the value 0.75 is used and the histogram window is 20x20, at least 300 out of the 400 pixels must not be masked for analysis to proceed on that window. If more than 100 pixels are masked, the algorithm discards the current window, advances to next one, and starts over.

The original Ratfor code I obtained from Dave Ullman used the value 0.65.

minPopProp

Python type:	float
Default value:	0.25
Minimum value:	0.0

Minimum proportional size of the smaller population.

If the histogram algorithm determines that the values of the non-masked pixels in the window have a bimodal distribution, it then selects the value that optimally separates them into two populations. As described on page 73 of the Cayula and Cornillon 1992 paper, if the proportion of non-masked pixels allocated to the smaller population is smaller than 0.25, the subsequent statistical tests will not be accurate. In this case, and the algorithm discards the current window, advances to next one, and starts over.

I do not recommend selecting a value other than 0.25 unless you understand the statistical analysis presented in the 1992 paper.

minTheta

Python type:	float
Default value:	0.76
Minimum value:	0.0

Minimum criterion function, theta(Topt), as described on pages 71-72 of the 1992 paper.

The criterion function is used to determine whether the histogram window contains a bimodal distribution, as would be expected if it encloses portions of two distinct water masses separated by a front. If the window yields a value less than this parameter--i.e. it is not sufficiently bimodal--the algorithm discards the current window, advances to next one, and starts over.

Cayula and Cornillon performed an extensive analysis to determine that the value 0.76 produced optimal results for the SST data they worked with. Selecting a smaller value allows windows with more homogenous, less bimodal distributions to be accpted by the algorithm. That will allow more "curvy" fronts to be identified, at the risk of misclassifying cloudy regions as fronts.

I do not recommend selecting a value other than 0.76 unless you understand the statistics presented in the original paper.

minSinglePopCohesion

Python type:	float
Default value:	0.9
Minimum value:	0.0

Minimum cohesion of a single population.

If the histogram window is found to have a sufficiently bimodal distribution of values, the cohesion algorithm is executed to check whether the pixels of the two populations are sufficiently spatially separated. High values indicate that they are separated, suggesting that two distinct populations (water masses) are present in the window. Low values indicate the populations are all mixed up, like a checkerboard, and suggest that the pattern results from clouds, noise or other random processes.

The first part of the cohesion algorithm checks the cohesion of each population by itself (equations 19 and 20 in the 1992 paper). As described in Appendix B of the 1992 paper, the optimal cohesion coefficients depend on the size of the histogram window. Cayula and Cornillon used the value 0.90 for their 32x32 window, which was calculated:

C = 1.0 - 0.02 - 1/winsize - 2*P(error) = 0.98 - 1/32 - 2(0.025) = 0.90

For a 16x16 window, the equation evaluates to 0.8675.

minGlobalPopCohesion

Python type:	float
Default value:	0.92
Minimum value:	0.0

Minimum cohesion of both populations.

The second part of the cohesion algorithm checks the cohesion of both populations together (equation 21 in the 1992 paper). As described in Appendix B of the 1992 paper, the optimal cohesion coefficients depend on the size of the histogram window. Cayula and Cornillon used the value 0.92 for their 32x32 window, which was calculated:

C = 1.0 - 1/winsize - 2*P(error) = 1.0 - 1/32 - 2(0.025) = 0.92

For a 16x16 window, the equation evaluates to 0.8875.

threads

Python type:	int
Default value:	1
Minimum value:	1

Number of threads to start for parallel processing.

The histogram and cohesion algorithms are CPU intensive but are designed to run in parallel on machines that have multiple processors. To maximize utilization of your machine's processors and shorten the time required to execute the algorithms, set the number of threads to the number of processors you wish to utilize. Do not set the number of threads to more than the number of processors you have; this will reduce performance.

outputMaskRasterList

Python type:	list of unicode or None, or None
Default value:	None
Minimum length:	0

List of output rasters to create that show the pixels of the input images that were masked prior to executing the Cayula and Cornillon algorithm.

Each raster will contain 8-bit integers and have the same dimensions as the input image. The value 1 indicates that the corresponding pixel of the input image was masked; 0 indicates the pixel was not masked.

outputFilteredImageRasterList

Python type:	list of unicode or None, or None
Default value:	None
Minimum length:	0

List of output rasters to create that show the median-filtered input images.

Each raster will have the same data type and dimensions as the input image (usually 16-bit signed integers). Non-masked pixels will have the median value of the non-masked cells in the surrounding window (the center pixel is included in the median selection). Masked pixels will be marked as NoData.

outputCandidateCountsRasterList

Python type:	list of unicode or None, or None
Default value:	None
Minimum length:	0

List of output rasters to create that indicate how many times the corresponding pixels of the input images were candidates for containing fronts, i.e. the number of times the pixels appeared in histogram windows that had a sufficiently large number of non-masked pixels to proceed with the histogramming step of the Cayula and Cornillon algorithm.

Each raster will contain 16-bit signed integers and have the same dimensions as the input image. Because the histogram window stride is typically less than the window size, successive histogram windows typically overlap, causing many non-masked pixels to have candidate counts greater than 1. Masked pixels can never be candidates for containing a front and will be marked as NoData.

outputFrontCountsRasterList

Python type:	list of unicode or None, or None
Default value:	None
Minimum length:	0

List of output rasters to create that indicate how many times fronts were detected at the corresponding pixels of the input images.

Each raster will contain 16-bit signed integers and have the same dimensions as the input image. The value will range from 0 (the input image pixel never contained a front) to the candidate count value for the pixel (it always contained a front in every histogram window that contained it). Masked pixels can never be candidates for containing a front and will be marked as NoData.

outputWindowStatusCodesRasterList

Python type:	list of unicode or None, or None
Default value:	None
Minimum length:	0

List of output rasters to create that indicate the result of the algorithm for the histogram window centered on the pixel. You can use this image to diagnose why the algorithm did not find fronts in your input images.

Each raster will contain 8-bit signed integers and have the same dimensions as the input image. The pixel values will be one of these code numbers:

• Code 0 - The algorithm was not executed for the window because the histogram window stride was greater than 1, causing the algorithm to skip over this window.
• Code 1 - The proportion of the window's pixels that had data was found to be too small. This typically occurs when the window occurs in a region where many of the pixels are masked due to land, clouds, or insufficient satellite coverage.
• Code 2 - After the histogram algorithm optimally separated the window's pixels into two populations, the proportion of pixels allocated to the smaller population was found to be too small. This can occur when a front occurs in the window, but the window is not centered on the front, causing it to contain a disproportionate number of pixels from one population. This is usually not a problem. As long as the histogram window stride is sufficiently small, the histogram window will eventually pass over the front and proceed to the next step of the algorithm.
• Code 3 - After the histogram algorithm optimally separated the window's pixels into two populations, the difference between the mean values of the two populations was found to be too small. This typically happens when the window does not contain a front or when the gradient along the front is small (i.e. it is a weak front).
• Code 4 - After the histogram algorithm optimally separated the window's pixels into two populations, the criterion function that was calculated was found to be too small (the criterion function is theta(Topt) described on pages 71-72 of the 1992 paper). This means that the two populations are not sufficiently bimodal to indicate that a front exists in the window.
• Code 5 - The window was found to have two populations that were sufficiently proportional, different in their means, and bimodal, but the cohesion of one or the other population was insufficient (as described by equations 19 and 20 in the 1992 paper). This indicates that the pixels of the two populations are spatially intermixed like a checkerboard, rather than being spatially separate, as occurs when a front is present.
• Code 6 - The window was found to have two populations that were sufficiently proportional, different in their means, and bimodal, and each population was found to be sufficiently cohesive, but the cohesion of the two populations together was insufficient (as described by equation 21 of the 1992 paper). As with code 5, this indicates that the pixels of the two populations are spatially intermixed like a checkerboard, rather than being spatially separate, as occurs when a front is present.
• Code 7 - The window passed all of the algorithm's tests and was classified as containing a front.

When the width and height of histogram window is an even number, the center pixel is the one to the lower right of the exact center of the window, which falls at the intersection of four pixels. For example, in a 6x6 window, the center pixel is the fourth from the left and fourth from the top.

outputWindowStatusValuesRasterList

Python type:	list of unicode or None, or None
Default value:	None
Minimum length:	0

List of output rasters to create that you can use in conjunction with the window status codes when diagnosing the results of the algorithm.

Each raster will contain 32-bit floating point numbers and have the same dimensions as the input image. The value of each pixel depends on the window status code for that pixel:

• Codes 0, 1, 7 - The pixel value is always 0.0.
• Code 2 - The pixel value is the proportion of the window's pixels that were allocated to the smaller population.
• Code 3 - The pixel value is the difference in the mean values of the window's two populations.
• Code 4 - The pixel value is the criterion function that was calculated for the window.
• Code 5 - The pixel value is the cohesion of the window's population that was found to be insufficiently cohesive. If both populations were insufficiently cohesive, it is the cohesion of the "cold" population.
• Code 6 - The pixel value is the cohesion of the window's two populations together.

By examining the pixel values, you can determine how to adjust the algorithm's parameters to cause more or fewer windows to pass the algorithm's tests, increasing or decreasing the number of fronts identified in the image. You should only adjust the parameters if you feel comfortable deviating from their published values.

projectedCoordinateSystem

Python type:	unicode or None
Default value:	None
Minimum length:	1

New coordinate system to project the raster to.

The raster may only be projected to a new coordinate system if the original projection is defined. An error will be raised if you specify a new coordinate system without defining the original coordinate system.

The ArcGIS Project Raster tool is used to perform the projection. The documentation for that tool recommends that you also specify a cell size for the new coordinate system.

I have noticed that for certain coordinate systems the ArcGIS 9.2 Project Raster tool seems to clip the projected raster to an arbitrary extent that is too small. For example, when projecting a global MODIS Aqua 4 km chlorophyll image in geographic coordinates to Lambert_Azimuthal_Equal_Area with central meridian of -60 and latitude of origin of -63, the resulting image is clipped to show only one-quarter of the planet. This problem does not occur when Project Raster is invoked interactively from the ArcGIS user interface; it only occurs when the tool is invoked programmatically (the ProjectRaster_management method of the geoprocessor). Thus you may not see it when you use Project Raster yourself but it may happen when you use MGET tools that invoke Project Raster as part of their geoprocessing operations.

If you encounter this problem, you can work around it like this:

• First, run this tool without specifying a new coordinate system, to obtain the raster in the original coordinate system.
• In ArcCatalog, use the Project Raster tool to project the raster to the new coordinate system. Verify that the entire raster is present, that it has not been clipped to an extent that is too small.
• In ArcCatalog, look up the extent of the projected raster by right-clicking on it in the catalog tree, selecting Properties, and scrolling down to Extent.
• Now, before running the MGET tool that projects the raster, set the Extent environment setting to the values you looked up. If you are invoking the MGET tool interactively from ArcCatalog or ArcMap, click the Environments button on the tool's dialog box, open General Settings, change the Extent drop-down to "As Specified Below", and type in the values you looked up. If you're invoking it from a geoprocessing model, right-click on the tool in the model, select Make Variable, From Environment, General Settings, Extent. This will place Extent as a variable in your model, attached to the MGET tool. Open the Extent variable, change it to "As Specified Below" and type in the values you looked up. If you're invoking the MGET tool programmatically, you must set the Extent property of the geoprocessor to the values you looked up. Please see the ArcGIS documentation for more information about this and Environment settings in general.
• Run the MGET tool. The extent of the raster should now be the proper size.

geographicTransformation

Python type:	unicode or None
Default value:	None
Minimum length:	1

A transformation method used to convert between the original coordinate system and the new coordinate system.

This parameter is a new option introduced by ArcGIS 9.2. You must have ArcGIS 9.2 to use this parameter.

This parameter is only needed when you specify that the raster should be projected to a new coordinate system and that new system uses a different datum than the original coordinate system, or there is some other difference between the two coordinate systems that requires a transformation. To determine if a transformation is needed, I recommend the following procedure:

• First, run this tool without specifying a new coordinate system, to obtain the raster in the original coordinate system.
• Next, use the ArcGIS 9.2 Project Raster tool on the raster to project it to the desired coordinate system. If a geographic transformation is needed, that tool will prompt you for one. Write down the exact name of the transformation you used.
• Finally, if a transformation was needed, type in the exact name into this tool, rerun it, and verify that the raster was projected as you desired.

resamplingTechnique

Python type:	unicode or None
Default value:	None
Allowed values:	u'NEAREST', u'BILINEAR', u'CUBIC'

The resampling algorithm to be used to project the original raster to a new coordinate system. The ArcGIS Project Raster tool is used to perform the projection and accepts the following values:

• NEAREST - nearest neighbor interpolation
• BILINEAR - bilinear interpolation
• CUBIC - cubic convolution

You must specify one of these algorithms to project to a new coordinate system. An error will be raised if you specify a new coordinate system without selecting an algorithm.

projectedCellSize

Python type:	float or None
Default value:	None

The cell size of the projected coordinate system. Although this parameter is optional, to receive the best results, the ArcGIS documentation recommends you always specify it when projecting to a new coordinate system.

registrationPoint

Python type:	unicode or None
Default value:	None
Minimum length:	1
Must match regular expression:	([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)

The x and y coordinates (in the output space) used for pixel alignment.

This parameter is a new option introduced by ArcGIS 9.2. You must have ArcGIS 9.2 to use this parameter. It is ignored if you do not specify that the raster should be projected to a new coordinate system.

clippingRectangle

Python type:	unicode or None
Default value:	None
Minimum length:	1
Must match regular expression:	([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)\s+([-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)

Rectangle to which the raster should be clipped.

If a projected coordinate system was specified, the clipping is performed after the projection and the rectangle's coordinates should be specified in the new coordinate system. If no projected coordinate system was specified, the coordinates should be specified in the original coordinate system.

The ArcGIS Clip tool is used to perfom the clip. The clipping rectangle must be passed to this tool as a string of four numbers separated by spaces. The ArcGIS user interface automatically formats the string properly; when invoking this tool from the ArcGIS UI, you need not worry about the format. But when invoking it programmatically, take care to provide a properly-formatted string. The numbers are ordered LEFT, BOTTOM, RIGHT, TOP. For example, if the raster is in a geographic coordinate system, it may be clipped to 10 W, 15 S, 20 E, and 25 N with the string:

10 15 20 25

Integers or decimal numbers may be provided.

buildPyramids

Python type:	bool
Default value:	False

If True, pyramids will be built for the raster, which will improve its display speed in the ArcGIS user interface.

skipExisting

Python type:	bool
Default value:	False

If True, conversion will be skipped for output rasters that already exist.

overwriteExisting

Python type:	bool
Default value:	False

If True and skipExisting is False, existing output rasters will be overwritten.

basePath

Python type:	unicode or None
Default value:	None
Minimum length:	1
Maximum length:	255
Must exist:	No

Base path to prepend to relative paths.

If any of the input paths (or output paths, if this method has outputs) contained in the lists are relative paths, they will be converted to absolute paths prior to processing, as follows:

• If a base path is provided, it will be prepended to the relative path.
• Otherwise, if the ArcGIS geoprocessor has been initialized and the geoprocessing workspace has been set (i.e. the Workspace property of the geoprocessor is not empty), it will be prepended to the relative path.
• Otherwise, the current working directory for the executing process will be prepended to the path. If you have not explicitly changed the working directory, it is usually the directory that contains the Python interpreter (e.g., on Windows computers, it would be C:Python24, if you're running Python 2.4).

---

GeoEco Python Reference

Previous: FindFrontsAsArcGISRastersArcGISTable Method Up: CoastWatchAVHRR Class Next: FindFrontsAsArcGISRastersTable Method

---

Marine Geospatial Ecology Tools version 0.8