Initial commit

6 files changed, 5172 insertions, 0 deletions

diff --git a/noao/digiphot/apphot/doc/specs/Ap.doc b/noao/digiphot/apphot/doc/specs/Ap.doc
new file mode 100644
index 00000000..66744d58
--- /dev/null
+++ b/noao/digiphot/apphot/doc/specs/Ap.doc
@@ -0,0 +1,1071 @@
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+1. Introduction
+
+    The  APPHOT  package  will  provide a set of routines for performing
+aperture photometry  on  uncrowded  or  moderately  crowded  fields,  in
+either  interactive  or  batch  mode.   The  basic  photometry technique
+employed  shall  be  fractional-pixel  aperture  integration;   no   PSF 
+fitting  techniques  shall  be  employed,  and  no  knowledge of the PSF
+shall be required.  This document presents the formal  requirements  and
+specifications  for  the  package,  and  describes  the algorithms to be
+used.
+
+
+
+2. Requirements
+
+    (1) The program shall take as input an IRAF imagefile  containing  a
+        starfield  which  has  been  corrected  for  pixel to pixel gain
+        variations,  high  frequency  fluctuations  in  the  background, 
+        nonlinearity,  and  any other instrumental defects affecting the
+        intensity value of a pixel.
+
+    (2) Given as input the approximate coordinates of  a  single  object
+        in   the   image,   the  program  shall  perform  the  following 
+        operations:
+
+            o   Determine a constant background  value  by  analysis  of
+                an   annular   region   surrounding   the  object.   The 
+                background is assumed to be flat in the  region  of  the
+                object,   but   may  contain  contaminating  objects  or 
+                defects which shall be detected and  eliminated  by  the
+                fitting  algorithm.   It  shall  be  permissible for the
+                background region to extend  beyond  the  boundaries  of
+                the  image;  the  out  of  bounds  region of the annulus
+                shall be excluded from the fit.
+
+            o   Determine  the  center  of  the   object,   taking   the 
+                approximate  object  coordinates  given  as  input  as a
+                starting  point.   The  center  determination  shall  be 
+                resistant   to   the  affects  of  nearby  contaminating 
+                objects.  The centering algorithm may  assume  that  the
+                object  is  circularly symmetric, or nearly so, and that
+                the object flux is positive.
+
+            o   Determine  the  integral  of  object  minus   background 
+                within  one  or  more  circular  apertures centered upon
+                the object.  The integration shall  be  performed  using
+                partial  pixel  techniques,  to  minimize the effects of
+                sampling.   If  the  aperture  contains  any  indefinite 
+                pixels,  or  if the aperture extends beyond the boundary
+                of the image, an indefinite result shall be returned.
+
+    (3) The  following  options  shall  be  provided   to   modify   the 
+        operation of the above functions:
+
+
+                                  -1-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+            o   Use  a  user  supplied  constant  background  value  and 
+                background  noise  estimate  instead  of   fitting   the 
+                background.
+
+            o   Use  the  starting  center  as  the actual center in all
+                cases.
+
+            o   Use the starting center as  the  actual  center  if  the
+                object  is  very  faint,  but tweak up the center if the
+                signal to noise is above a certain threshold.
+
+            o   Allow the object aperture to  extend  beyond  the  image
+                boundary,  using  only  that  portion  of  the  aperture 
+                which  is  in  bounds  when   computing   the   aperture 
+                integral.
+
+    (4) At  a  minimum, the following parameters shall be calculated and
+        output for each object:
+
+            o   The coordinates of the object, and the  estimated  error
+                in these coordinates.
+
+            o   The  mode  and standard deviation of the background; the
+                number of pixels left in  the  background  region  after
+                pixel rejection.
+
+            o   The  magnitude  of  the  object,  to  within an arbitary
+                zero-point,  and  the  statistical  uncertainty  of  the 
+                magnitude.   If  multiple concentric apertures are used,
+                a magnitude and uncertainty shall be given for each.
+
+    (5) The program shall be usable  both  interactively  and  in  batch
+        mode.   In  interactive  use, the user shall be able to mark the
+        positions of the objects by interactively positioning  a  cursor
+        on  a  2-dim  display device.  It shall be possible to enter the
+        control parameters for the analysis routines  interactively  for
+        each  object.   In  batch  mode, the control parameters shall be
+        fixed, and  object  coordinates  shall  be  taken  from  a  user
+        supplied  list.   The  display  device  shall not be required in
+        batch mode.
+
+    (6) The APPHOT package shall be  written  in  the  SPP  language  in
+        conformance  with  the  standards  and conventions of IRAF.  The
+        code shall be portable and device independent.
+
+
+
+2.1 Summary of the Limitations of APPHOT
+
+    The  APPHOT  package  is  designed  to   perform   simple   aperture 
+photometry subject to the following restrictions:
+
+    (1) Objects   must   be  circular  or  nearly  circular,  since  the 
+
+
+                                  -2-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+        aperture is circular.
+
+    (2) All pixels within the  object  aperture  are  weighted  equally.
+        All  pixels  in  the object aperture must be present; the object
+        aperture may not normally extend outside the  image.   Defective
+        pixels within the object aperture may not be detected.
+
+    (3) The  background  must  be approximately flat in the neighborhood
+        of the object  being  measured.   The  background  must  have  a
+        unique  mode,  or the background fitting routine will reject the
+        object.   Any  low  frequency  fluctuations  in  the  background 
+        should be removed before using APPHOT.
+
+    (4) The   object  aperture  must  be  kept  small  to  minimize  the 
+        degradation of signal to noise caused by sky pixels  within  the
+        aperture,  and  to minimize the effects of crowding.  Therefore,
+        the wings of the object will extend beyond the  aperture.   Good
+        photometric  results  will  be  obtained only if the aperture is
+        consistently well centered, and if the  shape  and  diameter  of
+        an  object  is  constant throughout the image and invariant with
+        respect to magnitude.
+
+
+
+3. Specifications
+
+    The  APPHOT  package  performs  aperture  photometry  on   digitized 
+starfields   maintained  as  IRAF  imagefiles.   Input  to  the  package 
+consists of an imagefile, a list of  object  coordinates,  and  numerous
+parameters  controlling  the  analysis  algorithms.   Output consists of
+successive lines of text, where each  line  summarizes  the  results  of
+the  analysis  for  a  particular  object.  The output may be saved in a
+textfile, which may easily be printed  or  written  onto  a  card  image
+tape   for   export.    The   package   routines   may  be  used  either 
+interactively or in batch mode.
+
+The CL callable part of the APPHOT package  consists  of  the  following
+routines:
+
+        apphot   -- the main aperture photometry routine.
+        coordtr  -- translations and rotations of coord lists.
+        fitsky   -- computes mode and sigma of a sky region.
+        fitpsf   -- compute the FWHM of the PSF.
+        imcursor -- reads the image cursor; used to make lists.
+        immark   -- marks objects on the display device.
+        radprof  -- computes the radial profile of an object.
+
+Routines  for  general list manipulation, reading and writing card image
+tapes,  reading  and  writing  images  to  FITS  tapes,   removing   the 
+instrumental   signature   from  the  data,  and  so  on  are  available 
+elsewhere in the  IRAF  system.   The  package  is  easily  extended  to
+include  peak  finding,  matching of object lists from different images,
+background fitting and removal, and so on.   The  APPHOT  package  shall
+
+
+                                  -3-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+eventually   supplant   both   the  KPNO  AUTOPHOT  and  KPNO  "Mountain 
+Photometry Code" packages.
+
+
+
+3.1 Standard Analysis Procedures
+
+    Before performing aperture photometry one must determine the  radius
+of  the  object  aperture  to  be used, the inner radius and size of the
+annulus to be used to fit the background, the full  width  at  half  max
+(FWHM)  of  the  point  spread  function  (PSF),  and so on.  Additional
+parameters are required by the centering algorithm.  A  list  of  object
+centers  must  be  prepared  if APPHOT is to be used in batch mode.  The
+standard procedure is as follows:
+
+    (1) Use RADPROF to determine values for the following parameters:
+
+            - the object aperture radius or radii, in pixels
+            - the inner radius of the annular (sky) region
+            - the width of the annular region
+
+    (2) Use FITPSF to fit gaussians to isolated, high  signal  to  noise
+        data  objects,  to  determine  the  FWHM  of  the  point  spread 
+        function.
+
+    (3) Use FITSKY to determine  the  sky  sigma  (standard  deviation).
+        APPHOT  assumes  that sigma is approximately constant throughout
+        the image.
+
+    (4) If one does not wish to  manually  mark  object  positions  with
+        the  cursor  during  analysis,  i.e.  when the analysis is to be
+        done in batch, a list of object coordinates  must  be  prepared.
+        This may be done in many ways:
+
+            o   By  running  RCURSOR with the standard output redirected
+                into the list file.
+
+            o   By transforming an existing list with  COORDTR,  OPSTRM,
+                MATCH, SORT, WINDOW, the editor, or some other filter.
+
+            o   By  an  automatic  object  finding  procedure, if one is
+                available.
+
+            o   By any other program which generates a  list  of  object
+                coordinates,  where  each line of the list describes one
+                object, and where x  and  y  in  pixel  coordinates  are
+                given  in  columns  one and two.  Additional columns, if
+                present, are ignored.
+
+            o   APPHOT output may be  used  as  coordinate  input  in  a
+                subsequent run.
+
+    (5) Finally,  APPHOT  is  run  to  measure  the  objects.   The user
+
+
+                                  -4-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+        should  be  familiar  with  the  algorithms  used  to  fit   the 
+        background,   measure   the   object  center,  and  compute  the 
+        aperture integral, magnitude, and errors.   The  values  of  all
+        visible   and  hidden  APPHOT  parameters  should  be  inspected 
+        before doing any serious processing.
+
+The general purpose IRAF list processing tools may be used  for  further
+analysis  of  APPHOT  output.   Output  lists  may be filtered to select
+objects based on the value of a  list  column,  i.e.,  all  the  objects
+within   a  certain  magnitude  range  may  be  selected,  objects  with 
+estimated errors larger than a certain value may be deleted, or  a  list
+may  be  sorted using the value in any column.  Columns may be extracted
+from a list to form new lists or to provide  input  to  a  plot  filter,
+and  lists  may  be  merged.   Arithmetic  may  be performed on lists to
+calculate colors, etc.
+
+The remainder of this section presents detailed specifications  for  the
+analysis procedures in the APPHOT package.
+
+
+
+3.2 The APPHOT Program
+
+    The  function  of  the  APPHOT  procedure  is  to  perform  aperture 
+photometry on isolated objects within an  image.   The  principal  input
+operands  are  the  name  of  the imagefile and the rough coordinates of
+the objects to be processed.  The  principal  output  operands  are  the
+coordinates and magnitudes of the objects.
+
+In  order  to  perform  aperture  photometry  APPHOT  must  perform  the 
+following  sequence  of  operations   (the   algorithms   employed   are 
+explained in more detail later in this section):
+
+    (1) The  mode  and sigma of an annular background region centered on
+        the object is calculated.
+
+    (2) The center of the object is determined.
+
+    (3) The background is subracted  from  the  object,  and  the  total
+        flux within the object aperture or apertures is calculated.
+
+Steps  (1)  and (2) above are optional; the background and center may be
+determined externally, rather than by APPHOT, if desired.
+
+
+3.2.1 APPHOT parameters
+
+    APPHOT has quite a few parameters  due  to  the  complexity  of  the
+algorithms  employed.   All  data dependent parameters are query mode to
+ensure that they get set properly when a new image  is  processed.   The
+data  independent  algorithm control parameters are hidden mode, and are
+given reasonable default values.   The  names,  datatypes,  and  default
+values of the APPHOT parameters are shown below.
+
+
+                                  -5-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+Positional or query mode parameters:
+
+        image           filename
+        apertures       string
+        annulus         real
+        width_annulus   real
+        fwhm_psf        real
+        sky_sigma       real
+
+
+List structured parameters (filename may be given on command line):
+
+        sky_mode        *real
+        coords          *imcur
+
+
+Hidden parameters:
+
+        spool           boolean         no
+        output          filename        "apphot.out"
+        fitsky          boolean         yes
+        max_sky_iter    integer         50
+        growing_radius  real            1.0 (fwhm_psf units)
+        k1              real            5.0
+        k2              real            2.0
+        center          boolean         yes
+        clean           boolean         yes
+        cleaning_radius real            0.8 (fwhm_psf units)
+        clipping_radius real            1.5 (fwhm_psf units)
+        max_cen_shift   real            1.0 (fwhm_psf units)
+        min_snratio     real            0.5
+        zmag            real            26.0
+        verbose         boolean         yes
+
+
+The  function  and  format  of  each of these parameters is explained in
+more detail below.
+
+
+    image           The name  of  the  image  or  image  section  to  be
+                    processed.
+
+    output          The  name  of  the  output  textfile  used  to spool
+                    APPHOT  output.   If  null,  output  will   not   be 
+                    spooled.   Note  that  output  always appears on the
+                    standard output,  whether  or  not  spooling  is  in
+                    effect.
+
+    apertures       The   radii  in  pixels  of  the  concentric  object 
+                    apertures, given all on  the  same  line,  delimited
+                    by  blanks.   At  least  one aperture must be given;
+                    the maximum number of apertures is  limited  by  the
+                    length  of  a  line.  A sample input string might be
+
+
+                                  -6-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+                    "5.0 5.5 6.0 6.5 7.0".  If only  a  single  aperture
+                    is  to  be  used,  a  real  expression  may  be used
+                    instead of a string type  argument.   The  apertures
+                    need  not  be  given  in  any particular order.  The
+                    average  radius  will  be  used   to   compute   the 
+                    uncertainty in the object magnitude.
+
+    annulus         The  inner  radius  of  the  annular  sky region, in
+                    pixels.
+
+    width_annulus   The width of the annular sky region, in pixels.
+
+    fwhm_psf        The FWHM of the psf, in pixels.   Used  as  a  scale
+                    factor to control the internal algorithms.
+
+    sky_sigma       The  standard  deviation  (noise value) of a typical
+                    region  of  sky  in  the  image.   Used  for   pixel 
+                    rejection in the sky fitting algorithm.
+
+    sky_mode        The  name  of a list file containing the mode of the
+                    background  of   each   of   the   objects   to   be 
+                    processed.   Required  only  if  FITSKY  is switched
+                    off.  If sky fitting is disabled, and no  list  file
+                    is given, APPHOT will query for the sky value.
+
+    coords          The  name  of a list file containing the coordinates
+                    of  the  objects  to  be  processed.    If   absent, 
+                    objects   may   be  marked  interactively  with  the 
+                    cursor.
+
+    fitsky          A  switch  used  to  specify  whether  or  not   the 
+                    background  will  be  fitted.  If background fitting
+                    is disabled, the mode and sigma  of  the  background
+                    will  be  read  from  the SKY_FILE list each time an
+                    object is processed.
+
+    max_sky_iter    The  maximum  number  of  iterations  for  the   sky 
+                    fitting    algorithm.    Since   the   sky   fitting  
+                    algorithm   is   guaranteed   to   converge,    this  
+                    parameter  should  normally  have a large value.  If
+                    the value is zero, the  median  of  the  sky  region
+                    will be used instead of the mode.
+
+    growing_radius  The  region  growing  radius  for pixel rejection in
+                    the sky region, in units of FWHM_PSF.   When  a  bad
+                    sky   pixel   is   detected,   all   pixels   within  
+                    (growing_radius  *  fwhm_psf)  pixels  of  the   bad 
+                    pixel  will  be rejected.  Used to exclude the wings
+                    of contaminating objects from  the  sky  sample,  to
+                    avoid biasing the mode.
+
+    k1              The  k-sigma  clipping factor for the first phase of
+                    the sky fitting algorithm.
+
+
+                                  -7-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+    k2              The  k-sigma  clipping  factor   for   the   second, 
+                    iterative, phase of the sky fitting algorithm.
+
+    center          A  switch  used  to specify whether or not centering
+                    is to be performed.  If centering is  disabled,  the
+                    initial center will be used as the object center.
+
+    clean           A   switch  used  to  specify  whether  or  not  the 
+                    symmetry-clean algorithm is to  be  employed  during
+                    centering.
+
+    cleaning_radius The   cleaning   radius   for   the   symmetry-clean  
+                    algorithm, in units of FWHM_PSF.
+
+    clipping_radius The   clipping   radius   for   the   symmetry-clean  
+                    algorithm, in units of FWHM_PSF.
+
+    max_cen_shift   The  maximum  permissible  shift of center, in units
+                    of  FWHM_PSF.   If  the  shift   produced   by   the 
+                    centering  algorithm  is larger than this value, the
+                    fit  will  terminate  and  no  magnitude   will   be 
+                    calculated.
+
+    min_snratio     Centering  will  be  skipped  if the signal to noise
+                    of  the  object,  as  calculated  from  the  initial 
+                    center,  is  less  than  the  value  given  by  this 
+                    parameter.
+
+    zmag            Zero point for the output magnitude scale.
+
+    verbose         If enabled, the output columns  are  labeled.   Note
+                    that  the  presence  of  column labels in the output
+                    may interfere with the use of  the  list  processing
+                    tools.
+
+
+
+3.2.2 The APPHOT Background Fitting Algorithm
+
+    A  good background fit is essential to aperture photometry.  Fitting
+the background is trivial in a sparse field, but difficult in a  crowded
+field.   In  general  the  background  region will contain contaminating
+objects which must be detected and excluded if  a  good  fit  is  to  be
+obtained.
+
+The  algorithm  employed  here  is  based  on the fact that contaminated
+pixels are  almost  always  spatially  correlated.   Background  fitting
+algorithms  which  work with a one dimensional sample (mode, median), or
+with the  one  dimensional  histogram  (mode  of  hgm)  have  difficulty
+rejecting  the  faint  wings of contaminated regions.  This is a serious
+defect of one  dimensional  fitting  algorithms,  because  it  is  these
+faint  wings,  not  the  bright central pixels, which are most likely to
+bias the calculated background value.
+
+
+                                  -8-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+The algorithm used in APPHOT is as follows:
+
+
+    algorithm fit_sky
+
+    begin
+            # Reject gross deviants.
+            compute the median of the annular region
+            detect pixels more than (k1*sky_sigma) from the median
+            reject all such pixels, without region growing
+
+            # Detect and reject contaminating objects.
+            while (number of iterations <= max_sky_iter) {
+                compute the histogram of the reduced sample
+                compute the sigma and mode of the histogram
+                detect pixels more than k2*sigma from the mode
+                reject all such pixels, with region growing
+                if (no pix rejected or all pix rejected)
+                    terminate loop
+            }
+
+            return the final mode, sigma, and sample size
+    end
+
+
+The mode of the histogram  is  found  by  cross  correlating  the  noise
+function  with  the  histogram.   The width of the the noise function is
+given  by  the  standard  deviation  of  the  current   sample.    Pixel 
+rejection  is  performed  by locating all pixels more than k2*sigma from
+the mode, and blindly rejecting all pixels within a  certain  radius  of
+each  deviant  pixel.   This  simple  algorithm  works  well because the
+sample is large, and therefore there is little  penalty  for  discarding
+pixels  that  might  not  be  deviant.   Region  growing  also  tends to
+accelerate convergence significantly.
+
+Very faint contaminating objects are difficult  to  detect  and  reject.
+If  there  are enough such objects, they should not be rejected, because
+there are probably a few in the object aperture as well.  A  higher  sky
+sigma  will  be calculated and the computed uncertainty in the magnitude
+will increase.  The best solution to this problem  may  be  to  increase
+the  size of the annulus to minimize the bias and maximize the liklihood
+of a detection.
+
+
+
+3.2.3 The APPHOT Centering Algorithm
+
+    The centering algorithm used in APPHOT  is  that  of  Auer  and  Van
+Altena,  with  the addition of the symmetry-clean algorithm developed by
+Barry Newell.  The main algorithm is as follows:
+
+
+
+
+
+                                  -9-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+    algorithm get_center
+
+    begin
+            if (centering is disabled) {
+                return initial center, zero uncertainty estimate
+
+            } else if (signal to noise of object < MIN_SNRATIO) {
+                compute uncertainty using initial center
+                return initial center, computed uncertainty
+
+            } else {
+                call measure_center
+                return image center and estimated uncertainty
+            }
+    end
+
+
+The  actual  center  determination  is  carried  out  by  the  following 
+algorithm:
+
+
+    algorithm measure_center
+
+    begin
+            extract subarray from the main data array
+
+            # Perform symmetry-cleaning.
+            if (cleaning is enabled) {
+                for (each pair of pixels diametrically opposed about
+                    the image center beyond the cleaning radius)
+                        if (i2 > i1 + 2*sky_sigma)
+                            replace i2 by i1
+                        else if (i1 > i2 + 2*sky_sigma)
+                            replace i1 by i2
+
+                perform 2*sky_sigma noniterative clip of all pixels
+                beyond the clipping radius, to remove any remaining
+                radially symmetric structures
+            }
+
+            # Compute the image center and uncertainty.
+            compute x and y marginals of the cleaned subarray
+            fit a gaussian of width FWHM_PSF to each marginal
+            compute the centering error from the covariance matrix
+
+            return image center and estimated uncertainty
+    end
+
+
+The  effect  of  the  symmetry-clean  algorithm  is  to edit the raster,
+removing any contaminating  objects  in  the  vicinity  of  the  primary
+object.   This  simplifies  the  fitting  algorithm  and  increases  its 
+reliability, since it does not have  to  deal  with  multipeak  marginal
+
+
+                                 -10-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+distributions.
+
+A  gaussian  is  fitted  to  the  marginal  distributions  because it is
+expected  to  yield  a  better  center  determination  for  undersampled 
+data.    An   alternative   is   to   empirically  derive  the  marginal 
+distributions of the psf and fit these to each data object.  This  is  a
+better  approach  in some cases, but in the case of undersampled data it
+is difficult to  derive  the  marginal  distributions  due  to  sampling
+effects,  and  fitting is difficult due to interpolation error.  The use
+of  a  gaussian  eliminates  interpolation  error.    Eventually,   both 
+techniques should be made available.
+
+
+
+3.2.4 The APPHOT Aperture Integration Algorithm
+
+    The  integral  of the flux within a circular aperture is computed by
+fractional pixel techniques.  Pixels are assumed to be square  apertures
+arranged  in  a  rectangular  grid.   The fraction of a pixel which lies
+within the circular APPHOT aperture is  computed  by  an  approximation,
+and all such contributions are summed to produce the total integral.
+
+The  simplicity  of aperture photometry limits the amount of information
+available for error analysis.   Using  only  the  noise  value  for  the
+background, the estimated error in the aperture integral is given by
+
+        flux_error = sky_sigma * sqrt (aperture_area)
+
+where  "sky_sigma"  is  either  the  sigma  calculated by the background
+fitting algorithm or the parameter SKY_SIGMA, depending on  whether  sky
+fitting  is  enabled,  and where "aperture_area" is the fractional pixel
+area of the aperture.
+
+It is possible, however, to produce a more useful error estimate  if  we
+include  some  information  about  the  psf.   For  the  purposes  of an
+improved error estimate, we assume that the PSF is  a  gaussian.   Given
+the  object  center,  the  background,  and  the  FWHM of the PSF, it is
+trivial to fit a two dimensional gaussian to the  object.   An  estimate
+of  the  average noise value for the pixels within the aperture may then
+be obtained by computing the standard deviation of the  residual  formed
+by  subtracting  the  fitted  two-dimensional  gaussian  from  the data.
+This value is used in place of SKY_SIGMA in the above  equation  for  an
+improved estimate of the actual flux error.
+
+In  the  limit  as the gaussian goes to zero, both uncertainty estimates
+tend to the same  value,  as  they  should.   For  bright  objects,  the
+uncertainty  produced  by  analysis  of  the  residual  will  tend to be
+pessimistic, since it is unlikely that the PSF can actually  be  modeled
+by  a  simple  gaussian.   Nonetheless,  a  plot  of  uncertainty versus
+magnitude should reveal objects which are  blended,  which  contain  bad
+pixels,  and  so  on.  The accuracy of the gaussian model will determine
+how reliably deviant objects can be discriminated.
+
+
+
+                                 -11-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+3.2.5 APPHOT Output
+
+    For each object processed, APPHOT prints a single line  of  text  on
+the  standard  output.   If  desired,  APPHOT  will simultaneously spool
+output into a user specified text file.  Each output line  will  contain
+the following information (excluding the commas):
+
+
+    x,y,cenerr,shift, mode,sigma,nskypix, mag1,...,magn,magerr
+
+where
+
+    x,y         object coordinates in pixels
+    cenerr      estimated uncertainty in the object center
+    shift       shift of center from initial coordinates
+    mode        mode of the background
+    sigma       sigma of the background
+    nskypix     number of sky pixels left after rejection
+    mag1        magnitude within the first annulus
+    magn        magnitude within the Nth annulus
+    magerr      estimated mag. uncertainty at the average radius
+
+
+Note  that  the estimated uncertainty in the magnitude is given only for
+the average object aperture  radius.   The  uncertainty  for  the  other
+apertures  can  easily  be  calculated  given SIGMA and the area of each
+aperture.  The zero point for  the  magnitude  scale  is  given  by  the
+hidden parameter ZMAG.
+
+Additional  information  could  be  calculated  and  output (such as the
+moments of the object and the  skew  of  the  background),  but  in  our
+experience  few people ever look at such information, and a more complex
+output format would be required.  Probably the calculation  of  anything
+but  object  centers,  magnitudes,  and  errors  should be left to other
+programs.
+
+
+
+3.3 The COORDTR Program
+
+    The function of COORDTR is to effect  a  linear  translation  and/or
+rotation  of  a  coordinate list.  COORDTR is a filter; coordinate lines
+are read from the standard input and written  to  the  standard  output.
+COORDTR  is  concerned  only  with coordinate transformations, and knows
+nothing about image boundaries.  A transformed coordinate may no  longer
+lie within an image.
+
+        x y other_stuff
+
+The  format  of a coordinate line is shown above.  COORDTR operates only
+on the coordinate pair x,y.  Any additional information on the  line  is
+passed on to the output without modification.
+
+
+
+                                 -12-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+COORDTR  is  actually  a  general  purpose list processing operator, and
+belongs in  a  list  processing  package,  rather  than  in  the  APPHOT
+package.   When  a list processing package is developed, COORDTR will be
+moved to that package.
+
+A COORDTR transformation consists of a linear  translation  followed  by
+a  rotation.   Either  the  translation,  the  rotation,  or both may be
+skipped.  The COORDTR parameters are summarized below.
+
+
+positional arguments:
+
+        xshift          real
+        yshift          real
+        xcenter         real
+        ycenter         real
+        theta           real
+
+
+hidden parameters:
+
+        translate       boolean         yes
+        rotate          boolean         no
+
+
+If more than two positional arguments  are  given,  COORDTR  knows  that
+both  a  translation  and a rotation are desired.  Otherwise the boolean
+parameters TRANSLATE and ROTATE are read to  determine  what  additional
+parameters  are  needed.   Thus  a  simple  linear  translation  of +2.5
+pixels in X and -0.2 pixels in Y would be specified by the command
+
+        coordtr (2.5, -.2, < "input", > "output")
+
+which transforms the list in file "input", writing the output  into  the
+new file "output".
+
+If  a  rotation  is  desired, XCENTER, YCENTER, and THETA must be given.
+The first two parameters specify the  pixel  coordinates  of  the  point
+about  which  the rotation is to be performed, while THETA specifies the
+rotation angle in degrees.  Positive THETA produces  a  counterclockwise
+rotation, if positive X is to the right and positive Y is up.
+
+
+
+3.4 The FITSKY Program
+
+    The  function  of  the  FITSKY  program is to determine the mode and
+sigma of the specified annular  regions,  printing  the  results  (mode,
+sigma,  and  npix)  on  the  standard  output.   FITSKY  is  similar  in 
+operation to APPHOT, except  that  its  function  is  to  fit  sky,  not
+perform aperture photometry.  The FITSKY parameters are the following:
+
+
+
+
+                                 -13-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+Positional or query mode parameters:
+
+        image           filename
+        annulus         real
+        width_annulus   real
+        fwhm_psf        real
+
+
+List structured parameters (filename may be given on command line):
+
+        coords          *imcur
+
+
+Hidden parameters:
+
+        spool           boolean         no
+        output          filename        "fitsky.out"
+        max_sky_iter    integer         50
+        growing_radius  real            1.0 (fwhm_psf units)
+        k1              real            5.0
+        k2              real            2.0
+        verbose         boolean         yes
+
+
+The  names  and functions of the FITSKY parameters are the same as those
+for APPHOT.  Note that ANNULUS  may  be  set  to  zero  to  measure  the
+background   within   a   circular  aperture.   The  maximum  number  of 
+iterations may be set to zero to measure the median of the  sky  sample.
+FITSKY output may be spooled into a file and used as input to APPHOT.
+
+
+
+3.5 The FITPSF Program
+
+    The  function  of the FITPSF program is to determine the FWHM of the
+point spread function.  This is done  by  selecting  an  isolated,  high
+signal  to  noise  object,  computing the x and y marginal profiles, and
+fitting a gaussian to each  profile.   Output  consists  of  the  object
+center,  the  error in the center, and the FWHM of the fitted gaussians.
+Note that the sigma of a gaussian may be obtained by dividing  the  FWHM
+by 2.354.
+
+        x y err x_fwhm y_fwhm
+
+The input parameters for the FITPSF program are shown below.
+
+
+
+
+
+
+
+
+
+
+                                 -14-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+Positional parameters:
+
+        image           filename
+        aperture        real
+        annulus         real
+        width_annulus   real
+        sky_mode        real
+        coords          *imcur
+
+
+Hidden parameters:
+
+        fitsky          boolean         yes
+        center          boolean         yes
+        spool           boolean         no
+        output          filename        "fitpsf.out"
+        verbose         boolean         yes
+
+
+If  background  fitting  is disabled, the parameter SKY_MODE defines the
+sky  level.   The  background  fitting  algorithm  is  a  simple  median 
+calculation  without  pixel  rejection  or  iteration.   This  should be
+sufficient, since FITPSF is expected to  be  used  mainly  in  uncrowded
+regions on high signal to noise objects.
+
+Note  that  FITPSF  is  set  up to process a list of input objects.  The
+list processing tools  (i.e.,  AVERAGE)  may  be  used  to  average  the
+results to produce the final FWHM of the PSF for the image.
+
+
+
+3.6 The IMCURSOR Program
+
+    The  function  of  the  IMCURSOR  program  is  to  read the STDIMAGE
+cursor, writing the cursor coordinates  on  the  standard  output.   The
+cursor  is  read  until  the  EOF  character is entered to terminate the
+loop.  The standard output may be redirected into a file to  generate  a
+coordinate list.  IMCURSOR has no parameters.
+
+
+
+3.7 The IMMARK Program
+
+    The  function  of  IMMARK  is  to  draw  marks on the diplay device.
+IMMARK is useful for verifying coordinate lists.
+
+
+parameters:
+
+        mark_type       string
+        mark_size       real
+        coords          *imcur
+
+
+
+                                 -15-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+Output is  the  current  frame  of  the  STDIMAGE  device.   Mark  types
+include  "circle",  "box",  "cross", "plus", and "diamond".  The size of
+a  mark  is  given  in  pixels.   The  third  parameter  is  a  standard 
+coordinate  list.   If  no  list is given, the image cursor will be read
+instead.
+
+
+
+3.8 The RADPROF Program
+
+    The function of  the  RADPROF  program  is  to  compute  the  radial
+profile  of  an object.  The output of RADPROF consists of a sequence of
+lines of text, each line  defining  the  profile  at  a  single  radius.
+Since  RADPROF  may  generate  many  lines  of output for a single input
+object, it is set up to process  only  a  single  input  object.   A  CL
+while loop may be written to process multiple objects, if desired.
+
+
+positional arguments:
+
+        image           filename
+        aperture        real
+        step_size       real
+        annulus         real
+        width_annulus   real
+        sky_mode        real
+
+
+hidden parameters:
+
+        fitsky          boolean         yes
+        center          boolean         yes
+        verbose         boolean         yes
+
+
+The  radial  profile  is  calculated  from  the  image center out to the
+radius specified by  the  parameter  APERTURE,  in  steps  of  STEP_SIZE
+pixels.   The  remaining  RADPROF  parameters  are  similar  to those of
+APPHOT and will not be discussed in detail.  If  background  fitting  is
+disabled,   the   parameter   SKY_MODE   defines  the  sky  level.   The 
+background fitting algorithm is  a  simple  median  calculation  without
+pixel   rejection  or  iteration.   This  should  be  sufficient,  since 
+RADPROF is expected to be used  mainly  in  uncrowded  regions  on  high
+signal  to  noise  objects.   Centering  is  via  gaussian  fits  to the
+marginal profiles, without cleaning.
+
+RADPROF output lines contain the following fields:
+
+        r, i(r), inorm(r), fraction(r)
+
+where
+
+        r               radius in pixels
+
+
+                                 -16-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+        i(r)            raw intensity at r
+        inorm(r)        normalized intensity at r (range 0-1)
+        fraction(r)     fraction of total integral at r
+
+
+RADPROF does not  generate  any  plots.   If  one  wishes  to  plot  the
+contents  of  an  output column, the column may be extracted with a list
+processing filter and piped to a graphics task.
+
+
+
+4.0 Example
+
+    A brief  example  may  help  illustrate  the  use  of  the  package.
+Suppose  we  want  to  process  a few hundred stars on images "blue" and
+"red".  We start by analyzing the blue image.
+
+        ap> radprof blue,15,0.5,20,10
+
+This gives us a radial profile printout for one  of  the  "blue"  stars.
+We  decide  that  an  aperture radius of 2.5 pixels is about right.  The
+annulus will start at a  radius  of  10.0  pixels  and  extend  to  20.0
+pixels.  The next step is to determine the FWHM of the PSF:
+
+        ap> fitpsf blue,3,10,20 | tee spoolfile
+
+By  default, the program will take coordinate input by reading the image
+display cursor.  When the program is waiting for cursor input,  it  will
+cause  the display cursor to blink rapidly; normally the cursor does not
+blink.  One has to be aware of this, because no other prompt is  issued.
+We  postion  the  cursor  on  several  stars,  and  tap the space bar to
+measure each one.  When finished we type  the  EOF  character  (<ctrl/z>
+on  our  systems)  to terminate the loop.  The screen will now look like
+this (the output column labels are ommitted):
+
+        ap> fitpsf blue,3,10,20 | tee spoolfile
+         283.12  157.40 0.035  2.887  2.751
+         546.08  213.45 0.023  2.833  2.902
+         318.32  354.73 0.064  2.791  2.824
+
+Since we elected to use TEE to spool the output, rather than  the  SPOOL
+parameter  of  FITPSF,  we will not see the results until all stars have
+been measured.  The next step is to average the  results,  to  determine
+the  final  FWHM  (the  FITPSF  output could have been piped directly to
+GETCOLS without using an intermediate spoolfile, if desired).
+
+        ap> getcols spoolfile,"4-5" | getcols | average
+        2.83133 0.0569725 6 
+
+There are many ways this average could have been  computed,  of  course;
+this  is  only  one  example.   Next,  to avoid having to write down the
+FWHM value, we put it into the appropriate APPHOT parameter  (note  that
+the parameter name is abbreviated).
+
+
+                                 -17-
+APPHOT (Aug83)    Digital Aperture Photometry Package     APPHOT (Aug83)
+
+
+
+        ap> apphot.fwhm = 2.831
+
+Finally,  we  must  determine a representative backround sigma value for
+the image.  This is done by using FITSKY to measure several  sky  areas,
+and  averaging column two of the output, much as we did for FITPSF.  The
+final value may be saved in "apphot.sky_sigma".
+
+By this point we have determined all the necessary  parameters,  and  it
+is  time  to  do  some photometry.  The only APPHOT argument we are sure
+of is the image name parameter,  so  that  is  all  we  include  on  the
+command line:
+
+        ap> apphot blue
+        aperture radii, pixels: 2.4 2.5 2.75 3.0
+        inner radius of sky annulus: 10
+        width of sky annulus (1 - ): 10
+        full width at half max of psf (2.831):
+        standard deviation of the image noise function (23.733):
+
+After  responding  to  the  prompts shown above, APPHOT will ask for the
+first pair of object coordinates,  and  the  cursor  blink  prompt  will
+again  be  given.  Several objects may be measured to verify that all is
+working.
+
+The last step is to prepare a list of  objects  to  be  processed.   The
+simplest  way  to  do this is to interactively mark the objects with the
+cursor.  Later, when we process the "red"  image,  the  same  coordinate
+list may again be used, possibly after filtering with COORDTR.
+
+        ap> imcursor > objlist
+
+At  this  point,  all  of the APPHOT parameters have been set, we have a
+list of objects to be processed, and we  are  ready  to  run  APPHOT  in
+batch  mode.   We  decide to save the output in the file "blue.out".  To
+ensure that we have a record of the parameters  used  for  the  fit,  we
+first  print  the  APPHOT parameters into the output file, then we start
+up the APPHOT batch run.
+
+        ap> lparam apphot > blue.out
+        ap> apphot >> blue.out &
+        [1]
+
+The batch job is  now  running,  appending  output  lines  to  the  file
+"blue.out".   We  can  proceed  to  set up the job for the red image, in
+much the same way that we set up the  job  for  the  blue  image.   When
+both  jobs  finish,  we  can use the list processing tools to filter out
+the good objects and calculate colors.
diff --git a/noao/digiphot/apphot/doc/specs/Ap.spc b/noao/digiphot/apphot/doc/specs/Ap.spc
new file mode 100644
index 00000000..911d04f1
--- /dev/null
+++ b/noao/digiphot/apphot/doc/specs/Ap.spc
@@ -0,0 +1,1032 @@
+.help apphot Aug83 "Digital Aperture Photometry Package"
+.sh
+1. Introduction
+
+    The APPHOT package will provide a set of routines for performing
+aperture photometry on uncrowded or moderately crowded fields, in either
+interactive or batch mode.  The basic photometry technique employed
+shall be fractional-pixel aperture integration; no PSF fitting techniques
+shall be employed, and no knowledge of the PSF shall be required.
+This document presents the formal requirements and specifications for
+the package, and describes the algorithms to be used.
+
+.sh
+2. Requirements
+.ls 4
+.ls (1)
+The program shall take as input an IRAF imagefile containing a starfield
+which has been corrected for pixel to pixel gain variations, high frequency
+fluctuations in the background, nonlinearity, and any other instrumental
+defects affecting the intensity value of a pixel.
+.le
+.ls (2)
+Given as input the approximate coordinates of a single object in the image,
+the program shall perform the following operations:
+.ls 4
+.ls o
+Determine a constant background value by analysis of an annular region
+surrounding the object.  The background is assumed to be flat in the region
+of the object, but may contain contaminating objects or defects which
+shall be detected and eliminated by the fitting algorithm.
+It shall be permissible for the background region to extend beyond the
+boundaries of the image; the out of bounds region of the annulus shall
+be excluded from the fit.
+.le
+.ls o
+Determine the center of the object, taking the approximate object
+coordinates given as input as a starting point.
+The center determination shall be resistant to the affects of nearby
+contaminating objects.  The centering algorithm may assume that the object
+is circularly symmetric, or nearly so, and that the object flux is positive.
+.le
+.ls o
+Determine the integral of object minus background within one or more
+circular apertures centered upon the object.  The integration shall be
+performed using partial pixel techniques, to minimize the effects of
+sampling.  If the aperture contains any indefinite pixels, or if the
+aperture extends beyond the boundary of the image, an indefinite result
+shall be returned.
+.le
+.le
+.le
+.ls (3)
+The following options shall be provided to modify the operation of the
+above functions:
+.ls
+.ls o
+Use a user supplied constant background value and background noise estimate
+instead of fitting the background.
+.le
+.ls o
+Use the starting center as the actual center in all cases.
+.le
+.ls o
+Use the starting center as the actual center if the object is very faint,
+but tweak up the center if the signal to noise is above a certain threshold.
+.le
+.ls o
+Allow the object aperture to extend beyond the image boundary,
+using only that portion of the aperture which is in bounds when computing
+the aperture integral.
+.le
+.le
+.le
+.ls (4)
+At a minimum, the following parameters shall be calculated and output
+for each object:
+.ls
+.ls o
+The coordinates of the object, and the estimated error in these coordinates.
+.le
+.ls o
+The mode and standard deviation of the background; the number of pixels
+left in the background region after pixel rejection.
+.le
+.ls o
+The magnitude of the object, to within an arbitary zero-point, and
+the statistical uncertainty of the magnitude.  If multiple concentric
+apertures are used, a magnitude and uncertainty shall be given for each.
+.le
+.le
+.le
+.ls (5)
+The program shall be usable both interactively and in batch mode.
+In interactive use, the user shall be able to mark the positions of the
+objects by interactively positioning a cursor on a 2-dim display device.
+It shall be possible to enter the control parameters for the analysis
+routines interactively for each object.  In batch mode, the control
+parameters shall be fixed, and object coordinates shall be taken from
+a user supplied list.  The display device shall not be required in
+batch mode.
+.le
+.ls (6)
+The APPHOT package shall be written in the SPP language in conformance
+with the standards and conventions of IRAF.  The code shall be portable
+and device independent.
+.le
+.le
+
+.sh
+2.1 Summary of the Limitations of APPHOT
+
+    The APPHOT package is designed to perform simple aperture photometry
+subject to the following restrictions:
+.ls
+.ls (1)
+Objects must be circular or nearly circular, since the aperture is
+circular.
+.le
+.ls (2)
+All pixels within the object aperture are weighted equally.  All pixels
+in the object aperture must be present; the object aperture may not normally
+extend outside the image.  Defective pixels within the object
+aperture may not be detected.
+.le
+.ls (3)
+The background must be approximately flat in the neighborhood of the
+object being measured.  The background must have a unique mode,
+or the background fitting routine will reject the object.  Any low
+frequency fluctuations in the background should be removed before
+using APPHOT.
+.le
+.ls (4)
+The object aperture must be kept small to minimize the degradation of
+signal to noise caused by sky pixels within the aperture, and to
+minimize the effects of crowding.  Therefore, the wings of the object
+will extend beyond the aperture.  Good photometric results will be
+obtained only if the aperture is consistently well centered, and if the
+shape and diameter of an object is constant throughout the image and
+invariant with respect to magnitude.
+.le
+.le
+
+.sh
+3. Specifications
+
+    The APPHOT package performs aperture photometry on digitized starfields
+maintained as IRAF imagefiles.  Input to the package consists of an imagefile,
+a list of object coordinates, and numerous parameters controlling the analysis
+algorithms.  Output consists of successive lines of text, where each line
+summarizes the results of the analysis for a particular object.  The output
+may be saved in a textfile, which may easily be printed or written onto a
+card image tape for export.  The package routines may be used either
+interactively or in batch mode.
+
+The CL callable part of the APPHOT package consists of the following
+routines:
+
+.ks
+.nf
+	apphot	 -- the main aperture photometry routine.
+	coordtr	 -- translations and rotations of coord lists.
+	fitsky	 -- computes mode and sigma of a sky region.
+	fitpsf	 -- compute the FWHM of the PSF.
+	imcursor -- reads the image cursor; used to make lists.
+	immark	 -- marks objects on the display device.
+	radprof	 -- computes the radial profile of an object.
+.fi
+.ke
+
+Routines for general list manipulation, reading and writing card image tapes,
+reading and writing images to FITS tapes, removing the instrumental signature
+from the data, and so on are available elsewhere in the IRAF system.
+The package is easily extended to include peak finding,
+matching of object lists from different images,
+background fitting and removal, and so on.  The APPHOT package shall eventually
+supplant both the KPNO AUTOPHOT and KPNO "Mountain Photometry Code" packages.
+
+.sh
+3.1 Standard Analysis Procedures
+
+    Before performing aperture photometry one must determine the radius
+of the object aperture to be used, the inner radius and size of the annulus
+to be used to fit the background, the full width at half max (FWHM) of
+the point spread function (PSF), and so on.
+Additional parameters are required by the centering algorithm.
+A list of object centers must be prepared if APPHOT is to be used in
+batch mode.  The standard procedure is as follows:
+.ls
+.ls (1)
+Use RADPROF to determine values for the following parameters:
+
+.nf
+    - the object aperture radius or radii, in pixels
+    - the inner radius of the annular (sky) region
+    - the width of the annular region
+.fi
+.le
+.ls (2)
+Use FITPSF to fit gaussians to isolated, high signal to noise data objects,
+to determine the FWHM of the point spread function.
+.le
+.ls (3)
+Use FITSKY to determine the sky sigma (standard deviation).
+APPHOT assumes that sigma is approximately constant throughout the image.
+.le
+.ls (4)
+If one does not wish to manually mark object positions with the cursor
+during analysis, i.e. when the analysis is to be done in batch, a list
+of object coordinates must be prepared.  This may be done in many ways:
+.ls
+.ls o
+By running RCURSOR with the standard output redirected into the list file.
+.le
+.ls o
+By transforming an existing list with COORDTR, OPSTRM, MATCH, SORT, WINDOW,
+the editor, or some other filter.
+.le
+.ls o
+By an automatic object finding procedure, if one is available.
+.le
+.ls o
+By any other program which generates a list of object coordinates,
+where each line of the list describes one object, and where x and y
+in pixel coordinates are given in columns one and two.  Additional
+columns, if present, are ignored.
+.le
+.ls o
+APPHOT output may be used as coordinate input in a subsequent run.
+.le
+.le
+.le
+.ls (5)
+Finally, APPHOT is run to measure the objects.  The user should be familiar
+with the algorithms used to fit the background, measure the object center,
+and compute the aperture integral, magnitude, and errors.  The values of
+all visible and hidden APPHOT parameters should be inspected before doing
+any serious processing.
+.le
+.le
+
+The general purpose IRAF list processing tools may be used for further
+analysis of APPHOT output.
+Output lists may be filtered to select objects based on the value of a
+list column, i.e., all the objects within a certain magnitude range may
+be selected, objects with estimated errors larger than a certain value
+may be deleted, or a list may be sorted using the value in any column.
+Columns may be extracted from a list to form new lists or to provide input
+to a plot filter, and lists may be merged.
+Arithmetic may be performed on lists to calculate colors, etc.
+
+The remainder of this section presents detailed specifications for the analysis
+procedures in the APPHOT package.
+
+.sh
+3.2 The APPHOT Program
+
+    The function of the APPHOT procedure is to perform aperture photometry
+on isolated objects within an image.  The principal input operands are the 
+name of the imagefile and the rough coordinates of the objects to be processed.
+The principal output operands are the coordinates and magnitudes of the
+objects.
+
+In order to perform aperture photometry APPHOT must perform the following
+sequence of operations (the algorithms employed are explained in
+more detail later in this section):
+.ls
+.ls (1)
+The mode and sigma of an annular background region centered on the object
+is calculated.
+.le
+.ls (2)
+The center of the object is determined.
+.le
+.ls (3)
+The background is subracted from the object, and the total flux within
+the object aperture or apertures is calculated.
+.le
+.le
+
+Steps (1) and (2) above are optional; the background and center may be
+determined externally, rather than by APPHOT, if desired.
+.sh
+3.2.1 APPHOT parameters
+
+    APPHOT has quite a few parameters due to the complexity of the
+algorithms employed.  All data dependent parameters are query mode to
+ensure that they get set properly when a new image is processed.
+The data independent algorithm control parameters are hidden mode,
+and are given reasonable default values.  The names, datatypes, and
+default values of the APPHOT parameters are shown below.
+
+
+.ks
+.nf
+Positional or query mode parameters:
+
+	image		filename
+	apertures	string
+	annulus		real
+	width_annulus	real
+	fwhm_psf	real
+	sky_sigma	real
+.fi
+.ke
+
+
+.ks
+.nf
+List structured parameters (filename may be given on command line):
+
+	sky_mode	*real
+	coords		*imcur
+.fi
+.ke
+
+
+.ks
+.nf
+Hidden parameters:
+
+	spool		boolean		no
+	output		filename	"apphot.out"
+	fitsky		boolean		yes
+	max_sky_iter	integer		50
+	growing_radius	real		1.0 (fwhm_psf units)
+	k1		real		5.0
+	k2		real		2.0
+	center		boolean		yes
+	clean		boolean		yes
+	cleaning_radius	real		0.8 (fwhm_psf units)
+	clipping_radius	real		1.5 (fwhm_psf units)
+	max_cen_shift	real		1.0 (fwhm_psf units)
+	min_snratio	real		0.5
+	zmag		real		26.0
+	verbose		boolean		yes
+.fi
+.ke
+
+
+The function and format of each of these parameters is explained in more
+detail below.
+
+.ls
+.ls 16 image
+The name of the image or image section to be processed.
+.le
+.ls output
+The name of the output textfile used to spool APPHOT output.
+If null, output will not be spooled.  Note that output always appears on
+the standard output, whether or not spooling is in effect.
+.le
+.ls apertures
+The radii in pixels of the concentric object apertures, given all on the
+same line, delimited by blanks.  At least one aperture must be given;
+the maximum number of apertures is limited by the length of a line.
+A sample input string might be "5.0 5.5 6.0 6.5 7.0".  If only a single
+aperture is to be used, a real expression may be used instead of a string
+type argument.  The apertures need not be given in any particular order.
+The average radius will be used to compute the uncertainty in the
+object magnitude.
+.le
+.ls annulus
+The inner radius of the annular sky region, in pixels.
+.le
+.ls width_annulus
+The width of the annular sky region, in pixels.
+.le
+.ls fwhm_psf
+The FWHM of the psf, in pixels.  Used as a scale factor to control the
+internal algorithms.
+.le
+.ls sky_sigma
+The standard deviation (noise value) of a typical region of sky in
+the image.  Used for pixel rejection in the sky fitting algorithm.
+.le
+.ls sky_mode
+The name of a list file containing the mode of the background of each of
+the objects to be processed.  Required only if FITSKY is switched off.
+If sky fitting is disabled, and no list file is given, APPHOT will query
+for the sky value.
+.le
+.ls coords
+The name of a list file containing the coordinates of the objects to
+be processed.  If absent, objects may be marked interactively with the
+cursor.
+.le
+.ls fitsky
+A switch used to specify whether or not the background will be fitted.
+If background fitting is disabled, the mode and sigma of the background
+will be read from the SKY_FILE list each time an object is processed.
+.le
+.ls max_sky_iter
+The maximum number of iterations for the sky fitting algorithm.
+Since the sky fitting algorithm is guaranteed to converge,
+this parameter should normally have a large value.  If the value
+is zero, the median of the sky region will be used instead of the mode.
+.le
+.ls growing_radius
+The region growing radius for pixel rejection in the sky region, in units
+of FWHM_PSF.  When a bad sky pixel is detected, all pixels within
+(growing_radius * fwhm_psf) pixels of the bad pixel will be rejected.
+Used to exclude the wings of contaminating objects from the sky sample,
+to avoid biasing the mode.
+.le
+.ls k1
+The k-sigma clipping factor for the first phase of the sky fitting algorithm.
+.le
+.ls k2
+The k-sigma clipping factor for the second, iterative, phase of the
+sky fitting algorithm.
+.le
+.ls center
+A switch used to specify whether or not centering is to be performed.
+If centering is disabled, the initial center will be used as the object center.
+.le
+.ls clean
+A switch used to specify whether or not the symmetry-clean algorithm
+is to be employed during centering.
+.le
+.ls cleaning_radius
+The cleaning radius for the symmetry-clean algorithm, in units of
+FWHM_PSF.
+.le
+.ls clipping_radius
+The clipping radius for the symmetry-clean algorithm, in units of
+FWHM_PSF.
+.le
+.ls max_cen_shift
+The maximum permissible shift of center, in units of FWHM_PSF.
+If the shift produced by the centering algorithm is larger than this value,
+the fit will terminate and no magnitude will be calculated.
+.le
+.ls min_snratio
+Centering will be skipped if the signal to noise of the object,
+as calculated from the initial center, is less than the value given
+by this parameter.
+.le
+.ls zmag
+Zero point for the output magnitude scale.
+.le
+.ls verbose
+If enabled, the output columns are labeled.  Note that the presence
+of column labels in the output may interfere with the use of the list
+processing tools.
+.le
+.le
+
+.sh
+3.2.2 The APPHOT Background Fitting Algorithm
+
+    A good background fit is essential to aperture photometry.  Fitting
+the background is trivial in a sparse field, but difficult in a crowded
+field.  In general the background region will contain contaminating objects
+which must be detected and excluded if a good fit is to be obtained.
+
+The algorithm employed here is based on the fact that contaminated pixels
+are almost always spatially correlated.  Background fitting algorithms
+which work with a one dimensional sample (mode, median), or with the one
+dimensional histogram (mode of hgm) have difficulty rejecting the faint
+wings of contaminated regions.  This is a serious defect of one dimensional
+fitting algorithms, because it is these faint wings, not the bright
+central pixels, which are most likely to bias the calculated background value.
+
+The algorithm used in APPHOT is as follows:
+
+
+.ks
+.nf
+    algorithm fit_sky
+
+    begin
+	    # Reject gross deviants.
+	    compute the median of the annular region
+	    detect pixels more than (k1*sky_sigma) from the median
+	    reject all such pixels, without region growing
+
+	    # Detect and reject contaminating objects.
+	    while (number of iterations <= max_sky_iter) {
+		compute the histogram of the reduced sample
+		compute the sigma and mode of the histogram
+		detect pixels more than k2*sigma from the mode
+		reject all such pixels, with region growing
+		if (no pix rejected or all pix rejected)
+		    terminate loop
+	    }
+
+	    return the final mode, sigma, and sample size
+    end
+.fi
+.ke
+
+
+The mode of the histogram is found by cross correlating the noise function
+with the histogram.  The width of the the noise function is given by the
+standard deviation of the current sample.  Pixel rejection is
+performed by locating all pixels more than k2*sigma from the mode,
+and blindly rejecting all pixels within a certain radius of each deviant
+pixel.  This simple algorithm works well because the sample is large,
+and therefore there is little penalty for discarding pixels that might
+not be deviant.  Region growing also tends to accelerate convergence
+significantly.
+
+Very faint contaminating objects are difficult to detect and reject.
+If there are enough such objects, they should not be rejected, because
+there are probably a few in the object aperture as well.  A higher sky
+sigma will be calculated and the computed uncertainty in the magnitude
+will increase.  The best solution to this problem may be to increase
+the size of the annulus to minimize the bias and maximize the liklihood
+of a detection.
+
+.sh
+3.2.3 The APPHOT Centering Algorithm
+
+    The centering algorithm used in APPHOT is that of Auer and Van Altena,
+with the addition of the symmetry-clean algorithm developed by Barry Newell.
+The main algorithm is as follows:
+
+
+.ks
+.nf
+    algorithm get_center
+
+    begin
+	    if (centering is disabled) {
+		return initial center, zero uncertainty estimate
+
+	    } else if (signal to noise of object < MIN_SNRATIO) {
+		compute uncertainty using initial center
+		return initial center, computed uncertainty
+
+	    } else {
+		call measure_center
+		return image center and estimated uncertainty
+	    }
+    end
+.fi
+.ke
+
+
+The actual center determination is carried out by the following
+algorithm:
+
+
+.ks
+.nf
+    algorithm measure_center
+
+    begin
+	    extract subarray from the main data array
+
+	    # Perform symmetry-cleaning.
+	    if (cleaning is enabled) {
+		for (each pair of pixels diametrically opposed about
+		    the image center beyond the cleaning radius)
+			if (i2 > i1 + 2*sky_sigma)
+			    replace i2 by i1
+			else if (i1 > i2 + 2*sky_sigma)
+			    replace i1 by i2
+
+		perform 2*sky_sigma noniterative clip of all pixels
+		beyond the clipping radius, to remove any remaining
+		radially symmetric structures
+	    }
+
+	    # Compute the image center and uncertainty.
+	    compute x and y marginals of the cleaned subarray
+	    fit a gaussian of width FWHM_PSF to each marginal
+	    compute the centering error from the covariance matrix
+
+	    return image center and estimated uncertainty
+    end
+.fi
+.ke
+
+
+The effect of the symmetry-clean algorithm is to edit the raster,
+removing any contaminating objects in the vicinity of the primary object.
+This simplifies the fitting algorithm and increases its reliability,
+since it does not have to deal with multipeak marginal distributions.
+
+A gaussian is fitted to the marginal distributions because it is expected
+to yield a better center determination for undersampled data.  
+An alternative is to empirically derive the marginal distributions of
+the psf and fit these to each data object.  This is a better approach in
+some cases, but in the case of undersampled data it is difficult to derive
+the marginal distributions due to sampling effects, and fitting is difficult
+due to interpolation error.  The use of a gaussian eliminates interpolation
+error.  Eventually, both techniques should be made available.
+
+.sh
+3.2.4 The APPHOT Aperture Integration Algorithm
+
+    The integral of the flux within a circular aperture is computed by
+fractional pixel techniques.  Pixels are assumed to be square apertures
+arranged in a rectangular grid.  The fraction of a pixel which lies within
+the circular APPHOT aperture is computed by an approximation, and all
+such contributions are summed to produce the total integral.
+
+The simplicity of aperture photometry limits the amount of information
+available for error analysis.  Using only the noise value for the background,
+the estimated error in the aperture integral is given by
+
+	flux_error = sky_sigma * sqrt (aperture_area)
+
+where "sky_sigma" is either the sigma calculated by the background fitting
+algorithm or the parameter SKY_SIGMA, depending on whether sky fitting
+is enabled, and where "aperture_area" is the fractional pixel area of the
+aperture.
+
+It is possible, however, to produce a more useful error estimate if we
+include some information about the psf.  For the purposes of an improved
+error estimate, we assume that the PSF is a gaussian.  Given the object center,
+the background, and the FWHM of the PSF, it is trivial to fit a two dimensional
+gaussian to the object.  An estimate of the average noise value for the
+pixels within the aperture may then be obtained by computing the standard
+deviation of the residual formed by subtracting the fitted two-dimensional
+gaussian from the data.  This value is used in place of SKY_SIGMA in the
+above equation for an improved estimate of the actual flux error.
+
+In the limit as the gaussian goes to zero, both uncertainty estimates tend
+to the same value, as they should.  For bright objects, the uncertainty
+produced by analysis of the residual will tend to be pessimistic, since
+it is unlikely that the PSF can actually be modeled by a simple gaussian.
+Nonetheless, a plot of uncertainty versus magnitude should reveal objects
+which are blended, which contain bad pixels, and so on.  The accuracy of
+the gaussian model will determine how reliably deviant objects can be
+discriminated.
+
+.sh
+3.2.5 APPHOT Output
+
+    For each object processed, APPHOT prints a single line of text on the
+standard output.  If desired, APPHOT will simultaneously spool output into
+a user specified text file.  Each output line will contain the following
+information (excluding the commas):
+
+
+.nf
+    x,y,cenerr,shift, mode,sigma,nskypix, mag1,...,magn,magerr
+
+where
+
+    x,y		object coordinates in pixels
+    cenerr	estimated uncertainty in the object center
+    shift	shift of center from initial coordinates
+    mode	mode of the background
+    sigma	sigma of the background
+    nskypix	number of sky pixels left after rejection
+    mag1	magnitude within the first annulus
+    magn	magnitude within the Nth annulus
+    magerr	estimated mag. uncertainty at the average radius
+.fi
+
+
+Note that the estimated uncertainty in the magnitude is given only for
+the average object aperture radius.  The uncertainty for the other
+apertures can easily be calculated given SIGMA and the area of each
+aperture.  The zero point for the magnitude scale is given by the
+hidden parameter ZMAG.
+
+Additional information could be calculated and output (such as the
+moments of the object and the skew of the background), but in our
+experience few people ever look at such information, and a more complex
+output format would be required.  Probably the calculation of anything
+but object centers, magnitudes, and errors should be left to other
+programs.
+
+.sh
+3.3 The COORDTR Program
+
+    The function of COORDTR is to effect a linear translation and/or
+rotation of a coordinate list.  COORDTR is a filter; coordinate lines
+are read from the standard input and written to the standard output.
+COORDTR is concerned only with coordinate transformations, and knows
+nothing about image boundaries.  A transformed coordinate may no longer
+lie within an image.
+
+	x y other_stuff
+
+The format of a coordinate line is shown above.  COORDTR operates only
+on the coordinate pair x,y.  Any additional information on the line is
+passed on to the output without modification.
+
+COORDTR is actually a general purpose list processing operator, and
+belongs in a list processing package, rather than in the APPHOT package.
+When a list processing package is developed, COORDTR will be moved to
+that package.
+
+A COORDTR transformation consists of a linear translation followed
+by a rotation.  Either the translation, the rotation, or both may be
+skipped.  The COORDTR parameters are summarized below.
+
+
+.ks
+.nf
+positional arguments:
+
+	xshift		real
+	yshift		real
+	xcenter		real
+	ycenter		real
+	theta		real
+.fi
+.ke
+
+
+.ks
+.nf
+hidden parameters:
+
+	translate	boolean		yes
+	rotate		boolean		no
+.fi
+.ke
+
+
+If more than two positional arguments are given, COORDTR knows
+that both a translation and a rotation are desired.  Otherwise the
+boolean parameters TRANSLATE and ROTATE are read to determine
+what additional parameters are needed.  Thus a simple linear translation
+of +2.5 pixels in X and -0.2 pixels in Y would be specified by the
+command
+
+	coordtr (2.5, -.2, < "input", > "output")
+
+which transforms the list in file "input", writing the output into the 
+new file "output".
+
+If a rotation is desired, XCENTER, YCENTER, and THETA must be given.
+The first two parameters specify the pixel coordinates of the point
+about which the rotation is to be performed, while THETA specifies
+the rotation angle in degrees.  Positive THETA produces a counterclockwise
+rotation, if positive X is to the right and positive Y is up.
+
+.sh
+3.4 The FITSKY Program
+
+    The function of the FITSKY program is to determine the mode and sigma
+of the specified annular regions, printing the results (mode, sigma, and npix)
+on the standard output.  FITSKY is similar in operation to APPHOT, except
+that its function is to fit sky, not perform aperture photometry.  The
+FITSKY parameters are the following:
+
+
+.ks
+.nf
+Positional or query mode parameters:
+
+	image		filename
+	annulus		real
+	width_annulus	real
+	fwhm_psf	real
+.fi
+.ke
+
+
+.ks
+.nf
+List structured parameters (filename may be given on command line):
+
+	coords		*imcur
+.fi
+.ke
+
+
+.ks
+.nf
+Hidden parameters:
+
+	spool		boolean		no
+	output		filename	"fitsky.out"
+	max_sky_iter	integer		50
+	growing_radius	real		1.0 (fwhm_psf units)
+	k1		real		5.0
+	k2		real		2.0
+	verbose		boolean		yes
+.fi
+.ke
+
+
+The names and functions of the FITSKY parameters are the same as those
+for APPHOT.  Note that ANNULUS may be set to zero to measure the
+background within a circular aperture.  The maximum number of iterations
+may be set to zero to measure the median of the sky sample.
+FITSKY output may be spooled into a file and used as input to APPHOT.
+
+.sh
+3.5 The FITPSF Program
+
+    The function of the FITPSF program is to determine the FWHM of the
+point spread function.  This is done by selecting an isolated, high
+signal to noise object, computing the x and y marginal profiles,
+and fitting a gaussian to each profile.  Output consists of the object
+center, the error in the center, and the FWHM of the fitted gaussians.
+Note that the sigma of a gaussian may be obtained by dividing the FWHM
+by 2.354.
+
+	x y err x_fwhm y_fwhm
+
+The input parameters for the FITPSF program are shown below.
+
+
+.ks
+.nf
+Positional parameters:
+
+	image		filename
+	aperture	real
+	annulus		real
+	width_annulus	real
+	sky_mode	real
+	coords		*imcur
+.fi
+.ke
+
+
+.ks
+.nf
+Hidden parameters:
+
+	fitsky		boolean		yes
+	center		boolean		yes
+	spool		boolean		no
+	output		filename	"fitpsf.out"
+	verbose		boolean		yes
+.fi
+.ke
+
+
+If background fitting is disabled, the parameter SKY_MODE defines
+the sky level.  The background fitting algorithm is a simple median
+calculation without pixel rejection or iteration.
+This should be sufficient, since FITPSF is expected to be used mainly
+in uncrowded regions on high signal to noise objects.
+
+Note that FITPSF is set up to process a list of input objects.
+The list processing tools (i.e., AVERAGE) may be used to average the
+results to produce the final FWHM of the PSF for the image.
+
+.sh
+3.6 The IMCURSOR Program
+
+    The function of the IMCURSOR program is to read the STDIMAGE cursor,
+writing the cursor coordinates on the standard output.  The cursor is read
+until the EOF character is entered to terminate the loop.  The standard
+output may be redirected into a file to generate a coordinate list.
+IMCURSOR has no parameters.
+
+.sh
+3.7 The IMMARK Program
+
+    The function of IMMARK is to draw marks on the diplay device.
+IMMARK is useful for verifying coordinate lists.
+
+
+.ks
+.nf
+parameters:
+
+	mark_type	string
+	mark_size	real
+	coords		*imcur
+.fi
+.ke
+
+
+Output is the current frame of the STDIMAGE device.  Mark types
+include "circle", "box", "cross", "plus", and "diamond".  The size of
+a mark is given in pixels.  The third parameter is a standard coordinate
+list.  If no list is given, the image cursor will be read instead.
+
+.sh
+3.8 The RADPROF Program
+
+    The function of the RADPROF program is to compute the radial profile
+of an object.  The output of RADPROF consists of a sequence of lines of
+text, each line defining the profile at a single radius.  Since RADPROF
+may generate many lines of output for a single input object, it is set up
+to process only a single input object.  A CL while loop may be written
+to process multiple objects, if desired.
+
+
+.ks
+.nf
+positional arguments:
+
+	image		filename
+	aperture	real
+	step_size	real
+	annulus		real
+	width_annulus	real
+	sky_mode	real
+.fi
+.ke
+
+
+.ks
+.nf
+hidden parameters:
+
+	fitsky		boolean		yes
+	center		boolean		yes
+	verbose		boolean		yes
+.fi
+.ke
+
+
+The radial profile is calculated from the image center out to the radius
+specified by the parameter APERTURE, in steps of STEP_SIZE pixels.
+The remaining RADPROF parameters are similar to those of APPHOT and will not be
+discussed in detail.  If background fitting is disabled, the parameter
+SKY_MODE defines the sky level.  The background fitting algorithm is
+a simple median calculation without pixel rejection or iteration.
+This should be sufficient, since RADPROF is expected to be used mainly
+in uncrowded regions on high signal to noise objects.
+Centering is via gaussian fits to the marginal profiles, without cleaning.
+
+RADPROF output lines contain the following fields:
+
+	r, i(r), inorm(r), fraction(r)
+
+.nf
+where
+
+	r		radius in pixels
+	i(r)		raw intensity at r
+	inorm(r)	normalized intensity at r (range 0-1)
+	fraction(r)	fraction of total integral at r
+.fi
+
+
+RADPROF does not generate any plots.  If one wishes to plot the contents
+of an output column, the column may be extracted with a list processing
+filter and piped to a graphics task.
+
+.sh
+4.0 Example
+
+    A brief example may help illustrate the use of the package.  Suppose
+we want to process a few hundred stars on images "blue" and "red".  We
+start by analyzing the blue image.
+
+	ap> radprof blue,15,0.5,20,10
+
+This gives us a radial profile printout for one of the "blue" stars.
+We decide that an aperture radius of 2.5 pixels is about right.
+The annulus will start at a radius of 10.0 pixels and extend to 20.0 pixels.
+The next step is to determine the FWHM of the PSF:
+
+	ap> fitpsf blue,3,10,20 | tee spoolfile
+
+By default, the program will take coordinate input by reading the image
+display cursor.  When the program is waiting for cursor input, it will
+cause the display cursor to blink rapidly; normally the cursor does not
+blink.  One has to be aware of this, because no other prompt is issued.
+We postion the cursor on several stars, and tap the space bar to measure
+each one.  When finished we type the EOF character (<ctrl/z> on our systems)
+to terminate the loop.  The screen will now look like this (the output 
+column labels are ommitted):
+
+.nf
+	ap> fitpsf blue,3,10,20 | tee spoolfile
+	 283.12  157.40 0.035  2.887  2.751
+	 546.08  213.45 0.023  2.833  2.902
+	 318.32  354.73 0.064  2.791  2.824
+.fi
+
+Since we elected to use TEE to spool the output, rather than the SPOOL
+parameter of FITPSF, we will not see the results until all stars have been
+measured.  The next step is to average the results, to determine the
+final FWHM (the FITPSF output could have been piped directly to GETCOLS
+without using an intermediate spoolfile, if desired).
+
+.nf
+	ap> getcols spoolfile,"4-5" | getcols | average
+	2.83133 0.0569725 6 
+.fi
+
+There are many ways this average could have been computed, of course;
+this is only one example.  Next, to avoid having to write down the FWHM value,
+we put it into the appropriate APPHOT parameter (note that the parameter
+name is abbreviated).
+
+	ap> apphot.fwhm = 2.831
+
+Finally, we must determine a representative backround sigma value for
+the image.  This is done by using FITSKY to measure several sky areas,
+and averaging column two of the output, much as we did for FITPSF.  The
+final value may be saved in "apphot.sky_sigma".
+
+By this point we have determined all the necessary parameters, and it is
+time to do some photometry.  The only APPHOT argument we are sure of is
+the image name parameter, so that is all we include on the command line:
+
+.nf
+	ap> apphot blue
+	aperture radii, pixels: 2.4 2.5 2.75 3.0
+	inner radius of sky annulus: 10
+	width of sky annulus (1 - ): 10
+	full width at half max of psf (2.831):
+	standard deviation of the image noise function (23.733):
+.fi
+
+After responding to the prompts shown above, APPHOT will ask for the
+first pair of object coordinates, and the cursor blink prompt will again
+be given.  Several objects may be measured to verify that all is working.
+
+The last step is to prepare a list of objects to be processed.  The simplest
+way to do this is to interactively mark the objects with the cursor.
+Later, when we process the "red" image, the same coordinate list may again
+be used, possibly after filtering with COORDTR.
+
+	ap> imcursor > objlist
+
+At this point, all of the APPHOT parameters have been set, we have
+a list of objects to be processed, and we are ready to run APPHOT in
+batch mode.  We decide to save the output in the file "blue.out".
+To ensure that we have a record of the parameters used for the fit,
+we first print the APPHOT parameters into the output file, then we
+start up the APPHOT batch run.
+
+.nf
+	ap> lparam apphot > blue.out
+	ap> apphot >> blue.out &
+	[1]
+.fi
+
+The batch job is now running, appending output lines to the file "blue.out".
+We can proceed to set up the job for the red image, in much the same way
+that we set up the job for the blue image.  When both jobs finish, we
+can use the list processing tools to filter out the good objects and
+calculate colors.
diff --git a/noao/digiphot/apphot/doc/specs/apphot.db b/noao/digiphot/apphot/doc/specs/apphot.db
new file mode 100644
index 00000000..df5dc2f3
--- /dev/null
+++ b/noao/digiphot/apphot/doc/specs/apphot.db
@@ -0,0 +1,366 @@
+# APPHOT.DDF -- Data definition for apphot package output
+
+builtin catalog functions
+builtin domain statements
+
+-------------------------------------------------------------------------------
+
+# domain statements
+
+domain	bool		type=short	format="%b"
+domain	posint		type=short	format="%5d"
+domain  pixels          type=real       format="%9.3f"
+domain	fwhmpsf		type=real	format="%9.3f"
+domain  counts		type=real	format="%15.7g"
+domain	sigma		type=real	format="%15.7g"
+domain  mag		type=real	format="%7.3f"
+domain  pars		type=real	format="%15.7g"
+domain  electrons	type=short	format="%5d"
+domain	ratio		type=real	format=%15.7g"
+
+# Apphot database descriptor
+record apphot {
+    iraf		char[]		"current version of iraf"
+    host		char[]		"host machine"
+    user		char[]		"user name"
+    package		char[]		"package name"
+    version		char[]		"package version"
+}
+
+--------------------------------------------------------------------------------
+
+# History record (1 per modification of the apphot database)
+record history {
+    task		char[]		"task name"
+    date		ltime		"date dask was run"
+    firstrec		posint		"first record written by task"
+    lastrec		posint		"last record written by task"
+}
+ 
+------------------------------------------------------------------------------ 
+
+# Data dependent parameter set (>= 1 per task execution)
+record datapars {
+    fwhmpsf		pixels		"full width half max of the psf"
+    emission		bool		"emission/absorption"
+    noise model		char[]		"data noise mode"
+    threshold		counts		"intensity threshold"
+    sigma		counts		"sigma of sky pixels"
+    gain		char[]		"image gain keyword"
+    epadu		ratio		"gain electrons/adu"
+    ccread		char[]		"image readout noise keyword"
+    readnoise		electrons	"readout noise electrons"
+}
+
+# Centering algorithm parameter set (>= 1 per task execution)
+record centerpars {
+    calgorithm		char[]		"centering algoritm"
+    cboxwidth		fwhmpsf		"centering box width"
+    maxshift		fwhmpsf		"maximum shift"
+    cmaxiter		posint		"maximum number of iterations"
+    minsnratio		ratio		"minimum signal to noise ratio"
+    clean		bool		"use clean algorithm"
+    rclean		fwhmpsf		"cleaning radius"
+    rclip		fwhmpsf		"clipping radius"
+    kclean		sigma		"sigma clean"
+}
+
+# Sky fitting algorithm parameter set (>= 1 per task execution)
+record fitskypars {
+    salgorithm		char[]		"sky fitting algorithm"
+    annulus		fwhmpsf		"inner sky annulus"
+    dannulus		fwhmpsf[]	"width of inner sky annulus"
+    smaxiter		posint		"maximum number od iterations"
+    skreject		sigma		"ksigma rejection"
+    snreject		posint		"maximum number of rejections"
+    khist		sigma		"half width of histogram"
+    binsize		sigma		"binsize of histogram"
+    smooth		bool		"smooth the histogram"
+    rgrow		fwhmpsf		"region growing radius"
+    skyvalue		counts		"user supplied sky value"
+}
+
+# Photometry parameter set (>= 1 per task execution)
+record photpars {
+    weighting		char[]		"weighting scheme"
+    apertures		fwhmpsf		"list of apertures"
+    zmagnitude		mag		"magnitude zero point"
+    exposure		char[]		"image exposure time keyword"
+    itime		""		"exposure time"
+}
+
+# Polygonal photometry parameter set (>= 1 per task execution)
+record polypars {
+    zmagnitude		mag		"magnitude zero point"
+    exposure		char[]		"image exposure time keyword"
+    itime		""		"exposure time"
+}
+
+# Radial profile fitting parameters (>= 1 per task execution)
+record radprofpars {
+    radius		fwhmpsf		"maximum profile radius"
+    stepsize		fwhmpsf		"profile step size"
+    order		posint		"number of spline pieces in fit"
+    kreject		sigma		"k sigma rejection"
+    nreject		posint		"max number of rejection cycles"
+}
+
+# Point spread function modeling parameters (>= 1 per task execution)
+record psfpars {
+    function		char[]		"analytic function"
+    box			fwhmpsf		"fitting box size"
+    kreject		sigma		"sigma rejection limit"
+    nreject		posint		"max number of rejections"
+}
+
+--------------------------------------------------------------------------------
+
+# Computed center answers (1 per star)
+record center {
+
+    datapars		posint		"record id of datapars record"
+    centerpars		posint		"record id of centerpars record"
+
+    image		char[]		"image name"
+    xinit		pixels		"initial x position"
+    yinit		pixels		"initial y position
+    id			posint		"sequence number in table"
+    coords		char[]		"coordinate list filename"
+    lid			posint		"sequence number in coord list"
+
+    xcenter		pixels		"x center position"
+    ycenter		pixels		"y center position"
+    xshift		pixels		"x position shift"
+    yshift		pixels		"y position shift"
+    xerror		pixels		"x position error"
+    yerror		pixels		"y position error"
+    cerrcode		posint		"centering error code"
+    cerrstring		char[]		"centering error message"
+
+}
+
+# Computed fitsky answers (1 per star)
+record fitsky {
+
+    datapars		posint		"record id of datapars record"
+    fitskypars		posint		"record id of fitskyprs record"
+
+    image		char[]		"image name"
+    xinit		pixels		"initial x position"
+    yinit		pixels		"initial y position
+    id			posint		"sequence number in table"
+    coords		char[]		"coordinate list filename"
+    lid			posint		"sequence number in coord list"
+
+    skyvalue		counts		"sky value"
+    skysigma		counts		"standard deviation of sky"
+    skyskew		counts		"skew of sky pixels"
+    nskypix		posint		"number of sky pixels"
+    nskyreject		posint		"number of rejected pixels"
+    serrcode		posint		"sky fitting error code"
+    serrstring		char[]		"sky fitting error message"
+
+}
+
+# Computed phot answers (1 per star)
+record phot {
+
+    datapars		posint		"record id of datapars record"
+    centerpars		posint		"record id of centerpars record"
+    photpars		posint		"record id of photometry record"
+
+    image		char[]		"image name"
+    xinit		pixels		"initial x position"
+    yinit		pixels		"initial y position
+    id			posint		"sequence number in table"
+    coords		char[]		"coordinate list filename"
+    lid			posint		"sequence number in coord list"
+
+    xcenter		pixels		"x center position"
+    ycenter		pixels		"y center position"
+    xshift		pixels		"x position shift"
+    yshift		pixels		"y position shift"
+    xerror		pixels		"x position error"
+    yerror		pixels		"y position error"
+    cerrcode		posint		"centering error code"
+    cerrstring		char[]		"centering error message"
+
+    skyvalue		counts		"sky value"
+    skysigma		counts		"standard deviation of sky"
+    skyskew		counts		"skew of sky pixels"
+    nskypix		posint		"number of sky pixels"
+    nskyreject		posint		"number of rejected pixels"
+    serrcode		posint		"sky fitting error code"
+    serrstring		char[]		"sky fitting error message"
+
+    aperts		pixels[]	"list of apertures"
+    sums		counts[]	"list of sums"
+    areas		pixels[]	"list of areas"
+    mags		mag[]		"list of magnitudes"
+    magerrs		mag[]		"list of mag errors
+    merrcodes		posint[]	"list of errcodes
+    merrstrings		char[]		"list of error messages"
+
+}
+
+# Computed wphot answers (1 per star)
+record wphot {
+
+    datapars		posint		"record id of datapars record"
+    centerpars		posint		"record id of centerpars record"
+    fitskypars		posint		"record id of fitskypars record"
+    photpars		posint		"record id of photpars record"
+
+    image		char[]		"image name"
+    xinit		pixels		"initial x position"
+    yinit		pixels		"initial y position
+    id			posint		"sequence number in table"
+    coords		char[]		"coordinate list filename"
+    lid			posint		"sequence number in coord list"
+
+    xcenter		pixels		"x center position"
+    ycenter		pixels		"y center position"
+    xshift		pixels		"x position shift"
+    yshift		pixels		"y position shift"
+    xerror		pixels		"x position error"
+    yerror		pixels		"y position error"
+    cerrcode		posint		"centering error code"
+    cerrstring		char[]		"centering error message"
+
+    skyvalue		counts		"sky value"
+    skysigma		counts		"standard deviation of sky"
+    skyskew		counts		"skew of sky pixels"
+    nskypix		posint		"number of sky pixels"
+    nskyreject		posint		"number of rejected pixels"
+    serrcode		posint		"sky fitting error code"
+    serrstring		char[]		"sky fitting error message"
+
+    aperts		pixels[]	"list of apertures"
+    sums		counts[]	"list of sums"
+    areas		pixels[]	"list of areas"
+    mags		mag[]		"list of magnitudes"
+    magerrs		mag[]		"list of mag errors
+    merrcode		posint[]	"list of errcodes
+    merrstrings		char[]		"list of error messages"
+}
+
+# Computed polyphot answers (1 per star)
+record polyphot {
+
+    datapars		posint		"record id of datapars record"
+    centerpars		posint		"record id of centerpars record"
+    fitskypars		posint		"record id of fitskypars record"
+    polypars		posint		"record id of polypars record"
+
+    image		char[]		"image name"
+    xinit		pixels		"initial x position"
+    yinit		pixels		"initial y position
+    id			posint		"sequence number in table"
+    coords		char[]		"coordinate list filename"
+    lid			posint		"sequence number in coord list"
+
+    xcenter		pixels		"x center position"
+    ycenter		pixels		"y center position"
+    xshift		pixels		"x position shift"
+    yshift		pixels		"y position shift"
+    xerror		pixels		"x position error"
+    yerror		pixels		"y position error"
+    cerrcode		posint		"centering error code"
+    cerrstring		char[]		"centering error message"
+
+    skyvalue		counts		"sky value"
+    skysigma		counts		"standard deviation of sky"
+    skyskew		counts		"skew of sky pixels"
+    nskypix		posint		"number of sky pixels"
+    nskyreject		posint		"number of rejected pixels"
+    serrcode		posint		"sky fitting error code"
+    serrstring		char[]		"sky fitting error message"
+
+    sum			counts[]	"aperture sum"
+    area		pixels[]	"aperture area"
+    mag			mag[]		"magnitude"
+    magerr		mag[]		"magnitude error"
+    merrcode		posint[]	"error code"
+    merrstring		char[]		"error message"
+
+    polygons		char[]		"name of polygons files"
+    pid			posint		"polygon sequence number"
+    oldxmean		pixels		"original mean x of polygon"
+    oldymean		pixels		"original mean y of polygon"
+    minradius		pixels		"min sky radius to exclude polygon"
+    nver		posint		"number of vertices"
+    xvertices		pixels[]	"list of x vertices coords"
+    yvertices		pixels[]	"list of y vertices coords"
+}
+
+# Computed radprof answers (1 per star)
+record radprof {
+
+    datapars		posint		"record id of datapars record"
+    centerpars		posint		"record id of centerpars record"
+    fitskypars		posint		"record id of fitskypars record"
+    photpars		posint		"record id of photpars record"
+    radprofpars		posint		"record id of radprofpars record"
+
+    image		char[]		"image name"
+    xinit		pixels		"initial x position"
+    yinit		pixels		"initial y position
+    id			posint		"sequence number in table"
+    coords		char[]		"coordinate list filename"
+    lid			posint		"sequence number in coord list"
+
+    xcenter		pixels		"x center position"
+    ycenter		pixels		"y center position"
+    xshift		pixels		"x position shift"
+    yshift		pixels		"y position shift"
+    xerror		pixels		"x position error"
+    yerror		pixels		"y position error"
+    cerrcode		posint		"centering error code"
+    cerrstring		char[]		"centering error message"
+
+    skyvalue		counts		"sky value"
+    skysigma		counts		"standard deviation of sky"
+    skyskew		counts		"skew of sky pixels"
+    nskypix		posint		"number of sky pixels"
+    nskyreject		posint		"number of rejected pixels"
+    serrcode		posint		"sky fitting error code"
+    serrstring		char[]		"sky fitting error message"
+
+    aperts		pixels[]	"list of apertures"
+    sums		counts[]	"list of sums"
+    areas		pixels[]	"list of areas"
+    mags		mag[]		"list of magnitudes"
+    magerrs		mag[]		"list of mag errors
+    merrs		posint[]	"list of error codes
+    merrstrings		char[]		"list of error messages"
+
+    pfwhm		pixels		"fitted profile fwhmpsf"
+    inorm		counts		"intensity normalization factor"
+    tinorm		counts		"total intensity normalization factor"
+    errcode		posint		"error code"
+    errstring		char[]		"error message"
+    rlist		pixels[]	"radii"
+    intensities		counts[]	"fitted intensities"
+    tintensities	counts[]	"integral of fitted total intensities"
+}
+
+# Computed fitpsf answers (1 per star)
+record fitpsf {
+
+    datapars		posint		"record id of datapars record"
+    fitpsfpars		posint		"record id of fitpsf record"
+
+    image		char[]		"image name"
+    xinit		pixels		"initial x position"
+    yinit		pixels		"initial y position
+    id			posint		"sequence number in table"
+    coords		char[]		"coordinate list filename"
+    lid			posint		"sequence number in coord list"
+
+    npars		posint		"number of parameters"
+    params		pars[]		"list of parameters"
+    parerrs		pars[]		"list of parameter errors"
+
+}
+
+-------------------------------------------------------------------------------
diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc b/noao/digiphot/apphot/doc/specs/apphot.spc
new file mode 100644
index 00000000..ecfdf364
--- /dev/null
+++ b/noao/digiphot/apphot/doc/specs/apphot.spc
@@ -0,0 +1,1296 @@
+.EQ
+delim $$
+.EN
+
+.RP
+.TL
+Specifications for the Aperture Photometry Package
+.AU
+Lindsey Davis
+.AI
+.K2 "" "" "*"
+Revised October 1987
+
+.AB
+The APPHOT package is a set of tasks for performing aperture photometry
+on uncrowded or moderately crowded fields, in either interactive or batch mode.
+The photometric technique employed is fractional pixel aperture
+integration. Point spread function fitting techniques are not used and no
+knowledge of the point spread function is required for the computation of
+magnitudes. Separate tasks are provided for creating and modifying object lists,
+computing accurate centers for a list of objects, computing sky values for
+a list of objects and performing aperture photometry inside circular or
+polygonal apertures.
+.AE
+
+.NH
+Introduction
+.PP
+The APPHOT package is a set of tasks for performing
+aperture photometry on uncrowded or moderately crowded fields.
+The photometric technique employed is fractional pixel integration. Point
+spread function techniques are not used and no knowledge of the point spread
+function is required for the computation of magnitudes.
+.PP
+The APPHOT package performs multi-aperture photometry on digitized starfields
+maintained as IRAF image files. Input to the package consists of an
+image file, a list of object coordinates, numerous parameters controlling
+the analysis algorithms and, optionally, the graphics terminal and/or
+display. APPHOT output consists of successive lines of text where each line
+summarizes the results of the analysis for a particular object.
+.PP
+Given starting coordinates and an IRAF image, the principal APPHOT
+task computes accurate centers, sky values and magnitudes
+for a list of objects.  Separate
+IRAF callable tasks in APPHOT exist to create and modify object
+lists, to determine image characteristics such as the full width half maximum
+of the point spread function or standard deviation of the sky pixels,
+to compute accurate centers for a list of objects, to compute accurate local sky
+values for a list of objects, and to compute magnitudes inside a polygonal
+aperture.
+
+.NH
+APPHOT Package Requirements
+.NH 2
+APPHOT Package Input
+.NH 3
+The IRAF Image
+.PP
+APPHOT assumes that images exist on disk in IRAF format. Facilities for reading
+and writing images exist elsewhere in IRAF such as in package DATAIO or
+MTLOCAL.
+.PP
+APPHOT assumes that the image data is linear.
+The input image is assumed to have been corrected for those instrumental
+defects which affect the intensity of a pixel. These include pixel to
+pixel variations in the bias values, pixel to pixel gain variations,
+cosmic rays, cosmetic defects, geometric distortion,
+and detector non-linearities.
+.PP
+APPHOT assumes that the local sky background is approximately flat in the
+vicinity of the object being measured. This assumption is equivalent to
+assuming that the local sky region has a unique mode. Therefore any
+variations in the sky background which occur at the same scale as the
+sky region should be removed prior to entering APPHOT.
+.PP
+The point spread function of the image is assumed to be constant for all
+regions of the image. This is particularly critical in the case of faint objects
+for which small apertures which minimize the effects of crowding and
+sky noise in the aperture are used. The wings of the object will
+almost certainly extend beyond the aperture and good results will only be
+obtained if
+objects are consistently well centered and the shape and diameter of an object
+is constant throughout the image and invariant to magnitude.
+
+.NH 3
+The Coordinate Lists
+.PP
+All APPHOT tasks operate on lists of object coordinates or interactive cursor
+input.  Lists are maintained as text files,
+one object per line with the x and y coordinates in
+columns one and two respectively. List files may be created interactively
+with either the graphics or image cursor, by a previously executed APPHOT
+task, by a previously executed IRAF task or by a user task.
+.PP
+The x and y coordinates contained in the list file can be either the
+starting centers for the objects of interest or the true centers.
+In either case the aperture centered around the object position must
+not extend beyond the boundary of the image. To obtain reliable results
+from the centering algorithm the starting centers should not be more than
+1 fwhmpsf pixels from the true centers.
+
+.NH 3
+Algorithm Parameters
+.PP
+Many tasks in the APPHOT package have an associated set of algorithm parameters
+which control the operation of the analysis routines. For example the
+centering and sky fitting algorithms each have an associated group of
+parameters.
+The APPHOT tasks supply reasonable defaults for these parameters. However
+the user may alter them at any time in interactive mode or by editing the
+appropriate parameter file before running the task in batch. 
+
+.NH 3
+Terminal Graphics and the Image Display
+.PP
+Most APPHOT programs may be run in either interactive or batch mode.
+In interactive mode, the user can mark the positions of objects by
+interactively, positioning the image cursor on the display device.
+Simple cursor commands can interactively alter the algorithm parameters. 
+In batch mode the algorithm parameters are
+fixed and object coordinates are taken from the user supplied coordinate list.
+The display device is not required in batch mode.
+.PP
+At present there is no high level IRAF display interface. Therefore the present
+version of APPHOT replaces the display device with terminal
+graphics. For example it is possible to load a contour plot of an image
+or image section, and run the APPHOT tasks, interactively marking
+positions on the plot. This is a temporary measure to tide thing over until
+the display interface is available. Furthermore this option is only
+really suitable for those terminal which have both text and graphics
+windows displayed at the same time.
+.PP
+Certain APPHOT tasks such as FITSKY occasionally require an interactive graphics
+capability. For example it is sometimes desirable to plot the histogram
+of the sky pixels and mark the peak of the histogram interactively rather
+than using the automatic sky fitting routines.
+Graphics capablity has been added to APPHOT tasks as deemed useful.
+
+.NH 2
+APPHOT Package Functions
+.NH 3
+Creating Coordinate Lists
+.PP
+APPHOT task(s) shall exist to create coordinate lists interactively within
+APPHOT by loading the IRAF image into the image display
+and successively marking the objects to be measured with the image cursor.
+It shall be possible to mark the positions of objects on the display, and draw
+circles of arbitrary size around the objects of interest.
+It shall be possible to verify existing coordinate lists by marking the object
+coordinates on the image display.
+.PP
+At present the full image display cababilities do not exist in IRAF.
+Therefore as a temporary measure most tasks will run with a contour
+plot and the graphics cursor as a substitute for the image display and
+image cursor by setting the image cursor to stdgraph and the display
+parameter for each task to stdgraph.
+The output coordinates will be written to a text file and may be used as
+starting coordinates for the APPHOT routines.
+.PP
+Those sites which have SUN workstations can use the IMTOOL facilites to
+create cursor lists.
+.PP
+APPHOT tasks shall exist to automatically detect objects by specifying the IRAF
+image to be searched, plus a few image characteristics such as a detection 
+threshold and the full width half maximum of the point spread function.
+The output coordinates plus a few object statistics  will be written to a
+text file.
+
+.NH 3
+Coordinate List Operations
+.PP
+General list processing tasks are or will be available in the IRAF lists
+package. Examples of useful currently existing tasks are list sorting by for
+example magnitude and performing a linear transformations
+on coordinate lists.
+.PP
+It may eventually be necessary to add some specialized list processing tasks
+to APPHOT. One example is a list matching facility in which objects in
+common to two lists are combined and output to a third list.
+
+.NH 3
+Determining the Image Characteristics
+.PP
+APPHOT tasks shall exist to estimate certain image
+characteristics such as the full width half maximum of the image point spread
+function and the standard deviation of the background. In order to obtain
+meaningful error estimates it is also necessary to specify the noise
+charactersitics of the detector and a noise model.
+In this version of APPHOT two noise
+functions will be supported a constant sky background noise,
+and constant background noise plus Poisson statistics in the object.
+.PP
+The reason for this capability is that the majority of the APPHOT
+algorithm parameters scale with these two image characteristics.
+For example all the pixel scale dependent parameters such as the centering
+aperture, object apertures, the two sky annuli and the
+maximum shift parameter all scale with the full width half
+maximum of the point spread function. Similarly most of the pixel intensity
+dependent parameters scale with the standard deviation of the sky pixels.
+
+.NH 3
+Centering
+.PP
+An APPHOT task shall exist to determine accurate centers for a list of objects,
+using the approximate object coordinates as a starting point.
+The centering aperture may extend beyond the boundaries of the image but
+a warning message will be generated.
+.PP
+A choice of centering algorithms with a range of efficiency and accuracy will
+be available.  The center determination must be resistant to the affects of
+nearby contaminating objects.
+.PP
+The user may opt to use the starting center as the actual center in all cases,
+to use the starting center as the actual center if the object is very faint,
+or tweak up the center if the signal to noise is above a certain threshold.
+.PP
+The output of the centering algorithm will the set of computed coordinates
+and their errors.
+
+.NH 3
+Fitting the Sky
+.PP
+An APPHOT task shall exist to compute a constant background value by analysis
+of an annular region surrounding the object.
+The background is assumed to be flat in the region
+of the object, but may contain contaminating objects or defects which
+shall be detected and eliminated by the fitting algorithm.
+It shall be permissible for the background region to extend beyond the
+boundaries of the image; the out of bounds region of the background shall
+be excluded from the fit.
+.PP
+The user may supply a constant background, with zero-valued noise and skew
+value or read appropriate values from a file instead of computing the
+background.
+.PP
+The output of the sky fitting algorithm shall be
+the mode, standard deviation and skew of the sky as well as the number
+of pixels left in the background region after pixel rejection and the number
+rejected.
+
+.NH 3
+Multi-aperture Photometry
+.PP
+APPHOT routines shall exist to compute the integral of object minus background
+within one or more circular apertures centered upon the object.
+The integration shall be
+performed using partial pixel techniques, to minimize the effects of
+sampling.  If the aperture contains any indefinite pixels, or if the
+aperture extends beyond the boundary of the image, an indefinite result
+shall be returned. Both normal and weighted photometry routines shall
+be available.
+.PP
+It shall be possible to normalize the output magnitudes to a user specified
+integration time using values stored in the IRAF image header.
+.PP
+The output shall consist of magnitudes and errors for each of the specified
+apertures.
+.NH 3
+Polygonal Aperture Photometry
+.PP
+Determine the integral of the object within a specified
+polygon. Aperture integration shall be by fractional pixel summation
+of successive image lines.
+
+.NH
+Specifications
+.NH 2
+Apphot CL Callable Tasks
+.PP
+The CL callable part of the APPHOT package consists of the following
+routines:\fL
+
+.nf
+.na
+        mark    -- create/verify coordinate lists interactively
+    polymark    -- create/verify polygon lists interactively
+     daofind    -- automatic image finder from DAOPHOT
+     lintran    -- linearly transform a list of coordinates (LISTS package)
+
+     radprof    -- compute the radial profile of an object.
+      fitpsf    -- model the PSF
+
+      center    -- compute accurate centers for a list of objects
+      fitsky    -- compute accurate sky values for a list of objects
+        phot    -- perform multi-aperture photometry on a set of objects
+    polyphot    -- compute the flux inside a set of irregular polygons\fR
+       wphot	-- perform weighted multi-aperture photometry
+.ad
+.fi
+
+.NH 2
+Standard Analysis Procedures
+.PP
+A standard reduction procedure would be something as follows.
+.IP 1.
+Estimate the image and data characteristics in the following manner.
+.RS
+.IP 1.
+Use the interactive setup option (i key) in the PHOT task to specify the
+fwhm of the psf,
+the centering apperture, the sky annuli, the photometry apertures as
+well as estimate the sky sigma.
+Examine the results (:show command) and optionally store the 
+new parameters in the parameter files (w key).
+.IP 2.
+Use the EPAR task to edit the parameter files directly. For example the
+detector gain and readout noise must be known before running PHOT in
+order to get reliable error estimates.
+.RE
+.IP 2.
+Prepare a coodinate list in one of the following ways.
+.RS
+.IP 1.
+Running MARK or POLYMARK.
+.IP 2.
+Run DAOFIND or some other automatic image finder.
+.IP 3.
+Run another APPHOT task such as CENTER .
+.IP 4.
+Run any other IRAF or user program which generates the appropriate
+format.
+.IP 5.
+Transform an existing list using the LISTS package facilities
+.RE
+.IP 3.
+Run PHOT or WHOT in non-interactive mode to perform the multi-aperture
+photometry.  The user should be familiar
+with the algorithms used to measure the object center, to fit the background,
+and compute the aperture integral, magnitude, and errors.  The values of
+all visible and hidden PHOT parameters should be inspected before doing
+any serious processing. Note that CENTER and FITSKY can be run independently
+of PHOT and their output used as input to PHOT.
+.EQ
+delim $$
+.EN
+
+.NH 2
+The APPHOT Algorithms
+.PP
+The principal APPHOT algorithms are described below.
+
+.NH 3
+The RADPROF Algorithm
+.PP
+The function of the RADPROF task is to compute the radial profile of
+selected, isolated, high signal to noise objects in an IRAF image.
+.PP
+Given the IRAF image, an initial center, an aperture and a step size,
+RADPROF computes the radial profile of an object in the following manner.
+.IP 1.
+The APPHOT centering routines are used to compute an accurate center for the
+object. The new center is used to compute the radial coordinate for each
+pixel in the subraster.
+.IP 2.
+The APPHOT sky fitting routines are used to compute an accurate sky value
+for the object. The new sky value is used to compute the object intensity
+for each pixel in the subraster.
+.IP 3.
+The CURFIT package routines are used to produce a smooth intensity versus
+radius curve by fitting a cubic least squares spline function to the data
+using linear least squares techniques.
+.IP 4.
+The fitted curve is evaluated at equally spaced intervals to produce the
+final radial profile. The profile is normalised using the r = 0 value.  
+.IP 5.
+The smoothed curve is integrated using the 
+1D integration routines IMINTERP to evalute the fraction of the total
+integral at each interval.
+.IP 6.
+The three quantities $I sub r$ the raw intensity, $Inorm sub r$ the
+normalized intensity, and $Ifraction sub r$ the fraction of the total
+intensity inside radius at r,  are plotted on the terminal and
+output as a function of r to a text file.
+.PP
+RADPROF is used principally to compute the stellar image and setup the
+parameters for doing photometry. Its default output is a radial profile
+plot with the phot parameters marked on it.
+
+.NH 3
+The FITPSF Algorithm
+.PP
+The function of the FITPSF task is to fit an analytic model to an object
+in order to derive information about the point spread function. Given
+an IRAF image, an initial center and an aperture, FITPSF computes the
+model parameters in the following manner.
+.IP 1.
+The fitting function is chosen.
+The present version of FITPSF offers two function choices a 2D radial Gaussian
+function and an elliptical Gaussian function.
+A third option, moment analysis, has been added to the FITPSF package.
+The image characteristics are evaluted by using the 0th, 1st and 2nd order
+moments of the image.
+.IP 2
+Initial guesses for the parameters are made from the subraster data.
+.IP 3
+The parameters and their errors are derived using standard non-linear least
+squares techniques and the NLFIT package.
+
+.NH 3
+The DAOFIND Algorithm
+.PP
+The function of the DAOFIND task is to automatically detect objects
+in an IRAF image above a certain intensity threshold.
+The user specifies an intensiyt threshold,
+the estimated full width half maximum of
+the point spread function,
+and limits on the sharpness and roundness of the objects to be detected.
+DAOFIND produces a list of x and y coordinates and a sharpness
+and roundness statistic for each detected object.
+.PP
+The DAOFIND algorithm works in the following way.
+.IP 1.
+The user specifies an intensity threshold above local sky and estimates
+the full width half maximum of the point spread function.
+.IP 2.
+DAOFIND computes a convolution kernel which is a linear
+function of the brightness values in an approximately circular array of
+pixels.  The original data is convolved with the computed kernel.
+The equivalent mathematical
+operation is a convolution of the original data
+with truncated, lowered circular Gaussian function with the specified FWHM,
+computed in such a way as to be the mathematical
+equivalent of fitting a Gaussian stellar profile to the object data by least
+squares. The coefficients of the linear function sum to zero so that the
+overall bias level (local sky) cancels out exactly. Since the function is
+symmetric about a single pixel, a smooth gradient in the sky brightness
+also cancels exactly. Therefore the user does not have to specify an
+absolute brightness threshold but only a threshold above local sky.
+.IP 3
+The convolved data is searched for local maxima. Local maxima which are
+less than the specified threshold are rejected. A pixel is defined to be
+a local maximum when it is the brightest pixel within
+$n ~*~ sigma sub Gauss$.
+.IP 4.
+Using the original data, DAOFIND computes an object sharpness statistic which
+can be used to reject
+hot or cold pixels.  The sharp parameter is defined below.
+Detected  objects with a sharpness parameter outside the range specifed
+by sharplo and sharphi are rejected. Typical values for sharplo and
+sharphi are 0.2 and 1.0 respectively.
+.nf
+
+    $I sub delta$ = height of best fitting $delta$ function = pixel value
+
+    $I sub Gauss$ = height of best fitting Gaussian function = convolved value
+
+    sharplo <= sharp = ${I sub delta} over {I sub Gauss}$ <= sharphi
+
+.fi
+If the brightness enhancement detected in the convolved data is due to
+a single bright pixel, then the best fitting delta function will have an
+amplitude equal to the height of this pixel above the local background,
+while the amplitude of the best fitting Gaussian will be pulled down by
+the surrounding low valued pixels. Sharp will be a number significantly
+greater than one. A single cold pixel will produce
+brightness enhancements approximately 0.5 * FWHM away
+from the pixel in question  in all directions. In this case the height
+of the delta
+function which best fits these spurious maxima is close to zero, while the
+height of the best fitting Gaussian is some small positive number.
+In this case sharp will be close to zero.
+.IP 5.
+The roundess statistic is computed from the original picture data by fitting
+1D Gaussians
+to the marginal sums in x and y. If the height of either 1D
+Gaussian is negative the object is rejected. If both heights are
+positive the roundness parameter is computed.
+.nf
+
+	$DELTA I ~=~ I sub {x ~ Gauss} ~-~ I sub {y ~ Gauss}$
+
+	$<I> ~=~ I sub {x ~ Gauss} ~+~ I sub {y ~ Gauss}$
+
+	$roundlo ~<=~  round ~=~ {DELTA I} over <I> ~<=~  roundhi$
+
+.fi
+Objects which are elongated in the
+x direction have roundness values less than zero and those elongated in
+the y direction have roundness greater than zero.
+Round discriminates only against objects which are elongated
+along either rows or columns. Objects elongated at a 45 degree angle will
+not be rejected.
+.IP 6.
+Finally the approximate x and y centroids of the detected objects,
+rough magnitudes relative to threshold are computed, and object is added
+to the output file.
+
+
+.NH 3
+The CENTER Task
+
+.NH 4
+Centering Package Routines
+.PP
+The following are the principal programmer callable routines routines in the
+centering package.
+.nf
+\fL
+
+                  apcinit (ap, cfunction, cbox, fwhmpsf, noise)
+            ier = apfitcenter (ap, im, xinit, yinit)
+            ier = aprefitcenter (ap)
+          value = apstat[ir] (ap, param)
+                  apstats (ap, param, str, maxch)
+                  apset[sir] (ap, param, value)
+                  apcfree (ap)
+
+\fR
+.fi
+.PP
+The following quantities can be examined or set by apstat/apset calls
+.nf
+\fL
+  data          1. fwhmpsf       full width half maximum of psf in pixels
+parameters      2. threshold     minimum intensity for centering
+                3. noise         noise model
+                4. sigma         standard deviation of background
+                5. readnoise     readout noise of CCD in electrons
+                6. epadu         electrons per adu
+
+centering       1. calgorithm    centering algorithm
+parameters      2. positive      emission / absorption features
+                3. cbox          centering radius in fwhmpsf
+                4. cmaxiter      maximum number of fitting iterations
+                5. maxshift      maximum permitted shift in fwhmpsf
+                6. minsnratio    minimum permitted signal to noise ratio
+                7. clean         clean subraster before centering
+                8. rclean        cleaning radius in fwhmpsf
+                9. rclip         clipping radius in fwhmpsf
+                10.kclean        k-sigma rejection for cleaning in sigma
+\fR
+.fi
+
+.PP
+The following computed quantities can be examined by apstat calls.
+.nf
+\fL
+              1. xcenter            computed x coordinate
+              2. ycenter            computed y coordinate
+              3. xerr               computed x coordinate error
+              4. yerr               computed y coordinate error
+\fR
+.fi
+.PP
+See the manual pages for CENTER and CENTERPARS for a detailed description
+of the centering parameters.
+
+.NH 4
+The Centering Algorithm
+.PP
+The function of the CENTER task is to compute accurate centers and errors
+for objects in an IRAF image given a list of initial positions and a
+centering aperture.
+.IP 1.
+If the centering algorithm is disabled, the computed center is set to the
+initial center and the uncertainty estimate is set to zero.
+.IP 2.
+If the cleaning algorithm is enabled, clean the subraster before centering.
+.IP 3.
+Estimate is made of the signal to noise of the object. If this quantity is
+less than a certain minimum value the computed center is kept
+but a warning message is issued.
+.IP 4.
+The center and errors are computed using one of several algorithms.
+.IP 5.
+If the computed center is greater than a user specified distance from the
+initial center then the computed center is returned with an error
+message.
+
+.NH 4
+Symmetry Clean Algorithm
+.PP
+The symmetry-clean algorithm attempts to remove defects in the centering
+subraster by assuming that the object has radial symmetry and comparing
+pixels on the opposite sides of the center of symmetry. The algorithm
+works in the following way.
+.IP 1.
+The center of symmetry is computed. Normally the center of symmetry is assumed
+to coincide with the position of the brightest pixel in the subarray.
+However if the maximum pixel is more than a user specified distance away
+from the intial center, the initial center is used as the center of symmetry.
+.IP 2.
+Pixels inside a specified cleaning radius are unaltered.
+.IP 3.
+Pairs of pixels diametrically opposed about the center
+in the cleaning region between the cleaning and clipping
+radii are tested for equality.  If the difference between the pixels is
+greater than a specified k-sigma rejection limit, the larger value is replaced
+by the smaller.
+In this region sigma is computed from Poisson statistics.
+.IP 4.
+Pairs of pixels in the clippping
+region are compared in the same manner as those in the cleaning region
+except that sigma is the standard deviation of the sky pixels.
+.PP
+The effect of the symmetry-clean algorithm is to edit the raster,
+removing any contaminating objects in the vicinity of the primary object.
+This simplifies the fitting algorithm and increases its reliability,
+since it does not have to deal with multipeak marginal distributions.
+
+.NH 4
+Signal to Noise Estimate
+
+.PP
+The signal to noise of the object is estimated from the data values
+in the subraster in the following way.
+.nf
+
+	$SNR ~=~ N sub object over {sqrt {n sub pix ~*~sigma sub sky sup 2}}$
+
+		or
+
+	$SNR ~=~ N sub object over {sqrt {N sub object ~+~ n sub pix~*~sigma sub sky sup 2}}$
+
+.fi
+where $N sub *$ is the number of counts in the object above threshold,
+$sigma sub sky$
+is the standard deviation of the pixels in the sky region and
+$n sub pix$ is the number of pixels in the object aperture.
+The first approximation corresponds to constant sky noise only,
+the second includes Poisson noise in the object.
+
+.NH 4
+Centroid
+.PP
+The centroid centering algorithm is similar to that used in MPC and can
+be briefly described as follows. For more detailed description
+see (Stellar Magnitudes From Digital Pictures, 1980, Adams et al).
+.IP 1.
+The marginal distributions in x and y are accumulated.
+.IP 2.
+The intensity weighted centroid positions for the marginals is computed
+using only data pixels which are above the threshold intensity. If the
+threshold parameter is 0 the mean intensity of the marginal is used
+in place of the threshold
+.nf
+
+    $I sub i ~=~ I sub i ~-~ threshold ~~~~~ I sub i ~>~ 0.0$
+
+    $x sub c ~=~ {sum I sub i ~ x sub i} over {sum I sub i}$
+
+.fi
+.IP 3.
+The errors are estimated in the following way
+.nf
+
+    $sigma sup 2 ~=~ {sum I sub i ~ x sub i sup 2} over {sum I sub i} ~-~ x sub c sup 2$
+
+    $err sub xc ~=~ sqrt {{sigma sup 2} ~/~ sum I sub i}$
+
+.fi
+
+.NH 4
+Gaussian Fit to the Marginals
+.PP
+The fit is performed in the following way.
+.IP 1.
+The  marginal distributions in x and y are accumulated.
+.IP 2.
+Initial guesses for the parameters of the 1D Gaussians $I sub Gauss$,
+$x sub c$ and $I sub sky$ are derived from the marginal distributions
+themselves. The width $sigma$ is held constant.
+.IP 3.
+The best fit parameters and their errors are derived using non-linear
+least-squares techniques and the NLFIT package.
+
+.NH 4
+Optimal Filtering of Marginals
+.PP
+The fit is performed is the following way.
+.IP 1.
+The marginal distributions in x and y are accumulated.
+.IP 2.
+The centroid of the observed distribution is computed by solving the
+following equation.
+.nf
+
+        $PSI (x sub c ) ~=~ sum omega sub i (x sub c ) ~ PHI sub i ~=~ 0$
+
+        $omega sub i ~=~ {{partial phi sub i} ~/~ {partial x sub c}} over {phi sub i~+~b}$
+
+.fi
+The assumptions are that the observed distribution $PHI sub i$ is correctly
+modeled by the profile function $phi sub i$. The usual choise of profile
+model for centering is a Gaussian. Howver in the interests of speed a triangle
+function has been substituted. This causes at most a 7% increase in the
+random centering error.
+.IP 3.
+The startup procedure is based on the following fact.
+.nf
+
+	$PSI (x sub n )~>~0~~for~~ x sub n ~<~ x sub c$
+
+	$PSI (x sub n ) ~<~0~~for~~ x sub n ~>~ x sub c$
+
+.fi
+The iteration is initialized by assuming that $x sub 1$ = $x sub c$ and
+computing $PSI (x sub 1 )$. The initial x 
+value is incremented by $+- sigma sub Gauss$ depending on the sign of $PSI$. The
+search is repeated until $PSI (x sub {n-1})$ and $PSI (x sub n)$ have
+opposite signs. At this point the true center is bracketed by the
+estimated positions $(x sub n, ~ x sub {n-1})$ and we have a table of at
+least 2 values of $PSI (x sub n )$.
+.IP 4.
+The computation proceeds by interpolating in the table of values for the
+estimated position $x sub {n+1}$ where $PSI$ = 0. If the table contains only
+two values as may be the case for the inititial interpolation, linear
+interpolation is used. In all other cases a quadratic fit to the three
+most recent $PSI$ values is used. The computation is complete when
+two successive estimates differ by less than some tolerance typically
+0.001 pixel.
+.IP 5.
+The errors are estimated as follows.
+.nf
+
+    $sigma sup 2 ~=~ ( {int {( partial phi ~/~ partial x sub c )} sup 2 over {
+    phi + b}} ) sup -1$
+
+    $err sub xc ~=~ sqrt {sigma sup 2}$
+
+.fi
+
+.NH 4
+Other Centering Methods
+.PP
+The code is constructed in such a way that new algorithms may be
+easily added at a future date, such as the more sophisticated techniques
+required for accurate astrometry.
+.EQ
+delim $$
+.EN
+.NH 3
+The FITSKY Task
+
+.NH 4
+Sky Fitting Routines
+
+.PP
+The following are the main entry points in the sky fitting package.
+.nf
+\fL
+         apsinit (ap, function, annulus, dannulus, fwhmpsf, noise)
+   ier = apfitsky (ap, im, xpos, ypos, sd, gd)
+   ier = aprefitsky (ap, sd, gd)
+ value = apstat[ir] (ap, param)
+	 apstats (ap, param, str, maxch)
+         apset[irs] (ap, param, value)
+         apsfree (ap)
+\fR
+.fi
+.PP
+The following quantities can be examined or set with apset/apstat calls.
+.nf
+\fL
+data             1. fwhmpsf     full width half maximum of the psf
+parameters       2. sigma       standard deviation of sky pixels
+
+sky fitting      1. annulus     inner radius of sky annulus in fwhmpsf
+parameters       2. dannulus    outer radius of sky annulus in fwhmpsf
+                 3. sfunction   sky fitting algorithm
+                 4. smaxiter    maximum number of fitting iterations
+                 5. kreject     k-sigma rejection limit sigma
+                 6. nreject     maximum number of rejection cycles
+                 7. rgrow       region growing radius in fwhmpsf
+
+                 8. khist       half-wdth of histogram in sigma
+                 9. binsize     binsize of histogram in sigma
+                 10.smooth      Lucy smooth the histogram
+
+                 11.skyfile     name of text file containing sky values
+                 12.skyvaluser  supplied constant value for sky
+\fR
+.fi
+.PP
+The following computed quantities can only be examined with apstat calls.
+.nf
+\fL
+              1. skymode           computed sky value
+              2. skysig            computed sky sigma
+              3. skyskew           computed sky skew
+              4. nsky              number of sky pixels
+              5. nsky_reject       number of rejected sky pixels   
+\fR
+.fi
+
+.NH 4
+The Sky Fitting Algorithms
+.PP
+A good background fit is essential to aperture photometry.  Fitting
+the background is trivial in a sparse field, but difficult in a crowded
+field.  In general the background region will contain contaminating objects
+which must be detected and excluded if a good fit is to be obtained.
+.PP
+The main algorithm used in APPHOT is the following.
+.IP 1.
+If the skyfitting switch is disabled either read the sky values from a text
+file or accept a user supplied constant for the sky.
+.IP 2.
+Perform the initial sky fit using one of the specified algorithms. The
+sky fitting algorithms fall into three general categories, those that use
+the actual sky pixel array itself, those that operate on a histogram of
+sky values and those that rely on user interaction.
+.IP 3.
+If the pixel rejection flags are set perform pixels rejection with optional
+region growing.
+
+.NH 4
+Sky Pixel Array Techniques
+
+.NH 5
+Median
+.IP 1.
+Sort the array of sky pixels. This is necessary to avoid quantization effects.
+.IP 2.
+Compute the median, and the standard deviation and skew with respect to the
+mean.
+.IP 3.
+If the k-sigma rejection limit is greater than zero and the maximum number
+of rejection cycles is greater than one, perform pixel rejection.
+Pixels greater than k-sigma from the median are rejected. Region growing
+is optional.
+.IP 4.
+Stop the rejection cycle on any given iteration if the maximum number of
+rejection cycles ix exceeded, no more sky pixels are left or no more
+pixels are rejected.
+
+.NH 5
+Mode
+.IP 1.
+Sort the array of sky pixels. This is necessary to avoid quantization effects.
+.IP 2.
+Compute the mode, and the standard deviation and skew
+with respect to the mean.
+.nf
+
+	$I sub mode ~=~ 3.0 ~*~ I sub median ~-~ 2.0 ~*~ I sub mean$
+
+.fi
+.IP 3.
+If the k-sigma rejection limit is greater than zero and the maximum number
+of rejection cycles is greater than one, perform pixel rejection.
+Pixels greater than k-sigma from the mode are rejected. Region growing
+is optional.
+.IP 4.
+Stop the rejection cycle on any given iteration if the maximum number of
+rejection cycles ix exceeded, no more sky pixels are left or no more
+pixels are rejected.
+
+
+.NH 4
+Histogram Techniques
+.PP
+The following three techniques all operate on the histogram of the sky pixels.
+The routines all construct the histogram in the following identical manner.
+.IP 1.
+The mean of the sky distribution is computed.
+.IP 2.
+If the user specified standard deviation of the sky pixels is INDEF the
+algorithm computes the standard deviation of the sky pixels with respect
+to the mean.
+.IP 3.
+All pixels within plus or minus sigma standard
+deviations are accumulated into a histogram. The user specifies the bin size.
+.IP 4.
+The histogram may optionally be Lucy smoothed before any operation is performed
+on it.
+
+.NH 5
+Centroid
+.PP
+The mode, sigma and skew of the sky pixels are computed in the following
+manner.
+.IP 1.
+The histogram is compiled as above.
+.IP 2.
+The mode, standard deviation and skew of the sky pixels are computed in the
+following manner.
+
+.nf
+    $I sub 0 ~=~ sum I sub i$
+    $I sub 1 ~=~ sum I sub i ~ x sub i$
+    $I sub 2 ~=~ sum I sub i ~ x sub i sup 2$
+    $I sub 3 ~=~ sum I sub i ~ x sub i sup 3$
+
+    $I sub mode ~=~ {I sub 1} ~/~ {I sub 0}$ 
+    $sigma ~=~ {( I sub 2 ~/~ I sub 0 ~-~ I sub mode sup 2 )} sup {1/2}$
+    $skew ~=~ ( {I sub 3 ~/~ I sub 0 ~-~ I sub mode ~*~ sigma sup 2 ~-~ I sub mode sup 3} ) sup {1/3}$
+
+.fi
+.IP 3
+If pixel rejection is enabled sky pixels within a user supplied limit of
+the mode are rejected with optional region growing.
+
+.NH 5
+Gaussian Fit
+.PP
+The mode, standard deviation and skew of the sky pixels are derived from a
+model fit in the following way.
+.IP 1.
+The histogram of the sky pixels is compiled as above. 
+.IP 2.
+Initial guesses to the model parameters, $N sub max$, $I sub mode$,
+$sigma$, and $skew$ are made from the histogram itself.
+.IP 3.
+Final parameters and their errors are derived using non-linear least squares
+techniques and the NLFIT package.
+.IP 4.
+If pixel rejection is enabled sky pixels within a user supplied limit of
+the computed mode are rejected with optional region growing.
+
+.NH 5
+Optimal Filtering
+.PP
+The method is as follows.
+.IP 1.
+The histogram is compiled as above.
+.IP 2.
+Using the mean of the sky pixels as the intital value of the sky mode,
+a new mode is computed using the optimal filtering technique
+described for centering.
+.IP 4
+If pixel rejection is enabled sky pixels within a user supplied limit of
+the computed mode are rejected with optional region growing.
+
+.NH 5
+Cross Correlation
+.PP
+The method is as follows.
+.IP 1.
+The histogram is compiled as above.
+.IP 2.
+The noise function is estimated using the standard deviation of the sky
+pixels and the cross-correlation function is computed.
+.IP 3.
+The mode is computed using quadratic interpolation around the peak of the
+distribution.
+.IP 4
+If pixel rejection is enabled sky pixels within a user supplied limit of
+the mode are rejected with optional region growing.
+
+.NH 4
+Interactive Techniques
+
+.NH 5
+Histogram Plot
+.PP
+The histogram is compiled as described above and the user marks the peak
+on the histogram plot with the graphics cursor. The sigma and skew of the
+sky distribution with respect to the mean is also computed.
+
+.NH 5
+Radial Distribution
+.PP
+A radial profile plot of the sky region is plotted and the user marks the
+sky value on the plot with the graphics cursor. The sigma and skew of the sky
+distribution with respect to the mean is computed.
+
+.NH 4
+Pixel Rejection and Region Growing
+.PP
+All the sky fitting algorithms permit pixel rejection and
+optional region growing.
+Pixel rejection  and region growing are
+performed by locating all pixels more than k * sigma from the mode,
+and blindly rejecting all pixels within a certain radius of each deviant
+pixel.  This simple algorithm works well because the sample is large,
+and therefore there is little penalty for discarding pixels that might
+not be deviant.  Region growing also tends to accelerate convergence
+significantly.
+.PP
+Very faint contaminating objects are difficult to detect and reject.
+If there are enough such objects, they should not be rejected, because
+there are probably a few in the object aperture as well.  A higher sky
+sigma will be calculated and the computed uncertainty in the magnitude
+will increase.  The best solution to this problem may be to increase
+the size of the annulus to minimize the bias.
+
+.NH 4
+The Principal PHOT Routines
+.PP
+The main entries in the photometry routine are the following.
+.nf
+\fL
+               apinit (ap, cfunction, cbox, sfunction, annulus, dannulus,
+                aperts, napert, fwhmpsf, noise)
+         ier = apfitcenter (ap, im, xinit, yinit)
+         ier = aprefitcenter (ap)
+         ier = apfitsky (ap, im, xcenter, ycenter, sd, gd)
+         ier = aprefitsky (ap, sd, gd)
+         ier = apmag (ap, im, xcenter, ycenter, skyval, skysig, nsky)
+         ier = apwmag (ap, im, xcenter, ycenter, positive, skyval, skysig, nsky)
+         ier = apremag (ap, positive, skyval, skysig, nsky)
+         ier = apwremag (ap, positive, skyval, skysig, nsky)
+       value = apstat[ir] (ap, param)
+               apstats (ap, param, str, maxch)
+               apset[sir] (ap, param, value)
+               apfree (ap)
+
+\fR
+.fi
+.PP
+The following parameters can be examined or altered by apset/apstat calls.
+.nf
+\fL
+                1. weighting        weighting scheme for wphot
+                2. aperts           list of apertues
+                3. naperts          number of apertures
+                4. zmag             zero point of magnitude scale
+                5. itime            effective integration time
+\fR
+.fi
+.PP
+The following quantities can be examined with apstat calls.
+.nf
+\fL
+
+                1. sums            array of aperture sums
+                2. areas            array of areas
+                3. mags             array of magnitudes
+                4. magerrs          array of magnitude errors
+
+\fR
+.fi
+
+.NH 4
+The PHOT Aperture Integration Algorithm
+.PP
+The integral of the flux within a circular aperture is computed by
+fractional pixel techniques.  Pixels are assumed to be square apertures
+arranged in a rectangular grid.  The fraction of a pixel which lies within
+the circular APPHOT aperture is computed by an approximation, and all
+such contributions are summed to produce the total integral.
+.PP
+The inclusion of a partial pixel inside the aperture is done as follows.
+.IP 1.
+If the distance of the current pixel from the center of the star, r, is
+exactly equal to the radius of the aperture R then one-half the counts in
+the pixel are included.
+.IP 2.
+If r < R - 0.5 the entire pixel is included while if r > R + 0.5 the pixel
+is wholly excluded.
+.IP 3.
+In between the fraction of the counts varies linearly. A circular aperture
+is approximated by an irregular polygon.
+.PP
+The simplicity of aperture photometry limits the amount of information
+available for error analysis.  The following three sources of error are
+considered.
+.IP 1.
+The error due to sky noise in the aperture.
+.nf
+
+	$error sub 1 ~=~ sigma sub sky ~*~ {A sub apert} sup {1/2}$
+
+.fi
+.IP 2.
+The error in the aperture sum.
+.nf
+
+	$error sub 2 ~=~ ( {A sub "sum"  ~/~ phpadu} ) sup {1/2}$ 
+
+.fi
+.IP 3.
+The mean error of the sky.
+.nf
+
+	$error sub 3 ~=~ sigma sub sky ~*~ A sub apert ~/~ nsky sup {1/2}$
+
+
+.fi
+where $sigma sub sky$ is either computed by the background fitting
+algorithm or set by the user,
+and $A sub apert$ is the fractional pixel area of the
+aperture.
+
+.NH 4
+The WPHOT Algorithm
+.PP
+The WPHOT algorithm computes a weighted aperture sum in an attempt to
+minimize noise in the sky. The algorithm is the following where w is
+the weight for each pixel, p is the noise free profile value and 
+$sigma$ is the noise per pixel from all sources. (See the paper
+by Stover and Allen 1987 for details)
+.nf
+
+	$A sub sum ~=~ sum {w sub i ~*~ (I sub i ~-~ sky)}$
+
+	$w sub i ~=~ C ~*~ p sub i ~/~ sigma sup 2 sub i$
+
+	$C ~=~ sum {p sub j} / sum {p sub j ~*~ w sub j}$
+.fi
+
+.NH 4
+The POLYPHOT ROUTINES
+.PP
+The principal polyphot routines are the following.
+
+.nf
+\fL
+               apyinit (ap, sfunction, annulus, dannulus, noise)
+         ier = apfitcenter (ap, im, wx, wy)
+	 ier = aprefitcenter (ap)
+	 ier = apfitsky (ap, im, xcenter, ycenter, sd, gd)
+         ier = aprefitsky (ap, sd, gd)
+         ier = polyfit (ap, im, xver, yver, nver)
+       value = apstat[ir] (ap, param)
+               apstats (ap, param, str, maxch)
+               apset[sir] (ap, param, value)
+               apfree (ap)
+
+\fR
+.fi
+
+.PP
+.NH 4
+The POLYPHOT Algorithm 
+.PP
+The function of the POLYPHOT task is to compute the flux inside an
+irregular polygon given a list of the coordinates of the vertices of a polygon.
+The polygon must be entirely inside the image and the vertices of the polygon
+must be specified in clockwise or counterclockwise order.
+The actual algorithm used is as follows.
+.IP 1.
+The range of image lines which intersect the polygon are computed.
+.IP 2.
+For each image line in the specified range the intersection points with the
+polygon are computed.
+.IP 3.
+The flux between pairs of limits is summed using a fractional pixel
+approximation for the endpoints.
+.IP 4.
+The sky is fitted using any of the methods previously discussed and a
+user specified annular region.
+.IP 5.
+The errors are computed as specified in the PHOT specifications.
+.PP
+.EQ
+delim $$
+.EN
+
+.NH
+Example
+.PP
+A brief example may help illustrate the use of the package.  Suppose
+we want to process a few hundred stars on image "blue".
+.PP
+The first step is to prepare a list of objects to be measured.  The simplest
+way to do this is to interactively mark the objects with the image
+cursor using the display (graphics) device and the RIMCURSOR (RGCURSOR)
+task.
+.nf
+\fL
+
+	... load image on the display ...
+
+	ap> rimcursor > starlist
+
+	    ... move cursor and mark stars ...
+
+
+	... load contour plot on graphics terminal ...
+
+	ap> rgcursor > starlist
+
+	    ... move cursor and mark stars ...
+\fR
+.fi
+
+Alternatively one can run DAOFIND to compute a list of candidate objects
+in the frame.
+The name of the coordinate file is stored in the PHOT parameter set.
+
+.nf
+\fL
+	ap> phot.coords=starlist
+\fR
+.fi
+
+.PP
+The next step is to set up the PHOT parameters interactively.
+First we load the image (contour plot) blue on the display (graphics
+terminal). Next we call up PHOT in interactive mode.
+
+.nf
+\fL
+	ap> phot blue
+	... cursor appears ...
+
+\fR
+.fi
+
+.PP
+PHOT takes input by reading the image (graphics)
+display (terminal) cursor. In order to display the available commands
+we tap the ? key and the following text appears on the screen.
+
+.nf
+\fL
+	Interactive Phot Commands
+
+?	Print options
+:	Colon command see below
+i	Setup PHOT parameters interactively
+w	Write PHOT parameters to the parameter files
+l	Process the remainder of the coordinate list
+r	Rewind the coordinate list
+c	Fit center around the current cursor position
+t	Fit sky around the current cursor position
+s	Fit sky around the current center position
+p	Compute magnitudes around the cursor position
+f	Fit center, sky and compute magnitudes
+sp	Fit center, sky, compute magnitudes, and save
+q	Exit program
+
+Phot parameters are listed or set with the following commands.
+
+:m [n]	Move cursor to the [nth] object in the coordinate list
+:n [n]	Measure the [nth] object in the coordinate list
+
+:show [center/sky/phot/all]    List the aphot parameters
+:fwhmpsf [value]               Full width half maximum of the PSF
+:noise [string]                Noise model
+:threshold [value]             Threshold value for centering
+:sigma [value]                 Standard deviation of the background
+:ccdread                       CCD readout noise keyword
+:readnoise                     Readout noise in electrons
+:gain                          Gain keyword
+:epadu                         Electrons per adu
+
+:calgorithm [string]           Centering function
+:positive [y/n]                Emission or absorption feature
+:cbox [value]                  Width of the centering box in fwhmpsf
+:cmaxiter [value]              Maximum number of centering iterations
+:maxshift [value]              Maximum shift in fwhmpf
+:minsnratio [value]            Minimum signal to noise ratio of pixels
+:clean [y/n]                   Clean subraster before centering
+:rclip [value]                 Clipping radius in fwhmpsf
+:rclean [value]                Cleaning radius in fwhmpsf
+:kclean [value]                Sigma for clean algorithm
+:mkcenter [y/n]                Mark the centers on the display
+
+:salgorithm [string]           Sky fitting algorithm
+:annulus [value]               Inner radius of sky annulus in fwhmpsf
+:dannulus [value]              Width of sky annulus in fwhmpsf
+:skyvalue [value]              User supplied sky
+:smaxiter [value]              Maximum number of rejection cycles
+:skreject [value]              +/- Pixel rejection limits in sky sigma
+:snreject [value]              Maximum number of rejection interations
+:khist [value]                 +/- Sky histogram size in sky sigma
+:binsize [value]               Resolution of sky histogram in sky sigma
+:smooth [y/n]                  Lucy smooth the sky histogram
+:rgrow [value]                 Region growing radius in fwhmpsf
+:marksky [y/n]                 Mark the sky annuli on the display
+
+:weighting                     Weighting for wphot
+:aperts [string]               Aperture radii in fwhmpsf
+:zmag [value]                  Zero point of magnitude scale
+:exposure [string]             Exposure time keyword
+:itime [value]                 Integration time
+\fR
+.fi
+
+.PP
+We select the interactive setup option, move the image
+cursor to a high signal-to-noise, isolated star and tap the i key.
+PHOT responds by plotting the radial profile of the star on the
+screen and requesting the user to mark the fwhm of
+the psf, the centering aperture, the inner and outer sky annuli,
+the sky background and sigma and the set of circular apertures.
+The parameters so set can be examined and/or reset with the : commands as shown
+above. Sample measurements can be made of several stars by moving the
+cursor and typing the f command. Finally when we are happy with the
+parameter set we type w to store the parameters and q to exit the program.
+.PP
+Now we are ready to do photometry. We enter the PHOT program in batch mode.
+
+.nf
+\fL
+	ap> phot blue inter- &
+\fR
+.fi
+
+The batch job is now running, appending output lines to the file "blue.mag.#".
+We can proceed to set up the job for the red image, in much the same way
+that we set up the job for the blue image.  When both jobs finish, we
+can use the list processing tools to filter out the good objects and
+calculate colors.
+
+.NH
+The APPHOT Tasks
+.PP
+Manual pages for the APHOT tasks are attached. Although the working of the
+various tasks may change in detail, the help pages attached here should
+provide a good description of the function of each task.
+.PP
+When the package has stabilized a detailed users guide will be written.
diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc.lw b/noao/digiphot/apphot/doc/specs/apphot.spc.lw
new file mode 100644
index 00000000..71285557
--- /dev/null
+++ b/noao/digiphot/apphot/doc/specs/apphot.spc.lw
@@ -0,0 +1,1296 @@
+.EQ
+delim $$
+.EN
+
+.RP
+.TL
+Specifications for the Aperture Photometry Package
+.AU
+Lindsey Davis
+.AI
+.K2 "" "" "*"
+Revised October 1987
+
+.AB
+The APPHOT package is a set of tasks for performing aperture photometry
+on uncrowded or moderately crowded fields, in either interactive or batch mode.
+The photometric technique employed is fractional pixel aperture
+integration. Point spread function fitting techniques are not used and no
+knowledge of the point spread function is required for the computation of
+magnitudes. Separate tasks are provided for creating and modifying object lists,
+computing accurate centers for a list of objects, computing sky values for
+a list of objects and performing aperture photometry inside circular or
+polygonal apertures.
+.AE
+
+.NH
+Introduction
+.PP
+The APPHOT package is a set of tasks for performing
+aperture photometry on uncrowded or moderately crowded fields.
+The photometric technique employed is fractional pixel integration. Point
+spread function techniques are not used and no knowledge of the point spread
+function is required for the computation of magnitudes.
+.PP
+The APPHOT package performs multi-aperture photometry on digitized starfields
+maintained as IRAF image files. Input to the package consists of an
+image file, a list of object coordinates, numerous parameters controlling
+the analysis algorithms and, optionally, the graphics terminal and/or
+display. APPHOT output consists of successive lines of text where each line
+summarizes the results of the analysis for a particular object.
+.PP
+Given starting coordinates and an IRAF image, the principal APPHOT
+task computes accurate centers, sky values and magnitudes
+for a list of objects.  Separate
+IRAF callable tasks in APPHOT exist to create and modify object
+lists, to determine image characteristics such as the full width half maximum
+of the point spread function or standard deviation of the sky pixels,
+to compute accurate centers for a list of objects, to compute accurate local sky
+values for a list of objects, and to compute magnitudes inside a polygonal
+aperture.
+
+.NH
+APPHOT Package Requirements
+.NH 2
+APPHOT Package Input
+.NH 3
+The IRAF Image
+.PP
+APPHOT assumes that images exist on disk in IRAF format. Facilities for reading
+and writing images exist elsewhere in IRAF such as in package DATAIO or
+MTLOCAL.
+.PP
+APPHOT assumes that the image data is linear.
+The input image is assumed to have been corrected for those instrumental
+defects which affect the intensity of a pixel. These include pixel to
+pixel variations in the bias values, pixel to pixel gain variations,
+cosmic rays, cosmetic defects, geometric distortion,
+and detector non-linearities.
+.PP
+APPHOT assumes that the local sky background is approximately flat in the
+vicinity of the object being measured. This assumption is equivalent to
+assuming that the local sky region has a unique mode. Therefore any
+variations in the sky background which occur at the same scale as the
+sky region should be removed prior to entering APPHOT.
+.PP
+The point spread function of the image is assumed to be constant for all
+regions of the image. This is particularly critical in the case of faint objects
+for which small apertures which minimize the effects of crowding and
+sky noise in the aperture are used. The wings of the object will
+almost certainly extend beyond the aperture and good results will only be
+obtained if
+objects are consistently well centered and the shape and diameter of an object
+is constant throughout the image and invariant to magnitude.
+
+.NH 3
+The Coordinate Lists
+.PP
+All APPHOT tasks operate on lists of object coordinates or interactive cursor
+input.  Lists are maintained as text files,
+one object per line with the x and y coordinates in
+columns one and two respectively. List files may be created interactively
+with either the graphics or image cursor, by a previously executed APPHOT
+task, by a previously executed IRAF task or by a user task.
+.PP
+The x and y coordinates contained in the list file can be either the
+starting centers for the objects of interest or the true centers.
+In either case the aperture centered around the object position must
+not extend beyond the boundary of the image. To obtain reliable results
+from the centering algorithm the starting centers should not be more than
+1 fwhmpsf pixels from the true centers.
+
+.NH 3
+Algorithm Parameters
+.PP
+Many tasks in the APPHOT package have an associated set of algorithm parameters
+which control the operation of the analysis routines. For example the
+centering and sky fitting algorithms each have an associated group of
+parameters.
+The APPHOT tasks supply reasonable defaults for these parameters. However
+the user may alter them at any time in interactive mode or by editing the
+appropriate parameter file before running the task in batch. 
+
+.NH 3
+Terminal Graphics and the Image Display
+.PP
+Most APPHOT programs may be run in either interactive or batch mode.
+In interactive mode, the user can mark the positions of objects by
+interactively, positioning the image cursor on the display device.
+Simple cursor commands can interactively alter the algorithm parameters. 
+In batch mode the algorithm parameters are
+fixed and object coordinates are taken from the user supplied coordinate list.
+The display device is not required in batch mode.
+.PP
+At present there is no high level IRAF display interface. Therefore the present
+version of APPHOT replaces the display device with terminal
+graphics. For example it is possible to load a contour plot of an image
+or image section, and run the APPHOT tasks, interactively marking
+positions on the plot. This is a temporary measure to tide thing over until
+the display interface is available. Furthermore this option is only
+really suitable for those terminal which have both text and graphics
+windows displayed at the same time.
+.PP
+Certain APPHOT tasks such as FITSKY occasionally require an interactive graphics
+capability. For example it is sometimes desirable to plot the histogram
+of the sky pixels and mark the peak of the histogram interactively rather
+than using the automatic sky fitting routines.
+Graphics capablity has been added to APPHOT tasks as deemed useful.
+
+.NH 2
+APPHOT Package Functions
+.NH 3
+Creating Coordinate Lists
+.PP
+APPHOT task(s) shall exist to create coordinate lists interactively within
+APPHOT by loading the IRAF image into the image display
+and successively marking the objects to be measured with the image cursor.
+It shall be possible to mark the positions of objects on the display, and draw
+circles of arbitrary size around the objects of interest.
+It shall be possible to verify existing coordinate lists by marking the object
+coordinates on the image display.
+.PP
+At present the full image display cababilities do not exist in IRAF.
+Therefore as a temporary measure most tasks will run with a contour
+plot and the graphics cursor as a substitute for the image display and
+image cursor by setting the image cursor to stdgraph and the display
+parameter for each task to stdgraph.
+The output coordinates will be written to a text file and may be used as
+starting coordinates for the APPHOT routines.
+.PP
+Those sites which have SUN workstations can use the IMTOOL facilites to
+create cursor lists.
+.PP
+APPHOT tasks shall exist to automatically detect objects by specifying the IRAF
+image to be searched, plus a few image characteristics such as a detection 
+threshold and the full width half maximum of the point spread function.
+The output coordinates plus a few object statistics  will be written to a
+text file.
+
+.NH 3
+Coordinate List Operations
+.PP
+General list processing tasks are or will be available in the IRAF lists
+package. Examples of useful currently existing tasks are list sorting by for
+example magnitude and performing a linear transformations
+on coordinate lists.
+.PP
+It may eventually be necessary to add some specialized list processing tasks
+to APPHOT. One example is a list matching facility in which objects in
+common to two lists are combined and output to a third list.
+
+.NH 3
+Determining the Image Characteristics
+.PP
+APPHOT tasks shall exist to estimate certain image
+characteristics such as the full width half maximum of the image point spread
+function and the standard deviation of the background. In order to obtain
+meaningful error estimates it is also necessary to specify the noise
+charactersitics of the detector and a noise model.
+In this version of APPHOT two noise
+functions will be supported a constant sky background noise,
+and constant background noise plus Poisson statistics in the object.
+.PP
+The reason for this capability is that the majority of the APPHOT
+algorithm parameters scale with these two image characteristics.
+For example all the pixel scale dependent parameters such as the centering
+aperture, object apertures, the two sky annuli and the
+maximum shift parameter all scale with the full width half
+maximum of the point spread function. Similarly most of the pixel intensity
+dependent parameters scale with the standard deviation of the sky pixels.
+
+.NH 3
+Centering
+.PP
+An APPHOT task shall exist to determine accurate centers for a list of objects,
+using the approximate object coordinates as a starting point.
+The centering aperture may extend beyond the boundaries of the image but
+a warning message will be generated.
+.PP
+A choice of centering algorithms with a range of efficiency and accuracy will
+be available.  The center determination must be resistant to the affects of
+nearby contaminating objects.
+.PP
+The user may opt to use the starting center as the actual center in all cases,
+to use the starting center as the actual center if the object is very faint,
+or tweak up the center if the signal to noise is above a certain threshold.
+.PP
+The output of the centering algorithm will the set of computed coordinates
+and their errors.
+
+.NH 3
+Fitting the Sky
+.PP
+An APPHOT task shall exist to compute a constant background value by analysis
+of an annular region surrounding the object.
+The background is assumed to be flat in the region
+of the object, but may contain contaminating objects or defects which
+shall be detected and eliminated by the fitting algorithm.
+It shall be permissible for the background region to extend beyond the
+boundaries of the image; the out of bounds region of the background shall
+be excluded from the fit.
+.PP
+The user may supply a constant background, with zero-valued noise and skew
+value or read appropriate values from a file instead of computing the
+background.
+.PP
+The output of the sky fitting algorithm shall be
+the mode, standard deviation and skew of the sky as well as the number
+of pixels left in the background region after pixel rejection and the number
+rejected.
+
+.NH 3
+Multi-aperture Photometry
+.PP
+APPHOT routines shall exist to compute the integral of object minus background
+within one or more circular apertures centered upon the object.
+The integration shall be
+performed using partial pixel techniques, to minimize the effects of
+sampling.  If the aperture contains any indefinite pixels, or if the
+aperture extends beyond the boundary of the image, an indefinite result
+shall be returned. Both normal and weighted photometry routines shall
+be available.
+.PP
+It shall be possible to normalize the output magnitudes to a user specified
+integration time using values stored in the IRAF image header.
+.PP
+The output shall consist of magnitudes and errors for each of the specified
+apertures.
+.NH 3
+Polygonal Aperture Photometry
+.PP
+Determine the integral of the object within a specified
+polygon. Aperture integration shall be by fractional pixel summation
+of successive image lines.
+
+.NH
+Specifications
+.NH 2
+Apphot CL Callable Tasks
+.PP
+The CL callable part of the APPHOT package consists of the following
+routines:\f(CW
+
+.nf
+.na
+        mark    -- create/verify coordinate lists interactively
+    polymark    -- create/verify polygon lists interactively
+     daofind    -- automatic image finder from DAOPHOT
+     lintran    -- linearly transform a list of coordinates (LISTS package)
+
+     radprof    -- compute the radial profile of an object.
+      fitpsf    -- model the PSF
+
+      center    -- compute accurate centers for a list of objects
+      fitsky    -- compute accurate sky values for a list of objects
+        phot    -- perform multi-aperture photometry on a set of objects
+    polyphot    -- compute the flux inside a set of irregular polygons
+       wphot	-- perform weighted multi-aperture photometry\fR
+.ad
+.fi
+
+.NH 2
+Standard Analysis Procedures
+.PP
+A standard reduction procedure would be something as follows.
+.IP 1.
+Estimate the image and data characteristics in the following manner.
+.RS
+.IP 1.
+Use the interactive setup option (i key) in the PHOT task to specify the
+fwhm of the psf,
+the centering apperture, the sky annuli, the photometry apertures as
+well as estimate the sky sigma.
+Examine the results (:show command) and optionally store the 
+new parameters in the parameter files (w key).
+.IP 2.
+Use the EPAR task to edit the parameter files directly. For example the
+detector gain and readout noise must be known before running PHOT in
+order to get reliable error estimates.
+.RE
+.IP 2.
+Prepare a coodinate list in one of the following ways.
+.RS
+.IP 1.
+Running MARK or POLYMARK.
+.IP 2.
+Run DAOFIND or some other automatic image finder.
+.IP 3.
+Run another APPHOT task such as CENTER .
+.IP 4.
+Run any other IRAF or user program which generates the appropriate
+format.
+.IP 5.
+Transform an existing list using the LISTS package facilities
+.RE
+.IP 3.
+Run PHOT or WHOT in non-interactive mode to perform the multi-aperture
+photometry.  The user should be familiar
+with the algorithms used to measure the object center, to fit the background,
+and compute the aperture integral, magnitude, and errors.  The values of
+all visible and hidden PHOT parameters should be inspected before doing
+any serious processing. Note that CENTER and FITSKY can be run independently
+of PHOT and their output used as input to PHOT.
+.EQ
+delim $$
+.EN
+
+.NH 2
+The APPHOT Algorithms
+.PP
+The principal APPHOT algorithms are described below.
+
+.NH 3
+The RADPROF Algorithm
+.PP
+The function of the RADPROF task is to compute the radial profile of
+selected, isolated, high signal to noise objects in an IRAF image.
+.PP
+Given the IRAF image, an initial center, an aperture and a step size,
+RADPROF computes the radial profile of an object in the following manner.
+.IP 1.
+The APPHOT centering routines are used to compute an accurate center for the
+object. The new center is used to compute the radial coordinate for each
+pixel in the subraster.
+.IP 2.
+The APPHOT sky fitting routines are used to compute an accurate sky value
+for the object. The new sky value is used to compute the object intensity
+for each pixel in the subraster.
+.IP 3.
+The CURFIT package routines are used to produce a smooth intensity versus
+radius curve by fitting a cubic least squares spline function to the data
+using linear least squares techniques.
+.IP 4.
+The fitted curve is evaluated at equally spaced intervals to produce the
+final radial profile. The profile is normalised using the r = 0 value.  
+.IP 5.
+The smoothed curve is integrated using the 
+1D integration routines IMINTERP to evalute the fraction of the total
+integral at each interval.
+.IP 6.
+The three quantities $I sub r$ the raw intensity, $Inorm sub r$ the
+normalized intensity, and $Ifraction sub r$ the fraction of the total
+intensity inside radius at r,  are plotted on the terminal and
+output as a function of r to a text file.
+.PP
+RADPROF is used principally to compute the stellar image and setup the
+parameters for doing photometry. Its default output is a radial profile
+plot with the phot parameters marked on it.
+
+.NH 3
+The FITPSF Algorithm
+.PP
+The function of the FITPSF task is to fit an analytic model to an object
+in order to derive information about the point spread function. Given
+an IRAF image, an initial center and an aperture, FITPSF computes the
+model parameters in the following manner.
+.IP 1.
+The fitting function is chosen.
+The present version of FITPSF offers two function choices a 2D radial Gaussian
+function and an elliptical Gaussian function.
+A third option, moment analysis, has been added to the FITPSF package.
+The image characteristics are evaluted by using the 0th, 1st and 2nd order
+moments of the image.
+.IP 2
+Initial guesses for the parameters are made from the subraster data.
+.IP 3
+The parameters and their errors are derived using standard non-linear least
+squares techniques and the NLFIT package.
+
+.NH 3
+The DAOFIND Algorithm
+.PP
+The function of the DAOFIND task is to automatically detect objects
+in an IRAF image above a certain intensity threshold.
+The user specifies an intensiyt threshold,
+the estimated full width half maximum of
+the point spread function,
+and limits on the sharpness and roundness of the objects to be detected.
+DAOFIND produces a list of x and y coordinates and a sharpness
+and roundness statistic for each detected object.
+.PP
+The DAOFIND algorithm works in the following way.
+.IP 1.
+The user specifies an intensity threshold above local sky and estimates
+the full width half maximum of the point spread function.
+.IP 2.
+DAOFIND computes a convolution kernel which is a linear
+function of the brightness values in an approximately circular array of
+pixels.  The original data is convolved with the computed kernel.
+The equivalent mathematical
+operation is a convolution of the original data
+with truncated, lowered circular Gaussian function with the specified FWHM,
+computed in such a way as to be the mathematical
+equivalent of fitting a Gaussian stellar profile to the object data by least
+squares. The coefficients of the linear function sum to zero so that the
+overall bias level (local sky) cancels out exactly. Since the function is
+symmetric about a single pixel, a smooth gradient in the sky brightness
+also cancels exactly. Therefore the user does not have to specify an
+absolute brightness threshold but only a threshold above local sky.
+.IP 3
+The convolved data is searched for local maxima. Local maxima which are
+less than the specified threshold are rejected. A pixel is defined to be
+a local maximum when it is the brightest pixel within
+$n ~*~ sigma sub Gauss$.
+.IP 4.
+Using the original data, DAOFIND computes an object sharpness statistic which
+can be used to reject
+hot or cold pixels.  The sharp parameter is defined below.
+Detected  objects with a sharpness parameter outside the range specifed
+by sharplo and sharphi are rejected. Typical values for sharplo and
+sharphi are 0.2 and 1.0 respectively.
+.nf
+
+    $I sub delta$ = height of best fitting $delta$ function = pixel value
+
+    $I sub Gauss$ = height of best fitting Gaussian function = convolved value
+
+    sharplo <= sharp = ${I sub delta} over {I sub Gauss}$ <= sharphi
+
+.fi
+If the brightness enhancement detected in the convolved data is due to
+a single bright pixel, then the best fitting delta function will have an
+amplitude equal to the height of this pixel above the local background,
+while the amplitude of the best fitting Gaussian will be pulled down by
+the surrounding low valued pixels. Sharp will be a number significantly
+greater than one. A single cold pixel will produce
+brightness enhancements approximately 0.5 * FWHM away
+from the pixel in question  in all directions. In this case the height
+of the delta
+function which best fits these spurious maxima is close to zero, while the
+height of the best fitting Gaussian is some small positive number.
+In this case sharp will be close to zero.
+.IP 5.
+The roundess statistic is computed from the original picture data by fitting
+1D Gaussians
+to the marginal sums in x and y. If the height of either 1D
+Gaussian is negative the object is rejected. If both heights are
+positive the roundness parameter is computed.
+.nf
+
+	$DELTA I ~=~ I sub {x ~ Gauss} ~-~ I sub {y ~ Gauss}$
+
+	$<I> ~=~ I sub {x ~ Gauss} ~+~ I sub {y ~ Gauss}$
+
+	$roundlo ~<=~  round ~=~ {DELTA I} over <I> ~<=~  roundhi$
+
+.fi
+Objects which are elongated in the
+x direction have roundness values less than zero and those elongated in
+the y direction have roundness greater than zero.
+Round discriminates only against objects which are elongated
+along either rows or columns. Objects elongated at a 45 degree angle will
+not be rejected.
+.IP 6.
+Finally the approximate x and y centroids of the detected objects,
+rough magnitudes relative to threshold are computed, and object is added
+to the output file.
+
+
+.NH 3
+The CENTER Task
+
+.NH 4
+Centering Package Routines
+.PP
+The following are the principal programmer callable routines routines in the
+centering package.
+.nf
+\f(CW
+
+                  apcinit (ap, cfunction, cbox, fwhmpsf, noise)
+            ier = apfitcenter (ap, im, xinit, yinit)
+            ier = aprefitcenter (ap)
+          value = apstat[ir] (ap, param)
+                  apstats (ap, param, str, maxch)
+                  apset[sir] (ap, param, value)
+                  apcfree (ap)
+
+\fR
+.fi
+.PP
+The following quantities can be examined or set by apstat/apset calls
+.nf
+\f(CW
+  data          1. fwhmpsf       full width half maximum of psf in pixels
+parameters      2. threshold     minimum intensity for centering
+                3. noise         noise model
+                4. sigma         standard deviation of background
+                5. readnoise     readout noise of CCD in electrons
+                6. epadu         electrons per adu
+
+centering       1. calgorithm    centering algorithm
+parameters      2. positive      emission / absorption features
+                3. cbox          centering radius in fwhmpsf
+                4. cmaxiter      maximum number of fitting iterations
+                5. maxshift      maximum permitted shift in fwhmpsf
+                6. minsnratio    minimum permitted signal to noise ratio
+                7. clean         clean subraster before centering
+                8. rclean        cleaning radius in fwhmpsf
+                9. rclip         clipping radius in fwhmpsf
+                10.kclean        k-sigma rejection for cleaning in sigma
+\fR
+.fi
+
+.PP
+The following computed quantities can be examined by apstat calls.
+.nf
+\f(CW
+              1. xcenter            computed x coordinate
+              2. ycenter            computed y coordinate
+              3. xerr               computed x coordinate error
+              4. yerr               computed y coordinate error
+\fR
+.fi
+.PP
+See the manual pages for CENTER and CENTERPARS for a detailed description
+of the centering parameters.
+
+.NH 4
+The Centering Algorithm
+.PP
+The function of the CENTER task is to compute accurate centers and errors
+for objects in an IRAF image given a list of initial positions and a
+centering aperture.
+.IP 1.
+If the centering algorithm is disabled, the computed center is set to the
+initial center and the uncertainty estimate is set to zero.
+.IP 2.
+If the cleaning algorithm is enabled, clean the subraster before centering.
+.IP 3.
+Estimate is made of the signal to noise of the object. If this quantity is
+less than a certain minimum value the computed center is kept
+but a warning message is issued.
+.IP 4.
+The center and errors are computed using one of several algorithms.
+.IP 5.
+If the computed center is greater than a user specified distance from the
+initial center then the computed center is returned with an error
+message.
+
+.NH 4
+Symmetry Clean Algorithm
+.PP
+The symmetry-clean algorithm attempts to remove defects in the centering
+subraster by assuming that the object has radial symmetry and comparing
+pixels on the opposite sides of the center of symmetry. The algorithm
+works in the following way.
+.IP 1.
+The center of symmetry is computed. Normally the center of symmetry is assumed
+to coincide with the position of the brightest pixel in the subarray.
+However if the maximum pixel is more than a user specified distance away
+from the intial center, the initial center is used as the center of symmetry.
+.IP 2.
+Pixels inside a specified cleaning radius are unaltered.
+.IP 3.
+Pairs of pixels diametrically opposed about the center
+in the cleaning region between the cleaning and clipping
+radii are tested for equality.  If the difference between the pixels is
+greater than a specified k-sigma rejection limit, the larger value is replaced
+by the smaller.
+In this region sigma is computed from Poisson statistics.
+.IP 4.
+Pairs of pixels in the clippping
+region are compared in the same manner as those in the cleaning region
+except that sigma is the standard deviation of the sky pixels.
+.PP
+The effect of the symmetry-clean algorithm is to edit the raster,
+removing any contaminating objects in the vicinity of the primary object.
+This simplifies the fitting algorithm and increases its reliability,
+since it does not have to deal with multipeak marginal distributions.
+
+.NH 4
+Signal to Noise Estimate
+
+.PP
+The signal to noise of the object is estimated from the data values
+in the subraster in the following way.
+.nf
+
+	$SNR ~=~ N sub object over {sqrt {n sub pix ~*~sigma sub sky sup 2}}$
+
+		or
+
+	$SNR ~=~ N sub object over {sqrt {N sub object ~+~ n sub pix~*~sigma sub sky sup 2}}$
+
+.fi
+where $N sub *$ is the number of counts in the object above threshold,
+$sigma sub sky$
+is the standard deviation of the pixels in the sky region and
+$n sub pix$ is the number of pixels in the object aperture.
+The first approximation corresponds to constant sky noise only,
+the second includes Poisson noise in the object.
+
+.NH 4
+Centroid
+.PP
+The centroid centering algorithm is similar to that used in MPC and can
+be briefly described as follows. For more detailed description
+see (Stellar Magnitudes From Digital Pictures, 1980, Adams et al).
+.IP 1.
+The marginal distributions in x and y are accumulated.
+.IP 2.
+The intensity weighted centroid positions for the marginals is computed
+using only data pixels which are above the threshold intensity. If the
+threshold parameter is 0 the mean intensity of the marginal is used
+in place of the threshold
+.nf
+
+    $I sub i ~=~ I sub i ~-~ threshold ~~~~~ I sub i ~>~ 0.0$
+
+    $x sub c ~=~ {sum I sub i ~ x sub i} over {sum I sub i}$
+
+.fi
+.IP 3.
+The errors are estimated in the following way
+.nf
+
+    $sigma sup 2 ~=~ {sum I sub i ~ x sub i sup 2} over {sum I sub i} ~-~ x sub c sup 2$
+
+    $err sub xc ~=~ sqrt {{sigma sup 2} ~/~ sum I sub i}$
+
+.fi
+
+.NH 4
+Gaussian Fit to the Marginals
+.PP
+The fit is performed in the following way.
+.IP 1.
+The  marginal distributions in x and y are accumulated.
+.IP 2.
+Initial guesses for the parameters of the 1D Gaussians $I sub Gauss$,
+$x sub c$ and $I sub sky$ are derived from the marginal distributions
+themselves. The width $sigma$ is held constant.
+.IP 3.
+The best fit parameters and their errors are derived using non-linear
+least-squares techniques and the NLFIT package.
+
+.NH 4
+Optimal Filtering of Marginals
+.PP
+The fit is performed is the following way.
+.IP 1.
+The marginal distributions in x and y are accumulated.
+.IP 2.
+The centroid of the observed distribution is computed by solving the
+following equation.
+.nf
+
+        $PSI (x sub c ) ~=~ sum omega sub i (x sub c ) ~ PHI sub i ~=~ 0$
+
+        $omega sub i ~=~ {{partial phi sub i} ~/~ {partial x sub c}} over {phi sub i~+~b}$
+
+.fi
+The assumptions are that the observed distribution $PHI sub i$ is correctly
+modeled by the profile function $phi sub i$. The usual choise of profile
+model for centering is a Gaussian. Howver in the interests of speed a triangle
+function has been substituted. This causes at most a 7% increase in the
+random centering error.
+.IP 3.
+The startup procedure is based on the following fact.
+.nf
+
+	$PSI (x sub n )~>~0~~for~~ x sub n ~<~ x sub c$
+
+	$PSI (x sub n ) ~<~0~~for~~ x sub n ~>~ x sub c$
+
+.fi
+The iteration is initialized by assuming that $x sub 1$ = $x sub c$ and
+computing $PSI (x sub 1 )$. The initial x 
+value is incremented by $+- sigma sub Gauss$ depending on the sign of $PSI$. The
+search is repeated until $PSI (x sub {n-1})$ and $PSI (x sub n)$ have
+opposite signs. At this point the true center is bracketed by the
+estimated positions $(x sub n, ~ x sub {n-1})$ and we have a table of at
+least 2 values of $PSI (x sub n )$.
+.IP 4.
+The computation proceeds by interpolating in the table of values for the
+estimated position $x sub {n+1}$ where $PSI$ = 0. If the table contains only
+two values as may be the case for the inititial interpolation, linear
+interpolation is used. In all other cases a quadratic fit to the three
+most recent $PSI$ values is used. The computation is complete when
+two successive estimates differ by less than some tolerance typically
+0.001 pixel.
+.IP 5.
+The errors are estimated as follows.
+.nf
+
+    $sigma sup 2 ~=~ ( {int {( partial phi ~/~ partial x sub c )} sup 2 over {
+    phi + b}} ) sup -1$
+
+    $err sub xc ~=~ sqrt {sigma sup 2}$
+
+.fi
+
+.NH 4
+Other Centering Methods
+.PP
+The code is constructed in such a way that new algorithms may be
+easily added at a future date, such as the more sophisticated techniques
+required for accurate astrometry.
+.EQ
+delim $$
+.EN
+.NH 3
+The FITSKY Task
+
+.NH 4
+Sky Fitting Routines
+
+.PP
+The following are the main entry points in the sky fitting package.
+.nf
+\f(CW
+         apsinit (ap, function, annulus, dannulus, fwhmpsf, noise)
+   ier = apfitsky (ap, im, xpos, ypos, sd, gd)
+   ier = aprefitsky (ap, sd, gd)
+ value = apstat[ir] (ap, param)
+         apstats (ap, param, str, maxch)
+         apset[irs] (ap, param, value)
+         apsfree (ap)
+\fR
+.fi
+.PP
+The following quantities can be examined or set with apset/apstat calls.
+.nf
+\f(CW
+data             1. fwhmpsf     full width half maximum of the psf
+parameters       2. sigma       standard deviation of sky pixels
+
+sky fitting      1. annulus     inner radius of sky annulus in fwhmpsf
+parameters       2. dannulus    outer radius of sky annulus in fwhmpsf
+                 3. sfunction   sky fitting algorithm
+                 4. smaxiter    maximum number of fitting iterations
+                 5. kreject     k-sigma rejection limit sigma
+                 6. nreject     maximum number of rejection cycles
+                 7. rgrow       region growing radius in fwhmpsf
+
+                 8. khist       half-wdth of histogram in sigma
+                 9. binsize     binsize of histogram in sigma
+                 10.smooth      Lucy smooth the histogram
+
+                 11.skyfile     name of text file containing sky values
+                 12.skyvaluser  supplied constant value for sky
+\fR
+.fi
+.PP
+The following computed quantities can only be examined with apstat calls.
+.nf
+\f(CW
+              1. skymode           computed sky value
+              2. skysig            computed sky sigma
+              3. skyskew           computed sky skew
+              4. nsky              number of sky pixels
+              5. nsky_reject       number of rejected sky pixels   
+\fR
+.fi
+
+.NH 4
+The Sky Fitting Algorithms
+.PP
+A good background fit is essential to aperture photometry.  Fitting
+the background is trivial in a sparse field, but difficult in a crowded
+field.  In general the background region will contain contaminating objects
+which must be detected and excluded if a good fit is to be obtained.
+.PP
+The main algorithm used in APPHOT is the following.
+.IP 1.
+If the skyfitting switch is disabled either read the sky values from a text
+file or accept a user supplied constant for the sky.
+.IP 2.
+Perform the initial sky fit using one of the specified algorithms. The
+sky fitting algorithms fall into three general categories, those that use
+the actual sky pixel array itself, those that operate on a histogram of
+sky values and those that rely on user interaction.
+.IP 3.
+If the pixel rejection flags are set perform pixels rejection with optional
+region growing.
+
+.NH 4
+Sky Pixel Array Techniques
+
+.NH 5
+Median
+.IP 1.
+Sort the array of sky pixels. This is necessary to avoid quantization effects.
+.IP 2.
+Compute the median, and the standard deviation and skew with respect to the
+mean.
+.IP 3.
+If the k-sigma rejection limit is greater than zero and the maximum number
+of rejection cycles is greater than one, perform pixel rejection.
+Pixels greater than k-sigma from the median are rejected. Region growing
+is optional.
+.IP 4.
+Stop the rejection cycle on any given iteration if the maximum number of
+rejection cycles ix exceeded, no more sky pixels are left or no more
+pixels are rejected.
+
+.NH 5
+Mode
+.IP 1.
+Sort the array of sky pixels. This is necessary to avoid quantization effects.
+.IP 2.
+Compute the mode, and the standard deviation and skew
+with respect to the mean.
+.nf
+
+	$I sub mode ~=~ 3.0 ~*~ I sub median ~-~ 2.0 ~*~ I sub mean$
+
+.fi
+.IP 3.
+If the k-sigma rejection limit is greater than zero and the maximum number
+of rejection cycles is greater than one, perform pixel rejection.
+Pixels greater than k-sigma from the mode are rejected. Region growing
+is optional.
+.IP 4.
+Stop the rejection cycle on any given iteration if the maximum number of
+rejection cycles ix exceeded, no more sky pixels are left or no more
+pixels are rejected.
+
+
+.NH 4
+Histogram Techniques
+.PP
+The following three techniques all operate on the histogram of the sky pixels.
+The routines all construct the histogram in the following identical manner.
+.IP 1.
+The mean of the sky distribution is computed.
+.IP 2.
+If the user specified standard deviation of the sky pixels is INDEF the
+algorithm computes the standard deviation of the sky pixels with respect
+to the mean.
+.IP 3.
+All pixels within plus or minus sigma standard
+deviations are accumulated into a histogram. The user specifies the bin size.
+.IP 4.
+The histogram may optionally be Lucy smoothed before any operation is performed
+on it.
+
+.NH 5
+Centroid
+.PP
+The mode, sigma and skew of the sky pixels are computed in the following
+manner.
+.IP 1.
+The histogram is compiled as above.
+.IP 2.
+The mode, standard deviation and skew of the sky pixels are computed in the
+following manner.
+
+.nf
+    $I sub 0 ~=~ sum I sub i$
+    $I sub 1 ~=~ sum I sub i ~ x sub i$
+    $I sub 2 ~=~ sum I sub i ~ x sub i sup 2$
+    $I sub 3 ~=~ sum I sub i ~ x sub i sup 3$
+
+    $I sub mode ~=~ {I sub 1} ~/~ {I sub 0}$ 
+    $sigma ~=~ {( I sub 2 ~/~ I sub 0 ~-~ I sub mode sup 2 )} sup {1/2}$
+    $skew ~=~ ( {I sub 3 ~/~ I sub 0 ~-~ I sub mode ~*~ sigma sup 2 ~-~ I sub mode sup 3} ) sup {1/3}$
+
+.fi
+.IP 3
+If pixel rejection is enabled sky pixels within a user supplied limit of
+the mode are rejected with optional region growing.
+
+.NH 5
+Gaussian Fit
+.PP
+The mode, standard deviation and skew of the sky pixels are derived from a
+model fit in the following way.
+.IP 1.
+The histogram of the sky pixels is compiled as above. 
+.IP 2.
+Initial guesses to the model parameters, $N sub max$, $I sub mode$,
+$sigma$, and $skew$ are made from the histogram itself.
+.IP 3.
+Final parameters and their errors are derived using non-linear least squares
+techniques and the NLFIT package.
+.IP 4.
+If pixel rejection is enabled sky pixels within a user supplied limit of
+the computed mode are rejected with optional region growing.
+
+.NH 5
+Optimal Filtering
+.PP
+The method is as follows.
+.IP 1.
+The histogram is compiled as above.
+.IP 2.
+Using the mean of the sky pixels as the intital value of the sky mode,
+a new mode is computed using the optimal filtering technique
+described for centering.
+.IP 4
+If pixel rejection is enabled sky pixels within a user supplied limit of
+the computed mode are rejected with optional region growing.
+
+.NH 5
+Cross Correlation
+.PP
+The method is as follows.
+.IP 1.
+The histogram is compiled as above.
+.IP 2.
+The noise function is estimated using the standard deviation of the sky
+pixels and the cross-correlation function is computed.
+.IP 3.
+The mode is computed using quadratic interpolation around the peak of the
+distribution.
+.IP 4
+If pixel rejection is enabled sky pixels within a user supplied limit of
+the mode are rejected with optional region growing.
+
+.NH 4
+Interactive Techniques
+
+.NH 5
+Histogram Plot
+.PP
+The histogram is compiled as described above and the user marks the peak
+on the histogram plot with the graphics cursor. The sigma and skew of the
+sky distribution with respect to the mean is also computed.
+
+.NH 5
+Radial Distribution
+.PP
+A radial profile plot of the sky region is plotted and the user marks the
+sky value on the plot with the graphics cursor. The sigma and skew of the sky
+distribution with respect to the mean is computed.
+
+.NH 4
+Pixel Rejection and Region Growing
+.PP
+All the sky fitting algorithms permit pixel rejection and
+optional region growing.
+Pixel rejection  and region growing are
+performed by locating all pixels more than k * sigma from the mode,
+and blindly rejecting all pixels within a certain radius of each deviant
+pixel.  This simple algorithm works well because the sample is large,
+and therefore there is little penalty for discarding pixels that might
+not be deviant.  Region growing also tends to accelerate convergence
+significantly.
+.PP
+Very faint contaminating objects are difficult to detect and reject.
+If there are enough such objects, they should not be rejected, because
+there are probably a few in the object aperture as well.  A higher sky
+sigma will be calculated and the computed uncertainty in the magnitude
+will increase.  The best solution to this problem may be to increase
+the size of the annulus to minimize the bias.
+
+.NH 4
+The Principal PHOT Routines
+.PP
+The main entries in the photometry routine are the following.
+.nf
+\f(CW
+               apinit (ap, cfunction, cbox, sfunction, annulus, dannulus,
+                aperts, napert, fwhmpsf, noise)
+         ier = apfitcenter (ap, im, xinit, yinit)
+         ier = aprefitcenter (ap)
+         ier = apfitsky (ap, im, xcenter, ycenter, sd, gd)
+         ier = aprefitsky (ap, sd, gd)
+         ier = apmag (ap, im, xcenter, ycenter, skyval, skysig, nsky)
+         ier = apwmag (ap, im, xcenter, ycenter, positive, skyval, skysig,
+                nsky)
+         ier = apremag (ap, positive, skyval, skysig, nsky)
+         ier = apwremag (ap, positive, skyval, skysig, nsky)
+       value = apstat[ir] (ap, param)
+               apstats (ap, param, str, maxch)
+               apset[sir] (ap, param, value)
+               apfree (ap)
+
+\fR
+.fi
+.PP
+The following parameters can be examined or altered by apset/apstat calls.
+.nf
+\f(CW
+                1. weighting        weighting scheme for wphot
+                2. aperts           list of apertues
+                3. naperts          number of apertures
+                4. zmag             zero point of magnitude scale
+                5. itime            effective integration time
+\fR
+.fi
+.PP
+The following quantities can be examined with apstat calls.
+.nf
+\f(CW
+
+                1. sums            array of aperture sums
+                2. areas            array of areas
+                3. mags             array of magnitudes
+                4. magerrs          array of magnitude errors
+
+\fR
+.fi
+
+.NH 4
+The PHOT Aperture Integration Algorithm
+.PP
+The integral of the flux within a circular aperture is computed by
+fractional pixel techniques.  Pixels are assumed to be square apertures
+arranged in a rectangular grid.  The fraction of a pixel which lies within
+the circular APPHOT aperture is computed by an approximation, and all
+such contributions are summed to produce the total integral.
+.PP
+The inclusion of a partial pixel inside the aperture is done as follows.
+.IP 1.
+If the distance of the current pixel from the center of the star, r, is
+exactly equal to the radius of the aperture R then one-half the counts in
+the pixel are included.
+.IP 2.
+If r < R - 0.5 the entire pixel is included while if r > R + 0.5 the pixel
+is wholly excluded.
+.IP 3.
+In between the fraction of the counts varies linearly. A circular aperture
+is approximated by an irregular polygon.
+.PP
+The simplicity of aperture photometry limits the amount of information
+available for error analysis.  The following three sources of error are
+considered.
+.IP 1.
+The error due to sky noise in the aperture.
+.nf
+
+	$error sub 1 ~=~ sigma sub sky ~*~ {A sub apert} sup {1/2}$
+
+.fi
+.IP 2.
+The error in the aperture sum.
+.nf
+
+	$error sub 2 ~=~ ( {A sub "sum"  ~/~ phpadu} ) sup {1/2}$ 
+
+.fi
+.IP 3.
+The mean error of the sky.
+.nf
+
+	$error sub 3 ~=~ sigma sub sky ~*~ A sub apert ~/~ nsky sup {1/2}$
+
+
+.fi
+where $sigma sub sky$ is either computed by the background fitting
+algorithm or set by the user,
+and $A sub apert$ is the fractional pixel area of the
+aperture.
+
+.NH 4
+The WPHOT Algorithm
+.PP
+The WPHOT algorithm computes a weighted aperture sum in an attempt to
+minimize noise in the sky. The algorithm is the following where w is
+the weight for each pixel, p is the noise free profile value and 
+$sigma$ is the noise per pixel from all sources. (See the paper
+by Stover and Allen 1987 for details)
+.nf
+
+	$A sub sum ~=~ sum {w sub i ~*~ (I sub i ~-~ sky)}$
+
+	$w sub i ~=~ C ~*~ p sub i ~/~ sigma sup 2 sub i$
+
+	$C ~=~ sum {p sub j} / sum {p sub j ~*~ w sub j}$
+.fi
+
+.NH 4
+The POLYPHOT ROUTINES
+.PP
+The principal polyphot routines are the following.
+
+.nf
+.na
+\f(CW
+               apyinit (ap, sfunction, annulus, dannulus, noise)
+         ier = apfitcenter (ap, im, wx, wy)
+         ier = aprefitcenter (ap)
+         ier = apfitsky (ap, im, xcenter, ycenter, sd, gd)
+         ier = aprefitsky (ap, sd, gd)
+         ier = polyfit (ap, im, xver, yver, nver)
+       value = apstat[ir] (ap, param)
+               apstats (ap, param, str, maxch)
+               apset[sir] (ap, param, value)
+               apfree (ap)
+
+\fR
+.ad
+.fi
+
+.PP
+.NH 4
+The POLYPHOT Algorithm 
+.PP
+The function of the POLYPHOT task is to compute the flux inside an
+irregular polygon given a list of the coordinates of the vertices of a polygon.
+The polygon must be entirely inside the image and the vertices of the polygon
+must be specified in clockwise or counterclockwise order.
+The actual algorithm used is as follows.
+.IP 1.
+The range of image lines which intersect the polygon are computed.
+.IP 2.
+For each image line in the specified range the intersection points with the
+polygon are computed.
+.IP 3.
+The flux between pairs of limits is summed using a fractional pixel
+approximation for the endpoints.
+.IP 4.
+The sky is fitted using any of the methods previously discussed and a
+user specified annular region.
+.IP 5.
+The errors are computed as specified in the PHOT specifications.
+.PP
+.EQ
+delim $$
+.EN
+
+.NH
+Example
+.PP
+A brief example may help illustrate the use of the package.  Suppose
+we want to process a few hundred stars on image "blue".
+.PP
+The first step is to prepare a list of objects to be measured.  The simplest
+way to do this is to interactively mark the objects with the image
+cursor using the display (graphics) device and the RIMCURSOR (RGCURSOR)
+task.
+.nf
+\f(CW
+
+	... load image on the display ...
+
+	ap> rimcursor > starlist
+
+	    ... move cursor and mark stars ...
+
+
+	... load contour plot on graphics terminal ...
+
+	ap> rgcursor > starlist
+
+	    ... move cursor and mark stars ...
+\fR
+.fi
+
+Alternatively one can run DAOFIND to compute a list of candidate objects
+in the frame.
+The name of the coordinate file is stored in the PHOT parameter set.
+
+.nf
+\f(CW
+	ap> phot.coords=starlist
+\fR
+.fi
+
+.PP
+The next step is to set up the PHOT parameters interactively.
+First we load the image (contour plot) blue on the display (graphics
+terminal). Next we call up PHOT in interactive mode.
+
+.nf
+\f(CW
+	ap> phot blue
+	... cursor appears ...
+
+\fR
+.fi
+
+.PP
+PHOT takes input by reading the image (graphics)
+display (terminal) cursor. In order to display the available commands
+we tap the ? key and the following text appears on the screen.
+
+.nf
+\f(CW
+	Interactive Phot Commands
+
+?	Print options
+:	Colon command see below
+i	Setup PHOT parameters interactively
+w	Write PHOT parameters to the parameter files
+l	Process the remainder of the coordinate list
+r	Rewind the coordinate list
+c	Fit center around the current cursor position
+t	Fit sky around the current cursor position
+s	Fit sky around the current center position
+p	Compute magnitudes around the cursor position
+f	Fit center, sky and compute magnitudes
+sp	Fit center, sky, compute magnitudes, and save
+q	Exit program
+
+Phot parameters are listed or set with the following commands.
+
+:m [n]	Move cursor to the [nth] object in the coordinate list
+:n [n]	Measure the [nth] object in the coordinate list
+
+:show [center/sky/phot/all]    List the aphot parameters
+:fwhmpsf [value]               Full width half maximum of the PSF
+:noise [string]                Noise model
+:threshold [value]             Threshold value for centering
+:sigma [value]                 Standard deviation of the background
+:ccdread                       CCD readout noise keyword
+:readnoise                     Readout noise in electrons
+:gain                          Gain keyword
+:epadu                         Electrons per adu
+
+:calgorithm [string]           Centering function
+:positive [y/n]                Emission or absorption feature
+:cbox [value]                  Width of the centering box in fwhmpsf
+:cmaxiter [value]              Maximum number of centering iterations
+:maxshift [value]              Maximum shift in fwhmpf
+:minsnratio [value]            Minimum signal to noise ratio of pixels
+:clean [y/n]                   Clean subraster before centering
+:rclip [value]                 Clipping radius in fwhmpsf
+:rclean [value]                Cleaning radius in fwhmpsf
+:kclean [value]                Sigma for clean algorithm
+:mkcenter [y/n]                Mark the centers on the display
+
+:salgorithm [string]           Sky fitting algorithm
+:annulus [value]               Inner radius of sky annulus in fwhmpsf
+:dannulus [value]              Width of sky annulus in fwhmpsf
+:skyvalue [value]              User supplied sky
+:smaxiter [value]              Maximum number of rejection cycles
+:skreject [value]              +/- Pixel rejection limits in sky sigma
+:snreject [value]              Maximum number of rejection interations
+:khist [value]                 +/- Sky histogram size in sky sigma
+:binsize [value]               Resolution of sky histogram in sky sigma
+:smooth [y/n]                  Lucy smooth the sky histogram
+:rgrow [value]                 Region growing radius in fwhmpsf
+:marksky [y/n]                 Mark the sky annuli on the display
+
+:weighting                     Weighting for wphot
+:aperts [string]               Aperture radii in fwhmpsf
+:zmag [value]                  Zero point of magnitude scale
+:exposure [string]             Exposure time keyword
+:itime [value]                 Integration time
+\fR
+.fi
+
+.PP
+We select the interactive setup option, move the image
+cursor to a high signal-to-noise, isolated star and tap the i key.
+PHOT responds by plotting the radial profile of the star on the
+screen and requesting the user to mark the fwhm of
+the psf, the centering aperture, the inner and outer sky annuli,
+the sky background and sigma and the set of circular apertures.
+The parameters so set can be examined and/or reset with the : commands as shown
+above. Sample measurements can be made of several stars by moving the
+cursor and typing the f command. Finally when we are happy with the
+parameter set we type w to store the parameters and q to exit the program.
+.PP
+Now we are ready to do photometry. We enter the PHOT program in batch mode.
+
+.nf
+\f(CW
+	ap> phot blue inter- &
+\fR
+.fi
+
+The batch job is now running, appending output lines to the file "blue.mag.#".
+We can proceed to set up the job for the red image, in much the same way
+that we set up the job for the blue image.  When both jobs finish, we
+can use the list processing tools to filter out the good objects and
+calculate colors.
+
+.NH
+The APPHOT Tasks
+.PP
+Manual pages for the APPHOT tasks are available in the IRAF on line help
+database.
diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc.toc b/noao/digiphot/apphot/doc/specs/apphot.spc.toc
new file mode 100644
index 00000000..757f9a79
--- /dev/null
+++ b/noao/digiphot/apphot/doc/specs/apphot.spc.toc
@@ -0,0 +1,111 @@
+.LP
+.sp
+1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01
+.sp
+2.\h'|0.4i'\fBAPPHOT Package Requirements\fP\l'|5.6i.'\0\01
+.br
+\h'|0.4i'2.1.\h'|0.9i'APPHOT Package Input\l'|5.6i.'\0\01
+.br
+\h'|0.9i'2.1.1.\h'|1.5i'The IRAF Image\l'|5.6i.'\0\01
+.br
+\h'|0.9i'2.1.2.\h'|1.5i'The Coordinate Lists\l'|5.6i.'\0\02
+.br
+\h'|0.9i'2.1.3.\h'|1.5i'Algorithm Parameters\l'|5.6i.'\0\02
+.br
+\h'|0.9i'2.1.4.\h'|1.5i'Terminal Graphics and the Image Display\l'|5.6i.'\0\02
+.br
+\h'|0.4i'2.2.\h'|0.9i'APPHOT Package Functions\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.1.\h'|1.5i'Creating Coordinate Lists\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.2.\h'|1.5i'Coordinate List Operations\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.3.\h'|1.5i'Determining the Image Characteristics\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.4.\h'|1.5i'Centering\l'|5.6i.'\0\03
+.br
+\h'|0.9i'2.2.5.\h'|1.5i'Fitting the Sky\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.2.6.\h'|1.5i'Multi-aperture Photometry\l'|5.6i.'\0\04
+.br
+\h'|0.9i'2.2.7.\h'|1.5i'Polygonal Aperture Photometry\l'|5.6i.'\0\04
+.sp
+3.\h'|0.4i'\fBAPPHOT Package Specifications\fP\l'|5.6i.'\0\04
+.br
+\h'|0.4i'3.1.\h'|0.9i'Apphot CL Callable Tasks\l'|5.6i.'\0\04
+.br
+\h'|0.4i'3.2.\h'|0.9i'Standard Analysis Procedures\l'|5.6i.'\0\05
+.br
+\h'|0.4i'3.3.\h'|0.9i'The APPHOT Algorithms\l'|5.6i.'\0\05
+.br
+\h'|0.9i'3.3.1.\h'|1.5i'The RADPROF Algorithm\l'|5.6i.'\0\05
+.br
+\h'|0.9i'3.3.2.\h'|1.5i'The FITPSF Algorithm\l'|5.6i.'\0\06
+.br
+\h'|0.9i'3.3.3.\h'|1.5i'The DAOFIND Algorithm\l'|5.6i.'\0\06
+.br
+\h'|0.9i'3.3.4.\h'|1.5i'The CENTER Algorithm\l'|5.6i.'\0\08
+.br
+\h'|1.5i'3.3.4.1.\h'|2.2i'Centering Package Routines\l'|5.6i.'\0\08
+.br
+\h'|1.5i'3.3.4.2.\h'|2.2i'The General Centering Procedure\l'|5.6i.'\0\09
+.br
+\h'|1.5i'3.3.4.3.\h'|2.2i'Symmetry Clean Algorithm\l'|5.6i.'\010
+.br
+\h'|1.5i'3.3.4.4.\h'|2.2i'Signal to Noise Estimate\l'|5.6i.'\010
+.br
+\h'|1.5i'3.3.4.5.\h'|2.2i'Centroid\l'|5.6i.'\010
+.br
+\h'|1.5i'3.3.4.6.\h'|2.2i'Gaussian Fit to the Marginals\l'|5.6i.'\011
+.br
+\h'|1.5i'3.3.4.7.\h'|2.2i'Radial Gaussian Fit to the Subraster\l'|5.6i.'\011
+.br
+\h'|1.5i'3.3.4.8.\h'|2.2i'Optimal Filtering of Marginals\l'|5.6i.'\011
+.br
+\h'|1.5i'3.3.4.9.\h'|2.2i'2D Optimal Filtering\l'|5.6i.'\012
+.br
+\h'|1.5i'3.3.4.10.\h'|2.2i'Other Centering Methods\l'|5.6i.'\012
+.br
+\h'|0.9i'3.3.5.\h'|1.5i'The FITSKY Task\l'|5.6i.'\013
+.br
+\h'|1.5i'3.3.5.1.\h'|2.2i'Sky Fitting Package Routines\l'|5.6i.'\013
+.br
+\h'|1.5i'3.3.5.2.\h'|2.2i'General Sky Fitting Procedures\l'|5.6i.'\014
+.br
+\h'|1.5i'3.3.5.3.\h'|2.2i'Sky Pixel Array Techniques\l'|5.6i.'\014
+.br
+\h'|2.2i'3.3.5.3.1.\h'|2.9i'Mean\l'|5.6i.'\014
+.br
+\h'|2.2i'3.3.5.3.2.\h'|2.9i'Median\l'|5.6i.'\014
+.br
+\h'|2.2i'3.3.5.3.3.\h'|2.9i'Mode\l'|5.6i.'\015
+.br
+\h'|1.5i'3.3.5.4.\h'|2.2i'Histogram Techniques\l'|5.6i.'\015
+.br
+\h'|2.2i'3.3.5.4.1.\h'|2.9i'Centroid\l'|5.6i.'\015
+.br
+\h'|2.2i'3.3.5.4.2.\h'|2.9i'Gaussian Fit\l'|5.6i.'\016
+.br
+\h'|2.2i'3.3.5.4.3.\h'|2.9i'Optimal Filtering\l'|5.6i.'\016
+.br
+\h'|2.2i'3.3.5.4.4.\h'|2.9i'Cross Correlation\l'|5.6i.'\016
+.br
+\h'|1.5i'3.3.5.5.\h'|2.2i'Interactive Techniques\l'|5.6i.'\016
+.br
+\h'|2.2i'3.3.5.5.1.\h'|2.9i'Histogram Plot\l'|5.6i.'\016
+.br
+\h'|2.2i'3.3.5.5.2.\h'|2.9i'Radial Distribution\l'|5.6i.'\016
+.br
+\h'|1.5i'3.3.5.6.\h'|2.2i'Pixel Rejection and Region Growing\l'|5.6i.'\017
+.br
+\h'|0.9i'3.3.6.\h'|1.5i'The APPHOT Task\l'|5.6i.'\017
+.br
+\h'|1.5i'3.3.6.1.\h'|2.2i'The APPHOT Package Routines\l'|5.6i.'\017
+.br
+\h'|1.5i'3.3.6.2.\h'|2.2i'The APPHOT Aperture Integration Algorithm\l'|5.6i.'\018
+.br
+\h'|0.9i'3.3.7.\h'|1.5i'The POLYPHOT Algorithm \l'|5.6i.'\018
+.sp
+4.\h'|0.4i'\fBExample\fP\l'|5.6i.'\019
+.sp
+5.\h'|0.4i'\fBThe APHOT Tasks\fP\l'|5.6i.'\021