RFMODEL

Description

RFMODEL calculates the mathematical models required for orthorectification using rational functions, and stores the result in a segment.

Parameters

rfmodel(mfile, dbgc, mmseg, adjorder, numcoeff, mapunits)

Name	Type	Caption	Length	Value range
MFILE*	str	Input file name, directory, or text file	1 -
DBGC	List[int]	Input GCP segment or layer	0 - 1
MMSEG	List[int]	Math model segment or layer	0 - 1
ADJORDER	List[int]	RPC adjustment order (0, 1, 2)	0 - 1	0 - 2
NUMCOEFF	List[int]	Number of coefficients (3 to 20)	0 - 1	3 - 20
MAPUNITS	str	Map units	0 -	PIXEL, UTM, METER, and others

* Required parameter

Parameter descriptions

MFILE

Specifies the name of a folder, image file, or text file that contains the input images. 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.

If MFILE is a directory name or if multiple file names are entered, then all images in MFILE should be processed using the parameters set for RFMODEL.

If a directory is specified, then the DBGC, MMSEG, ADJORDER, and NUMCOEFF parameters are set to a single value for all input images. If a text file is specified, the DBGC, MMSEG, ADJORDER, and NUMCOEFF parameters are read from the text file for each image, and those parameters can be empty.

If one file is specified for MFILE, the model computed will be an independent model (one image).

If a text file is specified for MFILE, the listed files in the text file are processed with the listed parameters.

DBGC

Specifies the ground control point (GCP) segment or layer to use to compute the model.

If a directory is specified for MFILE, then this segment number will be applied to all images. If a text file is specified, DBGC is read from the text file, and this parameter can be empty.

MMSEG

Specifies the math model segment or layer that stores the model.

If a directory is specified for MFILE, then this segment number will be applied to all images. If a text file is specified, MMSEG is read from the text file, and this parameter can be empty. If no value is specified, a new segment is created.

ADJORDER

If RPC data is supplied with the data, this value specifies the RPC adjustment order to be used in the RPC model refinement. Valid values are 0, 1 or 2.

NUMCOEFF

If RPC data is not supplied with the data, this value specifies the number of coefficients to be used to calculate the rational function. Valid values are 3 to 20.

MAPUNITS

Specifies the projection string for the output model.

The standard definitions are as follows:

PIXEL: pixel and line
UTM: Universal Transverse Mercator
SPCS: State Plane Coordinate System
LONG/LAT: longitude and latitude
METER: image along-row and along-column meters
FOOT: image along-row and along-column feet

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.

If this parameter is not specified, the map units of the GCP segment are used.

Return Value

Returns: A list of statistical values.

Type: PCI_DOUBLE

Parameter: IMSTAT

A list containing the doubles: [GCP RMS, GCP maximum RMS, GCP minimum RMS, abs(GCP maximum residual), abs(GCP minimum residual) math model segment number]. The last value in the returned list is the segment number to which the computed math model was written. The remaining values are in pixels. If more than one file is processed, the list is extended with the same set of statistical values for each file. This function returns only if it executes successfully; otherwise, it throws an exception instead of returning.

Details

RFMODEL calculates the mathematical model required for orthorectification using rational functions. It computes an updated rational functions solution, based on provided GCPs or rational function coefficients, or both.

There are several use scenarios for RFMODEL:

Enter an unreferenced raw image, GCPs, and a number of coefficients: RFMODEL computes the RPCs based on ground control information alone, and generates to a math model segment.
Enter a linked PCIDSK file to a raw image with RPCs (NITF, TIFF, with TXT): RFMODEL creates a math model segment in the linked PCIDSK database.
Enter an imported raw image with RPCs and GCPs: RFMODEL computes the x- and y- offsets, and generates to a math model segment on the input database.
Enter a folder of images or a wildcard selection of images with RPCs and GCPs: RFMODEL computes the x- and y- offsets for each image and generates to a math model segment on the input databases or linked databases, as required.
Enter a text file specifying parameters for several images: RFMODEL computes the x- and y- offsets for each and generates to a math model segment on the input databases or linked databases, as required.

Note: If you have RPCs but no GCPs, RFMODEL need not run. ORTHO and other functions interpret the RPC model transparently from the original raw image files (NITF, TIFF with TXT).

Note: When run with EASI the function sets the parameter named IMSTAT to the values that are returned by the Python version.

Examples

You have an IKONOS image and would like to correct it using rational functions.

from pci.rfmodel import rfmodel

mfile ="ikonos.pix"	# input image file
dbgc = [2]		# use gcp segment 2
mmseg = []		# create a new math model segment
adjorder = [0]		# use 0 order RPC adjustment
numcoeff = []		# Leave none for RPC coefficient number
mapunits = "UTM 11 d0"	# output projection

rfmodel (mfile, dbgc, mmseg, adjorder, numcoeff, mapunits)

You have an image without existing RPC math model and would like to generate a new RPC segment.

from pci.rfmodel import rfmodel

mfile ="17029_pan.pix"	# input image file
dbgc = [3]		# use gcp segment 3
mmseg = []		# create a new math model segment
adjorder = []		# leave none for RPC adjustment order
numcoeff = [20]		# use 20 for RPC coefficient number
mapunits = ""	# output projection

rfmodel (mfile, dbgc, mmseg, adjorder, numcoeff, mapunits)

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