NAME:
    basphote
 PURPOSE: (one line)
    Circular aperture photometry extraction from images.
 DESCRIPTION:

 CATEGORY:
    CCD data processing
 CALLING SEQUENCE:
    Basphote,gain,image,exptime,xloc,yloc,radius,sky1,sky2,logfile[,objnum]

 INPUTS:
    gain       : Gain of the CCD.  Photons per count (DN).
    image      : CCD image array.
    exptime    : Exposure time for the image in seconds.
    xloc, yloc : Current location of the cursor in image coordinates.
    radius     : Current aperture radius in pixels.
    sky1       : Inner radius of the sky annulus (in pixels).
    sky2       : Outer radius of the sky annulus (in pixels).
                   If sky2<0 then sky1 is taken to be the actual sky signal
                   in DN/pixel and |sky2| is the error on the sky.
    logfile    : Name of the photometry log file.

 OPTIONAL INPUT PARAMETERS:
    objnum     : Starting serial number for object in frame, default=0
                    If supplied as a scalar it will be incremented by
                    the number of positions supplied in xloc/yloc.
                 If given as a vector, will specify the exact number to
                    and there will be no incrementing when done.

 KEYWORD INPUT PARAMETERS: (default on flags is false):
    AIRMASS - Optional airmass value.
    ALTLOG  - Flag, if set, output is generated in an alternate format.
    BAD     - Flag (or array) marking data as bad, default=good
    BOXMRAD - Size of the box to look for local max in.
                 Default=radius[last value].
                 If boxmrad is negative, then the call to BOXM that finds the
                 local max is suppressed.  In effect, basphote assumes that
                 the input location is already the maximum.
    CALCFWHMSIZE - Size of the area to compute the FWHM over,
                    default=radius[last value].  This is especially important
                    to set if you want a tight search for the maximum
                    but still want an accurate FWHM (this happens when
                    boxmrad< Do not generate any screen output.
    ZPOINT  - Optional zero point.

 KEYWORD OUTPUT PARAMETERS:
    ERR     - Optional return of the magnitude error.
    FLERR   - Uncertainty (1 sigma) of object flux.
    FLUX    - Object flux (photons per second)
    FWHM    - FWHM of object image(s), in arcsec if PSCALE provided, otherwise
                 returned in pixels
    ONCHIP  - Byte array of flags that indicate if object was on-chip.
    OUTJD   - Optional output of Julian dates (for cubes). This will be a
              vector of length rank(image). Contents are computed from the
              input Julian date (JD=) and the input delta-time (DT=).
    MAG     - Optional return of the instrumental magnitude.
    MAX     - Optional return of peak signal in object.
    SKYMEAN - Optional return of sky signal, counts/pixel.
    SKYERR  - Optional return of sky signal uncertainty, counts/pixel.  This
                  number is the standard deviation of the mean.
    SKYSIG  - Optional return of the standard deviation of the sky signal.
    XCEN    - Optional output of centroid x-position(s).
    YCEN    - Optional output of centroid y-position(s).

 OUTPUTS:
    All output is sent to the screen and the logfile.  Selected variables are
 returned via optional keywords.

 COMMON BLOCKS:
    None.

 SIDE EFFECTS:

 RESTRICTIONS:

 PROCEDURE:

 MODIFICATION HISTORY:
    Ported by Doug Loucks, Lowell Observatory, 1992 Oct from the
    C-language version written by Marc Buie.

    93/6/1, Marc W. Buie, Lowell Observatory, added the alternate logfile
      format to the program.  Streamlined the required input parameters.
      Calling sequence is now different.

    1/25/93, MWB, changed default on boxmrad to be the LAST value in the
      radius vector.

    2/3/93, DWL. Moved the file format declarations outside of the main loop.
    2/4/93, DWL. Modified to accept all valid combinations of scalar and
      vector values for xloc, yloc, radius, sky1, and sky2 inputs.
    2/4/93, DWL. Added checks for 'seeing' sub-array extraction.
    2/4/93, DWL, Added keywords XCEN and YCEN to allow return of the refined
      center(s) to the calling program.  Also, xcen, ycen, xmax, and ymax
      will be vectors if xloc and yloc are vectors.
    2/10/93,DWL, Removed XMAX and YMAX keywords.
    2/10/93,DWL, Added checks for off-chip and too-near-edge conditions.
    4/21/93,DWL, Added keywords MAG and ERR.  The instrumental magnitude and
      uncertainty are returned to the caller if these keywords are present.
      If the inputs xcen and ycen are vectors, these variables will also be
      returned as vectors.
    5/21/93, MWB, Fixed variables that are undefined if off-chip condition
      is found.  Dummy values are set to prevent printouts from dying.
    5/26/93, MWB, Added FLUX, FLUXERR, and NOLOG keywords.  Fixed bug on
      computation of sky background error, errant gain factor removed.
    9/30/93, MWB, Modified usage of NAME to allow vector input.
    2/2/1994, DWL, Mods to allow 3-D image cube photometry. Also added
      OUTJD keyword.
    4/28/94, MWB, Fixed bug that recomputed a new centroid position if
      the EXACT flag was set.  This had NO effect on photometry.
    8/30/94, MWB, Added ONCHIP and PRINTALL keywords.
    5/18/95, MWB, Added FWHM optional output keyword.
    6/16/95, MWB, If PSCALE negative, fwhm not computed.
    1/8/96, MWB, Added override on serial number, objnum can now be a vector.
    7/13/96, MWB, changed FWHM calculation to remove function fitting.
   10/31/96, MWB, added BAD= keyword for flag pass through
    3/17/97, MWB, added MAX keyword
   97/09/10, MWB, removed extraneous sub-expression evaluation (5x faster).
   98/03/04, MWB, Added SKYMEAN, SKYERR return keywords.
   98/09/21, MWB, added suppression of BOXM call through a negative BOXMRAD.
 2000/01/18, MWB, added SKYSIG return keywords.
 2000/06/02, MWB, upgrade to photometry log file version that includes sky
                  measurement.
 2001/01/25, MWB, fixed bug in certain cases when overriding the object
                  serial number.  Also took out all "message" calls to make
                  sure info and warning messages are seen.
 2004/07/15, MWB, changed loop variables to LONG.
 2006/04/19, MWB, fixed bug in ALTLOG usage for upgrading photometry files
 2006/04/26, Peter L. Collins, Lowell Observatory, upgrade to include and
                   log CCD readout noise (keyword RDNOISE). The log level
                   is promoted to v1.1 from v1.0.
 2006/05/22, PLC, added another way to default the rdnoise, using keyword
                  RDNOISE=v where v is some negative value- as a convenience
                  to other code.
 2008/03/25, MWB, fixed minor bug related to an aperture that falls off chip
 2010/12/20, MWB, minor tweak to prevent negative photon noise.
 2011/12/23, MWB, added CALCFWHMSIZE keyword, this is an inportant change,
                     read the documentation on this keyword.  If you ever
                     used BOXMRAD with a value much smaller than RADIUS you
                     really need to read the new documentation.
 2013/07/06, MWB, added RADP keyword option
 2013/07/29, MWB, fixed a bug for normal FWHM calculation introduced when RADP
                    option was added.
 2021/03/24, MWB, fixed an error in the noise model.  The contribution of
                    sky photon noise in the object aperture was handled
                    incorrectly.