Help for FEATHERV

 PURPOSE:
Program FEATHERV takes input images and mosaics them to form an output image
with a gradual feathering in all directions of all image overlaps.
FEATHERV performs mosaicking by reading all of the input image files and 
combining them to form an output image according to the parameters for
edging, and an IBIS file for 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.  There are special 
features for cloud (or glint) removal, for brightness correction, for
colossal mosaics via tiling, and for analyst error checking.

A special feature of this program is that tiepoints between frames that are
declared to be neighbors in the IBIS file are gathered.  The brightness difference
statistics are averaged and result in two additional corrections:

1.  The average difference (halved) to all neighbors is added to each frame as
    a constant.  The constant is reported in a column of the IBIS file.

2.  The remaining differences (halved) to each declared neighbor is added to
    each frame as an angled ramp or half-plane.  The half plane is "hinged",
    has a zero value, down or across the middle of the image.  At the edge
    of the image, it has a ramp height that is reported in the IBIS file.
    
The four ramps are merged in each quadrant of the image by an approximation to
angular interpolation.  For example, the 45 degree diagonal to the upper left
corner of the image would get half of its value from the left=facing ramp and
half from the top-facing ramp.  The approximation is to use

         y/(x+y) to approximate atan(y/x)/90
 and        
         x/(x+y) to approximate (90-atan(y/x))/90

for example, on the diagonal, x=y and all four formulas give .5

The constant and ramp corrections are applied after the ADJUST keyword corrections,
since it is best to apply them as a residual operation.  The feathering and
cloud removal are applied after the constant and ramp corrections.
 EXECUTION:
 
Note that the image files are first in the parameter sequence, and the last
input is an IBIS file.  The IBIS file contains master mosaicking information
on all of the images used in the INP parameter (at the least) and is
recommended to contain information on all images in the application, even if
this numbers in the tens of thousands.  The program limits at present (9/99)
has a limit of 400 inputs, and it opens and closes them as a narrow mosaicking
band passes from top to bottom of the output.  The number of files open over
the band cannot exceed the VICAR limit for number of files open at once.
The IBIS file contains the following information in columns that can be
parameter specified or defaulted.  The default column numbers are given here:

1.  The name of the image file in any order, with or without pathname.
    Only the part of the pathname/filename after the last \ or / is read
    for checking
2.  The offset SL of the image input (see GeoTIFF options below)
3.  The offset SS of the image input (see GeoTIFF options below)
4.  The NL of the image input (cannot be less as in FASTMOS) (see GeoTIFF options below)
5.  The NS of the image input (cannot be less as in FASTMOS) (see GeoTIFF options below)
6.  Input factor for brightness equalization formulas (only one as of 9/99)
7.  Reserved for more complex brightness equalization formulas

GeoTIFF Options:  If the images all have GeoTIFF labels and the 'GEOTIFF
keyword is given, then there are two possibilities:

The first is: if columns 2-5 contain non-zero values (only column 4 is
checked for 0), then the values are compared with values calculated from
the GeoTIFF labels or the nl,ns from the VICAR label.  Since the values
might calculate with a slight inaccuracy, the TOLER parameter is provided
with a default value of 1.e-7.  If a calculated offset exceeds the TOLER
parameter, this indicates that the files have an inaccurate mapping for
the purposes of mosaicking and do not have an integral offset.  All mappings
are checked for consistency (map projection type, zones, meridians,
etc.).

The second is: if columns 2-5 contain zero values (only column 4 is
checked for 0), then the values are calculated from the GeoTIFF labels
or the nl,ns from the VICAR label.  The only check is that the offsets
are integral values (within the parameter TOLER) and that the mappings
are consistent.

When in the GeoTIFF case, a geotiff label is calculated and written
for the output mosaicked image.

The IBIS file is used for two reasons.  First, the input of offsets is 
simplified.  Second, coverage can be checked.  The program will abort with
an error message if a mosaic is performed and an input file cannot be found
in the IBIS file.  The program will also abort with an error message if a
mosaic is performed and an file in the IBIS file touches the output area
and is not included in the INP parameter (this is why NL,NS is in the IBIS
file).  If a file is opened and its (NL,NS) does not agree with the IBIS
file, the program aborts.  In all of these cases, the file is named.

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 image
file (see note above, this is the second input). 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.  This is no longer given
by parameters, but must be placed in the columns of an IBIS file as discussed
above.  The offset value must be in the IBIS file unless GeoTIFF labels are
used.  An offset of (1,1) means that the upper left pixel of the offset image
would line up with the upper left pixel of the output image (assuming that
it also had a (sl,s) of (1,1) (the normal case).

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, in fact, that is the motivation
for this program.

FEATHERV only has a single mode of overlap, namely, averaging.  The value at
a pixel will generally be the average of all values above the THRESH value
from images that cover the pixel.  But the averaging is modified by feathering
the edges of data as follows.  For each input, a MOORE DISTANCE ALGORITHM is
applied to data inside of the image so that the image is mirrored by a edge
distance image that gives distance from the edge of data above the THRESH 
value or the absolute edge of the input image (if the data goes fully to the
edge of the input image).  The MOORE DISTANCE ALGORITHM has to be applied
outside of the mosaic output image area, because an image edge some distance
from the mosaic output image area can contribute to a MOORE DISTANCE NUMBER
inside of the mosaic output image area.

for example, the image data

 16  16  16  16  16  16  16 
 16  16  16  16  16  16  16
 16  16  16  16  16  16  16
 16  16  16  16  16  16  16 
 16  16   0   0   0  16  16  
 
has the MOORE DISTANCE NUMBERS

 01  01  01  01  01  01  01 
 01  02  02  02  02  02  01
 01  02  02  02  02  02  01
 01  02  01  01  01  02  01 
 01  01   0   0   0  01  01  

The inputs are then weighted by the MOORE DISTANCE NUMBERS

   output = sum((Ith input pixel value)*(Ith MOORE DISTANCE NUMBER))
                  divided by sum(Ith MOORE DISTANCE NUMBER)
                  
The user inputs a parameter DFEATHER to set the distance that the MOORE
DISTANCE ALGORITHM will work.  Then all remaining inside numbers are set
to that value as a maximum.  If MOOREFAC is greater than one, the
value used is DFEATHER/MOOREFAC in tiles of size MOOREFAC x MOOREFAC, 
and also the DFEATHER will be adjusted slightly to a multiple of
MOOREFAC because of the tiling.  The net effect of MOOREFAC>1 is to
still feather to depth DFEATHER, but in coarser steps.

Increasing DFEATHER has two consequences.  First, the program will run
more slowly, probably sublinear to the size of this parameter.  Second,
the program will consume more memory space.  The virtual memory space in
bytes needed for image buffers and MOORE DISTANCE buffers is:

  3 x (max number of inputs open) x (max input NS) x DFEATHER / MOOREFAC**2

FEATHERV is written entirely in the C programming language and uses dynamic
memory allocation to avoid imposing any restrictions on the size of the
images. 

FEATHERV HAS BOTH THE OLD TYPES OF NIBBLING (SEE NEXT PARAGRAPH) AND
A NEW EDGING CAPABILITY BASED ON THE MOORE ALGORITHM.  The new edging
nibbles in a perpendicular direction to the edge of data in all
directions (the old nibble worked from the righ or left only).  Use 
the parameter MOORENBL to invoke this.  The default of 0 is no nibble,
a value of n nibbles all values where the MOORE distance from the edge
is n, etc.  To give a smooth transition, instead of starting at n+1,
the whole MOORE distance input is reduced by n so the MOORE distance
that is used in feathering still starts at 1.  Keep in mind that
MOOREFAC=3 means that a MOORENBL=1 will nibble 3 pixels from all
edges.

FEATHERV 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 or
equal to 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.  NOTE THAT EDGING IS INCREASED
BY USE OF MOOREFAC.  A NIBBLE OF TWO AND A MOOREFAC OF THREE WILL RESULT
IN SIX PIXELS BEING REMOVED.

FEATHERV has a parameter named ADJUST that can take a column(s) in the
IBIS file as an adjustment to brightness on a per image basis.  See the
parameter description for more details.

RAMP CALCULATIONS

A special feature of this program is that tiepoints between frames that are
declared to be neighbors in the IBIS file are gathered.  The brightness difference
statistics are averaged and result in two additional corrections:

1.  The average difference (halved) to all neighbors is added to each frame as
    a constant.  The constant is reported in a column of the IBIS file.

2.  The remaining differences (halved) to each declared neighbor is added to
    each frame as an angled ramp or half-plane.  The half plane is "hinged",
    has a zero value, down or across the middle of the image.  At the edge
    of the image, it has a ramp height that is reported in the IBIS file.
    
The four ramps are merged in each quadrant of the image by an approximation to
angular interpolation.  For example, the 45 degree diagonal to the upper left
corner of the image would get half of its value from the left=facing ramp and
half from the top-facing ramp.  The approximation is to use

         y/(x+y) to approximate atan(y/x)/90
 and        
         x/(x+y) to approximate (90-atan(y/x))/90

for example, on the diagonal, x=y and all four formulas give .5

The constant and ramp corrections are applied after the ADJUST keyword corrections,
since it is best to apply them as a residual operation.  The feathering and
cloud removal are applied after the constant and ramp corrections.


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:
      feather INP=(a...,ibis) OUT=b SIZE=(sl,ss,nl,ns) optional parameters
      feather INP=(a...,ibis) OUT=b  SL=sl SS=ss NL=nl NS=ns optional parameters
      feather (a...,ibis) b (sl,ss,nl,ns) optional parameters
      feather (a...,ibis) b optional parameters

      Here '(a...,ibis)' represents a list of one to 399 input image file
      names followed by an ibis file, and 'b' represents the output image file
      name.
The GeoTIFF options are:
      The following command line formats show the major allowable forms:
      feather INP=(a...,ibis,gtref) OUT=b SIZE=(sl,ss,nl,ns) optional parameters
      feather INP=(a...,ibis,gtref) OUT=b  SL=sl SS=ss NL=nl NS=ns optional parameters
      feather (a...,ibis,gtref) b (sl,ss,nl,ns) optional parameters
      feather (a...,ibis,gtref) b optional parameters

      Here '(a...,ibis,gtref)' represents a list of one to 398 input image file
      names followed by an ibis file, and then by a GeoTIFF reference image
      that defines the overall pixel space, and 'b' represents the output image file
      name.
EXAMPLES

See examples under program FASTMOS to learn more about the mosaicking process.
The major difference to note here is that SL,SS can be given for the mosaic
image space.
RESTRICTIONS
1. The input and output images must be byte or halfword data.
2. Plan carefully using the virtual memory limit formula

  3 x (max number of inputs open) x (max input NS) x DFEATHER / MOOREFAC**2

 OPERATION:

FEATHERV performs mosaicking on a line by line basis.  The offsetting of
input images is done at READ time.  However, the program has to read ahead
of the output line by distance DFEATHER to run the MOORE DISTANCE ALGORITHM.
This readahead buffer is called the "footprint" of the input.  The footprint
has to go above, to the right, to the left, and below the image output area
to get the MOORE DISTANCE NUMBERS.  Because the footprint buffers are large,
a rolling index scheme is used on them and on the MOORE DISTANCE BUFFERS.

Data in halfword format may include negative data numbers.  Negative data
numbers that do not meet the threshold criteria are ignored.

 TIMING: 

Will get back with this when some big cases are run.  Expect 3x slower
than FASTMOS.  Expect good behavior in the virtual memory (not a lot of
swapping).  

 ORIGINAL PROGRAMMER:    A. Zobrist          27 Oct 1999
 COGNIZANT PROGRAMMER:   Barbara McGuffie    27 Oct 1999
 
 REVISION HISTORY
  99-10-27    AZ   Initial version, named feather
  99-11-05    AZ   two pass version, named feather2
  99-11-18    AZ   ramps added to feather2
  99-11-18    AZ   halfword MOORE algorithm, named featherh
  99-11-28    AZ   all options rolled into featherh
  99-11-30    AZ   reduced resolution MOORE algorithm, named featherv
  00-04-16    AZ   GeoTIFF label use
    

PARAMETERS: