NAME:
  looker
 PURPOSE:
  Visual identification and measurement of moving objects in digital images.
 DESCRIPTION:

  This program handles visually inspecting large digital images and permiting
     measuring positions of the objects found.  The object lists created
     by this program are compatible with similar files used by ASTROM,
     GARTH, and FINDSRC.

 CATEGORY:
  Astrometry
 CALLING SEQUENCE:
  looker
 INPUTS:

 OPTIONAL INPUT PARAMETERS:

 KEYWORD INPUT PARAMETERS:

  GAIN     - Gain of CCD (e-/DN), default=3.0

    KEYLIST=      : Name of a file containing a correspondence list. This list
                    associates a set of standard names with the actual keyword
                    names found in a FITS file header. If this keyword is
                    omitted, a default list is used, as if a file with the
                    following contents had been supplied:
                     AIRMASS   K  AIRMASS
                     DATE      K  DATE-OBS
                     DATETMPL  T  DD-MM-YYYY
                     EXPDELTA  V  0.0
                     EXPTIME   K  EXPTIME
                     FILTER    K  FILTERS
                     FILENAME  K  CCDFNAME
                     OBJECT    K  OBJECT
                     UT        K  UT
                    The middle column is a flag. It may be K, for Keyword,
                    T, for Template, or V, for Value. If it is V, the contents
                    of the third field on that line should make sense for the
                    name in the first field.

  OBJRAD    - Radius of the object aperture to use when centroiding objects.
                Default is 6 pixels.

  PATH      - Optional path for original image directory.
                If not specified, the current directory is used.

  PSCALE    - Nominal plate scale of images in arcsec/pixel (default=0.26)

  XSIZE     - x size, in pixels, of the main window (default=1070)

  YSIZE     - x size, in pixels, of the main window (default=820)

  ZXSIZE    - x size, in pixels, of the score window (default=148)

  ZXSIZE    - x size, in pixels, of the score window (default=296)

 OUTPUTS:

 KEYWORD OUTPUT PARAMETERS:

 COMMON BLOCKS:

 SIDE EFFECTS:

 PROCEDURE:

  This program is intended to work with a collect of images taken on a single
    night of observing.  Generally it will be best to work in a directory
    separate from the raw (or processed) image data.   The optional keyword,
    PATH, is used to point to the directory containing the images.  You
    will also need to provide a keyword correspondence file for decoding the
    FITS headers.

  The images can either be in a simple format of one image per file or can
    be collections under the multi-group FITS format as used by the KPNO
    MOSAIC camera.

  Images that cover the same region of sky are considered to be a group
    identified by the "field name" which is taken from the OBJECT keyword
    in the FITS header.  If the images are multi-group files then the group
    being processed is identified by an extension tag of the form "xN" where
    N is the extension number being processed.

  You start using this program by creating a "new" field (under the File
    menu option).  To start a new field you will need to select an image
    that serves as the first epoch view of the field.  If you have images
    of varying quality it would be wise to make the first image selected be
    one of the best.  However, under most circumstances you will pick the
    earliest image.  After selecting the first frame it will be displayed as
    a red image.  This image is always loaded into the red display channel.

  To begin looking for moving objects, you must have at least two images
     of the field.  Add the second (or third, ...) to the list for this field
     with the appropriate File menu option.  If you already have multiple
     images identified then you can simply select the appropriate "secondary"
     image.  The secondary image is another image of the same field at a
     different time from the first image loaded.  The secondary image is
     always loaded into the blue and green planes of the display.  Any object
     that appears in both epochs at the same place will look white.  An
     object that moves will show as a red/cyan pair of images.

  Before you can effectively identify object, you must register the secondary
     frame relative to the first image.  In the Object status area of the
     tool it will indicate "Updating Offset" if image registration is in
     progress.  This mode is automatically entered when adding a new image to
     the list.  You can also enter this mode on your own with the "Adjust
     Frame Registration" option on the File menu.  In this mode, click left
     on a red (first epoch) star image.  Then, click middle on the same
     star in the blue (second epoch) image.  The relative offset will be
     computed and the second frame will be shifted to align with the first
     frame.  When you are done with the registration click the right button
     to exit the registration mode.

  The three mouse buttons are used for different functions in all three "image"
     windows.  These windows are called "Main" -- the largest window which
     shows the aligned image pair; "Zoom" -- small, square window in the lower
     right that shows a logrithmic stretch on the image just measured; and
     "Score" -- window in the upper right that is used for navigating and
     keeping track of what you've looked at so far.  The score window shows
     a minified schematic of the full sized image.  Areas that have been
     looked at are marked in green with the intensity increasing for each
     time the area is viewed.  The current display area is highlighted with
     a purple border.

  Here are the principle mouse function in each window:
     Score -
        Left: Center Main window at location of cursor.
        Middle: Move by half a image window in the direction of greatest
                 offset (vertical or horizontal) between the cursor and
                 the location of the current display area.
        Right:  Center Main window on the "slot" whose center is closest
                 to the cursor.  The "slots" are integral mappings of the
                 main window into the full image and are highly quantized.
                 Clicking right on a black region will always give you new
                 areas to view.

     Main -
        Left:   Measure object nearest cursor in first epoch (red) image.
                 The location clicked is used as a starting point for the
                 measurement and eventual position comes from a centroid
                 centered on the object even if you don't click precisely
                 on the object.  This action will cause the Zoom window to be
                 updated with an extraction centered on the centroided
                 location and a red circle will overdrawn on the object.
        Middle: Same as the left button except the second epoch (cyan) image
                 is measured.
        Right:  Select the nearest object (by its first epoch position)
                 to be the current object.  You can see this position on
                 the main image by the red circles and associated object
                 number label.  You must click within 50 pixels of the
                 object to select it.  When an object is selected, the
                 last known centroid location on the first epoch image
                 is used to update the zoom window as if you had just clicked
                 left on the object.

        Note, there is are a few protections built into this window.  If
        the main window location changes and the current object is no longer
        on the window, the object changes to be a NEW object. If you are
        using the second (or later) secondary image and if you click
        too far from a previous measurement on the same object you will get
        a warning box in case you meant to start a new object.  If you are
        using the first secondary image, a click more than 50 pixels from
        the current object will be treated as a request for a new object.
        To get new objects closer than 50 pixels requires clicking "New
        Object" first.

     Zoom -
        Left:   Re-locate the object position to the cursor position without
                 changing the zoom window view.  The overdrawn circle will
                 move, but not the image.  Use this feature to override an
                 automatic centroid position that is corrupted from field
                 stars, cosmic rays, or chip defects.
        Middle: Same as left except the zoom window is re-centered on the
                 location where you clicked.  The display stretch is also
                 recomputed using the pixel at the center as the peak
                 intensity for the object.
        Right:  This is used to nudge the aperture for the current position
                 being shown.  The aperture is nudged in the direction of
                 where you click in the zoom window.  The amount of the
                 nudge depends on how far from the current aperture the cursor
                 is when you click.  The most you can move in any direction
                 is two pixels which is when the cursor is half of the width
                 of the zoom window.  If the aperture is exactly centered,
                 then you get 2 pixels if you click at the edge.

  There is a pattern to the measurement process.  On the first pair of images
     you will generally click left then middle on each new object.  If a new
     object is more than 50 pixels from the current object you can just click
     left to start a new one.  If the new one is closer than this you must
     click "New Object".  If the secondary frame is other than the first
     possible you will have to click "New Object" each time.
     Once all the objects are found and measured
     in the first pair of images you will then look at the second pair (or
     third, ...)  Click left in the score window to center the main window,
     then click right on the red circle then click middle on the cyan image
     for that object.

  If you happen to click on a pair of objects that really are just chip
     defects that look like a moving object, you will get a warning.  Unless
     you are very, very sure it is real you should not keep such objects.

  The "Snap Object" tool on the pull-down menu will create a set of 10 files
     which are extractions on the current object.  The files all have the
     object name as the root of the name with a suffix of .tiff.  The code
     between _ and . determines the type of extraction:
       1   - linear stretch, centered on position 1 in frame 1
       1c  - linear stretch, centered on mid-point in frame 1
       1l  - power law stretch, centered on position 1 in frame 1
       1lc - power law stretch, centered on mid-point in frame 1
       2   - linear stretch, centered on position 2 in frame 2   
       2c  - linear stretch, centered on mid-point in frame 2    
       2l  - power law stretch, centered on position 2 in frame 2
       2lc - power law stretch, centered on mid-point in frame 2 
       c   - color composite, linear stretch
       l   - color composite, power law stretch.

 RESTRICTIONS:

  Even though you appear to be able to browse to a different directory
  for the raw data, don't.  All the raw frames should be in the same directory
  and pointed to by the PATH keyword.  Also, all the field names (aka, object
  lists) should be kept in the same directory as well.

  It is assumed that images from the same night are the same size.

  For multi-group images, it is assumed that all the relevant exposure
  information can be culled from the extension header.  In other words,
  the bulk of the primary header must be found in each of the extension
  headers.

  This entire scheme is predicated on there being just a "few" images on
  each field.  In theory there is no upper limit to the number of images
  on a field but in practice too large a number gets to be rather cumbersome
  in looking at the .obj files.  Basically things get really cluttered if
  there are too many related frames.  This isn't too bad since you don't
  need that many frames to get good astrometry anyway.  Three frames tells
  you just as much as 100 frames as long as the time span from first to
  last is the same.

 MODIFICATION HISTORY:
  98/10/27, Written by Marc W. Buie, Lowell Observatory
  98/11/20, MWB, added OBJRAD keyword
  99/03/19, MWB, fixed bug that corrupted obj files on adding 3rd frame.
  99/03/22, MWB, fixed bug for missing dt on non-group images.
  99/03/30, MWB, added rudimentary hardcopy function (File menu).
  99/04/01, MWB, fixed minor bug in cursor handling in zoom window.
  99/04/22, MWB, added Autoload function and menu toggle
  99/04/26, MWB, added rudimentary b/w blinking
  99/12/07, MWB, fixed problem with overwriting an existing .obj file with
                 non-group data, also fixed problem that would allow data
                 processing to proceed without having been queried for a
                 name to go with initials.
  2001/01/17, MWB, added "Snap Object" tool.
  2001/04/27, MWB, added FITS sub-image saves to "Snap Object"
  2001/09/04, MWB, added "Toggle Color Mode" option, displays difference image
  2002/02/19, MWB, fixed bug that caused crash when going to a different
                 field when new field had fewer images than current field.
  2002/09/25, MWB, added GAIN keyword
  2002/11/20, MWB, changed skysclim call to take advantage of LOWCLIP/HICLIP
  2003/07/02, MWB, added new Edit menu button and added a function to set all
                     ? objects to n in one operation.  Please use with care.
  2003/07/30, MWB, eliminated all 'readfits' calls, changed to fits_read
  2004/07/09, MWB, added support/protection regarding salted(fake) objects.
  2004/07/18, MWB, changed all Findfile calls to file_search
  2004/11/12, MWB, changed where object id labels plot in main window
  2005/03/30, MWB, now plots a predicted location for an object when 3 or
                     more frames are involved.  Also, object is no longer
                     automatically deselected when it goes off the frame
                     when there are 3 or more frames (with two frames the
                     deselect works as before).
  2005/05/06, MWB, desensitize Previous and Next buttons when in frame
                     offset mode, also suppress right button exit of frame
                     registration when two frames have not yet been
                     measured.
  2006/11/14, MWB, fixed a minor display problem with difference imaging.
  2007/01/03, MWB, added fine adjustment to registration controls.
  2011/08/19, MWB, fixed a bug when dealing with multi-extension FITS files
                     where there are 10 or more extensions.
  2015/01/31, MWB, changed the behavior of hanging onto an object if it falls
                     out of the current view.  Now, if you are working with
                     the first and second frame, you lose connection with
                     the current object if it leaves the field.  If you are
                     on the third or later frame, it won't take away the
                     selection.
  2015/02/21, MWB, Fixed long-time oddity with location of plot symbols in
                     the main display window.  Results as guided by zoom
                     window are unaffected and still valid.
  2015/02/22, MWB, Changed left-click logic on the main window to automatically
                     start a new object if looking at the first secondary
                     frame and you click well away from the current object.
  2015/04/04, MWB, Added new GUI controls to navigate among the secondary
                     frames.  Defaults changed to now reset to the first
                     secondary frame when changing fields/images.
  2015/04/05, MWB, Added zoom right click control to nudge aperture