NAME:
  wastrom
 PURPOSE:   (one line only)
  Widget for determining an interactive astrometric solution
 DESCRIPTION:
  This is a widget tool for interactively guiding an astrometric solution.
     This is not a general program in the sense that a lot of work needs to
     done to get ready to call this tool.  In addition to an image and some
     rough guess on the WCS, you have to provide the source and catalog
     lists.  The WCS guess can be pretty rough but the chirality of the image
     must be correctly declared with the "flip" input variable.  You can
     lock in on the real solution for all but the chirality.
  This is a model widget and will block all other activities while it runs.
     Upon return, the astrometric solution is supplied along with a flag
     that indicates if the operation was successful.  This tool works equally
     well if called from within a widget heirarchy or a normal IDL procedure.
     It is not really intended to be called directory by the user.  It needs
     a lot of setup and will usually be embedded in a larger program that
     will call this tool as needed.
 CATEGORY:
  Astrometry
 CALLING SEQUENCE:
  wastrom,im,ainfo,flip,sra,sdec,mag,xsrc,ysrc,binfo,success
 INPUTS:
  im - image to process (used for display only)
  ainfo - initial astrometric information structure (see mkastinfo.pro)
  flip  - Flag, if set means the image is inverted.
  sra   - Catalog RA (radians) of sources
  sdec  - Catalog Dec (radians) of sources
  mag   - Catalog magnitude of sources
  xsrc  - x pixel location of source in image
  ysrc  - y pixel location of source in image
 OPTIONAL INPUT PARAMETERS:
  GROUP - widget id of the group leader (providing this is entirely optional)
 KEYWORD INPUT PARAMETERS:
 OUTPUTS:
  binfo   - fitted astrometric solution for image (useful if success=1)
  success -  Flag, if set means the operation was a success and binfo
               will contain a useful, if not final, astrometric solution
 KEYWORD OUTPUT PARAMETERS:
 CONFIGURATION:
 COMMON BLOCKS:
  mwb_wastrom: used to return the output information
 SIDE EFFECTS:
 RESTRICTIONS:
  Currently hardcoded for linear plate solutions.
 PROCEDURE:
  The first two sources must be done entirely manually.  The first source
    is used to get an offset to line up the catalog against one source in
    the image.  Click left to select the source in the image (green X), click
    middle to select the corresponding source in the catalog (red diamonds).
    The order of providing these two items does not matter.  When both are
    selected, the GUI will show 'src <-> cat' and other ancillary information
    that indicates a valid pair has been selected.  To link this pair
    together, click the "Link" button.  At this point the catalog will snap
    to the selected source.  The rotation and scale could be completely 
    wrong at this point.  At the end of this first step, you do not yet have
    a valid solution and need to move on to specifying a second source.
  The second source is selected in the same way as the first.  Note that
    once a source is used from the source list and catalog it cannot be
    selected again.  After linking the second source you now should have a
    good scale and orientation but this solution is still not complete.  If
    you exit at this point the caller will be told the action was unsuccessful.
    You must have three or more linked stars to have a valid WCS solution.
  Next, you can either continue adding sources one at a time, or, clicking
    "Auto Match".  If you opt for the automatic tool, it will match all
    sources it can.  However, sources too close to the edge are ignored.
    Those sources that are being used to constrain the solution have different
    markings on the image from those that are still candidates for linking.

  As mentioned earlier, you cannot manually measure new sources to add to the
    source list.  This is a firm design choice since there are many ways to
    measure sources and this tool does not presume to know how to do this.
    Mixing measurement techniques is bad for astrometry, hence the reason
    you must provide positions for sources that are externally determined.
    This also gives you full control over the reference catalog as well.G
 MODIFICATION HISTORY:
  2021/11/24, Written by Marc W. Buie, Southwest Research Institute
  2021/11/30, MWB, fixed a problem with flipped data.