NAME:
  astrom
 PURPOSE:
  Astrometry from a digital image.
 DESCRIPTION:

  This program is designed to permit doing astrometry and catalog driven
   photometry of digital images.  It is implicitly assumed that these are
   true digital images, ie., that the images are strictly linear up to some
   signal level.  The possiblities supported by this program are quite
   extensive.  Read the PROCEDURE section below for more details.

 CATEGORY:
  Astrometry
 CALLING SEQUENCE:
  astrom,root,fileno

 INPUTS:
  root   - Root of data file name (ie., 970309), must be a string.
  fileno - File number to load (0-999), integer.
             If the file number is not provided then "root" is assumed
             to contain the entire file name.

  Normally I would use a call like:
     astrom,'080501',1
  and this would look for the file 080501.001 in the current directory.
  If the data are somewhere else (this is normal) I might use:
     astrom,'080501',1,path='/net/spikard/data1/buie/rawfits'
  In this case it would look for the file:
     /net/spikard/data1/buie/rawfits/080501/080501.001   (root is added to path)
  However,  you could do the same thing with:
     astrom,'/net/spikard/data1/buie/rawfits/080501/080501',1
  or
     astrom,'/net/spikard/data1/buie/rawfits/080501/080501.001'
  Note: if the file is actually named 080501.001.fits the commands above
  would not change and it would still find the file.

 OPTIONAL INPUT PARAMETERS:

 KEYWORD INPUT PARAMETERS:
  AUTODR   - Flag, if set, sets DRTHRESH automatically.  Obviously this only
                applies if there is a pre-existing source list.  But,
                DRTHRESH is set to half the mean spacing between sources in
                the image.  But, the minimum allowable value is taken from
                the input DRTHRESH variable (with its own default).

  BATCH    - Flag, if set supresses ALL interactive operations.  This
                doesn't mean it will all work right, rather, that when a
                problem is found it quits so that processing on other frames
                may continue.
  BINFAC   - Binning factor for displayed image.  Default=2

  BORDER   - Optional inset from each edge of array to be considered valid
                for measurements.  The default is 20 pixels in from each
                edge.  The value can either be scalar which is applied to
                all edges, or a 4 element vector that specifies the inset
                relative to [left,right,top,bottom]

  CATPAD   - Amount of extra padding for catalog extraction in arcsec.  The
                default is zero.

  CENTER   - Controls what is used for center of image for star extraction
                0 - (default)  with objects, uses object ephemeris as center
                               no objects, interactive query for choice.
                1 - Use the header coordinates, no corrections.
                2 - Use the header coordinates after taking out last known
                       position offset.
                3 - Use the known center of the image if it is known, if
                       it isn't known, reverts to center=2

  CLEAN    - Flag, if set requests filtering out
                cosmic ray strikes.  This step doesn't take too long on
                a Sun Ultra 1/170 but may be prohibitive on slower machines.

  DIGITS   - Optional input to indicate how many digits are in the suffix
                of the file name.  The default for this input is 0.  In this
                case it uses the ROBOCCD scheme which is three digits up
                to 999.  After that, it gets complicated, see numtoflist
                for more information.  If you were to give it a value of
                three you would get the same behavior except you won't get
                the ROBOCDD extension.  This is really designed for when
                you have four or more digits.

  DRTHRESH - Threshold on the radial distance (in pixels) of the catalog
                to source matching step when working with a pre-computed
                source list.  (Default=4.3)

  EDIT     - Flag, if set allows interactive culling of bad astrometric
                measurements in the reference net.

  EXTLIST  - If image is a multi-extension FITS image, this list will
                force the reduction of only the extension numbers listed.
                The default is to do all the extensions, one at a time.

  FNDRAD - passthrough to frmdxdy and frmdxyr (see discussion in frmdxdy
              documentation for how to use)
  FNSRC    - Name of source file to use for auto correlation.  The default
                is to use the original scheme where the files are
                automatically located.  If you want to change the default
                name and/or location, use this keyword.

  FORCETERMS - String array, if provided, is a list of terms (from "terms"
                  input variable) that will be forced to a constant
                  value rather than being fitted.  See astsolve.pro for a
                  complete description of the forcing process.
  FORCEVAL - name of file with force coefficients or the values themselves
                  look at astsolve.pro for complete details.

  GAIN     - Gain (e-/ADU) of the image.  Default=1.0

  IGNORESRC - Flag, if set suppresses using available src files in support
                of a twostar reduction.

  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 
                   RA        K  RA
                   DEC       K  DEC
                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.

  KILLREF  - Delete the existing Refstars/nnnXn.ref file, thus forcing
                a recomputation of the initial astrometric registration.

  MAGLIM   - Limiting (faint) magnitude for catalog extraction (default=30.0)

  MAGFILTER  - (default is no filter).  This is used to filter out some
                 portion of the sample of measured sources from the image.
                 This is needed when there is a big difference in the
                 magnitude range of the catalog and source list.
                 If supplied this will define a cut in the source list in
                 INSTRUMENTAL magnitudes and requires some care in its use.
                 The cut is defined to be:
                     magcut = median(mag)+magfilter
                 where median(mag) is the median instrumental magnitude.
                 Any source brighter than this cut is kept for source/catalog
                 correlation.

  MAXBADENNE - Maximum number of bad enneeants allowed without a confirmation
                 to proceed being asked.  Default=2

  MAXOFFSET - Maximum offset between the catalog and source list that will
                 be allowed without triggering a request for a twostar
                 reduction.  (Default=no maximum)  This has no effect if
                 the batch keyword is set.

  MAXPHOTSIG - Maximum signal that is considered to be photometric or
                 at least useful for astrometry.  If the peak signal in
                 a given is above this value, that star is not used in the
                 astrometric fit.  This has no effect on object measurements.
                 Default value is 13000.  If you aren't sure about this
                 value, set it to something large so that nothing gets
                 excluded.  Normally you use this to automatically exclude
                 reference stars whose cores are saturated.

  MAXRCRIT - Maximum value of rcrit for which SHELLS-style solution is to
                 be used on.  Default=no limit.  This is needed to control
                 when the shells solution is used.  As the field density drops
                 there may not be enough stars to do the initial
                 cross-correlation and the program will fail.  But, as the
                 field density drops there is less need to use the shells
                 solution.  For Mosaic data, this cross-over is poorly
                 defined but is near 30 pixels.

  MAXSTARS - Maximum number of reference stars to measure. (default=all)

  MINREFRESH - Flag, if set will minimize the amount of screen refreshes.

  NEWCAT   - Flag, if set forces the recreation of the STARFILE.

  NODISPLAY - Flag, if set supresses all graphical display.  This flag
                implies /NOOBJECTS,/NOREMIND,/BATCH,TWOSTAR=0,EDIT=0

  NOFWHMFILTER - Flag, if set suppresses the usual robomean filtering of
                   sources by FWHM.  It still eliminates things with
                   FWHM<0.7 but nothing else.  This is designed for working
                   with photographic plate data where the FWHM is not
                   really useful as a filter.

  NOSCALE  - Flag, if set suppresses conversion from integer to floating point
                when the FITS file is read.

  NOOBJECTS - Flag, if set suppresses the final step of measuring astrometric
                unknowns.

  NOREMIND - Flag, if set suppresses the query for the reminder location.

  NOSTRICTAPER - Flag, if set will suppress the protection that requires
                    the object aperature (OBJRAD) to match the aperture used
                    for the astrometry solution as found in the .ref files.
                    This is not considered appropriate when working with
                    CCD data but may be ok for scanned photographic plates.

  OBJNAME  - Name of object to collect astrometry for.  By default, the
                FITS header from the image is scanned for the OBJECT keyword
                and this becomes the OBJNAME after compressing multiple blanks,
                trimming leading and trailing blanks, and replacing single
                blanks by "_".

  OBJRAD   - Radius (in pixels) of object aperture for astrometry and
                photometry.  Default=10.  The sky aperture is set between
                objrad+10 and objrad+30.

  OBSCODE  - Observatory code used for plast and ephem.  Default = 688

  OUTDIR   - Root directory for all saved files.  Default is the current
               directory.

  PATH     - String, this is the name of the directory where the data are
                stored.  The actual data directory used is PATH+'/'+root.
                The default is '' (blank) and the file would be root.NNN
                which would permit putting a leading path on the root.

  PLASTFILE - This gives the name of the "plast" output file.  The default
                is OBJNAME.pla.  This file contains a list of asteroids that
                may be found on the image and is created by a separate
                program.  To disable this feature, set PLASTFILE='none'.

  PHOTOGRAPHIC - Flag, if set will use photphot.pro for centroid and photometry
                   calculations rather than basphote.  This is for use on
                   scanned photographic data.

  PHOTSTARS - Flag.  If set, turns on a special mode that performs photometry
                on all good astrometric reference stars.  The photometry is
                added to the root+'.log' file.  Multiple reductions are
                weeded out and the photometry log file is left sorted by
                file.  The log file is in the ALTLOG format (see basphote).
                The star name is automatically created from its coordinate.
                Ex: a star at 12:12:34.2 and +04:23:45 would be named
                NV1212342+042345.  The position used for the name comes from
                the catalog, not astrometry from the image.

  PRETTY    - String, if set, will cause the final image with overlays to
                be sent to a color postscript output file.  This will only
                be used if you are measuring objects (id., NOOBJECTS not set).
                If not specified, this file will not be created.

  QUEUE     - String, name of printer to send output to.  If supplied, a
                hardcopy of the image is generated along with a list of
                stars identified.  If blank or not specified, no printed output
                is generated.

  REFFILE  - Reference file name.  This is used to store the cross referenced
                list (stars vs. sources) for the input image.  By default
                the file is named suff.ref where suff is the suffix of the
                data file.  Note that the files are always placed in the
                Refstars directory.  You can override this is needed as
                might be the case for file names that are not particularly
                helpful for this scheme.

  REFSAVE  - Flag, if set the reffile will be saved if one or more points have
                been edited out during fitting.  Editing can be the result
                of automatic filtering or manual flagging.  Use with caution
                since you can't undo this without killing the reffile and
                starting all over again.

  RESFILE  - Filename where astrometric measurements are written to.  The
                default file name is OBJNAME.ast.  Only one line per image
                is allowed.  Subsequent measurements made by astrom will
                override the measures for this image.

  ROAM      - Flag, if set will provide a continuous running display of the
                RA and Dec of the cursor when you are in the object
                measurement loop.

  ROTSCAN   - Optional control of the automatic catalog-source correlation.
                If the initial correlation at the nominal rotation angle
                fails, the program will call FRMDXYR to try rotations angle
                near the nominal angle.  To use this keyword you need to
                provide a two element vector [maxangle,stepsize,tolerance],
                where maxangle is the largest amount to scan about nominal,
                stepsize is the angular step to take, and tolerance is the
                angular convergence required.  This causes the
                program to run a loop from -maxangle to maxangle at stepsize
                increments.  Once a useful rotation is seen it will do a
                binary search from there down to the tolerance level provided.
                Be careful in using this since you can really
                slow the program down a lot by scanning a large range of
                angles.  The default value for this is [1.0,0.1,0.001] and the
                values must be provided in degrees.

  SAVECLEAN - Flag, if set will save the cleaned image to disk.

  SCALEFAC - See frmdxdy.pro for full discussion.  This parameter
               lets you reduce the scale on the initial offset between
               source lists and catalog.  A value less than one helps an
               oversampled image get a better correlation.  This does need
               to be tuned somewhat to the actual data but most of the time
               the default works just fine.

  SHELLS   - Solve for astrometry in radial shells.  The default is to take
               the entire image all at once.  This is either a scalar or
               vector quantity.  Valid entries are between 0 and 1, exclusive.
               If any entry is out of range, behavior reverts to the default.
               If provided as a vector, the values should be in increasing
               order.  The first entry is always solved as a linear plate
               solution.  Values less than 0.35 are also treated as linear.
               Values less than 0.75 are solved by adding in the quadratic
               terms.  Above 0.75 uses a full cubic solution.  The last
               solution (using all available points) will use the terms as
               specified by TERMS.  Example: [0.3,0.65] would
               lead to a three step solution: 1) the first 30% of the image
               sorted by R with a linear solution, 2) 65% of the image with
               quadratic added, 3) all sources, solution using requested
               terms.  Note, this keyword has no effect if you have requested
               a pure linear solution.
  
  SKIPGOOD - Flag, if set will make the program skip any frame (or extension)
               that already has a viable solution.  A good solution is defined
               as one with a center in centers.dat and if there is a .ref file
               for that frame.

  SKIPOBJ -  Flag, if set, suppresses processing of any .obj files found
               that may be related to the current image.  This can give you
                substantial speed improvements if you aren't yet at at point
                where you care about the .ast files.

  SPOT     - Array containing explicit x,y coordinates.  Default=none.
                After the astrometric fit is complete, the RA,DEC of each
                x,y pair (2xN array) is computed, printed to the screen, and
                saved to an ancillary file, spot.dat, in the current directory.

  STARFILE - Filename where a list of astrometric reference stars is to
                be found.  The default file name is OBJNAME.cat.  If this file
                is not found, then this program will attempt to create the
                file by calling "refnet", a program that accesses the
                USNO A1.0 star catalog provided by David Monet of USNOFS.

  SUBEXP   - This keyword controls reducing images with multiple exposures.
                This keyword should contain one or more strings that will
                serve to identify the multiple exposures.  Ideally, this
                id string would be a single character, eg., 'a', 'b', etc.
                This program will loop over the string list for multiple
                reductions of the frame.  The id string will be appended to
                the frame # where ever it is used.  So, in the .ast file and
                fitcoeff.dat file the file name will be root.suffix_tag.  In
                Refstars, the files are suffix_tag.ref.  The default is to
                process one exposure per image and the _tag will not be added
                to any names.

  TERMS    - Vector that lists the terms to use in mapping from x,y to
                xi,eta.  (not case sensitive)
                default=['CONST','X','Y'] which is a pure linear fit.
                See ASTTERMS.PRO for a description of the terms available.

                Note: Version of this program prior to Nov. 2009 used
                XITERMS and ETATERMS instead (and they were allowed to be
                different).  To translate from the old vector to the new
                format use:
                names=['CONST','X','Y','R','XX','YY','XXX','XXY','XYY','YYY']
                z=where(xiterms eq 1)
                terms=names[z]
                Also note that  while 'R' is still supported, its use is
                not encouraged.  A better choice is 'XY'.   Lastly, there
                is no support for mixing different settings of terms within
                one night of data.  To use a different setting you must
                remove the fitcoeff.dat file before changing.

  TOHEADER - Flag, if set, the astrometric solution and photometric
                zero-point are added to or updated in the header of the
                image file.

  TRUSTCENTER - Flag, if set indicates that the 2-star solution and the
                   previously known plate center are to be trusted.  This
                   removes the need to do the catalog star identifications.
                   If the astrom.inf file is not found, or, if the plate
                   center is not found in the centers.dat file, then this
                   flag is ignored.  This flag is also ignored if there
                   is a valid Refstars file.

  TWEAKOBJ - Flag, if set, takes you to window 13 after measuring object
               in window 0 to allow you to tweak the position in case the
               automatic centroided position is not to your liking.  In
               this window, left is an explicit position, middle is
               redo automatic at this spot, and right is done (use last
               position).

  TWOMASS  - String.  Set to 'J', 'H', or 'K' to request 2MASS point-source
                   catalog data in that filter.

  TWOSTAR  - Flag, if set suppresses the automatic correlation of the source
                   list and catalog and switches to an interactive two star
                   solution to get the initial image location.  This should
                   be done on the first frame of a night.  It also seems to
                   be necessary for large fields with non-linear distortions.
                   This flag has no effect if there are no pre-existing
                   source lists generated by findsrc.pro.

  XCENTER  - Optional override of location of center of optical axis in
                pixel coordinates.  The default is the center of the array.
                This location is considered the location of the tangent plane
                and the location of x=y=0 for the (x,y) <--> (xi,eta)
                transformation.

  WINDOW   - window number to display image into.

  YCENTER  - Optional override of location of center of optical axis in
                pixel coordinates.  The default is the center of the array.
                This location is considered the location of the tangent plane
                and the location of x=y=0 for the (x,y) <--> (xi,eta)
                transformation.

 OUTPUTS:

  output is graphical and to a series of files.
     astrom.inf  - Records the last 2-star astrometric solution.
                     If the image being reduced is a multi-extension FITS
                     file, this file will be named astromNN.inf where
                     NN is the image extension of interest.
     centers.dat - Records the image center for all measured frames along with
                     the header coordinate and the offset between header and
                     measured center.  Column 1 is the file/extension name,
                     column 2&3 are the measured image center, column 4&5 are
                     the header center, and column 6&7 are the offsets in the
                     sense of measured-header converted to radians [cos(dec)
                     is included in the ra offset].
     root.log    - Photometry (if PHOTSTARS set)
     objname.ast - Astrometry of object
     objname.cat - Star catalog extraction
     objname.pla - Output of PLAST (list of asteroids on image).
     root.stars  - List of stars and coordinates for those where photometry
                      was measured.  Intended for inclusion in starcat.dat
                      (see GETSTARS.PRO or LOADSTAR.PRO).
     Refstars/fileno.ref - Binary file containing positions, mag, fwhm for
                           all catalog stars measured.  This file will be
                           be reused in later runs of ASTROM on this image
                           as long as the object aperture radius is the same.
     fitcoeff.dat- List of fit coefficients for each of the xi,eta axes.
     position.dat- List of x,y positions for all objects measured.

 KEYWORD OUTPUT PARAMETERS:

  FITDATA  - Anonymous structure containing all information pertaining
               to the astrometric fit.  If this reduction is for a simple
               fits file then the variable will contain a structure with
               the information.  If the file is a multi-group fits file
               then the tags will be arrays of values.

  FITERROR - Flag, if set means the fit failed for some reason.

 COMMON BLOCKS:
  MWB_ASTROMCOL  (used internal to this program)

 SIDE EFFECTS:

 RESTRICTIONS:

  Input files must all be FITS and the file names must be of the form:
    root.NNN where "root" is some string and NNN is a 3-digit number.

  The file name can also have an additional tag of .fits added to the above
    name.  This form is search for automatically and will be used
    preferentially if found.

 PROCEDURE:

  This program automates astrometric reductions of CCD images.  Once the
  astrometric solution is determined for the image, you can then proceed
  to measure any source in the image to ascertain it's position.  As you
  might guess from the above list, there are far too many options to this
  program.  It is rare that you will use all the options, instead, some
  subset can be tweaked and tuned to _your_ data to make the process run
  as quickly as possible and with as little user interaction as possible.
  Under certain circumstances this program can run complete automatically
  but only if a great deal is already known about the images.

  To illustrate one use of the program consider doing astrometry of 1 or
  more objects on an image.  Typically on the first invocation on a new
  image that you know little about you will not use any optional information.
  However, the first and most important optional input you can provide is
  the FITS keyword correspondence information through the KEYLIST option.
  If you have a decent header, then the program will have a good object name,
  time for the image, and (hopefully) a good coordinate for the image center.

  The object name is important because it is used to form file names for
  the output astrometry and the ancillary star catalog.  If the images you
  are reducing have the same name for different sky locations then this
  program will get hopelessly confused.

  Next, ASTROM will look for a special file, astrom.inf, that contains clues
  about the image scale and orientation.  If not found, you will be prompted
  for the needed information.  This file can be edited after creation if you
  need to try other guesses (such as flipping image, trying different scales,
  trying different rotation angles, etc.).  This step can be very frustrating
  if you don't have much information about your image.  I quite often find
  it necessary to edit this file many times and re-run ASTROM on the same
  image until it makes sense.

  Next, ASTROM will look for a list of stars that should be on the frame and
  will serve as the astrometric reference network.  If found, the file is
  read.  If not found, then ASTROM will try to create this file using another
  external program (refnet).  The set of stars requested will depend on the
  scale and orientation known at this point so if you get it wrong, delete the
  the star catalog and start over.  The center for the star search comes
  from a number of places.  This is what ASTROM tries, in order, (1)
  using the object name (first one if given an array), try to get an
  ephemeris position for the object for the time of the image, if this
  fails --> (2) ask for RA and DEC of image center.  (3) If NOOBJECTS is set,
  (1) and (2) are bypassed and the RA,DEC from the header are used (after
  precessing to J2000, if needed).  If you aren't doing objects, and the
  header value is bad, then you may need to insert your guess for the
  center directly into the "centers.dat" file.  Sometimes this is the only
  way to proceed if the headers are really screwy.

  Next, ASTROM will try to get a list of
  known asteroids that _might_ be on the image.  For this to work, you
  must have an external program that ASTROM will invoke to collect this
  information to a file.  If the file already exists, then it will be
  read directly without the need for the external program.  Note: this
  external program is non-trivial and cannot be easily exported away from
  Lowell Observatory.  Fortunately, it can be disabled, but, if you can
  use it then you will see positional overlays of the expected locations
  of any asteroids on the frame along with their line of variation scaled
  by the orbit uncertainty (green line) and a 1-hour motion vector (yellow
  line).

  With this information in hand, ASTROM begins to work with the screen image.
  The image is displayed with a fairly hard linear stretch, -7 sigma to
  +16 sigma about the mean sky signal.  The border is drawn and you are
  (possibly) asked to indicate a location on the image to be remembered.  I
  find this useful in marking the location of a specific object that will
  be highlighted throughout the analysis.  This is not used with NOOBJECTS
  set.

  If you allow it, ASTROM will proceed to remove cosmic rays from the image.
  This step is almost always useful but can sometimes take a long time to
  run depending on the size of the image and the speed of your computer.
  On a SUN Ultra 1/170E, a 4k x 2k image can take 10-20 seconds to clean.
  After cleaning the image is redisplayed with the same scaling.  If you watch
  carefully you will see the cosmic ray strikes "blink off".

  Next, the asteroid overlay is generated and plotted.  This involves
  generating ephemeris positions for all the asteroids for the time of this
  frame.  Again, an external program is called to generate these positions
  and you find the relevant documentation in my IDL front-end program, EPHEM.

  Now, we get on to the steps of getting the astrometric grid in place.
  The image center, scale and orientation are used in calculating the locations
  of all catalog stars.  Red diamonds, scaled in size by magnitude, are
  plotted on the image at these predicted locations.  Your job at this
  point is to match up the overlay with the image.  This can be either
  very easy, very hard, or anywhere in between.  You may find need to
  tweak the contents of astrom.inf, change MAGLIM, or more depending on
  the situation.  Sometimes the center is no good.  One of two things will
  happen, (1) the wrong star overlay is plotted on the image, or (2) no
  stars are plotted.  In the latter case, you will be prompted for a new
  image center.  If you're lucky, this will allow you to proceed.

  Assuming all goes well, you now must establish the correspondence between
  the overlay and the image.  At this step you must identify two stars
  in the image and the same two stars in the overlay.  The prompts from ASTROM
  will indicate what information it next desires.  Just remember that at
  any time ASTROM is looking for a mouse click to proceed, a right click will
  exit the program directly at that point.  After you identify the first star,
  the overlay is replotted so that the overlay star sits over the image.
  After you identify the second star ASTROM has enough information to predict
  the location of all the other catalog stars and can proceed to measure
  their locations.  Once all the catalog stars are measured, an astrometric
  function is fit to the positions.  See, ASTTERMS for all the possible
  terms.  The default is a linear solution which is usually pretty good for
  most CCD images.  At this step you may need to fiddle with the aperture
  radius used to measure the stars.  A radius (OBJRAD) that is too big
  or too small can lead to excessive scatter in the astrometry.  I usually
  try to set OBJRAD=fwhm or just slightly under the fwhm.  These positions
  the subsequent fit are saved to a couple of files so that if you come
  back to the image later, the fit is regenerated much quicker and you get
  directly to the next step, that of measuring unknown objects.

  Note that the fit to the star positions is done in a robust fashion.  Stars
  with large residuals, unusual fwhm, signal too weak, or signal too strong,
  are avoided in the fit.  These stars will plot as red circles in the final
  overlay while the good stars will overplot with yellow circles.  You can
  control the "too strong" threshold with MAXPHOTSIG or you can do a purely
  interactive editing of the star positions used with /EDIT.  Using /EDIT
  is required only if there just aren't that many stars (say 3-6) and there's
  no statistical basis for chucking out anything.  If there are lots of stars,
  the automatic stuff works just fine.

  If you find that the header gives consistently good predictions of the
  catalog star locations, then use the TRUSTCENTER keyword to bypass the
  2-star interactive step.  Be careful, you need to have pretty good
  for this to work effectively.  Also note that if you turn on the PHOTSTARS
  flag, ASTROM will automatically collect and save aperture photometry data
  on _all_ the catalog stars.

  At this point, you've arrived at the time you can measure new objects.
  You are prompted to click left on the object to measure.  Nothing is saved
  until you click middle (to go to next object) or click right (to quit).
  So you can feel free to poke around in the image measuring lots of objects
  without saving all of it.  When you click left it measures the location
  and computes RA,DEC, and, it puts up a small window on the object with the
  aperture location overplotted.  In this window, there is a non-linear
  stretch so that you can see the wings of the PSF as well as the core.
  You also get a radial profile for additional diagnostic information.
  If you continue with a middle click, ASTROM will step through the OBJNAME
  array (if provided) or when it runs of out names it knows, it will begin
  prompting you for a name.  This name is used to form the file name for
  all saved astrometry.  Once you have processed an entire nights worth of
  data then you can use the ASTCOL program to collection it all and save it
  to another master storage location.  The ASTCOL step is where the
  observatory code information is added to the astrometry.

  If you set /PRETTY, the very last thing done is to create a fancy postscript
  output image file.  This image has all the overlays and asteroid locations
  and is occasionally useful.

  This description is by no means exhaustive.  There are a very large number
  of options that must be tweaked to get the most out of the reduction.  I
  ususally find it useful to create a master script that contains all the
  flags and options as I develop a means to reduce some data.

  Here's one example:
      astrom,fdir,fnum,maglim=17, $
         binfac=1,objrad=objrad,path=d,key='../site.key',objname=o, $
         /noremind,noobjects=noob,gain=2.5,plastfile='none',trustcenter=trust, $
         xi=[1,1,1,0,0,0,0,0,0,0],eta=[1,1,1,0,0,0,0,0,0,0],maxphotsig=23000.0

  Here I've set the limiting magnitude for the reference stars to 17.0,
  no cosmic ray cleaning, don't ask for reminder location, set gain
  of CCD, turn off looking for field asteroids, force linear fit, and set
  saturation level of CCD.  The other options are either obvious or set
  to fixed values in the script handling this call.  Note that by splitting
  the file name into root and suffix, you can generate a loop on the suffix
  and step through all the images you have.

 MODIFICATION HISTORY:
  97/04/05, Written by Marc W. Buie, Lowell Observatory
  97/06/13, MWB, added keylist fits header reading generalization
  97/06/14, MWB, fixed line of variations plotting bug, also added saving
                 information on reference stars used.
  97/06/17, MWB, added controls over terms in Xi and Eta fits.
  97/06/18, MWB, added saving fit coeffcients and object positions.
  97/06/19, MWB, added NOREMIND keyword
  97/06/20, MWB, added TRUSTCENTER keyword
  97/09/09, MWB, added SUBEXP keyword
  97/10/08, MWB, added X,YCENTER keywords.
  97/10/16, MWB, added SPOT keyword.
  97/10/21, MWB, rewrote initial 2-star fit.
  97/11/24, MWB, added MAXSTARS keyword.
  98/01/06, MWB, added support for pre-cleaned images.
  98/03/13, MWB, some heavy rewriting.  NOCLEAN  is now CLEAN (default none)
                   plus internal cleanups, some changes to ancillary plots,
                   added support for external lists of image sources.
  98/06/24, MWB, added TWOSTAR flag.
  98/08/26, MWB, added ROAM keyword.
  98/10/07, MWB, a few optimizations and some bug fixes and enhancements
                   for multi-extension files.
  98/10/08, MWB, added DRTHRESH keyword
  98/11/04, MWB, added NOSCALE keyword
  98/12/02, MWB, changed usage of PATH so that you can append 'root' or not.
                   This now allows the image file name roots to be different
                   from the name of the directory they are stored in.
  99/03/30, MWB, fixed bug with precession of header coordinates.
  99/03/30, MWB, added KILLREF keyword.
  2000/01/18, MWB, modification for new version of rdastfc
  2000/02/04, MWB, added .fits optional tag on file name
  2000/02/07, MWB, added OBSCODE keyword
  2000/04/12, MWB, added new information output to centers.dat, also added
                      BATCH keyword.
  2000/05/11, MWB, added CATPAD keyword.
  2000/08/01, MWB, added NODISPLAY keyword.
  2000/09/12, MWB, rewrite of auto-astrometry for high order fits
  2000/09/17, MWB, added SKIPGOOD, SHELLS, AUTODR, and MAXRCRIT keywords.
  2000/09/18, MWB, added SKIPOBJ keyword.
  2000/09/19, MWB, fixed cos(dec) header offset problem
  2000/10/25, MWB, fixed lingering MAC--addslash bug.
  2001/03/28, MWB, added support of properly using a 24-bit display.
  2001/03/29, MWB, limit size of ephemeris error to twice field size.
  2001/04/20, MWB, changes to support new ephem/geteph version
  2001/10/23, MWB, changed constraint on minimum number of stars, was forced
                     to be 10, now it can be lower if you don't enable all
                     the cross terms.
  2002/02/06, MWB, removed CATPATH keyword
  2002/04/06, MWB, WATCHOUT!  I changed the program so that if you are using
                     the twostar reduction, it will save the refstars AFTER
                     the fit, thus excluding the ill-fitting objects from
                     the saved set.  This might be dangerous in some cases
                     so make sure to do a /killref if redoing the solution
                     where you think too many have been deleted.  I have a
                     suspicion that this will break some other case for the
                     program but I can't see where right now.  (Probably in
                     cases where it takes a very long time to do the
                     photometry on the fields stars in this program.)

                     Also, added IGNORESRC keyword.
  2002/04/22, MWB, restricted the number of catalog stars used during
                     shells solution.
  2002/04/24, MWB, added a two star solution helper to the shells operation
                     if the initial linear correlation fails.
  2002/08/16, MWB, modified to use new rdplast routine.
  2002/09/09, MWB, added support for string obscode values
  2003/02/26, MWB, merged with orphan code from Corwin, should be just
                     changes in comments and other documentation.
  2003/05/30, MWB, changed some loop variables to LONG
  2003/06/01, MWB, converted my Delfile calls to IDL file_delete calls
  2003/10/01, MWB, converted my Mkdir calls to IDL file_mkdir calls
  2004/9/21, MWB, removed obsolete call to Findfile
  2005/06/26, MWB, added TWOMASS (2MASS) catalog support
  2005/06/28, MWB, fixed obscure bug affecting window 13 when interactively
                    measureing objects.  No impact on output data.
  2006/01/12, MWB, added MAXOFFSET keyword
  2006/02/01, MWB, changed behavior if fileno.  Now if fileno is undefined
                     then root is taken to be the entire file name (.fits
                     tag is optional).
  2006/02/02, MWB, added FNSRC keyword (override on where src file names)
  2006/02/03, MWB, added output keyword FITDATA.
  2006/04/26, MWB, fixed FNSRC bug from previous change that affected 
                     multi-group fits files.
  2007/10/29, MWB, added PHOTOGRAPIC keyword on scanned plate data (incomplete)
                     added TWEAKOBJ keyword
  2007/11/06, MWB, fixed bug with partial solutions where you have to help
                     with a two star solution.  Problem if help led to a
                     significant change in rotation.
  2007/11/07, MWB, added NOSTRICTAPER keyword for photographic plate data
  2008/06/17, MWB, FNSRC input was being ignored, fixed.
                   Also modified to use rdstarc (which will modify .cat files)
  2008/10/31, MWB, fixed a minor problem affecting astrom.inf information
                      when the frame is really close to 0h RA (more likely at
                      higher Dec).
  2009/07/24, MWB, fixed bug related to correlating star lists with a source
                      list when a field rotation is needed in the auto
                      correlation.
  2009/12/02, MWB, big rewrite to change the selection and control of
                      fitting terms.  xiterms and etaterms are consolidated
                      and TOHEADER keyword was added.
  2009/12/09, MWB, another epoch of substantial changes to the program.
                      The routine astinvrt was retired in favor of the new
                      program, astsn2xy.  This version has been pretty
                      well tested against images with non-zero but weak
                      optical distortions.
  2009/12/30, MWB, added ability to force terms in the fit using the
                      keyword FORCETERMS
  2010/07/26, MWB, minor mod for new frmdxdy error codes
  2010/09/15, MWB, added REFFILE keyword
  2010/11/22, MWB, added ROTSCAN keyword
  2011/01/27, MWB, added photometric zero-point error to header output and
                      fit results return
  2011/01/28, MWB, added REFSAVE keyword
  2012/04/26, MWB, added OUTDIR keyword
  2012/05/29, MWB, added FITERROR output keyword and MAGFILTER keyword.
                      Watch out!  MAGFILTER is strange and may evolve in
                      its implementation from this instance.
  2012/12/03, MWB, Fixed a subtle error in the shells reduction where it
                      could quit prematurely with a low-density field.
                   Added SCALEFAC keyword support for new frmdxdy
  2012/12/20, MWB, added FORCEVAL keyword
  2013/03/22, MWB, added DIGITS keyword, also changed default location
                      of src files to be outdir+'Src/'.  Fixed a nasty
                      bug that had broken TWOSTAR solutions.
  2013/09/27, MWB, Added NOFWHMFILTER keyword
  2015/08/10, MWB, Fixed a glitch during two star solutions that didn't
                      let you properly restart or abort
  2016/04/16, MWB, Added FNDRAD keyword