IMERGE

Description

IMERGE automatically merges a set of geocoded images or digital elevation model (DEM) files into a single image or DEM file. You can, optionally, specify a different projection for the output data.

Parameters

imerge(mfile, filo, dboc, project, zone, row, ellips, llbound, ulx, uly, lrx, lry, bxpxsz, bypxsz, backval, resample, tfile, ftype, foptions)

Name	Type	Caption	Length	Value range
MFILE	str	Input file name, directory, or text file	0 - 191
FILO	str	Output file name	0 - 192
DBOC	List[int]	Output raster channel	0 - 1
PROJECT	str	Output projection	0 - 16	LONG/LAT, SPAF, SPCS, SPIF, UPS, UTM
ZONE	List[int]	Output projection zone number	0 - 1
ROW	str	Output projection row	0 - 1	A - Z
ELLIPS	str	Output ellipsoid or datum code	0 - 64
LLBOUND	str	Boundary coordinates are longitude/latitude	0 - 1	Y, N Default: Y
ULX	str	Upper-left X coordinate of output image	0 - 32
ULY	str	Upper-left Y coordinate of output image	0 - 32
LRX	str	Lower-right X coordinate of output image	0 - 32
LRY	str	Lower-right Y coordinate of output image	0 - 32
BXPXSZ	str	Horizontal pixel size	0 - 32
BYPXSZ	str	Vertical pixel size	0 - 32
BACKVAL	List[float]	Background value	0 - 1
RESAMPLE	str	Resampling method	0 - 5	NEAR, BILIN, CUBIC Default: NEAR
TFILE	str	Text file name	0 - 191
FTYPE	str	Output file type	0 - 3	Default: PIX
FOPTIONS	str	Output file options	0 - 191

Parameter descriptions

MFILE

Specifies a directory name, an image file name, or a text file name containing the input images to be processed. Wildcards (*) can be used.

MFILE can be set using any of the following options:

A specific data file name or directory path and file name (for example, "irvine.pix" or "c:\data\irvine.pix").
A specific file name pattern or all of the files in a folder (for example, "c:\data\*.pix" or "c:\data").
An existing text file that contains references to multiple files with, optionally, different parameter settings on a per file basis (for example, "c:\list.txt").

If the text file option is used, the following general rules apply:

Specify a .txt extension for the file containing multiple files and different parameter values.
List each set of parameters on its own line in the given order (see below).
Specify string parameters within quotation marks.
Do not specify numeric parameters within quotation marks.
A quotation mark preceded by a backslash is used as part of the string. For example, "ab\"c" is used as: ab"c.
Use an exclamation mark (!) before writing a comment in the text file.
Use semi-colons to delimit the parameters.
Leave the position between the semi-colons empty (";;") if you do not want to specify a value. Alternatively, if there are no remaining parameters to be specified on the end of a line, you may leave it blank.
Parameters in a text file may or may not be specified in the function:
- If a parameter is specified in the function and in the text file, the value provided in the text file is used.
- If a parameter is not specified in the text file, the parameter can be set in the function.

FILO

Specifies the name of the output file to receive the merged image data. If not specified, no output file is created or processed.

DBOC

Specifies the output channel to receive the merged image data. The default value is 1; if DBOC (Output) does not exist, IMERGE adds a new channel and automatically sets the value of DBOC (Output) to the index of the newly created channel.

PROJECT

Specifies the projection of the output file. If not specified, uses the map projection from the input files.

Supported projections include:

LONG/LAT: Longitude and Latitude
SPAF: State Plane (US Feet)
SPCS: State Plane (Meters)
SPIF: State Plane (International Feet)
UPS: Universal Polar Stereographic
UTM: Universal Transverse Mercator

ZONE

If the projection is equal to UTM or State Plane, specifies the zone number of the output projection; otherwise, this parameter is not used.

ROW

If the projection is equal to UTM or UPS, specifies the row number for the projection; otherwise, this parameter is not used.

Acceptable values for this parameter are A through Z.

ELLIPS

Specifies the output ellipsoid or datum code to use to define the shape of the Earth. If defaulted, the earth model from the input files is used.

For a detailed list of supported ellipsoids, see the Projections reference section.

LLBOUND

Specifies whether the bounds are longitude and latitude coordinates. If they are, set this parameter as Y or y (for YES). This is the default value.

If they are projection meters or feet, set as N or n.

ULX

Specifies the X (horizontal) bound of the upper left corner of the output image. If not specified, the minimum X coordinate from the input files is used.

ULY

Specifies the Y (vertical) bound of the upper left corner of the output image. If not specified, the maximum Y coordinate from the input files is used.

LRX

Specifies the X (horizontal bound of the lower right corner of the output image. If not specified, the maximum X coordinate from the input files is used.

LRY

Specifies the Y (vertical) bound of the lower right corner of the output image. If not specified, the minimum Y coordinate from the input files is used.

BXPXSZ

Specifies the horizontal pixel size of the output image. If defaulted, uses the minimum horizontal pixel size from the input files.

BYPXSZ

Specifies the vertical pixel size of the output image. If defaulted, uses the minimum vertical pixel size from the input files.

BACKVAL

Specifies the background value of the input image channel.

Pixels having the specified background value are interpreted as non-image values and are not transferred to the output file; this ensures that the output image contains only valid data from the input images.

If defaulted, the background value is zero (0).

RESAMPLE

Specifies the resampling method to use for the output image.

Supported resampling methods include:

Nearest Neighbor: identifies the gray level of the pixel closest to the specified input coordinates and assigns that value to the output coordinates. This is the default value
Bilinear Interpolation: determines the gray level from the weighted average of the four closest pixels to the specified input coordinates and assigns that value to the output coordinates.
Cubic Convolution: determines the gray level from the weighted average of the 16 closest pixels to the specified input coordinates and assigns that value to the output coordinates.

TFILE

Specifies the name of the text file containing information for merging the input files. If this parameter is not specified, no text file is read from or written to. If this parameter is specified and exists, the steps in the file are used when IMERGE is run, and the steps followed are recorded in the file before IMERGE exits. In addition to acting as a processing log for IMERGE, this parameter is a means of controlling IMERGE.

The text file specified by TFILE consists of several records. Each record starts with the record identifier of four or more characters. (Any characters after the fourth character are not used, but may be present. The characters may be lower- or upper-case.) Other fields on the record are separated by one or more spaces. Commas may also be used as field separators. Each record may be up to 132 characters and is terminated by the Return key (or the Enter key).

The order of the FILE records specifies the order of processing, but the order of any other records in the text file does not matter. Any LONG/LAT values are specified either as degrees, minutes, seconds, and hemisphere, with no spaces or commas separating the subfields, or as decimal degrees.

The TFILE records are as follows:

PROJECT: The output units derived from the PROJECT (Projection for Output Merged Layer), ZONE (Projection Zone), ROW (Projection Row), and ELLIPS (Earth Model) parameters are combined and stored as a 16-character string. For example:
```
"PROJ UTM    11 S E000"
 
```
ULX, ULY, LRX, LRY: The bounds for the output image are expressed as upper-left X, upper-left Y, lower-right X, and lower-right Y. For example:
```
"ULX  100000.0"
"ULY  5000000.0"
"LRX  300000.0"
"LRY  4900000.0"
```
BXPXSZ, BYPXSZ: The output image pixel size is expressed as the X (horizontal) and the Y (vertical) size. For example:
```
"BXPX 1000.0"
"BYPX 1000.0"
```
BACKVAL: The background value to which the output image is initialized. For example:
```
"BACK 0.000000"
```
RESAMPLE: The resampling method options are Nearest Neighbor (NEAR), Bilinear Interpolation (BILI), or Cubic Convolution (CUBIC). For example:
```
"RESA NEAR"
```
OTYPE: The output channel type, where 1 is CHN_8U, 2 is CHN_16S, 3 is CHN_16U, and 4 is CHN_32R. For example:
```
"OTYP 1"
```
Input CHANNEL and FILE to merge: The files are merged in the order in which they are read in the text file. For example, the following merges channel 1 and then channel 2 from file_a and then channel 1 from file_b. It does not matter whether the CHAN field (and channel number) is specified before the FILE field (and file name) or vice versa. File names are assumed to be prefixed by their full path name.
```
"CHAN 1 FILE file_a"
"CHAN 2 FILE file_a"
"FILE file_b CHAN 1"
```
The output BOUNDS and PSIZE are assumed to be in the PROJUNITS. For example, if PROJUNITS is set to "LONG/LAT", the bounds and pixel size are either in degrees, minutes, seconds, hemisphere, or in decimal degrees.
```
PROJ LONG/LAT    E000
ULX  117d45'00.00"W
ULY   33d45'00.00"N
LRX  117d30'00.00"W
LRY   33d30'00.00"N
BXPX   0d00'01.00"
BYPX   0d00'01.00"
BACK 0.000000
RESA NEAR
OTYP 1
CHAN 1 FILE ifiles~/longlat.pix
```
If PROJUNITS is set to "UTM zone" the bounds are in UTM E. and N. and the pixel size in UTM meters. For example:
```
PROJ UTM    11 S E000
ULX   100000.0
ULY  5000000.0
LRX   300000.0
LRY  4900000.0
BXPX 1000.0
BYPX 1000.0
BACK 0.000000
RESA NEAR
OTYP 1
CHAN 1 FILE file_a
CHAN 1 FILE file_b
 
```

FTYPE

Specifies the file format type of the output file. This is the abbreviated code for the file format, as listed in the Generic Database (GDB) Format Reference. Some examples of supported formats include:

PIX: PCISDK format (default)
TIF: Tagged Image File Format
XWD: X Window Dump

Note: IMERGE does not support all GDB formats.

FOPTIONS

Specifies the options for creating the output file. These are specific to the file format, and in each case a no-option default is allowed. FOPTIONS can be used to specify the compression schemes, file format subtype, or other information.

For example, FOPTIONS="LZW", which means to use a Lempel-Ziv Welch compression.

Details

IMERGE automatically merges a set of geocoded images or digital elevation model (DEM) files into a single image or DEM file. This function is most commonly used to merge DEM files.

If MFILE is a text file, the files and parameters listed in the text file are used. For IMERGE, the parameters in the text file must be delimited by semi-colons.

The area of interest to use for the output image can be specified (ULX, ULY, LRX, LRY); otherwise, the maximum bounds of the input image files are used.

LLBOUND specifies whether ULX, ULY, LRX, and LRY are longitude and latitude values (LLBOUND="Y") or output projection units (LLBOUND="N").

The pixel resolution for the output image can be specified (BXPXSZ, BYPXSZ); otherwise, the minimum pixel resolution from the input files is used.

If ELLIPS is defined, it takes precedence over any ellipsoid defined in the PROJECT parameter.

Example

Merge the DEM files to form a single DEM output file.

from pci.imerge import imerge

mfile    = "*.pix"
filo     = "single_dem.tif"
dboc     = []  #output to new created tif file channel 1
project  = ""  # "LONG/LAT" from the input files
zone     = []  # Only used if project is "UTM" or "SPCS"
row      = ""  # Only used if project is "UTM" or "UPS"
ellips   = ""  # "E008" from the input files
llbound  = ""  # Default is "Y"
ulx      = ""  # Default is minimum X of input files
uly      = ""  # Default is maximum Y of input files
lrx      = ""  # Default is maximum X of input files
lry      = ""  # Default is minimum Y of input files
bxpxsz   = ""  # Default is smallest X size of input files
bypxsz   = ""  # Default is smallest Y size of input files
backval  = []  # Default is 0.0
resample = ""  # Default is "NEAR"
tfile    = ""  # Default is do not read from or write to tfile
ftype    = "TIF"  #Output to TIFF File
foptions = ""

imerge( mfile, filo, dboc, project, zone, row, ellips,
llbound, ulx, uly, lrx, lry, bxpxsz, bypxsz,
backval, resample, tfile ,ftype, foptions)

Environments	PYTHON :: EASI :: MODELER
Quick links	Description :: Parameters :: Parameter descriptions :: Details :: Example