AUTOGCP

Name	Type	Caption	Length	Value range
MFILE *	String	Input file name, directory, or text file	1 - 192
DBIC	Integer	Input raw image channel(s)	0 -
SRCBGD	String	Source background value	0 - 192	Default: FILE
MMSEG	Integer	Math model segment number	0 - 1
LOCLMASK	String	Local exclusion mask	0 - 192	Default: NONE
DBGC	Integer	GCP segment	0 - 1
FILREF *	String	Input reference image file name	1 - 192
DBIC_REF	Integer	Reference image channel(s)	0 -	Default: 1
FILEDEM	String	Input DEM file or directory	0 - 192
DBEC	Integer	Elevation channel	0 - 1	Default: 1
BACKELEV	Float	Background elevation value	0 - 1
ELEVREF	String	Vertical reference for elevation values	0 - 192
ELEVUNIT	String	Units of elevation values	0 - 7	METER \| FEET \| US_FEET
ELFACTOR	Float	Elevation offset and scale	0 - 2
SMPLSRC	String	Sample point source	0 - 192	SUSAN \| GRID \| DBREF Default: GRID:64
ALGO	String	Matching algorithm	0 - 192	FFTP \| NCC Default: FFTP
SEARCHR	Integer	Search radius	0 - 1	1 - Default: 100
SEARCHUN	String	Search radius units	0 - 7	PIXEL \| METER \| FEET \| US_FEET Default: PIXEL
MINSCORE	Float	Minimum acceptance score	0 - 1	0.0 - 1.0 Default: 0.75
PROC	String	Processing algorithm	0 - 192
NUMGCPS	Integer	Total number of GCPs collected	0 - 1	0 -
REPORT	String	Report mode	0 - 192	Quick links

Parameter descriptions

MFILE

Specifies the name of a folder, image file, or text file that contains the input images to be processed. Since the input file(s) will be updated to store the collected GCPs, they must be PCIDSK files. 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". Each line has the following format:
- Filename;Channel List;Source Background;Math Model Segment;Output GCP Segment

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.
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.

For details about the MFILE text file format, see the Details section.

If MFILE does not specify the list of channels to process, the DBIC (Input Channels) parameter is used.

When specifying file channels, individual channels or channel sequences may be specified. An individual channel index is a single positive integer (for example, "1"). A channel sequence is a positive integer followed by a comma and a negative number (for example, "1,-3"). In this example, "1,-3" means to process channels 1 through 3 inclusive; it is internally expanded to "1,2,3". The second channel number in the sequence must be larger than the first channel number.

If MFILE does not specify the source background specification, the SRCBGD parameter is used.

If MFILE does not specify the math model segment number, the MMSEG parameter is used.

If MFILE does not specify the output GCP segment, the DBGC parameter is used.

DBIC

Specifies the channel(s) in the raw image file from which to extract the GCP samples. Multiple channels are averaged together.

If DBIC is specified in a text file (MFILE), this parameter is ignored.

If this parameter is not specified, all channels are processed by default.

Ranges of channels or segments can be specified with negative values. For example, {1,-4,10} is internally expanded to {1,2,3,4,10}. When you are not specifying a range in this way, only 48 numbers can be specified explicitly.

SRCBGD

Specifies which pixels in the source image are to be considered as background (NoData) pixels. In general, if a pixel is considered NoData, the application handles the pixel in a special manner.

Available options are:

FILE: reads the NoData value from the input file's NO_DATA_VALUE metadata. The file-level metadata tag is used as the default for every channel; channel-level tags, when available, override the default. When metadata does not exist, every pixel in the input is considered valid.
0: every pixel, in every channel, having a value of 0 is considered NoData
NONE: every pixel, in every channel, is considered valid
<value>: every pixel, in every channel, having the specified value is considered NoData.
FILE [, <value>]: same as FILE, but defines the NoData value for every channel, when metadata does not exist.

For example, the default "FILE, 0" specifies that the function uses metadata. If the metadata is unavailable, pixels that have a value of 0 are considered NoData>.

Note: To specify multiple values, use a comma-delimited list. The first value is applied to the first channel, the second value to the second channel, and so on. If fewer values are specified than the number of input channels, the last value is repeated for all remaining channels. If more values are specified than the number of input channels, the extra values are ignored.

MMSEG

Specifies the number of the segment in the input file that contains the math model that will be used to transform coordinates between the input and reference images. If this parameter is not specified, the function uses the highest-numbered math model segment that exists in the input file.

A special value of 0 instructs the function to use an affine math model based on the nominal georeferencing of the raw image.

A special value of -1 instructs the function to do the matching in pixel space exclusively; any and all georeferencing is ignored, meaning that the first pixel in the input image is assumed to correspond to the first pixel in the reference image. This method may be useful when trying to correct band-to-band misregistrations.

Note: If a segment other than 0 is specified but does not exist in the input file, this function raises an exception.

LOCLMASK

Specify whether to apply a local mask to prevent points from being collected in those locations. If no value is specified for this parameter (default), or you specify a value, but one or more of the source images do not contain a bitmap or vector segment, no local exclusion mask will be applied for those images.

The syntax for LOCLMASK is:

LOCLMASK = (NONE | BIT | VEC | <n>)

You can specify the value of LOCLMASK using the following:

NONE: exclude no pixels from the computation
BIT: use when there are bitmap segments in at least some of the source image files that define exclusion regions. When one of the source images contains multiple bitmaps, the last one is used. All image pixels covered by the bitmap are excluded from point collection.
VEC: use when there are vector segments in at least some of the source image files that define exclusion regions. When one of the source images contains multiple vector segments, the last one is used. This vector segment must be a polygon, and all image pixels enclosed by the polygon are excluded from point collection.
<n>: specifies a particular segment number that contains the desired mask segment to be used.

This parameter is optional.

DBGC

Specifies the GCP segment in the input file to receive the collected GCPs. If this parameter is not specified, a new GCP segment is created.

If a new segment is created, then AUTOGCP returns the segment number of the newly created segment. When called from EASI, this segment number is stored in the LASC parameter in the PRM file. See the Return Value section for more details.

GCP identifiers are composed of hash values of the raw image and reference vector files, respectively, and the consecutive GCP numbers. Each hash value is derived from the corresponding file base name and its creation date. Hash values are not guaranteed to be unique, but are likely to be distinct in most practical situations. The hash values for the raw and reference files are printed in the report.

AUTOGCP produces GCP IDs in the following format:

  XXXXXXXX_YYYY_N

where:

XXXXXXXX: the hash code of the input image
YYYY: the hash code of the reference image
N: the number of the GCP, 1 to any number

For example:

1BE489CD_F23A_001
1BE489CD_F23A_102

The collected GCPs are always written to the standard report file or device.

FILREF

Specifies the name of the file that contains the orthorectified reference image from which the horizontal coordinates of the collected GCPs will be derived.

DBIC_REF

Specifies the channel(s) in the input reference image to use as reference. Multiple channels will be averaged together.

See the Input (DBIC) parameter for additional details.

FILEDEM

Optionally specifies the name of a file, directory, or DEM index file that contains digital elevation model (DEM) tiles.

If FILEDEM is the name of a single raster DEM file, the DBEC and BACKELEV parameters are used, if defined.

If FILEDEM is not specified, the offset value of the ELFACTOR parameter is used for the elevation. If neither FILEDEM nor ELFACTOR are specified, an approximated elevation value is calculated from the system DEM file gmted2010.

If FILEDEM is the name of an existing directory, the specified directory is searched for a file named index.txt. The index.txt file must be in the DEM index format, which is described in the Details section.

If FILEDEM is the name of a text file (with a .txt extension), the specified file must be in the DEM index format, which is described in the Details section.

DBEC

Specifies the channel that contains the digital elevation model (DEM) from which GCPs will be obtained.

This parameter is ignored if FILEDEM is an empty string or a DEM index text file.

BACKELEV

Optionally specifies the background elevation (NoData) value of the input DEM. Areas that are defined as NoData in the DEM are excluded from consideration while searching for GCPs.

If this parameter is not specified, the function checks for ELEVATION_BACKGROUND or NO_DATA_VALUE metadata tags, first at the channel level, then at the file level. If this value is not specified or found in the metadata, the function uses the default value of -32768.

This parameter is ignored if FILEDEM is an empty string or a DEM index text file.

ELEVREF

Optionally specifies the vertical reference for the elevation values contained in the source DEM, or for the constant ELFACTOR (Elevation Offset/Scale) value, if defined.

Acceptable values are:

MSL: elevations are referenced to Mean Sea Level. The EGM2008 geoid model will be used to convert these to ellipsoidal heights.
ELLIPS: elevations are referenced to the ellipsoid. The coordinate system of the DEM raster file is examined to determine which ellipsoid and datum are to be used; for instance, if the DEM file is referenced to NAD83, the heights are assumed to be NAD83 ellipsoidal heights. If the DEM and math model are based on different coordinate systems, the heights will be automatically converted to the math model coordinate system before use.

If this parameter is not specified, the metadata tag ELEVATION_DATUM is searched at the file level and the channel specified by DBEC. If not found, MSL is the default value.

This parameter is ignored if FILEDEM is an empty string or a DEM index text file.

ELEVUNIT

Optionally specifies the units used to describe the elevation values of the input DEM file.

Acceptable values are:

METER (default value)
FEET
US_FEET

If elevation values are specified as FEET, the conversion factor to meters is 0.3048 (corresponding to International Feet); if US_FEET, the conversion factor is 1200/3937 (corresponding to U.S. Survey Feet).

If this parameter is not specified, the function searches for an ELEVATION_UNITS metadata tag at the file level, then again at the channel level. If this value is not specified through the parameter or found in the metadata, its value defaults to METER.

This parameter is ignored if FILEDEM is an empty string or a DEM index text file.

ELFACTOR

If an input digital elevation model (DEM) is specified the value of this parameter is used to shift and scale the DEM pixel values to values in the units indicated by the value of the ELEVUNIT parameter.

Two values are specified using this parameter: the first number defines the offset while the second optionally specifies the scale.

The conversion formula is as follows:

elevation_value = scale * (DEM_pixel_value + offset)

If FILEDEM is not specified, only the offset value of ELFACTOR is significant. This value is interpreted as a uniform elevation value in the units specified by ELEVUNIT and using the vertical reference specified by ELEVREF. If ELFACTOR is not specified and FILEDEM is not specified, an approximate DEM based on the global DEM file (located in the etc subdirectory of the CATALYST Professional installation folder) will be used.

This parameter is ignored if FILEDEM is an empty string or a DEM index text file.

If ELFACTOR is not specified, the offset default is 0.0 and the scale default is 1.0.

SMPLSRC

Specifies the source of sample points for GCP matching, and the number of points to use. GCPs may be automatically generated using the SUSAN or GRID option, or they may be explicitly specified in a sample file.

Available options are:

SUSAN:[samples=<s>],[trials=<t>] Sample points are automatically generated using the SUSAN algorithm, which finds the candidates by running a corner detection algorithm on the image, looking for corner-like features to use as candidates.
- samples=<s> where s defines the number of samples to use. The default value used is 64.
- trials=<t> where t specifies the number of trials for each point before giving up on the match. The algorithm will try to match the primary sample point and if that fails to match, a secondary point will be chosen within the same grid cell as an additional sample. This value can be any integer value from 1-500. The default number of trials used is 1. NOTE: Using the trials option will make the matching process slower as the system may try multiple times to match in each cell.
GRID:[samples=<s>],[margin=<m>],[trials=<t>] Sample points are automatically generated, using sample points distributed evenly across the overlap region.
- samples=<s> where s defines the number of samples to use. The size of the grid cells is automatically chosen based on the number of samples requested. The default value used is 64.
- margin=<m> where m controls the minimum distance, in pixel units, between the edge of the image and the placement of the candidates. When specified, the first point of the grid will be explicitly put at the value location. As well, when the margin option is used the points will be distributed starting at the edges of the overlap rather than in the center of the grid cells, which greatly improves the chances of finding matches at the edge(s) of the image. If margin is not specified the overlap region is divided into a grid and candidates, by default, are placed in the center of the grid cells.
- trials=<t> where t specifies the number of trials for each point before giving up on the match. The algorithm will try to match the primary sample point and if that fails to match, a secondary point will be chosen within the same grid cell as an additional sample. This value can be any integer value from 1-500. The default number of trials used is 1. NOTE: Using the trials option will make the matching process slower as the system may try multiple times to match in each cell.
DBREF:[file=<filename>],[dbvs=<segment number>] For Stereo GCP collection, which collects common GCPs amongst multiple raw images. DBREF instructs AutoGCP to run in Stereo GCP mode. In this mode, points on the reference image are pre-chosen (via the GCPCAND algorithm) and saved as a vector segment in a candidate file.
- file=<filename> Specifies the filename of the candidate file. If FILE is not specified, then AUTOGCP will look for the vector segment in FILREF.
- dbvs=<segment number> specifies the vector segment number from the file specified. If DBVS is not specified, AUTOGCP will look for the last vector segment in the file.

If this parameter is not specified, the default value is GRID:64.

If no value is specified for this parameter, the default value of SUSAN:64 is used.

The SUSAN and GRID options determine how to find the initial candidate positions in one image–the source image–for collecting sample points. AUTOTIE builds a patch around each candidate position that it searches for in overlapping images.

The SUSAN option finds the candidates by running a corner-detection algorithm on the image, which looks for corner-like features to use as candidates.
The GRID option creates candidates in a grid-like pattern. Because this option does not preprocess the image, it tends to be faster, but it may find fewer matches because the grid point might fall on a featureless flat patch somewhere in the image that cannot be matched to anything in the overlapping images.

When collecting GCPs, the GRID option is preferred because the SUSAN option finds candidates on building corners that may not be represented in the DEM, leading to GCPs with higher residuals due to height errors.

NOTE: Previous versions included basic support for the sample source along with the number of samples, similar to the lines shown below.

SUSAN:64

GRID:64

In this case the method and number of samples are specified with a single : as a separator. For backward compatibility, the SMPLSRC parameter will still support this method of specifying the source information, as well as supporting the new format.

ALGO

Specifies the algorithm used for automated GCP matching.

Supported methods are:

FFTP (Fast Fourier Transform Phase matching): When two images have a relative shift between them, the result is a phase difference in the Fourier domain. FFTP determines the shift between images using this phase difference.
NCC (Normalized Cross-Correlation matching): This method finds the relative shift between two images by finding the shift that produces the maximum cross-correlation coefficient of the gray values in the images.

If this parameter is not specified, FFTP is the default method.

When the two images being matched have similar gray values and appearances, NCC generally produces acceptable results. When there is a rotation or image size error in the initial math models, NCC may produce better matching results than FFTP. Because the template size that NCC uses is smaller than the one used by FFTP, this method also typically generates faster results.

For more consistently accurate results, FFTP is recommended. This method uses a larger template size than NCC and, because it works in the frequency domain, it looks at the patterns of details in the image rather than the gray values in a small neighborhood, which NCC uses. This makes FFTP more robust than NCC in cases where there is a large brightness difference between images or when a major land use change has occurred between the images and allows it to better match images of the same area from different sensors or spectral bands.

SEARCHR

Optionally specifies the distance in the X and Y directions from a starting location on the reference image over which the search for the best match with a fixed point on the input image will be conducted. The units for this value are controlled by the SEARCHUN (Search Radius Units) parameter.

The search radius is an estimation of error with the raw image's positional information and the DEM accuracy. If you know that your image is accurate to 80 meters and your DEM is accurate to 200 meters, set the search radius to 280 meters. A larger search radius will require more processing time, because more locations are evaluated to determine the best match for a GCP.

If this parameter is not specified, the function uses a search radius of 100 pixels.

SEARCHUN

Optionally specifies the units of the search radius value, as specified by the SEARCHR (Search Radius) parameter.

Acceptable values are:

PIXEL: search radius in pixels (default)
METER: search radius in meters
FEET: search radius in feet
US_FEET: search radius in U.S. Survey feet

When using PIXEL, the search radius value is interpreted to mean the number of pixels in the reference image. If the specified unit is METER, FEET, or US_FEET, the search radius represents meters or feet in the reference image.

MINSCORE

Optionally specifies a threshold value that controls whether a candidate GCP is accepted as a GCP or rejected. This parameter specifies the minimum match quality that is considered an acceptable match, with 1.0 indicating a perfect match.

When using the FFTP algorithm, this value is converted internally to a minimum acceptable phase shift peak value.

When using the NCC matching method, this value specifies the minimum match score value required to accept a local match between the input and reference images as a GCP. The default value is 0.75.

PROC

Controls the amount of memory (in megabytes) used by the algorithm.

If the host memory limit is not specified, the function uses a default of 1 GB or half the available physical memory, whichever is smaller.

NUMGCPS

Returns the total number of GCPs collected. When no GCPs are collected this is set to zero (0).

This is an output parameter; no user input is required.

REPORT

Specifies where to direct the generated report.

Available options are:

TERM: generates a report on the terminal (default)
DISK: generates a report on file "IMPRPT.LST"
OFF: turns off report generation
<filename>: appends a report to the specified file

Details

AUTOGCP collects ground control points (GCPs) from an input image using a reference image. A digital elevation model (DEM) may be used to extract the elevation for each GCP.

AUTOGCP is typically used to:

Co-register two referenced images

This is used for applications such as pansharpening, where the multispectral and the panchromatic images are slightly misaligned. You can use this function to collect GCPs between the input and reference files, then correct the input file using a resampling program such as REG.
Collect GCPs between an unreferenced image and a referenced file

This is used for orthorectifying satellite images. You can use this function to collect GCPs and a DEM to extract the elevation for each GCP. The resulting GCPs are then used to compute the geometric model (or math model). Use AUTOGCP to remove the bottleneck of manual GCP collection from the image rectification workflow.

You may specifiy a threshold value that controls whether a candidate GCP is accepted as a GCP or rejected. The MINSCORE (Minimun Acceptance Level) parameter specifies the minimum match quality that is considered an acceptable match, with 1.0 indicating a perfect match.

When using the FFTP algorithm, this value is converted internally to a minimum acceptable phase shift peak value.

When using the NCC matching method, this value specifies the minimum match score value required to accept a local match between the input and reference images as a GCP. The default value is 0.75.

You may also change the Search Radius (SEARCHR) for matching each GCP, and the units in which the radius is defined (SEARCHUN); the default radius is 100 pixels. If the approximate positions between the input and reference files are not accurate, increase the SEARCHR value.

Upon completion, AUTOGCP populates the NUMGCPS variable with the number of extracted GCPs.

If no GCPs were collected, there are several settings that can be adjusted to increase the channces of finding matches. Increasing the search radius will cause the matcher to search a larger area for each point and more matches may be found. If possible, measure the error between the raw image's model or georeferencing and the reference image and set the search radius to a value larger than it. Increasing the number of trials may also help with collecting more matches as it tries additional points near every point that failed to match. Increasing the number of samples may also result in more matches as it increases the number of locations where matches are attempted. Ensuring that the input channel and the reference channel have as similar spectral content as possible will also help the matcher find successful matches.

Working with radar data

When the input data contains image layers written as complex values, the total power in decibels is computed temporarily and used for matching. When possible, it is also recommended that you calibrate the data in sigma, beta or gamma naught. FFTP matching is also recommended when working with SAR data.

DEM index file

The FILEDEM parameter may specify the name of a file, a directory, or a text file. If a directory is specified, that directory is searched for a file named index.txt which must match the DEM index format.

If a text file is specified, the file's format must match the DEM index file format. The DEM index file format is treated as a single virtual DEM, eliminating the need to merge the DEM tiles into a single file.

The DEM index file (index.txt) and each DEM tile must meet the following conditions. Each tile must:

Be in the same coordinate system
Be raster-aligned; that is, the geocoding for all tiles is defined so that all pixels fall on a common raster grid
Use the same data type
Be based on the same height datum
Use the same NoData value
Use the same ELFACTOR value

The following text shows an example of a DEM index file.

MAPUNITS       LONG/LAT D000
DATATYPE       16S
DBEC           1
BACKELEV       -32768.000
ELEVREF        MSL
ELEVUNIT       METER
ELFACTOR       0.000 1.000000000000
RES_XY         0.0008333333333333 0.0008333333333333
#Filename                ULX                    ULY                     LRX                   LRY
srtm_01_02.tif   -180.000416666676760    55.000416618227803   -174.999583333343420    49.999583284894470
srtm_01_07.tif   -180.000416690891140    30.000417247801863   -174.999583357557810    24.999583914468531
srtm_01_12.tif   -180.000416690891140     5.000416642442191   -174.999583357557810    -0.000416690891143
srtm_01_15.tif   -180.000416666676760    -9.999582994342006   -174.999583333343420   -15.000416327675339
srtm_01_16.tif   -180.000416666676760   -14.999583115413941   -174.999583333343420   -20.000416448747274
srtm_01_17.tif   -180.000416666676760   -19.999583236485876   -174.999583333343420   -25.000416569819208
srtm_01_18.tif   -180.000416666676760   -24.999583357557810   -174.999583333343420   -30.000416690891143

The first eight lines of the file describe common values that apply to each image; they must be in the order shown in the example with no comments or blank lines between them. The remaining lines describe the image boundary records for each image in the DEM tile data set. Comments (lines beginning with a #) are allowed in the list of DEM tiles in the file.

The format of the eight header lines is:

MAPUNITS: The EPSG projection code or PCI map-units string for the coordinate system.
DATATYPE: The data type of the files.
Acceptable values are:
- 8U
- 8S
- 16U
- 16S
- 32U
- 32S
- 32R
- 64U
- 64S
- 64R
DBEC: The channel number for the input digital elevation model (DEM) elevation channel to be processed.
BACKELEV: The background elevation (NoData) value in the input DEM elevation layer.
ELEVREF: The vertical reference for the elevation values contained in the source DEM, or for the constant ELFACTOR value, if it is used.
ELEVUNIT: The units of the elevation values that are stored as pixel values in the input DEM, as specified either by FILEDEM or by the first entry in ELFACTOR.
ELFACTOR: When an input digital elevation model (FILEDEM) is specified, the value of this parameter is used to shift and scale the DEM pixel values to values in the units indicated by the value of the ELEVUNIT parameter.
RES_XY: The x and y image-resolution values.

Each line following the header lines is treated as either a comment line or as a raster-tile description. Empty lines or those beginning with a number sign (#) are treated as comment lines. Each raster-tile description line contains four parameters separated by white space:

DEM raster-file name: path to the DEM raster file. This may be an absolute path or a relative path. A relative path is relative to the DEM index file itself.
Upper-left x-coordinate: the x-coordinate at raster-column location 0.0, raster-row location 0.0
Upper-left y-coordinate: the y-coordinate at raster-column location 0.0, raster-row location 0.0
Lower-right x-coordinate: the x-coordinate at raster-column location 'numPixels', raster-row location 'numLines', where numPixels and numLines are the dimensions of the raster.
Lower right y-coordinate: the y-coordinate at raster-column location 'numPixels', raster-row location 'numLines', where numPixels and numLines are the dimensions of the raster.

Note: This description of the raster boundary provides coordinates at the outer extents of the pixels; with butt-joined tiles, the tile records should indicate gap-free coverage.

As individual raster tiles are accessed, their properties are compared with the values listed in the DEM index file. If they do not conform to the indicated values, an error message appears in the log.

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

AUTOGCP

Enhanced automatic GCP collection

Description

Parameters

Parameter descriptions

Details

Example