User's Guide

MERGEFOUR

Seamlessly merge a two-by-two array of overlapping images

Function:

MERGEFOUR uses linear weighting functions to seamlessly merge a two-by-two array of overlapping images which typically represent the northwest, northeast, southwest, and southeast quandrants of a region of interest. There is no restriction on the number of overlapping lines or samples between adjacent images. However, gaps between the edges of adjacent images are not permitted, and to insure a smooth transition between images which have different relative brightness in the overlap region, there should be a sizeable overlap region which is contained within all four images.

The output image window is determined automatically from the input image windows. MERGEFOUR permits the northwest and northeast images to have different top and/or bottom edges, and similarly for the southwest and southeast images. The same is true of the left and right edges of the northwest/southwest pair and the northeast/southeast pair. However, where the outside edges of the inputs are different, the output image window is reduced to the largest rectangle which contains only pixels which fall within at least one input window.

The program divides the output image space into separate regions for each combination of one, two, three, or four overlapping inputs; some regions, including all those which are not rectangular, are further subdivided for convenience in data processing. Within each overlap region, the corresponding pixels of the overlapping images are weighted separately in the x and y directions in proportion to their distance from the edge of the image.

MERGEFOUR can be also be used to seamlessly join two images which overlap vertically, a capability not currently supported by the OVEROPT="AVER" parameter of program CONCAT -- see Example 2.

Parameters:

IN
Names of the four input images. The images (or their specified spatial windows) must contain at least one pixel in common, and have the same map projection and projection parameters, the same pixel spacing, and the same rotational orientation. Each input image may be a "logical" image which concatenates bands from more than one image file (e.g., "IN(1)=alpha+beta+gamma").

OUT
Output image. The name of the output image created by merging the four input images.

ODTYPE("SAME" VALID=("SAME","BYTE","I*2","I*4","R*4")
Output data type. Allowed values are

    "SAME"	Output data type is same as data type of (first) input.
    "BYTE"	8-bit unsigned integers.  Range is 0 to 255.
    "I*2"	16-bit signed integers.  Range is -32768 to +32767.
    "I*4"	32-bit signed integers.  Approximate range is -2 billion
		to +2 billion.
    "R*4"	Signed 32-bit floating point values.  Range is
		approximately -3.4E38 to +3.4E38, with smallest
		magnitude 1.1E-38 and a precision of 7 significant
		digits.
NOTE that all data are converted to 64-bit floating point (R*8) prior to applying the weights. If the requested output format is BYTE, I*2, or I*4, the floating-point results are rounded to the nearest integer before being written to the output image.

Examples:

  1. LAS> mergefour in="(nw, ne, sw, se)" out=merged

    The four images NW, NE, SW, and SE which overlap along their edges are merged to create an output image named MERGED.

  2. LAS> mergefour in="(upper, upper, lower, lower)" out=all

    The image UPPER is merged with image LOWER, whose upper edge overlaps the lower edge of UPPER. Although averaging is actually done in both the x and y directions, only the y averaging produces pixel values which may be different from the input pixels; the x-direction averaging of pixels from the two occurrences of UPPER in the horizontal direction has no effect on the pixel values, since it merely averages two identical values at each pixel position, and the same is true for the two occurrences of LOWER.

    This example shows how to overcome a deficiency in CONCAT, which permits averaging overlapping inputs only in the x direction, using OVEROPT="AVER".

Description/Algorithm:

The program assumes that each of the four images to be merged can overlap each of the other images in a pattern such as that shown below:

       _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
      |				 _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _
      |				|     |				|
      |				|     |				|
      |				|     |				|
      |				|     |				|
      |		     NW		|     |				|
      |				|     |		NE		|
      |				|     |				|
      |				|     |				|
      |	 _ _ _ _ _ _ _ _ _ _ _ _|_ _ _|_			|
      | |			|  _ _|_|_ _ _ _ _ _ _ _ _ _ _ _|_
      | |			| |   | |			| |
      |_|_ _ _ _ _ _ _ _ _ _ _ _|_|_ _| |			| |
	|			|_|_ _ _|_ _ _ _ _ _ _ _ _ _ _ _| |
	|			  |	|			  |
	|			  |	|			  |
	|	      SW	  |	|			  |
	|			  |	|	 SE		  |
	|			  |	|			  |
	|			  |	|			  |
	|			  |	|			  |
	|			  |	|			  |
	|_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _|			  |
				  |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|

After obtaining the program arguments from the TAE interface, MERGEFOUR reads the input image DDRs to determine the coordinates of the edges of each input window. The program then examines the input image windows to identify the NW, NE, SW, and SE inputs. The top of the output window coincides with the lower of the top edges of the NW/NE pair, and the left edge of the output coincides with the rightmost of the left edges of the NW/SW pair. The other two output edges are defined similarly from the SW/SE pair and NE/SE pair, with values adjusted to make the image dimensions integer multiples of the pixel spacing. For the configuration in the diagram above, the output window is bounded by the top and right edges of the NE input and the left and bottom edges of the SW input. The program then determines the position of all edges of each input image relative to this output window; if the distances from the upper left corner of the output window to the upper left corner of an input image are not integer multiples of the pixel spacing, they are rounded to the nearest values which are.

MERGEFOUR then breaks the image into overlap regions by first determining the line and sample positions at which a particular combination of overlapping images may end. These positions are the last line and last sample of each input, and one line or sample before the first line and sample of each input. The program then sorts the region-ending line and sample positions, uses the line positions to define the start and end of succesive rows of overlap regions, and uses the sample positions to determine the start and end of each region in each row. This procedure results, in general, in some adjacent regions which have an identical set of overlapping inputs, and may also result in regions of zero height or width which are ignored in subsequent processing. The redundant regions do, however, simplify the computation of weights.

Each region is then examined to determine which input image windows contain it and the line and sample distances from the edges of each input image window to the upper left and lower right corners of the region. For each corner of the region, the program uses these distances as the relative x- and y-weights to be used for merging the images. To provide for a seamless transition from one region to the next, the y-weights are set equal for two images in the same row (NW/NE or SW/SE) at a region corner which is not on the left or right edge of either image; similarly, the x-weights are set for two images in the same column (NW/SW or NE/SE) at a corner which not on the top or bottom edge of either image. The program then computes the product of x-weights and y-weights for each contributing input image and normalizes them to total one. For each input image, the normalized weight at each corner of the region is used to compute the coefficients of a bilinear interpolating function of the form

	w(x,y) = a + bx + cy + dxy
where x and y are the offsets in pixels and lines from the upper left corner of the region.

After opening the input and output images, MERGEFOUR carries out the actual merging by creating one output line at a time. For each overlap region which contains the output line, each output pixel value is computed as the sum of the pixel values for each contributing input image times their respective weights. The program writes each output line as it is completed, and then closes all files after the last line is written.

  1. [mergefour-geoloc] Geographic coordinates for input XXXX window don't match those for YYYY

    The projection code, pixel spacing, or projection coordinates at the upper left window corners of the specified image files, which are components of the same "logical" input image, do not match. Processing continues; the projection and geolocation information for the output image are flagged as "INVALID".

  2. [mergefour-geoloc] Invalid projection data preclude verifying geographic registstration for XXXX and YYYY

    At least one of the input files for a "logical" input image has the "INVALID" flag set for projection information. The projection coordinates cannot be used to check that the input windows are in registration. Processing continues; the projection and geolocation information for the output image are flagged as "INVALID".

  3. [mergefour-projver] Invalid projection data in DDR preclude verifying that projections are same for all inputs

    At least one of the input images has the projection code flagged as "INVALID". The program cannot verify that all inputs are in the same projection. Processing continues assuming that they are, but the projection code for the output image is flagged as "INVALID".

  4. [mergefour-noupbdr] Unable to update output BDDR

    An error occurred while reading or writing the band-dependent data desriptor records for the output image. The BDRs may not correctly reflect minimum and maximum values.

  5. [mergefour-noupddr] Unable to update output DDR

    An error occurred while writing an updated descriptor record for the output image. The DDR may not contain correct georeferencing and projection information.

Fatal Error Messages:

  1. [mergefour-fatal] Fatal error encountered

    A fatal error occurred, which is described by the preceding error message(s).

  2. [mergefour-malloc] Memory allocation error

    An error occurred while allocating memory for temporary arrays or buffers. This may occur if the input images have a very large number of samples per line and a large number of bands, in which case it may be necessary to do the processing a few bands at a time. Otherwise, check whether other processes are using large amounts of memory.

  3. [mergefour-diffwin] Images in logical image have different window sizes

    An input image was specified as a "logical" image, consisting of more than one actual image file, and the constituent images were or different sizes or had different size windows specified for them. Adjust the window specifications so they are all the same.

  4. [mergefour-difband] Input images have different number of bands

    Each of the four input images must have the same number of bands. Explicitly specify the bands for each input to make the number of bands the same for each input.

  5. [mergefour-difproj] Inputs XXXX and YYYY are in different projections

    The two input images have different projection codes. Their upper left corner coordinates cannot be used to determine their relative positions in the output image.

  6. [mergefour-difunit] Inputs XXXX and YYYY use different projection units

    The two input images have different projection units. Their upper left corner coordinates cannot be used to determine their relative positions in the output image.

  7. [mergefour-invcorn] Input XXXX does not have valid entry for grid spacing or corner coords

    The grid spacing or corner coordinate information for the specified input image is flagged as "INVALID". Its upper left corner coordinates cannot be used to determine its relative position in the output image.

  8. [mergefour-difgrid] Inputs XXXX and YYYY have different grid spacings

    The two input images have different grid spacings. MERGEFOUR cannot merge them. One input must first be resampled to match the projection and grid spacing of the other.

  9. [mergefour-locate] Cannot assign inputs to NW, NE, SW, SE locations

    The four input images overlap in a complex pattern such that the upper and lower pairs or righthand and lefthand pairs cannot be clearly differentiated. Check input window specifications.

  10. [mergefour-inwind] Input window specification for XXXX extends outside image

    The window computed to fit the specified input image into the output image frame is invalid. The program has probably failed to correctly assign the four input images to the NW, NE, SW, and SE positions. Check the input image windows to see that their relative positions can be unambiguously determined.

User Note:

  1. If the input image DDRs specify that the projection code is valid, MERGEFOUR checks that all inputs have the same projection code, but does not check that datum codes and projection parameters are the same.