NAME:
    sumann
 PURPOSE: (one line)
    Integrate over an annulus.
 DESCRIPTION:

    This procedure computes the first two image moments of the pixels
    contained within the input annulus.  The position and inner and outer
    radii define the annulus.  Each pixel in the input image is then
    assigned a weighting value which is its areal overlap between the pixel
    and the annulus.  This weight varies from 0 to 1 and is the precise
    analytic area of overlap (computed by pixwt.pro).  Of course, this
    program doesn't do the computation for all pixels, only those near
    the edge.

    For historical reasons, the moments are split into two components:
    The moments of all negative pixels in the annulus and the moments of
    all positive pixels in the annulus.  Therefore, to get the true total
    number of counts you must add possum+negsum.  Likewise, to get the
    true center-of-mass (center-of-light) moment in either x or y, you
    should add the positive and negative moments, ie.,
       xmom = xcen + posxmom/possum + negxmom/negsum
       ymom = ycen + posymom/possum + negymom/negsum
    These numbers are returned separately because there are other reasons
    for wanting the distributions separated.  For example, one use of this
    routine is to compute the position of a star in an image.  For this
    you would make two calls.  The first is a call with back=0. centered
    (roughly) on the object.  you would then set inradious to be larger
    than the object and outradius to something larger still.  The sky
    (background) signal would then be possum+negsum.  Note this is NOT
    how I use this routine for photometry, it's meant as an example ONLY.
    The second call would then be made with inradius = 0 and outradius
    to be just larger than the star.  This time, set back to the
    background found in the first call.  The object brightness is then
    possum+negsum counts above sky.  Then, I use just posxmom and posymom
    as the position of the object.  Strictly speaking I should add the
    negative moments, but, I know that the negative stuff is most likely
    to be sky or bad pixels and irrelevant for the object location.
    (see also centrod.pro)

    Note: the use of this routine for computing sky signals has been
    superceded by a very different algorithm.  basphote.pro uses a
    combination of getannul.pro and robomean.pro to compute good sky
    background values.  This routine is used mostly for object counts and
    circular radial profiles.

 CATEGORY:
    CCD data processing
 CALLING SEQUENCE:
    Sumann, image, xcen, ycen, inradius, outradius, back, totweight, $
            possum, negsum, posxmom, negxmom, posymom, negymom

 INPUTS:
    image       : CCD image array.
    xcen,ycen   : Center of annulus.
    inradius    : Radius of inner circle.
    outradius   : Radius of outer circle.
    back        : Background to subtract from each pixel.

 OPTIONAL INPUT PARAMETERS:

 KEYWORD PARAMETERS:

 OUTPUTS:
    totweight          : Area of annulus.
    possum, negsum     : Sums of positive and negative pixels.
    posxmom, negxmom   : Positive and negative x moments relative to xcen.
    posymom, negymom   : Positive and negative y moments relative to ycen.

 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:

 PROCEDURE:

 MODIFICATION HISTORY:
    Ported by Doug Loucks, Lowell Observatory, 1992 Oct, from the
    C-language version written by Marc Buie.
    April, 1993. DWL. Replaced the inner FOR loop with vectors.
    98/09/21, MWB, optimizations
    98/09/29, MWB, fixed nasty bug introduced during optimization.
    2011/11/30, MWB, added output keywords XVAL, YVAL, WVAL