GCPREAD

Description

Parameters

gcpread(file, dbgc, dbsn, dbsd, mapunits, elevref, elevunit, tfile, gcpform)

Parameter descriptions

FILE

The name of the PCIDSK image file to which to write the GCP segment.

A new GCP segment (type 215) will be created.

DBGC

The GCP segment number in the input file that contains GCP information. During processing, the existing GCP information in the specified GCP segment is overwritten. If the GCP segment does not exist, an error message is displayed. If no value is specified for this parameter, a new GCP segment is created in the output file (FILE).

DBSN

The name, up to eight characters, of the output GCP segment. If a name is not specified, the default name GCP is applied.

DBSD

A description, up to 64 characters, of the contents or origins of the output data. If you do not specify a description, an empty string is applied for the parameter.

MAPUNITS

The units in which the second set of GCP coordinates is measured. The first set of GCP coordinates is measured in pixels by default.

The standard definitions are as follows:

• PIXEL: pixel and line
• UTM: Universal Transverse Mercator
• SPCS: State Plane Coordinate System
• LONG/LAT or LAT/LONG: longitude and latitude (first coordinate is always assumed to be longitude)
• METER: image along-row and along-column, in meters
• FEET: image along-row and along-column, in feet

If no value is specified for this parameter, the map units will be read from the text file specified for the Input GCP text file (TFILE) parameter, provided the map units are provided in the file. If no value is specified for this parameter, and the text file does not provide map units, or if the map units specified by this parameter are different from those provided in the text file, GCPREAD will throw an exception. To change the current projection of the GCPs, you must modify the text file directly.

For a complete list of supported projections and Earth models, see Understanding map projections. The format of the map-units string is described in Output units.

ELEVREF

The vertical reference for elevation values.

Valid values are defined as follows:

• MSL: Mean Sea Level (geoid)
• ELLIPS: ellipsoid

If no value is specified for this parameter, the elevation reference is read from the text file specified for the Input GCP text file (TFILE) parameter, provided it is specified in the file. If the text file also does not contain elevation reference, the default value of MSL is used.

If the elevation reference specified for this parameter differs from that in the text file, GCPREAD throws an exception.

This value is used only if GCPREAD creates a new GCP segment (see parameter DBGC).

ELEVUNIT

The code for the units of the elevation values in the GCP data.

If no value is specified for this parameter, the elevation units are read from the text file specified for the Input GCP text file (TFILE) parameter, provided it is specified in the file. If the text file also does not contain elevation units, the default value of METER is used.

If the elevation units specified for this parameter differ from those in the text file, GCPREAD throws an exception.

This value is used only if GCPREAD creates a new GCP segment (see parameter DBGC).

TFILE

The path and file name of the input text file from which to read the GCP coordinates.

For more information about the required format of the text file, see the description of the GCPFORM parameter.

GCPFORM

The code for the format of the GCP data in the input GCP text file.

The naming convention of the codes is as follows:

• 2D: ID P L X Y S
• 2DERR: D P L X Y eP eL eX eY S
• 3D: ID P L X Y Z S
• 3DERR: ID P L X Y Z eP eL eX eY eZ S
• BULK: ID S X Y Z PhotoID P L PhotoID P L ...

where:

• ID: the true GCP or check-point GCP ID
• P, L: pixel and line values
• X, Y, Z: georeferenced x, y, and z values
• eP, eL: pixel and line error values
• eX, eY, eZ: x, y, and z error values
• S: "G" for active GCPs, "I" for inactive GCPs, and "C" for check-point GCPs
• PhotoID: Image ID that corresponds to the pixel and line coordinates of each GCP

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

GCPREAD transcribes GCP data from a specified text file to a GCP segment in an image file. The function accommodates several formats of the GCP data in the input text file. You specifiy the format by using the GCP format (GCPFORM) parameter.

The data can be written to an existing GCP segment or to one that is created by GCPREAD. When the segment is created, its name and description are specified by the caller or given default values by this function. This information is not contained in the input text file.

A GCP may be for use as georeferencing control (a "GCP"), or for use in assessing the accuracy of a rectification result (a "check point"). The information read from the input text file includes a flag value (S) that distinguishes between the two. You can also view a report in CATALYST Professional Focus that shows which points are GCPs and which are check points. On the Files tab in Focus, right-click the GCP segment and click View.

Example

Read the GCP data from the text file gcp.txt, and then write the GCPs to a new segment in the PCIDSK file irvine.pix. The GCP data in the text file is in the "3DERR" format.

from pci.gcpread import gcpread

tfile = "gcp.txt"
gcpform = "3DERR"
file = "irvine.pix"
dbgc = []       # empty, so a new GCP segment will be created
dbsn = ""       # the GCP segment will be named "GCP" by default
dbsd = ""       # the GCP segment will have no descriptor string
mapunits = "UTM 11 E0"
elevref = ""    # empty, so the default value of "MSL" will be used
elevunit = ""   # empty, so the default value of "METER" will be used

gcpread(file, dbgc, dbsn, dbsd, mapunits, elevref, elevunit, tfile, gcpform)