User's Guide

SPREAD

Generates buffer zones around target pixels in an image

Function:

Generates buffer zones of contour distances or mask values around target pixels in an image. Subcommand -DIST creates an output image whose buffer zones contain the distances of the original image pixels from the nearest target pixel in the input image. Subcommand -MASK generates an output image whose buffer zones contain mask values surrounding the target pixels in the input image.

Parameters:

Subcommand -DIST:
Replaces image pixel values with their distance to the nearest target pixel. For each pixel in an image, SPREAD-DIST searches within the specified radial and angular limits for the nearest pixel in the specified target class. If a target pixel is found, the original pixel's value is replaced with its distance (in pixels) to that target pixel. If no target pixels are found within the specified angular and radial limits, the original pixel's value is replaced by the specified background value.

This function results in distance contours being generated around the target class of interest. If a full 360 degree search is specified, target areas are completely surrounded. If a limited direction search is specified, target areas generate "wedges."

IN
Input image. The image may be a BYTE, INTEGER*2, or INTEGER*4 image. Window and/or band options may be specified. For each pixel in this image, SPREAD searches for the nearest target pixel that falls within the user-specified radial and angular limits.

OUT
Output image. The name of the output image. It will be a BYTE image containing the same number of bands as specified in IN. Each pixel in this image is assigned either a distance value or the BACKGRND value.

PIXVAL
Pixel value. The pixel value being searched for. In the output image, distance contours will be generated around the locations where these pixels occurred so that these areas will have appeared to "spread out."

SRCHRAD
Search radius. The maximum radius, measured in pixels, that the program will consider while searching for a target pixel. Specifying a search radius of more than 16 pixels is not permitted. Searching more than 16 pixels can be accomplished through repeated runs of SPREAD-DIST and alternating with appropriate runs of RENUMBER.

BEGANG(0)
Beginning angle. The beginning angle for a distance search in a particular direction. It is measured in degrees clockwise from "north," i.e., the top of the image. Restricted angular searches generate "pie wedges" rather than disks around target areas. BEGANG can range from 0 to 359 degrees.

NDEGREES(360)
Number of degrees. The number of degrees to search in a clockwise direction. Restricted angular searches generate "pie wedges" rather than disks around target areas.

BACKGRND(0)
Background value. The background value to which pixels in the output image will be assigned if no target pixels were found within the user-specified radial and angular limits.
Subcommand -MASK:
Creates masked areas in an image around all target pixels. For each pixel in an image, SPREAD-MASK generates a buffer around each pixel in the specified target class. If a target pixel is found, the original pixel values surrounding the target pixel are replaced with the MASKVAL value. Original pixel values that do not fall within the radial limits are replaced with the BACKGRND value.

This function results in a mask buffer being generated around each target class of interest.

IN
Input image. The image may be a BYTE, INTEGER*2, or INTEGER*4 image. Window and/or band options may be specified. SPREAD generates a buffer of width SRCHRAD around each pixel in this image that is the value of PIXVAL.

OUT
Output image. The name of the output image. It will be a BYTE image containing the same number of bands as specified in IN. Each pixel in this image is assigned either the MASKVAL value or the BACKGRND value.

PIXVAL
Pixel values. The pixel values being searched for. In the output image, pixels that are up to SRCHRAD distance away from PIXVAL are assigned the MASKVAL value.

SRCHRAD
Search radius. The maximum radius of the buffer zone, measured in pixels, that the program will generate around the target pixels. Specifying a search radius of more than 80 pixels is not permitted. Searching more than 80 pixels can be accomplished through repeated runs of SPREAD-MASK alternating with appropriate runs of RENUMBER. A value must be entered for each value specified in PIXVAL unless the same radius is desired for all target pixels; then a single SRCHRAD value may be used.

QUADNUM(0)
Quadrant numbers. The quadrants to be processed for a user-specified angular search. The quadrants are set up in a Cartesian coordinate system, with each quadrant consisting of 90 degree "pie wedges." The following combinations may be specified: all four quadrants, one of any four quadrants, two of any four quadrants, three of any four quadrants, or quadrant "0" (zero) which causes all four quadrants to be processed and is the default value. A "0" specification supersedes all others in any combination. 


               ____________________________
              |             |              |
              |             |              |
              | Quadrant 2  |  Quadrant 1  |
              |             |              |
              |             |              |
              |----------------------------|
              |             |              |
              |             |              |
              | Quadrant 3  |   Quadrant 4 |
              |             |              |
              |_____________|______________|


VALID QUADRANT SPECIFICATIONS 
_____________________________

1 or 2 or 3 or 4 (each a 90 degree wedge)
Any combination of two consecutive (180 degree wedge)
Any combination of two adjacent (left or right diagonal)
Any combination of three quadrants (270 degree wedge)
A "0" in combination or alone (360 degree wedge)

MASKVAL(1)
Mask value. The value assigned to the output image pixels that fall within the SPREAD buffer zone.

BACKGRND(0)
Background value. The value assigned to the output image pixels that do not fall within the SPREAD buffer zone.

Examples:

  1. LAS> spread-dist in=land.class out=land.class.dist pixval=4 srchrad=10 backgrnd=99

    The program generates image LAND.CLASS.DIST in which each pixel has a value equal to its distance to the nearest target pixel with a value of 4 in the input image LAND.CLASS, provided there was such a pixel within a distance of 10. All other pixels in the output image are given the value of 99.

  2. LAS> spread-dist in=land.class out=land.class.wedge pixval=99 srchrad=8 begang=270 ndegrees=180

    The program creates the output image LAND.CLASS.WEDGE in which each pixel has a value equal to its distance to the nearest target pixel with a value of 99 in the input image LAND.CLASS, provided there was such a pixel within a distance of 8 and to its north. All other pixels in the output image are given the value of 0. The BEGANG is 270 and NDEGREES is 180, setting the search area to the north.

  3. LAS> spread-mask in=river out=river.mask pixval=50 srchrad=3 maskval=200 backgrnd=100

    The output image RIVER.MASK is created and contains the value of 200 for all pixels that fall within a 3 pixel radius of pixels with the value 50 in the input image. All other pixels in the output image contain the value of 100.

  4. LAS> spread-mask in=river out=river.spread.mask pixval=(100 110 120) srchrad=5

    The output image RIVER.SPREAD.MASK is created and contains the value of 1 for all pixels that fall within a 5 pixel radius of pixels with the value of 100, 110, or 120 in the input image. All other pixels in the output image contain the value of 0.

  5. LAS> spread-mask in=river out=river.spread.mask pixval=100 srchrad=3 quadnum=(1,4) backgrnd=255

    The output image RIVER.SPREAD.MASK is created and contains the value of 1 for pixels that fall within a 3 pixel radius of pixels with the value 100. The QUADNUM specification of (1,4) indicates that a search area of 0 to 180 degrees will be used. All other pixels in the output image will contain the value 255.

Description/Algorithm:

SPREAD-DIST: The algorithm searches concentrically outward from each pixel using a precomputed address table (either circular or wedged) until a target pixel is encountered. The outward-spiraling concentric search pattern guarantees there are no closer target pixels than the first one found. Images are scanned from left to right. If a target pixel is encountered at a distance D from a given pixel P, then the search from the pixel immediately to P's right need not test for target points closer than distance D-1 due to the triangular inequality.

SPREAD-MASK: The algorithm processes the image line by line, sample by sample, generating entries in run-end encoded arrays. For each input image pixel that contains the target value, an entry is made in the arrays showing its location and mask value. Entries are updated to include this pixel in any other pixel entries for the current line being processed, for all lines to the north of (above) the current line that are within the buffer radius, and for all lines to the south of (below) the current line that are within the buffer radius. When the input image has been processed completely, the output image is generated according to the entries in the run-end encoded arrays. Run-end encoding is a compressed raster data structure that stores a code along with the sample number of the last sample using that code.

Nonfatal Error Messages:

    None.

Fatal Error Messages:

  1. [spread-dtype] Type of the input image must not be REAL

    SPREAD does not allow the input image to be a REAL*4 image. Convert the input image and rerun the program.

  2. [spread-match] Number of pixel values and radius values does not match

    For SPREAD-MASK, an entry must be made in the SRCHRAD parameter for each entry in the PIXVAL parameter, or SRCHRAD must contain only one entry. Correct the number of values in SRCHRAD and rerun the program.

  3. [spread-pxval] Pixval out of range for the input data type

    The values to be searched for in the input image must not exceed the range of the data type of the input image. Correct the values in the PIXVAL parameter and rerun the program.

  4. [spread-getrec] Internal array size exceeded

    For SPREAD-MASK, the number of entries required to process the input image(s) exceeds the dimension of the run-end encoded arrays in the program. Apply windows to the image and run the program as many times as needed to generate the full size output image, or contact the LAS system manager for assistance.

User Notes:

  1. Searching for more pixels than the SRCHRAD limit allows may be accomplished through repeated runs of SPREAD followed with appropriate runs of RENUMBER.

  2. Times can vary greatly depending on input parameters and the subcommand used. Times for the -DIST subcommand can be reduced substantially if an angular range is specified, thereby generating "pie wedges". Times for the -MASK subcommand increase dramatically when multiple PIXVALs are specified. Similarly, times for both subcommands increase considerably when the SRCHRAD value becomes large and/or multiple bands are used. Finally, the use of the QUADNUM specification in the -MASK subcommand has no noticeable effect on execution time nor does the input data type on either subcommand.