| Environments | PYTHON :: EASI :: MODELER |
| Quick links | Description :: Parameters :: Parameter descriptions :: Details :: Examples :: Related |
| Back to top |
| Back to top |
reg(fili, filo, dbic, dboc, resample, dbgc, order, memsize)
| Name | Type | Caption | Length | Value range |
|---|---|---|---|---|
| FILI * | str | Input file name | 1 - | |
| FILO * | str | Output file name | 1 - | |
| DBIC * | List[int] | Layer or layers to correct | 1 - | |
| DBOC * | List[int] | Corrected output layer | 1 - | |
| RESAMPLE | str | Method of resampling | 0 - 5 | NEAR | BILIN | CUBIC | 8PT | 16PT Default: NEAR |
| DBGC * | List[int] | Input GCP segment | 1 - 1 | |
| ORDER | List[int] | Order of polynomial equation | 0 - 1 | -1 - 5 Default: 1 |
| MEMSIZE | List[int] | Working memory size | 0 - 1 | 0 - 2000 Default: 512 |
| Back to top |
FILI
The name of the input file that contains the uncorrected image data and the GCP segment.
FILO
The name of the output file to which to write the corrected image data. The file must exist before running REG.
DBIC
The image channel or channels from the input file to correct.
DBOC
The channel or channels in the output file to which to write the corrected image data.
RESAMPLE
The resampling method to use during registration.
For more information on the various resampling methods, see Resampling.
DBGC
The segment from the input file that contains the GCPs. Elevation values are ignored during the correction process.
The GCP segment is used to generate the polynomial transformation, which is used to map the uncorrected data to a corrected form. If the output units of the GCP segment are Pixel, REG uses this direct transformation to produce the corrected image.
If the GCP segment output units are not Pixel, REG converts them. That is, the conversion is done if the output units of the GCP segment are the same as the output units of the bounds defined in the georeferencing segment of the corrected image. You can define the output units and bounds for the corrected image database using GEOSET before running REG.
ORDER
The order to use for the regression model that will fit uncorrected-to-corrected GCP coordinates, or uses a -1 flag to indicate that a thin plate spline (TPS) transformation should be used.
To obtain good results, two-to-three times the minimum number of GCPs for a particular order are required; for example, 12-to-18 GCPs for the second order. GCPs should be distributed evenly over the entire uncorrected image.
MEMSIZE
The amount, in megabytes (MB), of internal memory allocated to REG.
The default is 512 MB. A typical amount of memory to allocate is approximately half of the system memory available per processing thread.
| Back to top |
REG performs registration of an input uncorrected image to an output master image, given a set of GCPs.
Registration is to transform and warp one set of image data–the uncorrected image–to register with a second set of data–the corrected, or master image. After registration, the two image sets each have the same scale, rotation, and so forth, and the previously uncorrected image will fit over the master image.
Registration consists of two phases: transformation and resampling. Transformation determines the exact location in the input image of every output pixel. Resampling determines the output-pixel value, based on the input-pixel values in the neighborhood of the transformed location. Registration and resampling are discussed in more detail later in this topic.
The first through fifth polynomial orders, or the TPS transformation, which describes how the uncorrected image data must be warped to fit over the master data, is based on the GCPs stored in a GCP segment. The transformations used in this function are two-dimensional: they use only the horizontal coordinates of the GCPs, and ignore any existing GCP elevations.
The TPS math model is a simple math model in which all the collected GCPs are used simultaneously to compute a transformation. The warping is distributed throughout the image with minimum curvature between the GCPs becoming almost linear 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. However, this also means that the math model does not provide direct means of detecting and correcting errors in GCP coordinates. To verify the derived transformation, you should acquire a number of check points large enough to ensure a thorough verification, such as an amount equal to half the number of GCPs.
To compute a warping transformation accurately, you should collect GCPs at the extremes of the terrain and along the break lines. 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 for the removal of terrain distortions or for images of rough terrain.
Selected input image channels (DBIC) are registered and corrected by using a polynomial transformation of the fifth order or lower, based on GCPs in a specified GCP segment (DBGC). The registered image is stored in the defined output image channels (DBOC) of an output file (FILO). The GCP segment must exist in the input file.
The GCPs used for registration must be acquired using one of the available GCP-acquisition tasks. For a description of the registration model, including how to obtain a report of the specific model that will be used by REG, follow the link to GCPREP under Related functions at the end of this topic.
REG outputs only actual resampled pixels to the output channels (DBOC). While this allows mosaicking of more than one image into the same channels, you must initially run clear the channels by running CLR. For more information, follow the link to CLR under Related functions at the end of this topic.
Transformation is a first-order or higher polynomial or a TPS function, which describes mathematically how to warp the uncorrected image to make it register (fit) over the master image. The transformation is generated automatically from the GCPs in the specified input GCP segment. GCPs are collected and the order of the transformation is modeled based on the order of polynomial equation.
The transformation from the uncorrected image to the corrected image must be resolved pixel-to-pixel. This may be done directly if the GCP segment output units are Pixel in the corrected image.
If the output units of the GCP segment are in units other than Pixel, the georeferencing segment will be read for the corrected image. If the output units of the bounds for the corrected image are the same as that of the GCP segment, REG will use the georeferencing transform to convert the output units of the GCP segment to the equivalent Pixel units. The output units and bounds for the corrected image can be defined by running GEOSET before running REG.
In general, polynomial transformations with terms up to first order (affine) can model only rotation, scaling, and translation, but are economical computationally. As additional terms are added (up to 21 in all, given a fifth-order polynomial), more complex warpings can be achieved at the expense of greater computation time. The TPS function replicates exactly the spatial misregistration at every GCP, interpolates smoothly between GCPs, and becomes linear far from the points.
Resampling is to sample one or more input pixels to create one output pixel. Resampling is distinct from transformation in that it determines where the output pixel lies on the input image. In general, resampling takes a weighted average of a small window of input pixels around a point as determined by transformation. The quality of the corrected output image and the time required to calculate is highly dependent on the selected resampling method.
Nearest: This method takes the single input pixel nearest to the transformed point as the resampled output pixel.
Bilinear: This method takes a weighted average of the four input pixels around the transformed point.
Cubic: REG applies the classic four-point method. This variation of cubic convolution uses a 4 x 4 window of input pixels. This method is closer to the perfect sin(x)/x resampler than Nearest or Bilinear.
Sin(x)/x: REG applies sin(x)/x resampler using either an 8 x 8 (8PT) or 16 x 16 (16PT) window.
Mosaicking
Mosaicking is to patch together juxtaposed or overlapping images from a number of sources into a single output image.
REG writes to the output channel only those pixels whose transformed positions are located within the spatial bounds of the input file. All other output pixels remain unchanged. This ability to 'embed' the registered input image into the output channels provides some mosaicking capability. A limitation of this ability, however, is that you must already have a master image of the entire area represented in the mosaic.
If possible, radiometrically enhance all of the uncorrected input images so there is consistent variation of spectral response; for example, similar brightness and coloring. This is important to minimize apparent 'seams' between images from different sources. For more information on algorithms you can run to enhance your imagery, follow the links to FUN, LUT, and STR under Related functions at the end of this topic.
Clear the output channels in the output file or set them to a background color. This is important; otherwise, the mosaic will be embedded in the random patterns currently in the output channels. For information on setting a background color, follow the link to CLR under Related functions at the end of this topic.
After tie-down of an uncorrected input image, run REG to embed the input image in the output channels. Where overlap occurs with previously embedded images, the overlap is overwritten.
Repeat step 3 for each input image in the mosaic.
Accuracy
Accuracy in registration results in a close match between features in the registered image channels and the corresponding features in the master channel. If the match is poor, these features will be off by one or more pixels. For example, roads that should lie on top of each other are adjacent to each other.
Accurate registration can be achieved only if the distortions between two images are smooth enough to be represented accurately by a low-order, two-dimensional polynomial. However, some distortions, such as terrain-induced shifts, do not satisfy these conditions. In such cases, the proper image-orthorectification process or TPS function must be used.
Poor distribution of GCPs: In general, GCPs should be distributed appropriately over the entire image. If points are clustered in just a few areas, those areas will be registered well and other areas poorly.
Poor quality of GCPs: Often, due to poor images, it is difficult, if not impossible, to be sure of the accuracy of the GCPs. In this case, you should collect as many GCPs as possible.
Inadequate transform model: The order of the warping transform is insufficient to model the error in the image, evidenced by a fit that is generally quite poor. To correct this problem, more terms are required in the warping transform. This can be achieved by collecting more GCPs and specifying a higher order (up to fifth-order). You can determine the best order to use by running GCPREP, and then assessing the lowest residual mean square in the report. In general, use the lowest-order transform possible to achieve high speed of execution without sacrificing accuracy. The compromise varies with the requirements for accuracy and the resolution qualities of the data.
Resampling method used: Nearest resampling is, on average, off by a fraction of a pixel. Bilinear, Cubic, or sin(x)/x (8PT) or (16PT) may yield slightly better registration results.
Time
For example, an affine transform applied to an image with little rotation and using nearest-neighbor resampling may be four-to-five times faster than a registration using a 10-term transformation with a 20-plus-degree rotation and cubic-convolution resampling, even though the input and output files are the same size in both cases.
| Back to top |
Correct a 3-channel input file using cubic-convolution resampling, and write the results to a 3-channel file. The GCPs are stored on segment 2 of the input file. The optimum polynomial order to use was established in modeling the image tie-down by using GCPREP.
from pci.reg import reg fili = 'map100.pix' # input file name filo = 'regout.pix' # ouput file name dbic = [1,2,3] # input channels to correct dboc = [3,2,1] # reverse order of input resample = 'CUBIC' # resampling method dbgc = [2] # GCP segment order = [2] memsize = [] reg( fili, filo, dbic, dboc, resample, dbgc, order, memsize )
Correct a single-channel input SAR file using the nearest-neighbor resampling method, and write the results to a single-channel file. The GCPs are stored in segment 2 of the input file. The TPS transformation is used.
from pci.reg import reg fili = 'rawsar.pix' # input file name filo = 'regsar.pix' # ouput file name dbic = [1] # input channel to correct dboc = [1] # output channel resample= 'NEAR' # resampling method dbgc = [2] # GCP segment order = [-1] # TPS transformation memsize = [128] # memory to use reg( fili, filo, dbic, dboc, resample, dbgc, order, memsize )
© PCI Geomatics Enterprises, Inc.®, 2026. All rights reserved.