User's Guide

FILLGAPS

Fill gaps in image by interpolation from neighbors

Function:

FILLGAPS attempts to replace each pixel located in a gap in the input image by linear interpolation from its non-gap nearest neighbors. Gap pixels are defined as those having the value specified by argument GAPVAL in the mask band specified by arguments MASKIMG and MASKBAND. By default, the first band of the input image is used as the mask band.

The interpolation procedure determines the distances between the centers of the two nearest non-gap neighbors located on either side of the gap pixel on the horizontal, vertical, and both diagonal lines passing through the pixel; for the diagonal lines, the distance between adjacent pixels is taken to be the square root of 2. The line for which the separation of the nearest non-gap pixels is least will be used for the interpolation. If the non-gap pixel separation is greater than the maximum specified by argument MAXGAP, the gap pixel is left unchanged. If the distance between the two nearest non-gap neighbors is the same for lines running in two or more directions, the mean of the values obtained for each such line will be averaged.

If the gap pixel is on the edge of the input image (or is part of a block of gap pixels which extends to the image edge) and the EDGEOPT argument is "NN", the distance to the nearest non-gap pixel in any direction is determined. If this distance is less than the distance to the closest non-gap pixel on the best potential interpolation line as defined above and not greater than 0.5 times the MAXGAP value, the gap is filled with the value of the nearest non-gap pixel. When the input window does not extend to the edge of the input image, an attempt will be made to apply the normal interpolation algorithm using input pixels outside the specified window.

The program reports the number of pixels filled, the number left unfilled, the maximum distance between nieghbors used for interpolation, and, if edge pixels were filled, the maximum distance to the nearest neighbor used for edge-pixel filling.

Parameters:

IN
Name of input image. May be a logical image set.

OUT
Name of output image.

GAPVAL(0.0)
Value which indicates gap pixel. Any pixel of the mask band (specified by arguments MASKIMG and MASKBAND) which has this value is assumed to be a gap pixel, to be filled using the values of non-gap neighbors. Default is 0.0.

MAXGAP(2.9)

Maximum distance between non-gap pixels used to replace gap value. If the distances between the nearest non-gap pixels on opposite sides of the gap pixel on the horizontal, vertical, and diagonal lines passing through the gap pixel all exceed this value, then the value of the gap pixel will be left unchanged.

The default value of 2.9 will cause gaps to be filled if their minimum dimension is 1 pixel, since the distance between nearest neighbors along a diagonal is 2.83. This means that a 1-pixel wide horizontal, vertical, or diagonal gap will be filled, but not a wider gap. To prevent filling gaps using diagonal nearest neighbors, set MAXGAP = 2.

For example, in the patterns of gap pixels shown below, in which non-gap pixels are denoted by "+" and gap pixels by upper-case letters, the value MAXGAP = 2.0 will permit filling pixels A-C, E-G, H-K, L, and S using horizontal and vertical nearest neighbors. Using the default value of 2.9 will permit also filling D, M-R, T, U, X, and Y using diagonal nearest neighbors. A value of 3.0 or greater will cause pixels V and W to be filled.


        + + + + + +     + + + + + +     + + + + + + +     + + + +
	+ A B C D +     + H + + + +     + L M + + + +     + T U +
	+ + + + E +     + + I + + +     + + N O + + +     + V W +
	+ + + + F +     + + + J + +     + + + P Q + +     + X Y +
	+ + + + G +     + + + + K +     + + + + R S +     + + + +
	+ + + + + +     + + + + + +     + + + + + + +

ODTYPE("SAME" VALID=("SAME","BYTE","I*2","I*4","R*4")
Data type for output image. Options are:


    SAME    Output has same data type as input (Default)
    BYTE    Output data type is byte
    I*2	    Output data type is two-byte integer.
    I*4	    Output data type is four-byte integer.
    R*4	    Output data type is four-byte real.
When interpolation results in a non-integer value, it will be rounded to the nearest integer unless the output data type is real. Fractions of exactly 0.5 will be rounded upwards.

EDGEOPT("LEAVE" VALID=("LEAVE","NN")
Flag specifying how to handle gap pixels at edge of image. A gap pixel is considered to be an edge pixel if it is at the edge of the image or part of a block of gap pixels which extends to the edge. Options are:


    LEAVE   Do not fill an edge pixel unless it can be filled in the
	    normal way using non-gap pixels on either side of it along a
	    horizontal, vertical, or diagonal line through the edge
	    pixel.  (Default)
    NN	    Fill edge pixels using the value of the nearest non-gap
	    pixel if both (a) the distance to the nearest neighbor is
	    less than the distance to the nearest non-gap pixel that
	    would be used for regular interpolation and (b) the distance
	    to the nearest neighbor is less than 0.5 times the value of
	    MAXGAP.  If there are two or more nearest neighbors at the
	    same distance, the mean of their values will be used.

MASKIMG(--)
Name of image used to define gap pixels. Default is the input image (or first image in a logical image set) specified by INPUT.

MASKBAND(--)
Band to be used to define gap pixels. The particular band of the image specified by MASKIMG which contains a value equal to that specified by GAPVAL for each pixel which is to be filled, if possible, by interpolation from non-gap neighbors. The non-gap pixels in the mask band may have arbitrary values so long as they do not equal GAPVAL. Default is the first band of MASKIMG, if it is specified, or the first input band, otherwise.

Examples:

  1. LAS> fillgaps in=merged_dem out=filled_dem edgeopt=leave

    A digital elevation image created by concatenating several smaller DEMs is found to have 1-pixel wide gaps along some of the boundaries of the smaller DEMs. The default value of MAXGAP will cause 1-pixel wide gaps to be filled. However, the setting of the EDGEOPT argument specifies that gaps along the outside edges of the merged DEM are not to be filled using the adjacent non-gap pixels

Description/Algorithm:

FILLGAPS begins by reading the program arguments. If any input windows are less than the full image size, the windows are extended outwards, if possible, by MAXGAP - 1 lines and pixels. FILLGAPS then allocates buffers to hold MAXGAP + 1 lines for each input band.

After opening the input and output files and reading in all available lines needed to fill potential gaps in the first output line, FILLGAPS processes one output line at a time. The value of the mask image is compared to the mask value for each pixel on the line. If the mask is set, FILLGAPS determines the distances to the nearest non-gap pixels in each direction, horizontal, vertical, and diagonal, and finds the direction(s) having the minimum gap. If the gap is less than the maximum allowed gap, the gap pixel is replaced by linear interpolation between the non-gap pixel values, unless the gap pixel is at the edge of the image, in which case a check is made to see whether a single neighboring pixel should be used instead. The counters of either filled or unfillable pixels are incremented depending on whether the gap pixel was successfully replaced. After each line has been processed, the (possibly updated) line is written to output and the additional input data needed for processing the next line are read in.

When all lines have been processed, FILLGAPS closes the files, updates output minimum/maximum values and history as needed, reports on the number of pixels filled and the maximum gap size used, and writes a program completion message.

Nonfatal Error Messages:

  1. [fillgaps-upddr] Unable to update output DDR

    The attempt to use input image projection and georeferencing information to create the corresponing fields in the output image DDR failed. See LAS system manager.

  2. (etc.) !.FATALS Fatal Error Messages:

  3. [fillgaps-fatal] Fatal error encountered

    An error occurred which forced FILLGAPS to terminate processing. The nature of the error is specified in the preceeding message(s).

  4. [fillgaps-alloc] Error allocating memory

    FILLGAPS was unable to allocate all the memory needed for temporary storage. The total memory needed is roughly proportional to the size of argument MAXGAP, the number of samples per line, and the number of bands. If these are all large, it may be necessary to subdivide the image into smaller spatial or spectral windows.

  5. [fillgaps-diffwin] Mismatched input windows

    The separate image files which comprise the logical input have different dimensions or different spatial windows specified for them. FILLGAPS requires all spatial windows to be the same. Check the file sizes and adjust the window specifications.

  6. [fillgaps-maskwind] Mask window differs from input window

    The spatial windows for the mask image and the input image are not the same. FILLGAPS requires they be the same. Check the input file sizes and adjust the window specifications.

  7. [fillgaps-readerr] Error reading input needed for output line XXX

    An error occurred while reading from the input or mask image file(s). Check whether the file has become corrupted.

  8. [fillgaps-ocopy] Error copying/converting from input to output buffer

    An error occurred while copying the input data to the output buffer, perhaps while converting the data type. This is probably a software or system error. Notify the LAS system manager.

  9. [fillgaps-maskconv] Error converting mask pixel value

    An error occurred while converting the data type of a mask pixel before comparing it to the GAPVAL argument. This is probably a software or system error. Notify the LAS system manager.

  10. [fillgaps-pxlconv] Error converting pixel value

    An error occurred while converting the data type of an input image pixel while computing an output fill value. This is probably a software or system error. Notify the LAS system manager.

User Notes:

    None.