LOOKER

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.

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