User's Guide

FINITE

Creates a Geometric or Radiometric Mapping Grid using the finite element method (triangulation) for surface fitting.

Function:

Creates a geometric or radiometric mapping grid using the finite element method (triangulation) for surface fitting.

Parameters:

Subcommand -RADIOMETRIC:
Creates a radiometric mapping grid file. Creates a radiometric mapping grid file to be used by radiometric mapping routines.

INFILE
Input file. INFILE is an IBIS file in graphics format and contains point number, line, sample, and brightness shift values. These points are used to generate a grid that radiometrically adjusts an image. The maximum number of points is 900.

OUTGRID
Output grid file. This output radiometric mapping grid file contains the line/sample locations and brightness shift values needed by radiometric mapping routines in order to alter the brightness values of an image.

GRIDSPEC
Grid boundary specifications. Using line/sample coordinates, specify the upper-left corner of the output grid and the number of lines and samples the output grid will represent.

NLGRID(-- )
Number of lines per grid. The number of lines contained in each output grid cell. If NLGRID is NULL, the radiometric mapping grid size is set to the maximum and then reduced according to the TOLVAL parameter.

NSGRID(-- )
Number of samples per grid. The number of samples contained in each output grid cell. If NSGRID is NULL, the radiometric mapping grid size is set to the maximum and then reduced according to the TOLVAL parameter.

TOLVAL(0.5)
Tolerance value. Tolerance (in pixel values) for reducing the density of radiometric mapping grid points. If NLGRID and NSGRID are not NULL, the TOLVAL parameter is ignored.

DUPRAD(0)
Duplicate radius. Radius of area where input control points are considered duplicate. The first of the duplicate points is used in the finite element surface fitting.

CORNOPT(AVERAGE)
Corner option. This determines how the brightness shift value of the four triangulation corner points projected outside the image area are assigned.


  = FIRST:   First order fit.  The brightness shift 
	     values of the triangulation corner 
	     points are calculated from a first order
             fit of the brightness shift values of 
             the first 160 input points.
  = AVERAGE: Average.  The brightness shift values of
	     the triangulation corner points are cal-
             culated from the average of all the 
	     brightness shift values of the input 
             points.
  = USER:    User specified.  The brightness shift 
	     values of the triangulation corner 
	     points are user defined using the param-
             eter CORNVALS.

NOTE:  See the User Notes section for detailed 
       diagram of a triangulized surface.

CORNVALS(--)
Corner values. These are the brightness shift values that are associated with the four triangulation corner points. CORNVALS is only used when USER is specified in the CORNOPT parameter. The values should be entered in this order:


	LEFT, LOWER, UPPER, RIGHT 

NOTE:  See the User Notes section for detailed
       diagram of a triangulized surface.

OUTPLOT(--)
Output plot file. Name of plot file containing the triangular network in output coordinates. Each record contains a line segment and is stored as:


	TRIANGLE NUMBER, OUTPUT LINE, OUTPUT SAMPLE, 
	DELTA LINE, DELTA SAMPLE

OUTFORM(SHORT)
Output format.


  = SHORT:  Short form.  The print-out contains a 
            summary of the triangulation process.
  = LONG:   Long form.  The print-out contains the
            same information as the short form and 
            also includes all the point residuals 
            from the polynomial fit that is per-
            formed on each of the triangles.	

PRINT(TERM)
Output destination. The destination of the output.


  = TERM:      Terminal.  Output is sent to the
               user's terminal.
  = LP:        Line printer.  Output is sent to the 
               printer defined by $PRINTER.
  = Filename:  User-supplied filename.  Output is 
               sent to the user-supplied file with 
               the extension ".prt".
Subcommand -GEOMETRIC:
Creates a geometric mapping grid file. Creates a geometric mapping grid file for use in the rectification process.

INFILE(--)
Input file. INFILE is an IBIS file in graphics format and contains point number, output line/sample locations, and input line/sample location shift values. These points are used to generate a grid that geometrically adjusts an image. The maximum number of tie point pairs is 900.

INFILE and/or INTL need to be specified. If both INFILE and INTL are specified, the points are read from INFILE and the projection corners (and related information) of the output space are read from INTL.

If only INFILE is specified, the points are read from INFILE and the projection corners (and related information) of the output space are invalidated.

INTL(--)
Input tie point location file. The tie point location file containing the tie point coordinate pairs to be used in calculating the output geometric grid. The maximum number of tie point pairs is 900.

INFILE and/or INTL need to be specified. If both INFILE and INTL are specified, the points are read from INFILE and the projection corners (and related information) of the output space are read from INTL.

If only INTL is specified, both the points and the projection corners (and related information) of the output space are read from INTL.

OUTGRID
Output grid file. This output geometric mapping grid file contains the output line/sample locations and input line/sample locations needed by geometric rectification routines in order to alter the line/sample locations of an image.

GRIDSPEC
Grid boundary specifications. Using line/sample coordinates, specify the upper-left corner of the output grid and the number of lines and samples the output grid will represent.

NLGRID(-- )
Number of lines per grid. The number of lines contained in each output grid cell. If NLGRID is NULL, the geometric mapping grid size is set to the maximum and then reduced according to the TOLVAL parameter.

NSGRID(-- )
Number of samples per grid. The number of samples contained in each output grid cell. If NSGRID is NULL, the geometric mapping grid size is set to the maximum and then reduced according to the TOLVAL parameter.

TOLVAL(0.015625)
Tolerance value. Tolerance (in pixel values) for reducing the density of geometric mapping grid points. If NLGRID and NSGRID are not NULL, the TOLVAL parameter is ignored.

DUPRAD(0 )
Duplicate radius. Radius of area where input control points are considered duplicate. The first of the duplicate points is used in the finite element surface fitting.

INPLOT(--)
Input plot file. Name of plot file containing the triangular network in input coordinates. Each record contains a line segment and is stored as:


	TRIANGLE NUMBER, OUTPUT LINE, OUTPUT SAMPLE, 
	DELTA LINE, DELTA SAMPLE

OUTPLOT(--)
Output plot file. Name of plot file containing the triangular network in output coordinates. Each record contains a line segment and is stored as:


	TRIANGLE NUMBER, OUTPUT LINE, OUTPUT SAMPLE, 
	DELTA LINE, DELTA SAMPLE

OUTFORM(SHORT )
Output format.


  = SHORT:  Short form.  The print-out contains a 
            summary of the triangulation process.
  = LONG:   Long form.  The print-out contains the
            same information as the short form and 
            also includes all the point residuals 
            from the polynomial fit that is per-
            formed on each of the triangles.	

PRINT(TERM )
Output destination. The destination of the output.


  = TERM:      Terminal.  Output is sent to the
               user's terminal.
  = LP:        Line printer.  Output is sent to the 
               printer defined by $PRINTER.
  = Filename:  User-supplied filename.  Output is 
               sent to the user-supplied file with 
               the extension ".prt".

Examples:

  1. LAS> finite-radiometric infile=in.dat outgrid=grid.dat gridspec=(1,1,3600,3600) nlgrid=100 nsgrid=100 cornopt=average

    The points are read from IN.DAT. Any points that have exactly the same line/sample locations are considered duplicate as DUPRAD=0. GRID.DAT contains a uniform, rectangular, radiometric mapping grid consisting of line/sample locations and brightness values which were derived from a finite element surface interpolation of the points in IN.DAT. The number of lines and samples that are within the row and column cells of the GRID.DAT is 100 each. The output grid does not have a line/ sample location lower than 1,1 or greater than 3600,3600.

    The four triangulation corner points receive a brightness shift value which is the average of all the brightness shift values. There is no plot file created. The short output format is printed to the terminal.

  2. LAS> finite-geometric infile=in.dat outgrid=grid.dat gridspec=(100,100,1114,1121) nlgrid= -- nsgrid= -- tolval=0.1 duprad= 2.5 inplot=plin.dat outplot=plout.dat outform=long print=finite1

    The points are read in from IN.DAT. Any points that are within 2.5 pixels of each other are considered duplicate. If any duplicate points are found, the first of the duplicate points is used in the triangulation process. GRID.DAT contains a uniform, rectangular, geometric mapping grid which was derived from a finite element surface interpolation of the points in IN.DAT. The number of rows and columns that are generated for GRID.DAT is at the most 4095 in each direction. The grid points that are within 0.1 pixels of each other are thrown out. The output grid does not have a line/ sample location lower than 100,100 or greater than 1213,1222.

    The input plot file is called PLIN.DAT and output plot file is called PLOUT.DAT. The long output format is printed to a file named FINITE1.PRT.

  3. LAS> finite-geometric intl=in.dat outgrid=grid.dat gridspec=(100,100,1024,1024) nlgrid=50 nsgrid=50 tolval = 0.1 duprad=2.5 inplot=plin.dat outplot=plout.dat outform=long print=finite2

    The points are read in from IN.DAT. Any of the points that are within 2.5 pixels of each other are considered duplicate. If any points are considered duplicate, only the first of the duplicate points are used in the triangulation process. GRID.DAT contains a uniform, rectangular, geometric mapping grid which was derived from a finite element surface interpolation of the points in IN.DAT. The number of lines and samples that are between the row and column cells of GRID.DAT are 50 in each direction. The value specified for TOLVAL is ignored. The output grid does not have a line/sample location lower than 100,100 or greater than 1123,1123.

    The input plot file is called PLIN.DAT and output plot file is called PLOUT.DAT. The long output format is printed to a file named FINITE2.PRT.

Description/Algorithm:

Subcommand -RADIOMETRIC:  
_______________________

After reading the input parameters, INFILE and OUTGRID are opened for read and write, respectively. The point locations and brightness shift values are read in and the following steps are performed on the points.


   1.  A first order polynomial is performed on the first
       160 points and the coefficients are reported to the
       user to be used as a reference.

   2.  The brightness shift values of the four triangulation 
       corner points projected outside the image border are 
       calculated as specified by the parameter CORNOPT.

   3.  The location of the four triangulation corner locations 
       are calculated as follows:
	 left point = minline - delta, (minsamp + maxsamp)/2
	 top point = (minline + maxline)/2, maxsamp + delta
	 right point = (minline + maxline)/2, minsamp - delta
	 bottom point = maxline + delta, (minsamp + maxsamp)/2
       where
	 minline, maxline = the minimum and maximum line 
	 locations of the input points
	 minsamp, maxsamp = the minimum and maximum sample 
	 locations of the input points
	 delta = 5 * (maxline - minline + maxsamp - minsamp)

   4.  The control points are triangulized using the "Greedy" 
       triangulation method.

   5.  The triangle which contains each output grid intersection
       is located, and the radiometric difference value is com-
       puted based on the first order polynomial fit of the three
       vertices of the triangle.

After all the points are processed and the grid is written to the output file--all the files are closed and the completion message is displayed.

Subcommand -GEOMETRIC:  
_____________________

After reading the input parameters, INFILE and/or INTL and OUTGRID are opened for read and write, respectively. The point pair locations are read in and the following steps are performed on the points.


   1.  A first order polynomial is performed on the first
       160 points and the coefficients are reported to the
       user to be used as a reference.

   2.  The location of the four triangulation corner points 
       that lie far outside the image border are calculated 
       as follows:
	 left point = minline - delta, (minsamp + maxsamp)/2
	 top point = (minline + maxline)/2, maxsamp + delta
	 right point = (minline + maxline)/2, minsamp - delta
	 bottom point = maxline + delta, (minsamp + maxsamp)/2
       where
	 minline, maxline = the minimum and maximum line 
	                    locations of the input points
	 minsamp, maxsamp = the minimum and maximum sample 
	                    locations of the input points
	 delta = 5 * (maxline - minline + maxsamp - minsamp)

   3.  The control points are triangulized using the "Greedy"
       triangulation method.

   4.  The triangle which contains each output grid intersection
       is located, and the radiometric difference value is com-
       puted based on the first order polynomial fit of the three
       vertices of the triangle.

After all the points are processed and the grid is written to the output file--all the files are closed and the completion message is displayed.

Nonfatal Error Messages:

  1. [finite-close] Error closing input file

    An error was encountered while closing the input file. The data may still be valid.

  2. [finite-free] Error freeing dynamic memory

    An error occurred freeing dynamic memory. Contact the System Manager.

  3. [finite-ncolumns] Number of grid columns exceeded maximum [finite-ncolumns] Number of grid columns set to maximum

    The number of geometric mapping grid columns exceeded the maximum allowed. This error occurs when the user enters too small a grid spacing (NSGRID) for the GRIDSPEC specified. The number of columns is set to the maximum.

  4. [finite-nrows] Number of grid rows exceeded maximum [finite-nrows] Number of grid rows set to maximum

    The number of geometric mapping grid rows exceeded the maximum allowed. This error occurs when the user enters too small a grid spacing (NLGRID) for the GRIDSPEC specified. The number of rows is set to the maximum.

  5. [finite-warn] Nonfatal error encountered

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

Fatal Error Messages:

  1. [finite-alloc] Error allocating dynamic memory

    An error occurred allocating dynamic memory. Contact the System Manager.

  2. [finite-fatal] Fatal error encountered

    A fatal error was encountered during processing. The output grid file may or may not be deleted. The message that is displayed immediately preceding this error message is the specific error that was encountered.

  3. [finite-grid] A grid intersection is not in a triangle

    The grid boundary specifications are too large for the triangulation network. Respecify the parameter GRIDSPEC.

  4. [finite-file] INFILE and/or INTL must be specified

    Either INFILE and/or INTL file must be specified as input. Specify INFILE and/or INTL depending on the file type.

  5. [finite-max] Maximum number of points has been reached

    The number of input point pairs is greater than 900. FINITE can only handle 900 input point pairs. Specify a file with only 900 or less point pairs.

  6. [finite-open] Cannot open <XXXXXX> file

    The <XXXXXX> file could not be opened and processing is terminated. Verify that the <XXXXXX> file exists.

  7. [finite-read] Error reading <XXXXXX> file

    The <XXXXXX> file could not be read; and therefore, an output file cannot be created. Verify that the format of the file is correct.

  8. [finite-tiepoint] A minimum of four sets of tie points are needed

    At least four tie points are needed to do the finite element mapping. Create a file with at least four tie points.

  9. [finite-write] Error encountered writing to <XXXXXX>

    An error occurred while trying to write to the <XXXXXX> file. Check output parameters or free disk space.

  10. [finite-invalid] <XXXXX> must be greater than zero

    The input parameter <XXXXX> was set to be less than 1 by the user. Try again with a valid value.

User Notes:

  1. Refer to the Geometric Manipulation Package Overview Document (GEOMPOD) for detailed discussions of geometric gridding techniques and the grid reduction technique.

  2. A diagram of the triangulized surface and the four triangulation corner points follows.