User's Guide

GEOM

Geometric rectification program

Function:

Performs the geometric rectification of an image as specified by a previously generated mapping grid using a one-pass, two-dimensional; a two-pass, one-dimensional; or a three-pass, one-dimensional algorithm. Resampling is accomplished using nearest neighbor interpolation, parametric cubic convolution interpolation, bilinear interpolation, or a user-entered table of resampling weights.

Parameters:

IN
Input image. The input image is a single or multi-band file with BYTE, INTEGER*2, INTEGER*4, or REAL*4 data type. Windowing is not allowed; band specifications are.

OUT
Output image. The output image is a single or multi-band file. The output image size is defined by the geometric mapping grid and the input window specification or the output window specification.

INGRID
Input grid file. The geometric mapping grid file contains output line and sample coordinates and their corresponding positions in the input image.

INRWT(--)
Input resampling weight table file. A file containing an externally generated table of resampling weights. This parameter is valid when RESAMP=TABLE. It is ignored for all other resampling methods.

INTLIM(--)
Interpolation limits. The minimum and maximum intensity allowed as a result of resampling. If a null value is received, INTLIM defaults to the maximum range for the image data type used.

ODTYPE(SAME)
Output data type. The data type of the output image.


  = SAME:  Same as input.
  = BYTE:  BYTE      (8-bit unsigned integer)
                     (0 through 255)
  = I*2:   INTEGER*2 (16-bit signed integer)
                     (-32768 through 32767)
  = I*4:   INTEGER*4 (32-bit signed integer)
                     (-2147483648 through 2147483647)
  = R*4:   REAL*4    (32-bit signed real)
                     (System dependent)

WINDOPT(OUT)
Window option. The rectangular image window to be transformed may be specified either in terms of the input image or the output image.


  = IN:   Input window.
  = OUT:  Output window.

If window option OUT is specified, the window coordinates are used directly to select the desired region of the geometric mapping grid. The output window coordinates are relative to the coordinates used to define the mapping grid.

If window option IN is specified, output image position is determined by the input window and the output image size is determined by the geometric mapping grid.

WINDOW(--)
Window specification. The values specifying the upper-left corner of the image window and its size are entered in the following order:


   (SL) Starting line
   (SS) Starting sample
   (NL) Number of lines in window
   (NS) Number of samples per line

If WINDOW is NULL, the entire image is processed according to values contained in the geometric mapping grid and the WINDOPT parameter is ignored.

WARPMETH(ONE)
Warp method. Rectification may be accomplished using one of three different methods:


  = ONE:    One two-dimensional pass.  The image is 
            rectified using one two-dimensional pass 
            through the data.
  = TWO:    Two one-dimensional passes.  The image 
            is rectified using two one-dimensional
            (vertical, horizontal) passes through 
            the data.
  = THREE:  Three one-dimensional passes.  The image 
            is rectified using three one-dimensional 
            (horizontal, vertical, horizontal) passes 
            through the data.

RESAMP(CC)
Resampling method. Pixel values in the output image are determined by finding the corresponding location in the input image. The pixel location in the input image is a floating point value, i.e., it can fall between pixels. A method of interpolating a brightness value for that pixel location is therefore needed.


  = NN:     Nearest neighbor.  Nearest neighbor 
            interpolation uses the brightness value 
            of the pixel closest to the calculated 
            floating point pixel value.
  = BI:     Bilinear.  Bilinear interpolation uses a 
            2 x 2 block of input pixels which surround 
            the calculated floating point pixel value 
            to determine the output pixel brightness 
            value.
  = CC:     Cubic convolution.  Cubic convolution 
            interpolation uses a 4 x 4 block of input 
            pixels which surround the calculated 
            floating point pixel value to determine 
            the output pixel brightness value.
  = TABLE:  Table-based.  Table-based resampling uses 
            a N x M block of input pixels which 
            surround the calculated floating point 
            pixel value to determine the output pixel 
            brightness value.  The dimensions N and M, 
            as well as the resampling kernel 
            (resampling weights), are contained in the 
            user-entered file of resampling weights.

PCCALPHA(-0.5)
Parametric cubic convolution alpha parameter. Commonly used values are -1.0 and -0.5; values -3.0 through 3.0 produce reasonable results. Other values may cause unpredictable results but are permitted for experimental purposes. This parameter is valid when RESAMP=CC. It is ignored for all other resampling methods.

BACKGRND(0.0)
Background value. Gray level fill value assigned to all output pixels which map to locations outside the edges of the input image. If the resampling method is bilinear, cubic convolution, or table-based, an output pixel is considered to fall outside the input image if any of the input pixels needed for the interpolation are at positions outside the input edges.

GRIDFLG(YES)
Grid flag. Flag to determine whether grid correctness should be checked. This option may be useful with certain global projections where grid wrapping occurs. In certain instances, if grid checking is not done, invalid output data may occur.

  = YES:  Check for grid correctness
  = NO:   Do not check for grid correctness

Examples:

  1. LAS> geom in=image.dat ingrid=map.grd out=image.out

    The geometric mapping grid file MAP.GRD is used to map IMAGE.DAT to IMAGE.OUT. Cubic convolution with an alpha parameter of -0.5 is the resampling method used. Since a window was not specified, the output image size is determined by the geometric mapping grid.

  2. LAS> geom in=image.dat ingrid=map.grd out=image.out window=(1,1,512,512) resamp=bi backgrnd=255.0

    IMAGE.DAT will be mapped to IMAGE.OUT. An output window of (1,1,512,512) limits the output image to 512 lines by 512 samples. Bilinear interpolation resampling is used and all background areas are set to 255.0.

  3. LAS> geom in=image.dat ingrid=map.grd out=image.out windopt=in window=(1,1,256,256) resamp=nn

    IMAGE.DAT is mapped to IMAGE.OUT using MAP.GRD. The first 256 lines and 256 samples of the input image will be mapped. The output image size is determined by the mapping grid. Nearest neighbor interpolation is used.

  4. LAS> geom in=image.dat ingrid=map.grd out=image.out window=(1,1,512,512) resamp=table inrwt=tab.tab gridflg=no

    IMAGE.DAT is mapped to IMAGE.OUT using the mapping grid MAP.GRD and table-based resampling. The user-entered table of resampling weights is contained in TAB.TAB. The output image size will be 512 lines by 512 samples. This is the method of operation used (RESAMP=TABLE) when applying a restoration kernel to an image. No grid-wrapping check is performed on the image.

Description/Algorithm:

Parameters are input to the program using TAE. The geometric mapping grid file is then read from disk and is analyzed to determine the input image requirements for each output grid cell. The validity of the grid may be checked at this time. Next, the size of the output image is determined. By default, this is determined by the mapping grid. The user may override this by using the WINDOW and WINDOPT parameters.

If input windowing is used, the output image size is determined by the geometric mapping grid. Input image data processed is limited to the window specified.

If output windowing is used, the output image size is specified by the WINDOW parameter. The input image window is automatically determined based on the output image window and the geometric mapping grid.

If table-based resampling (RESAMP = TABLE) is used, user-generated resampling weights are read from INRWT and checked for validity.

For each output grid cell, interpolation variables are initialized, required image lines are loaded into memory and resampling is performed. Resampling is accomplished using one of three different methods:


  1.  One-pass, two-dimensional method:

      The image is resampled in one two-dimensional pass through
      the data.  The output is written to a temporary output file.
      This method is radiometrically the most accurate of the two;
      however, it also contains the most computations.  This method
      may be used with any degree of rotation.

  2.  Two-pass, one-dimensional method:

      The image is resampled in two one-dimensional passes.  In 
      the first pass, the image is resampled in the vertical 
      direction.  During the second pass, horizontal resampling is 
      performed.  It is recommended that this method only be used 
      for angles of rotation less than +/- 30 degrees.  It contains 
      fewer computations than the one-pass method and is
      significantly faster.  It does, however, cause errors which 
      are visible with more than +/- 30 degrees of rotation or 
      sooner if the image is enlarged.

  3.  Three-pass, one-dimensional method:

      The image is resampled in three one-dimensional passes.  In 
      the first pass, the image is oversampled in the horizontal
      direction by a factor of (tan x + 1), where x is the angle of
      rotation.  During the second pass, vertical resampling is 
      performed.  The third and final pass resamples in the horizontal
      direction and undersamples the resulting image by (tan x + 1).
      It is recommended that this method only be used for angles of 
      rotation less than +/- 45 degrees.  It contains fewer 
      computations than the one-pass method.

When the entire grid has been processed, the individual grid cell images are reblocked to form the output image.

If the input image is large, the output image may be obtained in segments by specifying consecutive output windows and consecutive runs of GEOM. The resulting output image segments may be combined using the program CONCAT. This method of processing works only with output windows because a rectangular space is defined in the output image area. Input windowing defines a rectangular area in input space which is then possibly warped to a nonrectangular output space--and thus neighboring windows will not combine easily.

Nonfatal Error Messages:

  1. [geom-background] BACKGRND out of range, Background is set to zero

    The background parameter given was out of range for the data type of the image. The background is set to zero and processing continues.

  2. [geom-limits] INTLIM out of range, INTLIM adjusted to range of data type

    The minimum and maximum interpolation values given were out of the range of the data type of the image. The minimum interpolation value is set to the smallest value for the data type and the maximum interpolation value is set to the largest value for the data type. Processing continues.

  3. [geom-warn] Nonfatal error encountered

    A nonfatal error was encountered during processing. The program's data is probably valid and therefore saved. The message displayed immediately preceding this error message is the specific error encountered. Processing continues.

Fatal Error Messages:

  1. [geom-fatal] Fatal error encountered

    A fatal error was encountered during processing. The error message displayed immediately preceding this message is the specific error encountered. Processing is terminated.

  2. [geom-alloc] Error allocating memory

    An error occurred allocating memory. Rerun the function, and if the error reoccurs, process the image in segments as described by the Description/Algorithm section. If the error again reoccurs, notify the system manager.

  3. [geom-dtype] Data type must be same for all input images

    The data type of each input image must be the same. Grid cell and input image statistics are calculated only once; the requirements change when the image data types change. Correct the input images to be the same data type or run them separately.

  4. [geom-size] Input images must be the same size

    The input images must be of the same size. Grid cell and input image statistics are calculated only once; the requirements change when the image sizes change. Correct the input images to be the same size or run them separately.

  5. [geom-outwind] Output window falls outside mapping grid

    All or part of the output window falls outside the mapping grid. Correct the window to be within the mapping grid.

  6. [geom-tempfi] Error creating temp file

    An error occurred while creating the temporary blocking file. Verify there is enough disk space available for the input image, the reblocking file, and the output image. Each band of input data has its own reblocking file. The reblocking file is roughly the same size as a single-band output image.

  7. [geom-tempio] Error writing to temp file

    An error occurred while attempting to write to the temporary blocking file. Check the amount of disk available. Each band of input data has its own reblocking file. The reblocking file is roughly the same size as an output image band.

  8. [geom-badgridl] Grid lines wrapped or not strictly increasing

    The line coordinates in the part of the geometric mapping grid that defines input space locations must be strictly increasing. GEOM detected this error in the grid file. It is also possible that the grid is wrapping back onto itself. Correct the mapping grid. This may involve changing control point or tie point distributions.

  9. [geom-badgrids] Grid samples wrapped or not strictly increasing

    The sample coordinates in the part of the geometric mapping grid that defines input space locations must be strictly increasing. GEOM detected this error in the grid file. It is also possible that the grid is wrapping back onto itself. Correct the mapping grid. This may involve changing control point or tie point distributions.

  10. [geom-double] Grid has double-valued input

    The geometric mapping grid parameters specify a grid cell having double-valued input. Correct mapping grid.

  11. [geom-outside] Output window outside image

    The output window specified lies entirely outside of the input image. Check the window parameters and the geometric mapping grid for errors.

  12. [geom-byte] Only BYTE images are allowed

    The two-pass resampling (WARPMETH=TWO) works on byte data only.

  13. [geom-find] Error calculating the resampling coefficients

    For one-pass resampling, the grid scale and/or grid coordinates are too large for the fixed point coefficients to be computed. For twoand three-pass resampling, there was an error allocating memory for the coefficients. See error 2 for more information.

User Notes:

  1. File descriptions of the geometric mapping grid file and the resampling weight table file may be found in the LAS Programmer's Manual.

  2. Geometric mapping grid files are created by the ROTRNSCL, GRIDGEN, POLYFIT, REMAP, and GRIDFORM modules.

  3. GEOM requires mapping grids be in the LAS geometric mapping grid standard format. Users having grids with other formats may reformat their grids using GRIDFORM.

  4. Resampling weight table files may be generated with the RTABLE module.

  5. Two-pass resampling (WARPMETH=TWO) works on byte data only and does not include the nearest neighbor resampling method.

  6. For nearest neighbor resampling, use WARPMETH=ONE. This is the fastest way to map an image with nearest neighbor resampling.

  7. A few cases have arisen for which the resampling grid scale and/or coordinates are too large for a one-pass resampling. Such cases will result in error 13 listed above. The multipass options will probably work with these larger grids.