User's Guide

ROTRNSCL

Defines rotation, translation, and scaling of an image

Function:

Generates a mapping grid which corresponds to a linear transformation representing a combination of rotation, translation, and geometric scaling.

Parameters:

Subcommand -EXPLICIT:

Transformation defined by entering explicit parameters. The transformation is defined by a rotation angle, a pivot point, and pre- and post-scaling.

OUTGRID
Output grid file. The resulting output geometric mapping grid file is in the format as required by RESAMPLE. The geometric mapping grid file contains output line and sample coordinates and their corresponding positions in the input image. The polynomial used in grid creation is also included, as is projection-related information if it is given.

NL
Number of lines. Defines the number of lines in the output image created when the geometric mapping grid is applied through RESAMPLE.

NS
Number of samples. Defines the number of samples in the output image created when the geometric mapping grid is applied through RESAMPLE.

ROTANG(0.0)
Rotation angle. The positive or negative rotation angle in degrees relative to either the image center or a user-defined pivot point. A positive angle represents a clockwise rotation and a negative angle represents a counterclockwise rotation.

ROTOPT(CENTER)
Rotation option. Specifies whether the rotation is about the center of the grid or about a user-specified pivot point.
  = CENTER:  Rotate around center of grid       
  = PIVOT :  Rotate around specified pivot point
PIVCOORS(--)
Pivot coordinates. The pivot coordinates about which rotation occurs. The values are entered in the following order: input line, input sample and corresponding output line, output sample. PIVCOORS should only be specified if ROTOPT=PIVOT; otherwise, it is ignored.

SCALFACT(1.0,1.0,1.0,1.0)
Scale factors. The horizontal and vertical scale factors to apply before rotation, followed by the horizontal and vertical scale factors to apply after rotation.

IN(--)
Input image. If an image name is given, the image's DDR is read to obtain projection-related information for the geometric mapping grid and the resulting output image when RESAMPLE is run. Projection information is adjusted in the usual way if a window specification is given with the image name.

Subcommand -DIRECT:

Transformation defined by the coefficients a through f. The transformation is defined by supplying the coefficients a through f.

OUTGRID
Output grid file. The resulting output geometric mapping grid file is in the format as required by RESAMPLE. The geometric mapping grid file contains output line and sample coordinates and their corresponding positions in the input image. The polynomial used in grid creation is also included, as is projection-related information if it is given.

NL
Number of lines. Defines the number of lines in the output image created when the geometric mapping grid is applied through RESAMPLE.

NS
Number of samples. Defines the number of samples in the output image created when the geometric mapping grid is applied through RESAMPLE.

TRANCOEF
Transformation coefficients. The transformation coefficients a through f. The general linear transformation--giving the input line and sample locations (in_line,in_samp) in terms of output coordinates (out_line,out_samp)--is of the form:
        in_line = a(out_line) + b(out_samp) + c
        in_samp = d(out_line) + e(out_samp) + f
Enough values must be nonzero that (ae - bd) is nonzero.
IN(--)
Input image. If an image name is given, the image's DDR is read to obtain projection-related information for the geometric mapping grid and the resulting output image when RESAMPLE is run. Projection information is adjusted in the usual way if a window specification is given with the image name.

Subcommand -INVERT:

Transformation defined by the coefficients a' through f'. The transformation is defined by supplying the coefficients a' through f'.

OUTGRID
Output grid file. The resulting output geometric mapping grid file is in the format as required by RESAMPLE. The geometric mapping grid file contains output line and sample coordinates and their corresponding positions in the input image. The polynomial used in grid creation is also included, as is projection-related information if it is given.

NL
Number of lines. Defines the number of lines in the output image created when the geometric mapping grid is applied through RESAMPLE.

NS
Number of samples. Defines the number of samples in the output image created when the geometric mapping grid is applied through RESAMPLE.

TRANCOEF
Transformation coefficients. The transformation coefficients a' through f'. The inverse linear transformation--giving the output line and sample locations (out_line,out_samp) in terms of input coordinates (in_line,in_samp)--is of the form:
        out_line = a'(in_line) + b'(in_samp) + c'
        out_samp = d'(in_line) + e'(in_samp) + f'
Enough values must be nonzero that (a'e' - b'd') is nonzero.
IN(--)
Input image. If an image name is given, the image's DDR is read to obtain projection-related information for the geometric mapping grid and the resulting output image when RESAMPLE is run. Projection information is adjusted in the usual way if a window specification is given with the image name.

Subcommand -TWOPTS:

Transformation defined by two tie point pairs. The transformation is defined by supplying coordinates of two tie point pairs.

OUTGRID
Output grid file. The resulting output geometric mapping grid file is in the format as required by RESAMPLE. The geometric mapping grid file contains output line and sample coordinates and their corresponding positions in the input image. The polynomial used in grid creation is also included, as is projection-related information if it is given.

NL
Number of lines. Defines the number of lines in the output image created when the geometric mapping grid is applied through RESAMPLE.

NS
Number of samples. Defines the number of samples in the output image created when the geometric mapping grid is applied through RESAMPLE.

TVAL
Tie point values. A set of four tie point pairs giving line and sample coordinates relative to the input image and line and sample coordinates relative to the output image for the first tie point; followed by tie point pairs giving line and sample coordinates relative to the input image and line and sample coordinates relative to the output image for the second tie point. The tie points may not coincide in either input or output space, so not all values in TVAL may be zero.

IN(--)
Input image. If an image name is given, the image's DDR is read to obtain projection-related information for the geometric mapping grid and the resulting output image when RESAMPLE is run. Projection information is adjusted in the usual way if a window specification is given with the image name.

Examples:

LAS> rotrnscl-explicit outgrid=grid.r1 nl=512 ns=512 rotang=45
Produces a geometric mapping grid corresponding to a 45 degree clockwise rotation of the input image about its center. The geometric mapping grid produces a 512 x 512 image when used by RESAMPLE.
LAS> rotrnscl-explicit outgrid=grid.r2 nl=512 ns=512 rotang=10 rotopt=pivot pivcoors=(1,1,100,100)
A geometric mapping grid is produced that corresponds to a translation of the input point (1,1) to the output point (100,100), about which there is a clockwise rotation of 10 degrees. The geometric mapping grid produces a 512 x 512 image when used by RESAMPLE.
LAS> rotrnscl-direct outgrid=grid.r4 nl=512 ns=512 trancoef=(1,0,100,0,1,200)
A mapping grid is produced that translates the image by 100 lines and 200 samples.
LAS> rotrnscl-twopts outgrid=grid.r5 nl=512 ns=512 tval=(1,1,100,100,500,500,400,400)
A mapping grid is produced in which the point (1,1) is translated to (100,100) and (500,500) is translated to (400,400).
LAS> rotrnscl-explicit outgrid=grid.r1 nl=512 ns=512 rotang=-45 in=image.dat
Produces a geometric mapping grid corresponding to a 45 degrees counterclockwise rotation of the input image about its center. The geometric mapping grid produces a 512 x 512 image when used by RESAMPLE. Projection-related information is read from the IMAGE.DAT DDR file and is used in calculating projection coordinates of the output space defined by the geometric mapping grid. In this example, the projection coordinate system is rotated -45 degrees from the image coordinate system.

Description/Algorithm:

Computation of Transformation Coefficients From Explicit Geometric Operators: ___________________________________________________________________________
The general linear transformation giving the input line and sample positions (in_line,in_samp) in terms of output coordinates (out_line,out_samp) is of the form:
  in_line = a(out_line) + b(out_samp) + c                      (1)

and

  in_samp = d(out_line) + e(out_samp) + f                      (2)
If (in_line',in_samp') and (out_line',out_samp') are the coordinates of a pivot point (PIVCOORS), ROTANG is the clockwise angle of rotation about the pivot point, (s_line,s_samp) are the scale factors applied to the input image, and (s_line',s_samp') are the scale factors applied to the rotated image, then the relation between input and output coordinates can be expressed as:
  s_line(in_line - in_line') = 
           -(1.0/s_samp')(out_samp - out_samp') sin ROTANG +
            (1.0/s_line')(out_line - out_line') cos ROTANG     (3)

and

  s_samp(in_samp - in_samp') = 
            (1.0/s_samp')(out_samp - out_samp') cos ROTANG +
            (1.0/s_line')(out_line - out_line') sin ROTANG     (4)
Expressions for the coefficients a through f in equations 1 and 2 in terms of the scale factors, pivot point coordinates, and rotation angle are obtained by solving equations 3 and 4 for in_line and in_samp.
Inversion of Transformation Coefficients:
________________________________________
Sometimes it is more convenient to define the output coordinates in terms of the input coordinates:
  out_line = a'(in_line) + b'(in_samp) + c'                    (5)

and

  out_samp = d'(in_line) + e'(in_samp) + f'                    (6)
This transformation can be inverted by solving the system of equations 5 and 6 for in_line and in_samp, giving:
  in_line = (e'/D)out_line - (b'/D)out_samp + (b'f' - e'c')/D  (7)

and

  in_samp = -(d'/D)out_line + (a'/D)out_samp + (d'c' - a'f')/D (8)
where the value of the determinant is D = a'e' - b'd'. These equations are in the form of equations 1 and 2.
Computation of Transformation Coefficients From Tie Points:
__________________________________________________________
Two tie points may be used to specify a rotation, translation, and uniform scaling of an image by giving the input coordinates (in_line',in_samp') and (in_line'',in_samp'') of the two points and the corresponding output coordinates (out_line',out_samp') and (out_line'',out_samp''). The mapping is more easily given in terms of equations 3 and 4, where the parameters are:
  s_line = s_samp = 1                                          (9)

  s_line' = s_samp' = out_dist/in_dist                        (10)

  sin ROTANG = [(in_samp'' - in_samp')(out_line'' - out_line')
             - (in_line'' - in_line')(out_samp'' - out_samp')] 
             / (in_dist)(out_dist)                            (11)

  cos ROTANG = [(in_samp'' - in_samp')(out_line'' - out_line')
             + (in_line'' - in_line')(out_line'' - out_line')] 
             / (in_dist)(out_dist)                            (12)
and the distances between tie points in input and output coordinates are:
  in_dist = [(in_samp'' - in_samp')**2 + 
             (in_line'' - in_line')**2]**1/2                  (13)

and

  out_dist = [(out_samp'' - out_samp')**2 +
             (out_line'' - out_line')**2]**1/2                (14)
Again, coefficients a through f of equations 1 and 2 are obtained from equations 3 and 4 after the expressions in equations 9 through 14 have been evaluated.

Nonfatal Error Messages:

[rotrnscl-warn] Nonfatal error encountered
A nonfatal error was encountered during processing. The error message that is displayed immediately preceding this message is the specific error that was encountered. Processing continues.
[rotrnscl-noproj] Projection information not available
Projection information either could not be read from the image DDR or it was invalid. In either case, the projectionrelated fields of the geometric mapping grid cannot be calculated. This warning message is given only if an input image name was supplied by the user.

Fatal Error Messages:

[rotrnscl-fatal] Fatal error encountered
The error message that is displayed immediately preceding this message is the specific error that was encountered. Processing is terminated.
[rotrnscl-scale] Scale out of range
The absolute value of the scale factor is outside the range [.01,100]. Check the tie point coordinate entries and the ratio do/di in equation 10 of the description/algorithm section.
[rotrnscl-zero] Determinant too near zero
The determinant of coefficients to be inverted is too near to zero. Check the entries for TRANCOEF.
[rotrnscl-tiepts] Tie points coincide
Tie points are coincident in either the input or the output space. Check the tie point coordinate entries.
[rotrnscl-alloc] Error allocating memory
An error occurred allocating memory for the output geometric mapping grid file. Rerun the function, and if the error reoccurs, contact the system manager.
[rotrnscl-invalid] NL/NS must be greater than zero
The NL (also NS) parameter was specified to be an invalid value. If specified, it must be greater than zero.

User Note:

The maximum grid size is 4095 x 4095. It is suggested that the user not actually make grids this dense since it would consume greater than 250 MB of memory.
The output geometric mapping grid file is used by the program RESAMPLE for performing the geometric transformation corresponding to the mapping contained in the grid.