Help for FASTMOS

 PURPOSE:

Program FASTMOS takes input images and mosaics them to form an output image.
FASTMOS performs mosaicking by reading all of the input image files and 
combining them to form an output image according to the parameters for
mosaicking mode, edging, and image placement.  In a typical application, the
output image is a composite picture made from two or more input images each
of which contains a portion of the overall picture.
 EXECUTION:

The size of the output image is determined by the number of lines and number 
of samples in the SIZE field if the SIZE field is entered by the user.  If the
SIZE field is not entered, the output file is the same size as the first
input file.

FASTMOS can accept from one to 48 input images.  The input images are not
required all to have the same size.  The data type of the input images may
either be byte or halfword data, but all of the input images must have the
same data type.  The data type is obtained from the VICAR label of the first 
input image.

For mosaicking, the program needs to know the locations in the output image 
of each of the input images.  This is done by giving the location in the output
image of each input image.  The locations are given in terms of line number and
pixel number within a line.  The offset parameters (OFF1, OFF2, OFF3,...) are
used to specify the locations for the respective input images.  The offset
parameter can be omitted for images at the default location of line 1, pixel 1.
An input image is not required to lie entirely within the boundaries of the
output image.  If the upper left hand corner of an input image is not within 
the boundaries of the output image, the location of the input image is given
by extending the numbering of lines and pixels beyond the boundaries of the
output image.  Thus negative numbers or zero would be used for the locations
of input images beginning to the left or above the boundaries of the output
image.  Input images are allowed to overlap.

The mode by which FASTMOS determines the output data number values from the
input data numbers is user selectable through the MODE parameter.  There
are currently five modes to choose from.  All of the modes make use of the
THRESH threshold parameter, which is usually greater than or equal to 0.
In determining the output data number for a given pixel, FASTMOS finds
out which of the input images containing that pixel have a data number for that
pixel which is greater than the THRESH value.  The data numbers
for that pixel from those input images form a set of values that is then used
in the selected mode to give the output data number.  For example, if 
MODE=AVERAGE is selected, then the output data number for a pixel is the
average of those values for the pixel that are greater than the
THRESH value.  The following rules apply for each of the modes.  If none
of the input images have a data number value for a given pixel that is
greater than the THRESH value, the output data number is the
data number from the first input image if the pixel is contained in the
first input image, and the output data number is L0 if the pixel is not
contained in the first input image, where L0 is 0 if THRESH is greater than 0,
L0 is 0 if THRESH=0 and the data format is byte, and L0 is equal to THRESH
otherwise for integer data.  For real*4 data, L0 is -1.0E10.
If exactly one of the input images has 
a data number value for a given pixel that is greater than the 
THRESH value, the output data number is the data number from the one input 
image.  If more than one of the input images have a data number value for a 
given pixel that is greater than the THRESH value, the output 
data number is determined by the mosaicking mode.  The five mosaicking modes 
are discussed under the MODE parameter.

FASTMOS has an option for edging the input images prior to applying the
mosaicking mode.  Edging effectively removes the 'edges' of the input images
so that pixels in the 'edges' are not considered to be contained in their
images as far as the mosaicking process is concerned.  Several parameters
determine the precise effect of edging in any situation, but basically if
edging is selected, then each line of each input image is edged first on the
left and then on the right.  Edging means scanning through a line from one
end or another to the point at which the data numbers are greater than
a threshold value and then removing the pixels from the end of
the line up to a certain number of pixels beyond the point.  This is 
referred to as finding the edge of the scene data and nibbling-in a 
certain number of pixels beyond the edge.  Because of the line by 
line processing performed by the program, edging is only available
in the horizontal direction.  (Edging the top and bottom of images would
normally require an intermediate data set.)  Edging is typically used
to remove distortion around the edges of pictures that was caused by
interpolation, filtering, or other things.

FASTMOS uses dynamic memory allocation (using subroutine STACKA) to avoid
imposing any restrictions on the size of the images. 

The output image has the same data format  (byte or halfword) as the input 
images.  
TAE COMMAND LINE FORMAT
      The following command line formats show the major allowable forms:
      fastmos INP=(a...) OUT=b SIZE=(sl,ss,nl,ns) optional parameters
      fastmos INP=(a...) OUT=b  SL=sl SS=ss NL=nl NS=ns optional parameters
      fastmos (a...) b (sl,ss,nl,ns) optional parameters
      fastmos (a...) b optional parameters

       Here '(a...)' represents a list of one to 48 input image file names,
       and 'b' represents the output image file name.
EXAMPLES

1.    fastmos INP=(A,B,C) OUT=D SIZE=(1,1,1000,1000)                          'AVERAGE  OFF1=(100,100) OFF2=(-100 -25 600 700) 

      In this example the output file D is a 1000 line by 1000 pixel 
      image produced by mosaicking three images using
      the averaging mode. The default THRESH threshold value of 0 is used.
      The position relative to the output image of each of the input 
      images is as follows:

      Image A,  the first input, is positioned with its upper-lefthand
                corner (ULC) at line 100, pixel 100.  Since only two values
                were specified for OFF1, the entire image is used.

      Image B,  is positioned with its ULC outside the boundaries of
                the output image at line -100, pixel -25.  The first 600
                lines and the first 700 pixels per line are used from image B.
                Of these, the first 101 lines and 26 samples are ignored
                because they do not lie within the boundaries of the output
                image.

      Image C,  is positioned with its ULC at the default position of
                line 1, pixel 1.  The entire image is used.
2.    fastmos INP=(A,B,C,D,E) OUT=F

      In this example the output file F has the same size as the input file
      A.  The data format of the files defaults to the format given in the
      label of file A.  The mosaicking is performed by using the default
      overlay mode. The default THRESH value of 0 is used.  The five input
      images have been pre-registered so that they begin in the same location.


3.    fastmos INP=(A,B,C,D,E) OUT=F THRESH=10   'EDGE NTHRESH=50

      In this example the output file F has the same size as the input file
      A.  The data format of the files defaults to the format given in the
      label of file A.  The mosaicking is performed by using the default
      overlay mode. The THRESH value of 10 is used.  Each of the input
      images gets edged horizontally using a threshold value of 50.  
      The edging nibbles away (the default) four pixels beyond the edge 
      of the scene data.

4.    fastmos INP=(A,B,C,D,E) OUT=F THRESH=10   'AVERAGE                    'EDGE LTHRESH=5 LNIBBLE=3 RTHRESH=10 RNIBBLE=1

      This is the same as example 3 except that the averaging mode is used
      and the edging parameters are different.  The edging on the left 
      uses a threshold of 5 and extends 3 pixels beyond the scene edge.
      The edging on the right uses a threshold of 10 and extends 1 pixel
      beyond the scene edge. 

5.    GEN A 10 10
      GEN B 10 10 IVAL=101
      fastmos INP=(A,B) OUT=F SIZE=(1 1 16 16) THRESH=0 'OVERLAY OFF1=(2,1) 

      This is a mostly academic example in which all of the files have
      byte data format.  In this example the output file F has the size 
      16 lines by 16 samples.  Program FASTMOS internally makes a copy of
      files A and B padded with zeroes to a size of 16 by 16 with the offsets
      specified for A and defaulted for B.  It then compares the copy of A
      to the THRESH value.  Since THRESH=0, everything in the copy of A
      goes into the file F, and nothing in file B is utilized.
      This illustrates that THRESH=0 is not normally used for mosaicking
      byte data.  (It might be used for averaging images of the same size and 
      offset.  fastmos was originally implemented with the requirement of 
      THRESH >= 1 since it uses 0 for any padding around byte input images.)

RESTRICTIONS
The input images may be any format of 4 or fewer bytes per pixel, and must all
be of the same format.  The output image will be the same format as the inputs.


 OPERATION:

FASTMOS performs mosaicking on a line by line basis.  The offsetting of
input images is done at READ time.

 TIMING: 

  The following CPU times for FASTMOS was obtained on a 
VAX 8650 (MIPL2) in April 1993
			                                                CPU Time
gen FASTA1 NL=1000 NS=1000 IVAL=0 
gen FASTA2 NL=1000 NS=1000 IVAL=200
fastmos INP=(FASTA1,FASTA2) OUT=FASTAO8 SIZE=(1,1,2000,2000)  !  				4-93  SP  CPU TIME ON MIPL2 (VAX8650)    17.66s

For more information, see the file timefastmos.pdf in fastmos.com.

 The following timing data were measured on a Solaris Sun4 with two 1000x1000
 byte input images, in seconds:

                          User   System   Wall-clock
 byte/halfword version:   0.17    0.17      0.73 
 real*4 version:          0.26    0.17      0.89

 ORIGINAL PROGRAMMER:    W. Benton
 PORTED TO UNIX: Steve Pohorsky
 COGNIZANT PROGRAMMER:   Lucas Kamp

 REVISION HISTORY
1993-04-07 SP  Made portable for UNIX.  Added PROGRESS parameter to
               print percentage DONE during execution.
2003-08-14 NTT Enabled for 3D (multi-banded) images
2012-09-18 lwk Enabled for real*4 data (converted all buffers to real*4).
2012-10-02 lwk made THRESH parameters consistent with old (integer) FASTMOS;
               because the default threshold is now 0.0 (used to be 1), the
               tests are now for DN>THRESH instead of DN>=THRESH.
2018-12-18 WLB Fixed line buffer initialization bug.

 CHANGED BEHAVIOUR DUE TO CONVERSION TO REAL*4 (OCT.2012):
The output of FASTMOS is slightly different than it used to be, because of
the requirement that the behaviour with respect to the default threshold
value of zero be consistent between the two versions. The integer version
(old fastmos) did this by setting the default THRESH parameter to 1 and
keeping DN >= THRESH. However, for real*4 data, that would lead to the
undesirable result of throwing away DNs between 0 and 1, so the default
value of THRESH was changed to 0 and the check was changed to keep DN>THRESH.
The logfile of the old version is retained in the .com file under the name
tstfastmos_integer.log_solos, for comparison with the new one, named
tstfastmos.log_solos. It can be seen that, when the default THRESH is used,
the results are the same for the two versions, but when a non-zero value of
THRESH is specified, the results differ at the edges, typically by one pixel.

PARAMETERS: