User's Guide

CONCAT

Sequentially concatenate and/or overlay a list of input images.

Function:

Creates an output image (OUT) by overlaying each input image (IN) into OUT, or updates the first input image by overlaying the other input images on the first image if OUT is made NULL. The MASKVAL and OVEROPT parameters are also dimensioned according to the number of input images specified by the user in IN. MASKVAL is the sample value ,or range in each input image that represents masked areas. When overlapping of images occurs, OVEROPT allows the user to select which image has preference.

Parameters:

Subcommand -MANUAL:
Enter starting line and sample manually. The starting line and sample of each of the input images is manually entered.

IN
Input images. The list of input images to be concatenated and/or overlaid into OUT. The input image(s) may contain BYTE, INTEGER*2, INTEGER*4, or REAL*4 data. Window and band options may be specified. The number of bands must be the same for each element of IN. Each IN specification may contain up to ten images. Except in update mode when IN(1) must be equal to one.

OUT
Output image. The output data type will be the maximum data type of the input images. The size of the output image is determined by the values of NL and NS. The number of bands is determined by the number of bands in each element of IN. If OUT is made NULL, update mode will be assumed and any value specified in NL and NS will be ignored.

SL
Starting line. Describes the line where the input image is to be positioned on the output image (OUT). SL must contain the same number of values as specified by IN. However, in update mode SL may contain one less value, the value that corresponds to the first image may be omitted, and the first SL value will then apply to second image.

SS
Starting sample. Describes the sample where the input image is to be positioned on the output image (OUT). SS must contain the same number of values as specified by IN. However, in update mode SS may contain one less value, the value that corresponds to the first image may be omitted, and the first SL value will then apply to second image.

NL
Number of lines. The number of lines desired in the output image. If OUT is NULL, NL must either be set to a value that will be ignored or set to NULL. In this case, the number of lines will be set to the size of the first image specified by IN.

NS
Number of samples. The number of samples desired in the output image. If OUT is NULL, NS must either be set to a value that will be ignored or set to NULL. In this case, the number of samples will be set to the size of the first image specified by IN.

MASKVAL("0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0", "0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0", "0","0","0","0","0","0","0","0","0","0","0","0","0","0")
Mask value. The value(s) used to designate masked areas or areas of bad data. Samples with this value are not used in the calculations. MASKVAL must contain the same number of values as specified by IN. However, in update mode MASKVAL may contain one less value, the value that corresponds to the first image may be omitted, and the first MASKVAL value will then apply to second image. This value is input as REAL*4 data and is converted as necessary to the data type of the output image. This parameter may be entered as a range if it is entered like "20 30".

The MASKVAL(1) value is used to specify the fill value in the output image.

OVEROPT(REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC)
Overlap option. Describes how overlay areas are handled, i.e., which image has preference if the images overlap. OVEROPT must contain the same number of values as specified by IN. However, in update mode OVEROPT may contain one less value, the value that corresponds to the first image may be omitted, and the first SL value will then apply to second image.

  = LEAVE:   Leave the value of the current output 
             image.  This option uses the value of 
             the input image only when the sample 
             value of the current output image is 
             MASKVAL.
  = REPLAC:  Replace the value of the current output 
             image.  This option uses the value of 
             the current output image only when the 
             sample value of the input image is MASKVAL.
  = AVER:    Average the overlap values.  The average
	     value is calculated based upon the distance
	     from the edge of each image.  Thus, at the
	     center of the overlap 50 percent of each
	     image value is added together to make the
	     new value.
Subcommand -AUTO:
Use the calculated line and sample. The starting line and sample of each of the input images is calculated from the projection coordinates which are stored in each of the input DDR files. This subcommand will not run correctly unless all the input images have VALID projection coordinates, which means that at least the upper left corner must be specified along with the number of lines and samples, and the projection distance.

IN
Input images. The list of input images to be concatenated and/or overlaid into OUT. The input image(s) may contain BYTE, INTEGER*2, INTEGER*4, or REAL*4 data. Window and band options may be specified. The number of bands must be the same for each element of IN. Each IN specification may contain up to ten images. Except in update mode when IN(1) must be equal to one.

OUT
Output image. The output data type will be the maximum data type of the input images. The size of the output image will be determined by the values of OUTSIZE or by the lower right corners of the input images. The number of bands is determined by the number of bands in each element of IN. If OUT is made NULL, update mode will be assumed.

ULCOORS(--)
Upper-left coordinates. The coordinates of the upper-left corner of the output image in projection units. If defaulted, the upper-left corner is calculated from the upper-left corners of the input image(s).

OUTSIZE(--)
Output image size. The size of the output image in projection units. The first value should be the size in the line direction and the second value should be the size in the sample direction. If defaulted, the output size is calculated from the lower-right corners of the input image(s)

MASKVAL("0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0", "0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0","0", "0","0","0","0","0","0","0","0","0","0","0","0","0","0")
Mask value. The value(s) used to designate masked areas or areas of bad data. Samples with this value are not used in the calculations. MASKVAL must contain the same number of values as specified by IN. However, in update mode MASKVAL may contain one less value, the value that corresponds to the first image may be omitted, and the first MASKVAL value will then apply to second image. This value is input as REAL*4 data and is converted as necessary to the data type of the output image. This parameter may be entered as a range if it is entered like "20 30".

The MASKVAL(1) value is used to specify the fill value in the output image.

OVEROPT(REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC,REPLAC, REPLAC,REPLAC)
Overlap option. Describes how overlay areas are handled, i.e., which image has preference if the images overlap. OVEROPT must contain the same number of values as specified by IN. However, in update mode OVEROPT may contain one less value, the value that corresponds to the first image may be omitted, and the first SL value will then apply to second image.

  = LEAVE:   Leave the value of the current output 
             image.  This option uses the value of 
             the input image only when the sample 
             value of the current output image is 
             MASKVAL.
  = REPLAC:  Replace the value of the current output 
             image.  This option uses the value of 
             the current output image only when the 
             sample value of the input image is MASKVAL.
  = AVER:    Average the overlap values.  The average
	     value is calculated based upon the distance
	     from the edge of each image.  Thus, at the
	     center of the overlap 50 percent of each
	     image value is added together to make the
	     new value.

Examples:

  1. LAS> concat-manual in=inset out=bordered sl=11 ss=11 nl=50 ns=50 maskval=0.0 overopt=replac

    This example creates a ten-sample border around the image INSET in the output image BORDERED.

  2. LAS> concat-manual in=(one two three four five) out=new sl=(1 1 11 31 21) ss=(1 11 1 26 6) nl=50 ns=50 maskval=(0.0 0.0 0.0 0.0 0.0) overopt=(replac replac replac replac replac)

    This example overlays five input images of various sizes into the output image NEW.

  3. LAS> concat-auto in=(one two) out=out ulcoors=(1000,1000) outsize=(500,500) maskval=(0.0 0.0) overopt=(replac replac)

    This example concatenates two 3-band images into the multi-band output image OUT. The upper-left corner of the output image begins at the projection coordinates of 1000,1000 and the lower-right corner of the output image is at the projection coordinates of 1490,1490. The projection distance is (10,10).

    NOTE: Images ONE and TWO have the same upper-left corner coordinates.

  4. LAS> concat-manual in=(one two three) out=new sl=260,340,60 ss=230,60,60 nl=440 ns=440 maskval=(0.0 0.0 0.0) overopt=(replac replac leave)

    This example concatenates three single-band images together. Image ONE is placed into the output image first at location 260, 230. Image TWO consists of two grey scales and is placed into the output image next at location 340, 60. Because OVEROPT(2) is set to REPLAC, the pixel values of image TWO will replace the pixel values of image ONE except where the pixels of image TWO have values equal to MASKVAL. It is assumed that the pixels between the two grey scales have values equal to MASKVAL. Image THREE is placed into the output image at location 60, 60. Because OVEROPT(3) is set to LEAVE, the pixel values of image THREE will NOT replace the pixel values of image ONE within the overlap area of images ONE and THREE. The output image will be 440 by 440.

Description/Algorithm:

SUBCOMMAND -MANUAL

The program begins with the standard initialization and retrieval of user-specified parameters. The data type of the output image is set by determining the maximum data type of the input images. If an output image is requested, the output image is opened to the specified dimensions (NL and NS parameters) and padded with the first MASKVAL value. If OUT is made NULL, the first input image is assumed to be the output image and is opened for update mode. The input images are then sequentially overlaid into the output image according to the appropriate values in the SL and SS parameters. The output image is closed and reopened for update after each image has been overlaid. After the output image is completed, a second pass is made if the min and max values of each band were requested. An associated history file is created for the output image and a completion message is output.

SUBCOMMAND -AUTO

The program begins with the standard initialization and retrieval of user-specified parameters. The data type of the output image is set by determining the maximum data type of the input images. Each of the input DDR files are read and valid flag of the corner projection coordinates are checked. If any of the flags are not VALID, an error message will be output and the processing will be terminated. The upper-left corner values of each input image are compared to determine which image will be placed in the upper-left corner of the output image if ULCOORS has been defaulted. Otherwise, the values of the parameter ULCOORS will be used as the upper-left corner of the output image. The starting line and sample location of each input image within the output image is then calculated. The size of the output image is calculated from the the values of the parameter OUTSIZE or the lower-right corners of the input images if defaulted. If an output image is specified, the whole image is then padded with the first MASKVAL value. If OUT is made NULL, the first input image is assumed to be the output image and is opened for update mode. The parameter OUTSIZE will then be considered as the number of lines and samples which will be updated. The input images are then sequentially overlaid into the output image according to the calculated projection values in the input DDR file. The output image is closed and reopened for update after each image has been overlaid. After the output image is completed, a second pass is made if the min and max values of each band were requested. An associated history file is created for the output image and a completion message is output.

Nonfatal Error Message:

  1. [concat-close] Error closing files

    An error was encountered while trying to close a file. Contact system manager when this error occurs.

  2. [concat-warn] Nonfatal error encountered

    A nonfatal error was encountered during processing. The image data is probably valid and is therefore saved. The message that is displayed immediately preceding this message is the specific error that was encountered from a library routine. Processing continues.

Fatal Error Messages:

  1. [concat-alloc] Error allocating dynamic memory

    An error occurred while trying to dynamically allocate buffer space.

  2. [concat-ddr] Error reading DDR file

    The DDR file for the specified image either does not exist or is not in the correct format. Create a new DDR file.

  3. [concat-fatal] Fatal error encountered

    A fatal error was encountered during processing. The error message that is displayed immediately preceding this message is the specific error that was encountered.

  4. [concat-invalid] Corner projection <XXXXXX>'s of image <XX> are invalid

    The projection <XXXXXX> validity flag of image <XX> was found to be invalid. The starting line and sample location of this image cannot be automatically calculated. Use the -MANUAL subcommand or place valid <XXXXXX>'s in the DDR of image <XX>.

  5. [concat-lname] Error calculating LAS name

    There was an error calculating the LAS name from the specified host name. Check the syntax of the input names.

  6. [concat-location] Starting <XXXX> location is outside output image

    The <XXXX> location exceeds the specified bounds of the image. Change the value of <XXXX> accordingly and rerun the program.

  7. [concat-maskval] Mask value is not in range of output image

    The mask value specified is not valid for the data type of the output image. Change the value of MASKVAL accordingly and rerun the program.

  8. [concat-nbands] IN entries do not have the same number of bands

    The number of bands in each element of IN must be the same. Remove or replace the incorrect input images and rerun the program.

  9. [concat-pdist] The projection distance of <XXXXXX> does not equal the projection distance of the other input images

    The projection distance of <XXXXX> is not the same as the distance of the other input images. The starting line and sample of these images cannot be automatically calculated. Use the -MANUAL subcommand.

  10. {concat-size] NL and NS must be specified

    NL and NS must be specified if an output file is to be created. Specify a value for NL and NS.

  11. [concat-tolerance] The projection coordinates of <XXXXX> are not within tolerance of the other input images

    The projection coordinates of <XXXXX> are not within the tolerance of the other input images that make up one logical image. All images that are used to form one logical image have to have the corner projection coordinates within the specified tolerance. Increase the tolerance or use an image with corner coordinates that are within tolerance of the other images.

  12. [concat-unequal] The number of values specified for IN and <XXX> are not equal

    The same number of values must be entered for IN and the specified parameter. Enter the appropriate number of values and rerun the program.

  13. [concat-window] Images do not have same window size

    If more than one image is specified in an IN entry, then the window size of each image in that entry must be the same. Change the window specification and rerun the program.

  14. [concat-zone] UTM zones are not the same

    If the projection is UTM, the images must be in the same zone. Make sure that the images should be concatenated.

User Note:

  1. Any input images exceeding the bounds of the output image are reset to the output image bounds.