
NICMosaic (and NICStikum) is used to arrange nicmos images into a mosaic.
This is particularly useful for images not taken as part of an association.
(If your images ARE taken as part of an association, STScI provides a
data product with the '_mos' extension that is an image mosaic.)

 IDL> nicmosaic,flist,table=table,/bigsize,maxscreen=maxscreen

The argument to nicmosaic is a file containing a list of FITS filenames.
NICMosaic will align the images in the file list according to the WCS
information in the image headers.  The user then manually tweeks up the
alignment by blinking pairs of images, looking for offsets in the overlapping
areas, and moving or rotating each image into alignment.

When NICMosaic exits it writes a 'table' file that documents the relative
offsets and rotations of all the images.  If NICMosaic is run again on this
same set of images, this output table can optionally be supplied to force
the images to be aligned as detailed in the table.  The name of the
table will be the name of the file list with the extension '.tbl' added.

Another optional parameter is the switch "/bigsize" which forces the images
to be displayed at twice their normal size.  This sometimes makes it easier
to see the details in the images when doing alignments.

The optional keyword 'maxscreen' allows the user to set the maximum dimension
of the graphics display.  The default is 800.  This is for users with smaller
display screens so they can set maxscreen to something like 600 so the entire
widget will fit on their screen.

(The table is also used in the program NICStikum to create a single, mosaiced
image.)

Assuming the input list contains two or more images, one of the images
will always be considered the 'primary' image and one considered the
'secondary' image.  The primary image is the one that is moved and rotated
by the widget buttons and the secondary is the image that is blinked with
the primary image.  The primary image is marked by being enclosed by a
white rectangle and the the secondary image is marked by being partially
enclosed by 1/2 of a rectangle, the bottom and left side of the rectangle,
forming an 'L'.

One of the images, usually the most central image, is chosen by the program
to be the 'immovable object' image.  This is the image that determines the
world coordinates for the system of images and cannot be moved or rotated
by the user.

Note: When NicMosaic starts up, the 'immovable object' image is set to be
      the 'primary' image.  This is done to show the user which image is
      immovable.  In this configuration, no movements are possible and
      the user must set a different image to be primary before the movements
      can be used.

The controls in NICMosaic are quite simple.  The left mouse button selects
the closest image (to the mouse position) as the primary image, the right
mouse button selects the closest image (to the mouse position) as the secondary
image and the center mouse button blinks the primary and secondary images
once.

There are four 'directional movement' buttons and two 'rotation buttons'
at the bottom of the user interface.  All of these buttons only move the
primary image and only then if that image is not the 'immovable object'
image.

The 'ShiftAmount' field allows the user to adjust the number of pixels
the primary image will be shifted when the movement buttons are pressed.
The 'RotAmount' field allows the user to adjust the number of degrees
the primary image will be rotated when the rotation buttons are pressed.
Both ShiftAmount and RotAmount can be fractional.

For rotations, the 'ccw' button rotates the image counter-clockwise and
the 'cw' button rotates the image clockwise.  Both of these rotate the
image about the lower left corner of the image.

The 'BackSubtract' field is currently not implemented.

The 'Z1' and 'Z2' fields allow the user to adjust the upper and lower
limits of the range of values which are mapped to the greyscale for display.

The 'C' button redraws the display collecting all of the image offsets into
a single offset from the original data.  This is to 'Clean' up the display
after many sub-pixel shifts (which uses a simple bi-linear interpolater)
may have smeared the data somewhat.

The 'Save' button is not implemented and may be deleted eventually.

The 'Redraw' button redraws the display simple to remark the primary and
secondary images.

The 'Exit' button exits the program.
