APUNDISTORT

Description

Convert aerial photos to conform to the ideal pin-hole camera model by removing lens distortions in image space. If specified, it also computes the ideal coordinates for GCPs and/or Tie points from their observed or matched coordinates in image space.

Parameters

apundistort(oeproji, distort, imgset, oeprojo, outbgd, outdir, resample)

Name	Type	Caption	Length	Value range
OEPROJI *	str	Input OrthoEngine project file	1 -
DISTORT	str	Algorithm to use to undistort photos	0 -	Default: LENS
IMGSET	str	Set of photos to process	0 -	Default: ALL
OEPROJO *	str	Output OrthoEngine project file	1 -
OUTBGD	List[float]	Output background value	0 - 1	Default: 0
OUTDIR	str	Deliverable output file folder (directory)	0 - 256
RESAMPLE	str	Resampling method	0 -	NEAR\|BILIN\|CUBIC\|SINC8\|SINC16\|AVERAGE\|MEDIAN\|LAGRANGE4\|LAGRANGE8\|GAUSSIAN Default: CUBIC

* Required parameter

Parameter descriptions

OEPROJI

The path and file name of the OrthoEngine project file (*.prj) containing the aerial photos to remove distortions.

The aerial camera in the OrthoEngine project file must have undergone a self-calibration. Otherwise, an exception will be thrown.

DISTORT

Specifies the undistort algorithm. The following values are valid:

LENS: This option specifies the type of lens distortion.
- ALL: all of below distortions. This is the default option if not specified.
- GRID: Bingo exported distortion grid.
- RAD: Radial distortion.
- DEC: Decentering distortion.
POINTS: This option specifies which points will be included and thus should remove lens distortions.
- BOTH: Remove image distortions of both GCPs and TPs. This is the default option if not specified.
- GCP: Remove image distortions of GCPs, and delete TPs.
- TP: Remove image distortions of TPs, and delete GCPs.

Example parameter values are:

LENS, POINTS: Remove all lens distortions from photos, and remove coordinate distortions at both GCPs and TPs.
LENS GRID RAD: Remove grid and radial distortions from photos. The decentering distortions will be kept in the output photos if any. In addition, both GCPs and TPs will be deleted in the output OrthoEngine project file.
LENS GRID, POINTS GCP: Remove grid distortions from photos, and remove corrdinate distortions at GCPs. The TPs are deleted in the output OrthoEngine project file.

IMGSET

Specifies which photos should be processed.

Available options are:

ALL (or unspecified): all photos are processed
IMAGES id001,id002,...: specify one or more comma-delimited photo IDs; These photo IDs correspond to the base name.
SUBSET n OF N: images are divided into N subsets and the n-th subset is processed.
file.txt: specify a text file that contains scene IDs of photos to process.
The specified text file contains the following entries for each scene:
```
                    [PHOTOID]
                    
```
where:
- PHOTOID: specifies the base filename of the photo. In rare circumstance, there are two images with the same basename. That means one of the images has assigned a different ID.

OEPROJO

The path and file name of the output OrthoEngine project file to export the undistorted photos.

The output OrthoEngine project file cannot already exisit. If a file with the same name exists, an error message will be thrown.

OUTBGD

The background (NoData) value to use for pixels that are not populated. Each channel is set to the same background value. The background value provided is truncated to the range allowed by the source image data type.

OUTDIR

A folder (directory) to which the distortion-free images will be written. If the folder does not exist, it is created automatically.

If no value is specified for this parameter, a folder that is the basename of OEPROJO is created automatically.

The name of a generated image file has generally the same base name as that of the source image file.

RESAMPLE

The resampling method to use in the undistorting process.

The following methods are supported:

NEAR: nearest neighbor
BILIN: bilinear interpolation
CUBIC: cubic convolution (default)
SINC8,SHAPINGWINDOW=[sw],BETA=[beta]: 8 point sin(x)/x
where:
- SHAPINGWINDOW specifies a window to attenuate the SINC coefficients to reduce resampling artifacts. The value can be KAISER, HAMMING, HANN, LANCZOS, PARABOLA, or NONE. SHAPINGWINDOW is optional; the default value is KAISER.
- BETA is applicable only when the SHAPINGWINDOW is KAISER. It determines the shape of the KAISER window; a larger BETA value produces greater attenuation of the SINC coefficients. Its value can be between 1.0 and 10.0. BETA is optional.
SINC16,SHAPINGWINDOW=[sw],BETA=[beta]: 16 point sin(x)/x
where:
- SHAPINGWINDOW specifies a window to attenuate the SINC coefficients to reduce resampling artifacts. The value can be KAISER, HAMMING, HANN, LANCZOS, PARABOLA, or NONE. SHAPINGWINDOW is optional; the default value is KAISER.
- BETA is applicable only when the SHAPINGWINDOW is KAISER. It determines the shape of the KAISER window; a larger BETA value produces greater attenuation of the SINC coefficients. Its value can be between 1.0 and 10.0. BETA is optional.
AVERAGE,NUMCOLS=[nc],NUMROWS=[nr]: "Average" resampler for generating downsampled products
MEDIAN,NUMCOLS=[nc],NUMROWS=[nr]: "Median" resampler for generating downsampled products. NUMCOLS and NUMROWS can be any value from 1 to 11.
LAGRANGE4: four-point Lagrange interpolation
LAGRANGE8: eight-point Lagrange interpolation
GAUSSIAN,DSFACTORCOL=[dc],DSFACTORROW=[dr]: Gaussian resampler.
where:
- DSFACTORCOL is the fraction downsampling factor in col (>=1). If you do not specify a value, a default factor is computed automatically based on the output and input pixel sizes.
- DSFACTORROW is the fraction downsampling factor in row (>=1). If you do not specify a value, the value of DSFACTORCOL is applied, by default.

For each resampling method, the parameters MIN=[min], MAX=[max], and FILL=[NN or BGD] can be appended as a comma-delimited list. MIN and MAX define the clamp range for output pixels; this is useful when you want to keep pixel values within a certain range (for example, 1 to 2047 if 11-bit data is stored in a 16-bit file). FILL defines the behavior when the resampling window contains NoData pixels: NN directs the resampler to use the nearest-neighbor method, while BGD indicates that the output pixel will be set to the background value. By default, NN is used as the value of FILL.

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

APUNDISTORT resamples raw image to compensate for lens distortions. The lens distortions can be represented in radial, decentering and grid forms. Especially the distortion grid can be a discrete form from a mix of all types of contiguous distortion models such as from various added self-calibration parameters. With BINGO, the grid can even represent non-lens distortions including corrections from atmospheric refraction and/or earth curvature.

This function has two major steps in processing. First, the transformation relationship is established for the distortion-free photos. This is done by computing the actual coordinates on the raw photo given any ideal coordinates on the distortion-free photo using camera's intrinsic parameters. Second, the values of pixels on the distortion-free photo are obtained by a specified resampling method from the raw photos employing the afore-mentioned transformation.

APUNDISTORT output new disotrtion-free photos to the output directory as well as a new OrthoEngine project file.

Example

In the following example, all photos are processed with grid distortions removed, and image observation distortions are removed from GCPs. while all Tie points are deleted from the output OE project file.

from pci.apundistort import apundistort

oeproji = "airphoto_model.prj"
distort = "LENS GRID, POINTS GCP"
imgset = ""
oeprojo = "airphoto_model_undistort.prj"
outbgd = [0]
outdir = ""
resample = "CUBIC"

apundistort(oeproji, distort, imgset, oeprojo, outbgd, outdir, resample)

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