GCPCAND

Name	Type	Caption	Length	Value range
MFILE *	str	Input file name, folder, or text file	1 -
DBIC	List[int]	Reference image channel(s)	0 -
SRCBGD	str	Source background value	0 -	Default: FILE
LOCLMASK	str	Local exclusion mask	0 -	Default: NONE
SMPLSRC	str	Candidate samples source	0 -	SUSAN \| GRID Default: GRID
DISTRIB	str	Distribution unit	0 -	MAPSPACING \| PIXELSPACING \| ENTIRE Default: MAPSPACING
DISTNUM	str	Distribution number	0 -
TRIALS	List[int]	Number of trials per candidate	0 - 1	1 - 8 Default: 1
PROC	str	Processing algorithm	0 -
FILO	str	Output file or folder	0 -

Parameter descriptions

MFILE

The name of a folder, image file, or text file that contains the reference images from which to produce candidates. If necessary, you can use a wildcard (*) in the string.

You can specify the value of the MFILE parameter by using any of the following:

A specific data file name or folder 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 per file; for example, "C:\list.txt". Each line has the following format:
- Filename;Channel List;Source Background

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 in quotation marks.
Do not specify numeric parameters in 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 semicolons to delimit the parameters.
Leave the position between the semicolons empty (";;") if you do not want to specify a value. Alternatively, if there are no remaining parameters to be specified at the end of a line, you can 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.

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

When specifying file channels, you can specify individual channels or channel sequences. 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 expanded internally to "1,2,3". The second channel number in the sequence must be greater than the first channel number.

If the MFILE you specify does not have the source background specification, the value of the SRCBGD parameter is used.

DBIC

The channel or channels in the reference-image file from which to extract the SUSAN corner features when using the SUSAN detector. When there are multiple channels, they are averaged together.

If the value of the DBIC parameter is in a text file (MFILE), this parameter is ignored.

If no value is specified for this parameter, the first channel is processed by default.

This parameter is ignored when the value of the SMPLSRC (Candidate samples source method) parameter is any option other than SUSAN.

SRCBGD

The pixels in the source image to consider as background (NoData) pixels. In general, if a pixel is considered NoData, GCPCAND processes the pixel in a specific manner.

You can choose from the following options:

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

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

Note: To specify multiple values, use a comma-delimited list. The first value applies 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. This parameter is ignored when the value of the SMPLSRC (Candidate samples source method) parameter is any option other than SUSAN.

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 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 image files that define exclusion regions. When one of the 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.

SMPLSRC

The source of sample points for the candidates

If no value is specified for this parameter, GRID is used by default.

The SUSAN and GRID options determine how to find the candidate positions in the reference image. AutoGCP will attempt to collect GCPs at these locations.

The SUSAN option finds 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 also finds 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 digital elevation model (DEM), leading to GCPs with higher residuals due to height errors.

DISTRIB

The unit of value to use for the DISTNUM parameter.

You can choose from the following options:

MAPSPACING: reads the value of the DISTNUM parameter as the spacing in reference-image map units between each point.
PIXELSPACING: reads the value of the DISTNUM parameter as the spacing in reference-image pixels between each point.
ENTIRE: reads the value of the DISTNUM parameter as a target number of points for the entire reference image.

DISTNUM

This controls the number of GCPs to find, in the units specified for the DISTRIB (Distribution) parameter. The default value generally produces approximately 100 points evenly distributed over the reference image. When the value of the DISTRIB (Distribution) parameter is MAPSPACING, and the reference image has a projection in degrees, you can specify a string in the format degrees-minutes-seconds. The specific format is as follows:

DD MM SS.SSS: separated by blanks.
DDdMM'SS.SSS": delimited by degrees (d), minutes ('), seconds (") tokens
DDdMM'SS.SSS: delimited by degrees (d), minutes ('), but no token needed for seconds field
DD.DDD: decimal degrees
SS.SSS": seconds only

TRIALS

The number of trials per candidate. Trials are backup candidates to try when the main candidate failed to match a given raw image. When there is an insufficient number of stereo GCPs, it is recommended that you use a denser distribution rather than more trials, as the backup trials are only collected if the main candidate failed to match for a particular image.

PROC

The amount of memory (in megabytes) used by GCPCAND.

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

FILO

The name of the output file or folder to which to write the processed files, depending on the value of the MFILE parameter:

If it is a single file, specify the name of the new candidate file to create. If you do not specify a value, the output file will have the same name as the input file, prefixed with "c". If there is an existing file in your output folder using the name you specify, and it is a PCIDSK file, a new vector segment will be written to it.
If it represents multiple files, specify the name of the output folder to which to write the new files. Each will have the same name as its corresponding input file, prefixed with "c". If you do not specify a folder, the output files will be created in the current working folder.

The vector segment GCPCAND creates will be named GCPCand and have a description of GCP candidate points.

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

GCPCAND

Candidate generation for automatic GCP collection

Description

Parameters

Parameter descriptions

Return Value

Details

Example