GCPREFN

Description

GCPREFN refines the ground control points (GCP) of a GCP segment in a raw image file by using a computed sensor model or a polynomial equation, and then exports the refined GCPs to a new GCP segment.

Parameters

gcprefn (file, dbgc, mmseg, orbit, modeltyp, order, reject, pointopt, lasc, imstat)

Name	Type	Caption	Length	Value range
FILE *	str	Input file name	1 -
DBGC *	List[int]	Input GCP segment or layer	1 - 1
MMSEG	List[int]	Math-model segment or layer	0 - 1
ORBIT	List[int]	Input orbit segment	0 - 1
MODELTYP *	str	Model type	2 - 4	SAT \| RF \| AP \| POLY \| ADS \|RS
ORDER	List[int]	Transformation order	0 - 1	-2 - 8 Default: 0
REJECT	List[float]	Rejection method	0 - 3	Default: 5.0, 2.0, 2.0
POINTOPT	str	Point option? DEL/INACT	0 - 5	Default: INACT
LASC	List[int]	Output refined GCP segment number	0 -
IMSTAT	List[float]	Output GCP refinement statistics	0 -

* Required parameter

Parameter descriptions

FILE

The name of the file that contains the image data and the set of GCPs to refine.

DBGC

The GCP segment or layer number that contains the set of GCPs to refine. The segment or layer must be in a georeferencing unit other than pixels.

MMSEG

The math-model segment that contains the math model to use for the refinement.

ORBIT

If the satellite ortho model, specified by the Model Type (MODELTYP) parameter, is used to remove inaccurate GCPs from a raw satellite scene, this parameter specifies the orbit segment that contains the ephemeris data for the input raw image. If you specify POLY (Polynomial) as the model type, you need not specify a value for this parameter.

MODELTYP

The model type to use in refining the GCPs.

The following options are available:

SAT: Toutin's Model
RF: Rational Function Model
AP: Airphoto Model
POLY: Polynomial
ADS: (Leica Airborne Digital Scanner)
RS: Radar Model

ORDER

The polynomial transformation order number for the Polynomial or Rational Function Model.

REJECT

The method to use to reject GCPs.

If no value is specified for this parameter, GCPREFN uses the root-mean-square (RMS) error-rejection method by default, with the values for the minimum x and y RMS set to 2.0.

There are five modes available. The parameters are defined using two values (PARAM1, PARAM2). These vary in meaning depending on the selected rejection method (MODE).

The supported rejection modes and their parameters are as follows:

MODE=1 represents the absolute number of points to reject, starting with the ones with the highest residual.
With the Absolute Number rejection method:
- PARAM1 represents the number of GCPs to reject.
- PARAM2 represents the ratio of weighting between the x and y residuals.
For example, to give twice the weight to the x-residual as the y-residual, enter a rejection weighting of 2. By default, the residual in x and y will have the same weight. Therefore, if you have a point with an x-residual of 0.4 and a y-residual of 0.5, the point will be given an x-residual of 0.8 and a y-residual of 0.5 for the rejection.

To, for example, apply the Absolute Number rejection method (mode 1), reject 10 GCPs, and give the x-residual half the weight as that of the y-residual, enter 1, 10, 0.5.
MODE=2 represents the percentage number of points to reject, starting with the one with the highest residual.
With the Percentage Number rejection method:
- PARAM1 represents the percentage of the number of GCPs to reject.
- PARAM2 represents the ratio of weighting between the x and y residuals.
For example, to give twice the weight to the x-residual as the y-residual, enter a rejection weighting of 2. By default, the residual in x and y will have the same weight. Therefore, if you have a point with an x-residual of 0.4 and a y-residual of 0.5, the point will be given an x-residual of 0.8 and a y-residual of 0.5 for the rejection.

To, for example, apply the Percentage Number rejection method (mode 2), reject five percent of GCPs, and give the x-residual twice the weight as that of the y-residual, enter 2, 5 ,2.
MODE=3 represents the sigma standard deviation of points to reject.
With the Standard Deviation method:
- PARAM1 represents the minimum standard deviation value of the x-residual to reject.
- PARAM2 represents the minimum standard deviation value of the y-residual to reject.
For example, to apply the Standard Deviation rejection method (mode 3), reject points that have a standard deviation higher than two of the x-residual mean, and reject points that have a standard deviation higher than one of the y-residual mean, enter 3, 2, 1.
MODE=4 represents the absolute distance of the points to reject in terms of the residuals.
With the Absolute Distance rejection method:
- PARAM1 represents the minimum absolute x-pixel residuals to reject.
- PARAM2 represents the minimum absolute y-pixel residuals to reject.
Rejection starts from the point with the largest x or y residual distance.

For example, to apply the Absolute Distance rejection method (mode 4), reject pixels with an x-residual value greater than 2 pixels, and reject pixels with a y-residual value greater than 2 pixels, enter 4, 2, 2.
MODE=5 represents the RMS error of points to reject. Rejection starts from the point with the largest residual error for any point, then recomputes the math model and RMS error. If the RMS error is still above the specified thresholds, the point with the next highest residual is removed and so on, until the x-RMS and y-RMS errors are equal to or less than PARAM1 pixels or PARAM2 pixels.

For example, to apply the RMS Error rejection method (mode 5) and reject points with the highest residuals until the x-RMS and y-RMS values are both less than 2 pixels, enter 5, 2, 2.

POINTOPT

Whether to write 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 converted GCPs are omitted. In all other cases, an error is generated.

Tip: When you specify INACT, you can see which written points remain as GCPs and which became inactive by viewing the segment in CATALYST Professional Focus. On the Files tab in Focus, right-click the GCP segment, and then click View.

LASC

The segment number of the refined GCP segment. If no refined GCP segment was created, a value of -1 is returned.

IMSTAT

Various statistics describing the result of the refinement.

On completion of processing, the following entries are displayed:

first IMSTAT array element : number of GCPs accepted.
second IMSTAT array element : number of GCPs rejected.
third IMSTAT array element : original number of inactive points in the GCP segment.
fourth IMSTAT array element : original x-residual error of the accepted GCPs.
fifth IMSTAT array element : original y-residual error of the accepted GCPs.
sixth IMSTAT array element : new x-residual error of the accepted GCPs.
seventh IMSTAT array element : new y-residual error of the accepted GCPs.
eighth IMSTAT array element : x-residual error of the rejected GCPs.
ninth IMSTAT array element : y-residual error of the rejected GCPs.
tenth IMSTAT array element : x-residual error of all inactive points (original inactive points plus rejected GCPs).
eleventh IMSTAT array element : y-residual error of all inactive points.

If GCPREFN does not create a refined segment, all of the entries will display as 0.

Return Value

Returns: Execution status

Type: PCI_INT

The return value is 0. This function returns only if it executes successfully; otherwise, it throws an exception.

Details

GCPREFN removes GCPs with large errors from GCP segments. The algorithm reads the GCPs from the GCP segment specified for InputGCP (DBGC) in the database file. The GCP segment must be in a georeferencing unit other than pixels.

With the Model Type (MODELTYP) parameter, you select a polynomial equation or a satellite ortho model to use to remove inaccurate GCPs. When Model Type (MODELTYP) is Toutin's Model (SAT), you must also specify an orbital segment. GCPREFN extracts the ellipsoid from the GCP segment.

For more information about the rejection methods you can use, see REJECT .

GCPREFN saves the final GCPs and writes them to a new GCP segment.

Note: GCPREFN does not use refined GCPs to create or update an output math-model segment. To compute a model with updated GCPs, use a specific modeling algorithm, such as RFMODEL, RSMODEL, SATMODEL, APMODEL, or OEMODEL. For more information about any of the preceding algorithms, follow the link to each under Related functions.

By default, GCPREFN creates a report of the final GCPs and their residuals. If you do not want to create a report, you can specify OFF as the value of REPORT.

On completion, GCPREFN updates the NUMGCPS variable with the number of GCPs remaining after refinement. It also updates IMSTAT with various statistics about GCPs.

Note: If you specify a segment that includes inactive GCPs or check points, they will be copied to the output segment. That is, they are not included in the refinement process.

Example

Extract GCPs and use the satellite ortho model to delete inaccurate GCPs. Any points with an x or y absolute residual error over five must be removed.

from pci.gcprefn import gcprefn

file        =   "test.pix"
dbgc        =   [3]
mmseg       =   [4]
orbit       =   [2]
modeltyp    =   "SAT"
order       =   []
reject      =   [5,5,5]
pointopt    =   "INACT"
lasc            =       []
imstat          =       []

gcprefn( file, dbgc, mmseg, orbit, modeltyp, order, reject, pointopt, lasc, imstat )

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

GCPREFN

GCP refinement

Description

Parameters

Parameter descriptions

Return Value

Details

Example