| Back to top |
| Back to top |
| Name | Type | Caption | Length | Value range |
|---|---|---|---|---|
| FILI * | String | Input file name | 1 - 192 | |
| DBGCPIN * | Integer | Input GCP segments | 1 - | 1 - 1024 |
| DBGCPSUP | Integer | Supplemental input GCP segments | 0 - | 1 - 1024 |
| DBGCPOUT | Integer | Output GCP segment | 0 - 1 | 0 - 1024 |
| NROWCOL * | Integer | Number of rows and columns | 2 - 2 | 1 - 900 |
| USECELLS | Integer | Cells to use | 0 - 900 | 1 - 900 |
| GCPRANGE * | Integer | Minimum, maximum GCPs per cell | 2 - 2 | -100 - 1024 |
| MASKFILE | String | Area mask file | 0 - 192 | |
| MASK | Integer | Area bitmap or vector mask | 0 - 1 | |
| OUTSUM | Integer | Output summary | 0 - 5 | 0 - 4096 |
| OUTCELL | Integer | Output number of GCPs per cell | 0 - 10000 | 0 - 1024 |
| OUTMASK | Integer | Output mask coverage per cell | 0 - 10000 | 0 - 100 |
| POINTOPT | String | Point option? DEL/INACT | 0 - 5 | Default: INACT |
| Back to top |
FILI
Specifies the input file that contains one or more GCP segments.
DBGCPIN
Specifies the primary input ground control point segments in the input file (FILI). The values must be in the range between 1 and 1024.
If an input ground control point segment has a metadata attribute LockedGCPs with the case-insensitive value of TRUE, then all GCPs in this segment are retained.
All check points (CPs) and inactive points (IPs) from the primary segments are retained. They are not included in the counts of valid GCPs in individual cells.
Primary segments without any data (GCPs, CPs or IPs) are ignored, but their numbers are included in a warning message with the list of no-data segments.
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.
DBGCPSUP
Optionally specifies the GCP segments in the input file (FILI) that can be used as lower-quality supplemental GCPs. The values must be in the range between 1 and 1024.
Check points (CPs) and inactive points (IPs) from the supplemental segments are not retained.
Supplemental segments without any data (GCPs, CPs or IPs) are ignored, but their numbers are included in a warning message with the list of no-data segments.
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.
DBGCPOUT
Specifies the GCP segment to receive the output GCPs. The value must be in the range between 1 and 1024.
If this parameter is specified, all segments specified in the DBGCPIN and DBGCPSUP parameters must have the same projection as the DBGCPOUT segment.
If this parameter is not specified, a new output GCP segment is created and its number is returned in this parameter. In this case the output segment projection is copied from the first primary segment in DBGCPIN that has at least one data point (GCP, CP or IP).
NROWCOL
Specifies the number of rows and columns that divide the image extents into cells. The number of rows times the number of columns must be equal to or less than 900.
USECELLS
Specifies the cell numbers in the grid that should contain GCPs.
The cells are numbered consecutively along the cell rows in the left-to-right then down order, starting from the upper-left cell of the image. GCPs outside the specified cells will not be included in the final GCP segment. If no cells are specified, all the cells are used.
GCPRANGE
Specifies the minimum and maximum number of GCPs allowed in each cell. The first value (minimum) must be in the range between 1 and 1024.
The second value has two interpretations. If it is positive, then it specifies the maximum number of GCPs to retain in each cell. In this case its value must be not lower than the minimum number in the first value, and not greater than 1024.
If the second value is negative, it must be in the range between -100 and -1 inclusive. Its absolute value is then interpreted as the percentage of GCPs to retain in each cell.
All GCPs from segments with the LockedGCPs attribute set to TRUE are accepted, even if their count in any particular cell exceeds the maximum or percentage value specified in this parameter.
GCPs from primary segments that would increase GCP counts in individual cells above the specified maximum or percentage value are accepted, but are converted to inactive points.
GCPs from the supplemental segments are used only to bring GCP counts in individual cells to the specified minimum value, but are ignored otherwise.
MASKFILE
Optionally specifies the name of the file containing the mask.MASK
Optionally specifies the input bitmap or vector segment in the input file to be used as an area mask. If you specify a MASK but not a MASKFILE, GCPPRUNE obtains the MASK from the input file.
If this parameter is specified, the GCPs in the area under the mask will be excluded from the output GCP segment. If unspecified, all GCPs will be considered for inclusion in the output segment.
All GCPs from segments with the LockedGCPs attribute set to TRUE are accepted, even if they are under the mask.
All check points (CPs) and inactive points (IPs) from the locked segments are accepted, even if they are under the mask.
OUTSUM
Check points (CPs) from locked segments are not included in the counts.
OUTCELL
Output parameter that reports the total number of GCPs retained in each cell. The cell numbering scheme is the same as that used for the USECELLS parameter.
The check points (CPs) from locked segments are not included in the individual cell GCP counts.
OUTMASK
Output parameter that reports the percentage of masked areas for each cell. The cell numbering scheme is the same as that used for the USECELLS parameter.
POINTOPT
Whether to keep rejected points. When you specify INACT (inactive), GCPs that have been converted to inactive points are written to the newly created GCP segment. When you specify DEL (delete), the rejected GCPs are eliminated. In all other cases, an error is generated.
| Back to top |
The GCPPRUNE module combines and prunes GCPs based on distribution and consistency. The main goal of the module is to ensure a complete coverage of image extents by GCPs, without overweighting any particular area with too many points. The uniform GCP coverage ensures that the math model refined with the points is stable and accurate.
After checking the parameters GCPPRUNE inspects the primary segments to find any locked segments that are identified by a metadata tag LockedGCPs set to TRUE (case insensitive). All points (Ground Control Points, Check Points and Inactive Points) in locked segments are transferred without any editing to the output segment, except the points outside image (with their image coordinates outside the image line and pixel numbers).
The input segments are arranged in a list with the locked segments first, followed by the remaining primary segments and then supplemental segments, if any. The order within each category is the same as in the parameters DBGCPIN and DBGCPSUP. The segments are further processed in this order.
All segments with no data (GCPs, CPs or IPs) are omitted from processing. Their numbers are included in a summary warning issued only when there are such segments.
The first processing step identifies gross outliers (blunders) among the GCPs only. Blunder detection is based on the concept of consistency of residuals between GCPs, as opposed to their absolute magnitudes, to accommodate nominal math models of image geometry with potentially large errors. The GCPs from locked segments are never flagged as blunders.
General rules:
All points outside image bounds are silently eliminated.
All accepted or passed-through point IDs that are identical to an already existing ID are appended with a successive number, starting from _1.
Handling of locked segments:
All locked GCPs, CPs and IPs are transferred to the output segment without any modifications (except for a possible extension of their IDs). They are never removed as blunders, are not screened against other points with the same image location, and are not checked against the mask or the cells from the USECELLS parameter. Locked GCPs are counted in the total number of GCPs per cell, and may exceed the maximum number or percentage limit.
Handling of primary segments:
All primary CPs and IPs are transferred to the output segment (with a possible extension of their IDs).
GCPs are silently eliminated if they are:
identified as blunders;
have an identical image location (to within 1e-8th of line and pixel) as an already accepted GCP;
are under the mask;
are outside the cells listed in the GCPRANGE parameter.
The remaining GCPs are collected for individual cells and are then added to each cell until the specified maximum GCP count or percentage per each cell is reached. The points in each cell are examined with a stride derived from the number of points required in that cell, considering the already accumulated locked GCPs. This minimizes the possibility of selecting GCPs concentrated in a small area of each cell. The actual percentage of GCPs retained in individual cells may deviate slightly from the value requested in the second element of the GCPRANGE parameter.
The surviving surplus GCPs are converted to IPs.
Handling of supplemental segments:
All CPs and IPs are ignored.
Eligible GCPs (non-blunder, non-duplicate, outside the mask, within the cells listed in USECELLS) are used only to bring the individual cell counts to the specified minimum.
The remaining supplemental GCPs are ignored (they are not converted to IPs).
Once all input segments are processed, the output GCP segment is written out, and the collection statistics are returned in the output parameter OUTSUM.
© PCI Geomatics Enterprises, Inc.®, 2026. All rights reserved.