fastreg - Registers 2-D data to a user-defined base map and projection.

SYNOPSIS

fastreg  [ parameter=value ... ]  [ inputfile outputfile ]
fastreg  [ parameter=value ... ]  [ inputfile ... directory ]

fastreg2  [ parameter=value ... ]  [ inputfile outputfile ]
fastreg2  [ parameter=value ... ]  [ inputfile ... directory ]

Parameters for fastreg are: master_file, include_vars, poly_size, max_memory, split_aspect.

Parameters for fastreg2 are: master_file, master_var, include_vars, brute_force, poly_size, interpolate, min_good, off_protect, whole_input, add_to_output, add_method, max_memory, split_aspect, sensor_resol.

DESCRIPTION

fastreg and fastreg2 register variables from input datasets to a user-defined base map and projection (meaning a master dataset - see master). For each input dataset, a corresponding output dataset is created to hold the re-mapped variables.

Registration can be applied to any earth locatable 2- or 3-D variables with Y and X coordinate dimensions (e.g., line and sample). All output registered variables will have the same Y and X dimensions, i.e., the line and sample dimension from the master dataset, regardless of their input resolutions.

fastreg does not support any special features for encountering missing (bad) data or change in pixel resolution during registration. However, functions such as magnify or smear can be run prior to registration using fastreg. See magnify and smear.

fastreg2 supports similar magnification and shrinking strategies to those supported by magnify: nearest neighbor, nearest good neighbor, bilinear interpolation, and cubic convolution. Bilinear interpolation within a given rectangle requires at least 3 good corner values, or else the result is missing (bad). Cubic convolution is essentially a 3x3 boxcar average, though a minimum number of good values other than 9 can be specified.

Using fastreg2 with the nearest neighbor strategy is the same as running fastreg.

Registration is defined by the following process:

For each variable V in the output dataset (and corresponding
variable V' in the input dataset)

    For each pixel V(Y,X)   (Y = line, X = sample)

        Compute the corresponding latitude and longitude

        Compute the corresponding real coords (Y',X') of V'

        If the (Y',X') cannot be computed or is outside the
        dimensions of V'

            Set V(Y,X) = bad value of V'
        Else
            Set V(Y,X) = F(V',Y',X'), where F is either
              nearest neighbor, nearest good neighbor,
              bilinear interpolation or cubic convolution.

fastreg and fastreg2 speed up the registration process by using piecewise polynomial interpolation. The output dataset is divided up into nearly square regions of size poly_size (see diagram below), each of which is covered by its own pair of biquadratic polynomials:

Tl(output line, sample) = input line Ts(output line, sample) = input sample

where Tl and Ts represent biquadratic functions (bivariate polynomials of order 2 with 9 coefficients), which are based on the 9 line and sample pairs from the input and output datasets. Line and sample from the output dataset are always integers while input line and sample values are computed as real numbers.

               |    poly size    |    poly size    |
            ---#--------#--------#--------#--------#--
               |                 |                 |
               |                 |                 |
          poly |                 |                 | poly
          size #        #        #        #        # size
               |                 |                 |
               |                 |                 |
               |                 |                 |
            ---#--------#--------#--------#--------#--
               |                 |                 |
               |                 |                 |
               |                 |                 |
               #        #        #        #        #
               |                 |                 |
               |                 |                 |
               |                 |                 |
               #--------#--------#--------#--------#

Diagram Description: A uniform output dataset is shown here. The borders of the four boxes of size poly_size are highlighted by lines and the 9 output dataset points used to compute the Tl and Ts polynomials are marked with symbols on each box.

The error induced by using piecewise polynomial interpolation was found to be less than .15 kilometers for AVHRR data when poly_size was set to 100 kilometers.

When the option brute_force=yes, fastreg2 does not use the above approach with polynomials. Instead, fastreg2 directly computes (latitude, longitude) and corresponding input (line, sample) for every output pixel. This can be extremely slow.

Normally, fastreg and fastreg2 attempt to use no more memory than is specified by the max_memory parameter. However, this is not the case with fastreg2 when either brute_force=yes or whole_input=yes. In these cases, entire input variables are read into memory during registration. See NOTES for instances when it may be advisable to use brute_force=yes or whole_input=yes.

fastreg2 has an option to register input variables into an existing output dataset. Normally, both fastreg and fastreg2 create a new output dataset for every input dataset. However, if exactly one input dataset and one output dataset is specified, and the output dataset exists and is not a directory, fastreg2 checks its add_to_output parameter.

Registering into an existing output dataset is similar to compositing two output datasets registered to the same master file using composite. See composite. The following compositing methods are supported by fastreg2: last, first, max, min, mean. Here, last refers to the newly registered values; first refers to the previously existing output values.

last	- if last is good, use it, else use first
first	- if first is good, use it, else use last
max	- if only one is good, use it, else use max
min	- if only one is good, use it, else use min
mean	- if only one is good, use it, else use mean

Any output area not covered by the input is not affected.

PARAMETERS

master_file

Enter the name of the master dataset. Each input dataset is interpolated onto a geographical region defined by this dataset.

Valid responses are any TeraScan dataset containing an earth transform. The default is [Master].

master_var
If no master_var is specified, fastreg2 registers all input to the first set of (line, sample) dimensions it finds in the master dataset. If master_var is specified, its (line, sample) dimensions will be used as the basis of registration by fastreg2, e.g., all output variables will be parallel to the master_var.
The valid responses are any master dataset variable name, or no name at all. The default is blank (unspecified).

include_vars

The variables to register. If the list is preceded by a hyphen, then the variables in the list are excluded from the output dataset, and all other variables in the input files are included.

Valid responses are any variable names in the input files, properly delimited (space or comma). The default is to include all variables.

brute_force
If brute_force=no, fastreg2 uses the piecewise polynomial scheme described above. However, if brute_force=yes, then for every output pixel, fastreg2 will directly compute (latitude, longitude) and corresponding input (line, sample) coordinates. As stated earlier, this can be extremely slow. It can also require a large amount of RAM, because entire input variables are read into memory during registration.
Valid responses are [yes, no]. The default is no.

poly_size

Specify the width of the square regions that the output dataset is divided into. The units of poly_size are kilometers.

Valid range is [10 to 200]. The default is 100.

interpolate

This parameter determines the method of interpolation to be used by fastreg2. Choices are nn (nearest neighbor), ngn (nearest good neighbor, bl (bilinear interpolation), and cc ( (cubic convolution). The default is nn.

min_good

When interpolate=cc (cubic convolution), this parameter specifies the least number of good values needed to compute the boxcar average. The value must be between 1 and 9. The default value is 5.

off_protect

Use off_protect=no if the image has no Earth edges inside the master dataset. This assumption allows to reduce the computational time required for registration. Use off_protect=yes if there are points in the master dataset that are off the Earth.

Valid answers are yes or no. The default answer is no.

whole_input
If whole_input=yes, fastreg2 will attempt to read in an entire input variable prior to registering it. If whole_input=no, fastreg2 attempts to use no more RAM than is specified by the max_memory parameter for both input and output data.
The valid responses are yes and no. The default is no.
add_to_output
This parameter is used by fastreg2 only if there is exactly one input file and one output file, and the output file exists. If add_to_output=yes, the input data will be registered into the existing output data. If add_to_output=no, the existing output file will be overwritten by a new output file. The default is no.
add_method
If add_to_output=yes, this parameter specifies the composite method. Choices are last, first, max, min, mean. The default is last.
max_memory
OPTIONAL. This parameter is used by fastreg2 only if brute_force=no and whole_input=no; it is always used by fastreg. max_memory specifies the maximum RAM in megabytes to be used during registration.
Valid responses are integers in the range [1, 128]. The default is controlled by the environment variable TSCANMAXMEM. If TSCANMAXMEM is not defined, then the default is 4.
split_aspect
OPTIONAL. This parameter determines how the output area is recursively divided in half so the registration process can fit into the memory specified by max_memory. If split_aspect=no, the output area is split horizontally if it is taller than it is wide, or split vertically if it is wider than it is tall. If split_aspect=yes, the output area is only split vertically if the output horizontal aspect is 2.5 times greater than the corresponding input horizontal aspect, e.g., (output_ns/output_nl) > 2.5*(input_ns/input_nl). The default is yes.
sensor_resol
OPTIONAL. If yes, the dimensions of each output variable are determined so the input pixel resolution is preserved. If the input variable is in sensor coordinates, the input pixel resolution is determined at the satellite subpoint. If the input variable is in projection coordinates, the input pixel resolution is determined at the mathematical center of the projection. If sensor_resol=no, then each output variable has the same size, namely the size of the master. The default is no.

EXAMPLES

Register the TeraScan dataset named big to the master_file named Master. If there is not enough memory to process each data channel in one pass, the dataset is processed in pieces as shown below.

[1] % fastreg big big.reg
master_file    : char(75) ? [Master]
poly_size      : real     ? [100]
big.reg: avhrr_ch1:  [   1, 1024] X [   1,  512]
big.reg: avhrr_ch1:  [   1, 1024] X [ 513, 1024]
big.reg: avhrr_ch2:  [   1, 1024] X [   1,  512]
big.reg: avhrr_ch2:  [   1, 1024] X [ 513, 1024]
big.reg: avhrr_ch3:  [   1, 1024] X [   1,  512]
big.reg: avhrr_ch3:  [   1, 1024] X [ 513, 1024]
big.reg: avhrr_ch4:  [   1, 1024] X [   1,  512]
big.reg: avhrr_ch4:  [   1, 1024] X [ 513, 1024]
big.reg: avhrr_ch5:  [   1, 1024] X [   1,  512]
big.reg: avhrr_ch5:  [   1, 1024] X [ 513, 1024]

SEE ALSO

master, magnify, smear, avhrr, datasets, etx.

NOTES

To test the accuracy of using piecewise polynomials as opposed to direct calculations, one can run fastreg2 using brute_force=no, then run it again with brute_force=yes, and then compare the two output datasets using tsdiff. See tsdiff.

When rectangles of input data are highly non-convex in the master dataset coordinate system, fastreg and fastreg2 have been known to fail, leaving small slivers of missing data in the output. (For example, this may occur when registering a Mercator input image to an oblique stereographic master.) Often, this failure can be corrected by trying whole_input=yes, or brute_force=yes. There is a small performance degradation using whole_input=yes. There is a huge performance degradation using brute_force=yes.


Last Update: $Date: 1999/03/03 14:06:45 $