APMODEL

Description

Parameters

apmodel(oeproj, tfile, maxiter, xyzthr, angthr, radearth, units)

Parameter descriptions

OEPROJ

Specifies the path and file name of the input OrthoEngine project file.

The input OrthoEngine project file must exist, and must list the path names of the files that contain the aerial images. It must also contain calibrated values for the internal camera geometry, and initial values for the camera position and orientation at the exposure of each image.

The project file may also contain ground control points (GCPs) and tiepoints (TPs) to be used for the bundle adjustment. If the file does not contain GCPs or TPs, a bundle adjustment is not done, and the camera geometry and initial position and orientation values are copied to the image files.

Images in the project file must contain model information. The updated math models are automatically saved to a math model segment for each image in the project. If the image files are not in PCIDSK format, a linked file with the same name is created in the same folder to store the math model segment. This linked file is then used as input for the ortho task.

TFILE

Specifies the path and file name of the output text file. If this parameter is defined, a text file with the specified path and file name is created, containing a line of information for each input image.

Every line in the text file contains the path and file name of an image file affected by the adjustment. It also contains the number of the math model segment in that file that contains the calibrated camera geometry values and the adjusted or initial position and orientation values. A blank field exists between these two values. This text file format can be read by the ORTHO function.

The following example shows a line from an output text file, indicating that math model segment 4 in "C:\pci\S129.pix" will hold the calibrated camera geometry values and the position and orientation values for the image contained in that file. Because the fields are delimited by a semicolon, "; ;" indicates the empty field.

C:\pci\S129.pix; ; 4

The file names written to the output text file are retrieved from the input project file (OEPROJ). It is possible that the input project file does not contain the full absolute path for an image file; in this case, the prefix for the file name in the output text file will include the absolute path for the present working directory.

MAXITER

Specifies the maximum number of iterations that the adjustment computation can perform before terminating. The default value is 100.

XYZTHR

Specifies the bundle adjustment convergence criteria for the camera positions. The units are in meters or feet, depending on the map projection defined in the project file. The default value is 1.0.

ANGTHR

Specifies the convergence threshold, in degrees, for the exterior orientation angles. The default value is 0.5.

RADEARTH

Specifies the radius value, in meters or feet, of the Earth in the working area. A unit is the same as a GCP unit.

If this parameter is not specified, errors caused by the curvature of the Earth are not corrected. An average value of 6,372,200 meters or 20,906,000 feet can be used, depending on the GCP unit. By default, no correction is made

The distortion from the Earth curvature depends on the altitude; it becomes more severe as the radial distance from the ground nadir point to the object point increases. This distance increases if the radial distance, r, increases, if the altitude increases, or if the focal length decreases. For example, for an altitude of 1,800 meters and a 152 mm focal length camera lens, an image of a radial distance of 100 mm from the principal point has an Earth curvature radial distance of 6 micrometers. For an altitude of 18,000 meters, the Earth curvature radial distance is approximately 22 micrometers. The correction of the Earth curvature requires more computation time when running ORTHO. You need not correct for the Earth curvature if the error is negligible.

UNITS

Specifies the units in which the point residuals in the model calculation summary are reported.

The default value is GROUND.

Return Value

Returns: program execution status

Type:  PCI_INT

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

Details

APMODEL calculates the mathematical model required for orthorectifying a set of images in an OrthoEngine project file. The GCPs and orbit information are taken from the project file. The appropriate math model calculation task is called, depending on the math model that is specified in the project file.

The APMODEL is an iterative, least-squares adjustment that calculates the math model several times to find the best possible solution. The best possible solution is determined when the model has converged to the point that the residual errors of the GCPs and tie points fall within the limit set in the XYZ threshold (Camera Position), the angle threshold, or until the number of iterations limit is reached. Usually, the adjustment converges quickly and using the parameter defaults does not limit the accuracy. By adjusting the thresholds and maximum number of iterations, however, you can control the convergence criteria of the model.

Example

In this example an OrthoEngine project file named "airphoto_model.prj" is processed. The numbers of the math model segments that the adjusted interior and exterior parameter values are written to are listed in file "out.txt".

from pci.apmodel import apmodel

oeproj = 'airphoto_model.prj' # input project file
tfile = 'out.txt' # list the math model segments that hold the adjusted values
maxiter = [10]    # iterate the adjustment a maximum of ten times
xyzthr = []		  # use the default camera position ...
angthr = []		  # ... and orientation angle convergence criteria
radearth =[]      # do not correct for earth curvature
units = 'pixels'  # report residuals in pixel units

apmodel(oeproj, tfile, maxiter, xyzthr, angthr, radearth, units)