TPSMODEL

Description

TPSMODEL is a simple math model in which all the collected ground control points (GCPs) are used simultaneously to perform a transformation.

Parameters

tpsmodel(mfile, dbgc, mmseg)

Name	Type	Caption	Length
MFILE *	str	Input file name, directory, or text file	1 -
DBGC	List[int]	Input Ground Control Point segment or layer	0 - 1
MMSEG	List[int]	Output math model segment or layer	0 - 1

* Required parameter

Parameter descriptions

MFILE

Specifies a particular file or multiple files 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.

DBGC

Specifies the input GCP segment or layer to use when computing the model.

DBGC must be specified either in the task or in the text file. If a folder is specified for MFILE, this segment number applies to all images. If MFILE specifies a text file, the value for DBGC is read from the file; this parameter can therefore remain empty.

MMSEG

Specifies the output math model segment or layer in which to store the computed model.

If a folder is specified for MFILE, this segment number applies to all images. If MFILE specifies a text file, the value for MMSEG is read from the file; this parameter can therefore remain empty. If no value is specified, a new segment is created.

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 instead of returning.

Details

The Thin Plate Spline (TPS) is a simple math model in which all collected GCPs are used simultaneously to compute a transformation. Warping is distributed throughout the image with minimum curvature between the GCPs, becoming almost linear in areas away from the GCPs.

The TPS math model fits the GCPs exactly; therefore, a GCP can be added in an area where the transformation is not satisfactory. This also means, however, that the math model does not provide a direct means of detecting and correcting errors in GCP coordinates. To verify the derived transformations, you must acquire a number of check points that are large enough to ensure a thorough verification, such as an amount equal to half the number of GCPs.

The TPS math model can handle more variations in terrain than the polynomial math model, because it recognizes three-dimensional GCPs and minimizes the extrapolation errors that can occur between the GCPs.

To accurately compute a warping transformation, you must collect GCPs at the extremes of the terrain and along the breaklines. If you use the TPS math model with an image in rough terrain, it may be necessary to acquire hundreds of GCPs. For this reason, the TPS math model is recommended only for distortions that can be accurately represented using up to a few dozen GCPs. It is not recommended that you remove terrain distortions or images of rough terrain. For these types of images, a rigorous model, such as the satellite orbital or aerial photography math model, is recommended.

Example

Compute the TPS model of an image.

from pci.tpsmodel import tpsmodel

mfile="Photolist.txt"
dbgc=[3]
mmseg=[]

tpsmodel(mfile, dbgc, mmseg)

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