Initial commit

1 files changed, 1881 insertions, 0 deletions

diff --git a/noao/digiphot/apphot/doc/userdocs/apuser.ms b/noao/digiphot/apphot/doc/userdocs/apuser.ms
new file mode 100644
index 00000000..24492bcc
--- /dev/null
+++ b/noao/digiphot/apphot/doc/userdocs/apuser.ms
@@ -0,0 +1,1881 @@
+.RP
+
+.TL
+A User's Guide to the IRAF Apphot Package
+
+.AU
+Lindsey Elspeth Davis
+.AI
+
+.K2 "" "" "*"
+Revised May 1989
+
+.AB
+.PP
+The APPHOT package is a set of tasks for performing aperture photometry
+on uncrowded or moderately crowded stellar fields in either interactive or batch
+mode. The photometric technique employed is fractional pixel 
+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 and sky values for a list of objects,
+and performing photometry inside concentric
+circular or polygonal apertures.
+.PP
+This document describes the data preparation required to run APPHOT, how
+to set up the display and graphics devices, how to set the algorithm
+parameters, how to run the package tasks in interactive or batch mode
+and how to selectively examine the results. Detailed descriptions of the
+algorithms can be found in the document \fISpecifications for the
+APPHOT Package\fR by the author.
+.PP
+This document applies to APPHOT under IRAF version 2.8.  APPHOT
+can be run under IRAF versions 2.5, 2.6 and 2.7  with only minor changes in
+the task setup. These differences are documented
+where appropriate in the text.
+.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(s), an optional list(s) of object coordinates,
+numerous parameters controlling
+the analysis algorithms and, optionally, the graphics terminal and/or
+display. APPHOT output consists of successive records, where each record
+records the results of the analysis for a single object. Some tasks 
+also produce graphics output in the form of plot metacode files.
+.PP
+Given starting coordinates and an IRAF image, the principal APPHOT
+task \fBphot\fR 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.
+.PP
+The image data requirements of the APPHOT package are described in section 2.
+Section 3 describes various ways to tailor the IRAF environment to run
+the APPHOT package. Section 4 describes how to load the APPHOT tasks and how
+use the on-help facility.  Section 5 describes how to examine and edit the
+APPHOT task and algorithm parameters. Several methods of creating and
+modifying APPHOT coordinate lists files are described in section 6.
+Sections 7 and 8 describe how to run the APPHOT tasks interactively without
+and with a coordinate list respectively. Batch mode reductions in APPHOT are
+described in section 9.  Section 10 describes the format of the APPHOT output
+catalogue and plot files. Section 12 lists various APPHOT recipes for reducing
+common types of astronomical data with APPHOT.
+
+.NH
+Data Preparation and Requirements
+.PP
+APPHOT assumes that the images to be analyzed exist on disk in IRAF readable
+format.  Facilities for reading and writing images exist elsewhere in IRAF
+in the DATAIO and MTLOCAL packages. None of the current APPHOT
+tasks alter the disk input images in any way.
+.PP
+APPHOT assumes that the pixel data is linear. The input images should be
+corrected for those instrumental defects which affect the intensity
+of a pixel prior to entering the APPHOT package. These defects include pixel
+to pixel variations in the bias values,
+pixel to pixel gain variations, cosmic rays, cosmetic defects, geometric
+distortion and detector non-linearities. Users should be aware of the IRAF
+CCDRED package for reducing CCD data and the DTOI package for converting
+photographic density data to intensity data.
+.PP
+Extreme valued pixels should be removed from the images prior to entering
+the APPHOT package. These include pixel values at or near the data limits of the
+host machine as well as any host machine values such as INDEF,
+produced by divide by zero, and floating point underflows and overflows.
+Floating point operations involving such numbers may crash
+with arithmetic exception errors. For efficiency and portability reasons
+the APPHOT package and most IRAF routines do not test for these numbers.
+The \fBimreplace\fR and \fBimedit\fP tasks in the PROTO  package can be used to replace extreme
+valued pixels.  More general system facilities for handling bad pixels
+inside IRAF are planned for the near future.
+.PP
+In order to normalize the magnitude scales of a list of images to a common
+integration time,
+APPHOT requires that the image exposure times be stored in the image header.
+Similarly the correct computation of magnitude errors requires that
+the readout noise and gain parameters also be present in the image
+header or be supplied as constants in the APPHOT parameter files.
+The readout noise must be supplied in units of electrons and the gain
+is assumed to be in electrons per adu. The time units are arbitrary
+but must be consistent for a given set of images.
+APPHOT tasks access this information using a keyword and value scheme.
+The IMAGES package task \fBhedit\fR can be used to insert or edit this
+information prior to entering the APPHOT package. For example the following
+commands will enter the gain, readout noise and exposure time information
+into the headers of a list of images.
+
+.nf
+	\f(CWcl> hedit *.imh gain 14.0 add+ ver-
+	cl> hedit *.imh readout 20.0 add+ ver-
+	cl> hedit *.imh exptime add+ ver+\fR
+.fi
+
+.PP
+The point spread function is assumed to be constant for all regions
+of the image. This is 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 object and invariant to magnitude.
+.PP
+The centering routines built into the APPHOT package  assume that
+the images are close to circularly symmetric over the region to be used
+in centering although small deviations do not
+significantly affect the accuracy of the results.
+The user should be aware of the more sophisticated 
+but less efficient centering routines in the \fBdaofind\fR and \fBfitpsf\fR
+routines. Several choices of centering algorithm are available in
+APPHOT including  no centering.
+.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 the APPHOT package.
+
+.NH
+Setting up the IRAF Environment for APPHOT
+.NH 2
+Script, Compiled and Pset Tasks
+.PP
+IRAF supports three types of tasks: scripts, compiled tasks and pset tasks.
+In order to distinguish one type of task from another, APPHOT users should 
+set the cl parameter \fBshowtype\fR to yes as shown below.
+
+.nf
+	\f(CWcl> cl.showtype=yes\fR
+.fi
+
+The cl command \fB?\fR or \fB?\fR \fIpackage\fR identifies script
+tasks by a terminating period and pset tasks by a terminating @.
+No trailing characters are added to the compiled task names. Pset tasks are
+important to the APPHOT package and will be discussed further in
+section 5.
+
+.NH 2
+Other IRAF Packages
+.PP
+Before running APPHOT, users may wish to load the IRAF packages, DATAIO,
+IMAGES, 
+TV and PLOT. Various input and output routines exist in the DATAIO package,
+including the fits reader and writer and the cardimage reader and
+writer. The IMAGES package contains routines for basic image arithmetic,
+for computing image statistics, for listing individual pixel values,
+and for examining and
+modifying the image headers. TV, a subpackage of IMAGES, contains the
+\fBdisplay\fR task for loading images into the display device.
+The PLOT package contains tasks for plotting
+image data and for extracting and displaying individual plots from the plot
+metacode files produced by the APPHOT tasks.
+.PP
+Various useful tasks for manipulating and displaying the data produced by
+APPHOT can be found in the PROTO package under the NOAO package. In
+particular the user should be aware of the \fBfields\fR, \fBmkhistogram\fR
+and \fBtvmark\fP tasks.
+
+.NH 2
+The Image Cursor and Display Device
+.PP
+The APPHOT tasks are designed in interactive mode to read the image cursor
+and to perform various actions based on the position of the image cursor
+and the keystroke typed. The image cursor is directed to the display
+device defined by the environment variable \fBstdimage\fR. To check the
+value of the default display device, type the following command.
+
+.nf
+	\f(CWcl> show stdimage
+	imt512\fR
+.fi
+
+In this example the default display device is the 512 pixel square SUN
+imtool window.
+All tasks which write images to the display access this
+device. For example the
+TV package \fBdisplay\fR program will load an image onto this device.
+.PP
+In normal operation IRAF tasks which read the image cursor would read
+the hardware cursor from this device.
+In response to the user command
+
+.nf
+	\f(CWcl> =imcur
+	or
+	cl> show imcur\fR
+.fi
+
+the cursor would come up on the image display ready to accept a
+keystroke command.  At this point the user should check that the display
+is reading the correct image coordinates by moving the image cursor to
+the lower left hand corner of the display image and tapping any key.
+The coordinates should read x,y = (1,1) if the whole image was
+displayed.
+.PP
+Cursor readback is currently implemented under IRAF version 2.7 for the
+SUN workstations and the IIS model 70. Users with older versions of IRAF
+or other devices cannot run APPHOT tasks directly from the image display
+device and must redirect the image cursor.
+Two choices are available.
+.IP [1]
+The image cursor can be directed to accept commands from
+the standard input. This is the default setup under IRAF version 2.6.
+This setup can be checked by typing the following command.
+
+.nf
+	\f(CWcl> show stdimcur
+	text\fR
+.fi
+
+If the value of \fBstdimcur\fR is not "text" the user can set this value by
+typing the following.
+
+.nf
+	\f(CWcl> set stdimcur = text\fR
+.fi
+
+Each time the cursor is to be read the user will be prompted for image
+cursor mode text input. The form and syntax of this command are
+described in detail in section 7.3.
+.IP [2]
+Alternatively a contour plot of the image can be used in place of the
+image display and APPHOT tasks can be directed to read the graphics cursor.
+To direct the image cursor to the graphics device the user types
+
+.nf
+	\f(CWcl> set stdimcur = stdgraph\fR
+.fi
+
+This usage permits interactive use of the APPHOT package for users with graphics
+terminals but no image display. This setup is most suitable for terminals
+which permit the text and graphics planes to be displayed simultaneously.
+.RS
+.LP
+It is currently the responsibility of the user to ensure that the image
+displayed on the image display is the same as the image operated on by
+the APPHOT tasks.
+.RE
+
+.NH
+Loading the Apphot Package
+.PP
+At this point the user has the local environment set up and is ready to
+load the APPHOT package.  APPHOT resides in the DIGIPHOT package (IRAF
+version 2.8 and later) under the NOAO suite of packages.
+Assuming
+that the NOAO package is already loaded the user types the following.
+
+.nf
+	\f(CWcl> digiphot
+	cl> apphot\fR
+.fi
+
+APPHOT can also be an add-on package (IRAF version 2.7 and earlier) 
+installed under the
+LOCAL package. In this case the user types.
+
+.nf
+	\f(CWcl> local
+	cl> apphot\fR
+.fi
+
+The following menu of tasks is displayed.
+
+.nf
+\f(CW
+  apselect      daofind     fitsky        photpars@   polyphot   wphot
+  center        datapars@   fitskypars@   polymark    qphot    
+  centerpars@   fitpsf      phot          polypars@   radprof
+\fR
+.fi
+
+The APPHOT package is now loaded and ready to run.
+A quick one line description of each APPHOT task can be obtained by typing
+the following command.
+
+.nf
+	\f(CWap> help apphot\fR
+.fi
+
+The following text appears.
+.KS
+.nf
+\f(CW
+digiphot.apphot:
+       apselect - Extract select fields from apphot output files
+         center - Compute accurate centers for a list of objects
+     centerpars - Edit the centering parameters
+        daofind - Find stars in an image using the DAO algorithm
+       datapars - Edit the data dependent parameters
+         fitpsf - Model the stellar psf with an analytic function
+         fitsky - Compute sky values in a list of annular or circular
+                  regions
+     fitskypars - Edit the sky fitting parameters
+           phot - Measure magnitudes for a list of stars
+       photpars - Edit the photometry parameters
+       polymark - Create polygon and coordinate lists for polyphot
+       polyphot - Measure magnitudes inside a list of polygonal regions
+       polypars - Edit the polyphot parameters
+          qphot - Measure quick magnitudes for a list of stars
+        radprof - Compute the stellar radial profile of a list of stars
+          wphot - Measure magnitudes with weighting
+\fR
+.fi
+.KE
+For the remainder of this document
+we will use the principal APPHOT task \fBphot\fR as an example of how to
+setup the parameters in both interactive and batch mode.
+To get detailed help  on the phot task the user types the following.
+
+.nf
+	\f(CWcl> help phot | lprint\fR
+.fi
+
+The help page(s) for the \fBphot\fR task will appear on the local default
+printer.
+
+.NH
+Setting the APPHOT Photometry Task Parameters
+.PP
+The principal APPHOT task PHOT is described in sections 5.1 to 5.6.  The
+quick photometry task QPHOT is described in section 5.7 and the
+polygonal aperture photometry task POLYPHOT is described in section
+5.8.
+.NH 2
+The Task Parameters
+.PP
+The \fBphot\fR task parameter set specifies the required image, coordinate
+and output files, the graphics and display devices, the graphics and image
+cursor and the mode of use of the task, interactive or batch. To enter
+and edit the parameter set for the \fBphot\fR task the user types the
+following.
+
+.nf
+	\f(CWcl> epar phot\fR
+.fi
+
+The parameter set for the \fBphot\fR task will appear on the terminal ready
+for editing as follows.
+
+.nf
+\f(CW
+                             IRAF
+             Image Reduction and Analysis Facility
+
+   PACKAGE = apphot
+   TASK = phot
+   
+   image   =                       Input image
+   (datapar=                     ) Data dependent parameters
+   (centerp=                     ) Centering parameters
+   (fitskyp=                     ) Sky fitting parameters
+   (photpar=                     ) Photometry parameters
+   (coords =                     ) Coordinate list
+   skyfile =                       Sky file
+   (output =              default) Results file
+   (plotfil=                     ) File of plot metacode
+   (graphic=             stdgraph) Graphics device
+   (display=             stdimage) Display device
+   (command=                     ) Image cursor: [x y wcs] key [cmd]
+   (cursor =                     ) Graphics cursor: [x y wcs] key [cmd]
+   (radplot=                   no) Plot the radial profiles
+   (interac=                  yes) Mode of use
+   (verify =                  yes) Verify critical parameters in non
+                                   interactive mode
+   (verbose=                   no) Print messages in non interactive mode
+   (mode   =                   ql)
+\fR
+.fi
+
+The \fBphot\fR parameters can be edited in the usual fashion by successively
+moving
+the cursor to the line opposite the parameter name, entering the new value,
+followed by a carriage return, and finally typing a ^Z to exit the
+\fBepar\fR task and update the parameters.
+Some general points about the task
+parameter sets are summarized below. For more detailed descriptions of each
+parameter see the help pages for each task.
+.IP [1]
+\fBImage\fR specifies the list of input image(s) containing the 
+stars to be measured. \fBImage\fR may be a list of images, an image
+template or a file containing a list of images.
+For example if we wish to measure stars in three images: m31U, m31B and
+m31V we could specify the \fBimage\fR parameter in the following three ways.
+
+.nf
+\f(CW
+   image   =       m31B,m31U,m31V  Input image
+	or
+   image   =             m31*.imh  Input image
+	or
+   image   =              @imlist  Input image
+\fR
+.fi
+
+"Imlist" is the name of a text file containing the list of images
+one image name per line. The image list file can easily be created with the cl
+package \fBfiles\fR task or the editor.
+.IP [2]
+Four parameter sets, henceforth psets, \fBdatapars\fR, \fBcenterpars\fR,
+\fBfitskypars\fR and \fBphotpars\fR specify the algorithm parameters.
+They are described in detail in later sections. 
+.IP [3]
+\fBCoords\fR specifies the name of the coordinate file(s) containing the
+initial positions of the stars to be measured. If \fBcoords\fR = "",
+the current image cursor position is read and used as the initial position.
+The number of files specified by
+\fBcoords\fR must be either one, in  which
+case the same coordinate file is used for all the images, or equal in
+number to the set of input images.
+\fBCoords\fR can be a list of files, a file name template,
+or a file
+containing the list of x and y coordinates one per line.
+For example if we have three coordinate files "m31B.coo", "m31U.coo" and
+"m31V.coo" for the three images listed above, we could set the \fBcoords\fR
+parameter in the following three ways.
+
+.nf
+\f(CW
+   (coords = m31B.coo,m31U.coo,m31V.coo) Coordinate list
+	or
+   (coords =             m31*.coo) Coordinate list
+	or
+   (coords =           @coordlist) Coordinate list
+\fR
+.fi
+
+"Coordlist" is the name of a text file containing the names of the coordinate
+files in the desired order one per line.
+.IP [4]
+\fBOutput\fR specifies the name of the results file(s). If \fBoutput\fR =
+"default" then a single output file is created for
+each input image and the root of the output file name is the name of the
+input image. In the case of the above example \fBphot\fR would create three
+output files called "m31B.mag.1", "m31U.mag.1" and "m31V.mag.1" assuming
+that this was the initial run of \fBphot\fR on these images.
+If the user sets the \fBoutput\fR parameter then the number of output files
+must be either one or equal to the number of input images. For example the
+user could set \fBoutput\fR to either
+
+.nf
+\f(CW
+   (output =              m31.out) Results
+   or
+   (output = m31b.out,m31u.out,m31v.out) Results
+\fR
+.fi
+
+If the user sets \fBoutput\fR = "" then no output file is written.
+.IP [5]
+The parameters \fBgraphics\fR and \fBdisplay\fR specify the graphics and
+image display devices. In IRAF version 2.6 and later the APPHOT tasks
+which reference these parameters will in interactive mode issue a warning
+if they cannot open either of these devices
+and continue execution. In IRAF version 2.5 the \fBdisplay\fR parameter must
+be set to "stdgraph" as listed below
+
+.nf
+\f(CW
+   (display=             stdgraph) Display device
+\fR
+.fi
+
+or the following system error will be generated.
+
+.nf
+\f(CW
+    "cannot execute connected subprocess x_stdimage.e"
+\fR
+.fi
+Most of the APPHOT tasks use IRAF graphics in interactive mode to allow
+users to set up their parameters and /or examine their results using radial
+profile plots. The \fBgraphics\fR specifies which graphics device these plots
+will be written to. Similarly most IRAF tasks permit the user to optionally
+mark the star positions, apertures and sky annuli on the display device.
+The parameter \fBdisplay\fR specifies which image display device this
+information will be written to. Currently IRAF does not support an image display
+kernel so the display marking features of APPHOT are not available unless
+the user chooses to run APPHOT interactively from a contour plot.
+.IP [6]
+If \fBplotfile\fR is not equal to "", then for each star written to
+\fBoutput\fR
+a radial profile plot is written to the plot metacode file \fBplotfile\fR.
+The \fBplotfile\fR is opened in append mode and succeeding executions
+of \fBphot\fR write to the end of the same file which may in the process
+become very large.
+\fIThe user should be aware that writing radial profile plots
+to \fBplotfile\fI can significantly slow the execution of \fBphot\fR.
+The variable \fBradplots\fR enables radial profile plotting in interactive mode.
+For each star measured a radial profile plot displaying the answers is
+plotted on the screen.
+.IP [7]
+The \fBinteractive\fR parameter switches the task between interactive
+and batch mode.
+In interactive mode plots and text are written to the terminal as well as the
+output file and the user can show and set the parameters. In batch mode
+\fBphot\fR executes silently.
+.IP [8]
+The \fBverify\fP parameter allows the user to verify the critical task
+parameters in non interactive mode.  It is normally set to yes but
+should be turned off when submitting jobs to background.
+.IP [9]
+The \fBverbose\fP switch permits the printing of results to the standard
+output in non interactive mode.  It is normally turned off.
+
+.NH 2
+APPHOT Psets
+.PP
+APPHOT algorithm parameters have been gathered together into logical
+groups and stored in parameter files. The use of psets permits the
+user to store APPHOT parameters with their relevant datasets rather than
+in the uparm directory and allows APPHOT tasks to share common parameter
+sets. APPHOT presently supports 5 pset files: 1) \fBdatapars\fR which contains
+the data dependent parameter 2) \fBcenterpars\fR which contains the
+centering algorithm parameters 3) \fBfitskypars\fR which contains the
+sky fitting
+algorithm parameters 4) \fBphotpars\fR which contains the multiaperture
+photometry parameters and 5) \fBpolypars\fR which contains the polygonal
+aperture
+photometry parameters. The user should consult the manual page for each
+of the named pset files as well as the attached parameter set document,
+\fIExternal Parameter Sets in the CL and Related Revisions\fR, by Doug Tody.
+.PP
+The default mode of running APPHOT is to edit and store the pset parameter
+files in the uparm directory.  For example to edit the
+\fBdatapars\fR parameter set, the user types either
+
+.nf
+	\f(CWcl> epar datapars\fR
+	or
+	\f(CWcl> datapars\fR
+.fi
+
+and edits the file as usual. All the top level tasks which reference this
+pset will pick up the changes from the uparm directory, assuming
+datapars = "".
+.PP
+Alternatively the user can edit the \fBphot\fR
+task and its psets all at once as follows using \fBepar\fR.
+
+.nf
+	\f(CWcl> epar phot\fR
+.fi
+
+Move the cursor to the \fBdatapars\fR parameter line and type \fB:e\fR.
+The menu for the 
+\fBdatapars\fR pset will appear and is ready for editing. Edit the desired
+parameters and type \fB:q\fR. \fBEpar\fR will return to the main
+\fBphot\fR parameter set.
+Follow the same procedure for the other three psets
+\fBcenterpars\fR, \fBfitskypars\fR and \fBphotpars\fR and exit the program
+in the usual manner.
+.PP
+Sometimes it is desirable to store a given pset along with the data.
+This provides a facility for keeping many different copies of say the
+\fBdatapars\fR pset with the data.
+The example below shows how to write a pset out to a file in the same directory
+as the data. The user types
+
+.nf
+	\f(CWcl> epar phot\fR
+.fi
+
+as before, enters the datapars menu with \f(CW:e\fR and edits the parameters.
+The command
+
+.nf
+	\f(CW:w data1.par\fR
+.fi
+
+writes the parameter set to a file called "data1.par" and a \fB:q\fR
+returns to the main task menu.
+A file called "data1.par" containing the new \fBdatapars\fR parameters
+will be written in the current directory. At this point the user is in the
+\fBphot\fR parameter set at the line opposite \fBdatapars\fR and
+enters "data1.par" on the line opposite this parameter.
+The next time \fBphot\fR is run the parameters will
+be read from "data1.par" not from the pset in the uparm directory.
+This procedure can be repeated for each data set which has distinct parameters,
+as in for example data taken on separate nights.
+
+.NH 2
+Datapars
+.PP
+All the data dependent parameters have been gathered together in one
+pset \fBdatapars\fR. The idea behind this organization is to facilitate
+setting up the algorithm
+psets for data taken under different conditions. For example the
+user may have determined the optimal centering box size, sky annulus radius
+and width and aperture radii in terms of the current \fBfwhmpsf\fR and the
+rejection criteria in terms of the current background standard deviation
+\fBsigma\fR.  In order to use the same setup on
+the next image the user need only reset the \fBscale\fR and background
+\fBsigma\fR parameters to the new values.
+The only pset which need be edited is \fBdatapars\fR.
+.PP
+To examine and edit the \fBdatapars\fR pset type
+
+.nf
+	\f(CWap> datapars\fR
+.fi
+
+and the following menu will appear on the screen.
+
+.nf
+\f(CW
+                                IRAF
+                  Image Reduction and Analysis Facility
+
+   PACKAGE = apphot
+   TASK = datapars
+
+   (fwhmpsf=                   1.) FWHM of the PSF in scale units
+   (emissio=                  yes) Features are positive
+   (noise  =              poisson) Noise model
+   (thresho=                   0.) Detection threshold in counts above
+                                   background
+   (cthresh=                   0.) Centering threshold in counts above
+                                   background
+   (sigma  =                INDEF) Standard deviation of background in counts 
+   (scale  =                   1.) Image scale in units per pixel
+   (ccdread=                     ) CCD readout noise image header keyword
+   (readnoi=                INDEF) CCD readout noise in electrons
+   (gain   =                     ) CCD gain image header keyword
+   (epadu  =                   1.) Gain in electrons per count
+   (exposur=                     ) Exposure time image header keyword
+   (itime  =                INDEF) Integration time
+   (datamin=                INDEF) Minimum good data pixel
+   (datamax=                INDEF) Maximum good data pixel
+   (mode   =                   ql)
+   ($nargs =                    0)
+\fR
+.fi
+
+.PP
+The following is a brief description of the parameters and their function
+as well as some initial setup recommendations.
+
+.PP
+\fBScale\fP is the image scale parameter in units per pixel, for example
+arc-seconds per pixel.  All distance dependent parameters in the APPHOT package
+including the centering box width \fBcbox\fP in \fBcenterpars\fP, the 
+inner radius and width of the sky annulus, \fBannulus\fP and 
+\fBdannulus\fP in \fBfitskypars\fP, and the radii of the concentric
+circular apertures \fBapertures\fP in \fBphotpars\fP are defined
+in scale units, for example arc seconds.  This permits easy comparison
+with apertures published in the literature.  Some other algorithm
+parameters such as \fBmaxshift\fP in \fBcenterpars\fP and the region
+growing radius \fBrgrow\fP in
+\fBfitskypars\fP are also defined in scale units.  By default all
+distance parameters are defined in pixels.
+.PP
+\fBFwhmpsf\fP is used as a first guess for modelling the psf in the 
+\fBfitpsf\fP task, is important for the optimal use of the \fBdaofind\fP
+algorithm, and critical for the centering algorithms "gauss" and
+"ofilter" as well as the \fBwphot\fP task.
+\fBFwhmpsf\fR as well as the other distance dependent parameters
+can be set interactively from inside most of the APPHOT tasks.
+.PP
+\fBFwhmpsf\fP and \fBscale\fP can be combined in an interesting way.
+\fBScale\fP can be defined in units of half width half maximum of the psf per
+pixel in which case the value of \fBfwhmpsf\fP should be set to
+\fB2.0\fP by definition.  By trial and error and use of the interactive
+setup menu optimal values of the remaining distance dependent parameters
+can be determined in units of \fBscale\fP.  Once determined the same
+setup can be reused on another image by simply reseting the \fBscale\fP
+parameter.
+.PP
+APPHOT photometry routines permit measurement of both emission and absorption
+features.  For the majority of applications including photometry of
+stars and galaxies
+all "objects" are emission "objects" and the \fBemission\fR parameter should
+be left at yes.
+.PP
+APPHOT currently supports two noise models "constant" and "poisson".
+If \fBnoise\fR = "constant" the magnitude errors are computed from the
+Poisson noise in the sky background plus the readout noise.
+If \fBnoise\fR = "poisson"
+the magnitude errors are computed on the basis of the Poisson noise in the
+constant sky background, Poisson noise in the object and readout noise.
+Most users
+with CCD data will wish to leave \fBnoise\fR = "poisson".
+\fBCthreshold\fR is a parameter required by the centering algorithms.
+If \fBcthreshold\fR > 0.0, pixels below the data minimum plus
+threshold in the centering subraster are not used by the centering algorithm.
+For difficult centering problems the user may wish to adjust
+this parameter.
+The \fBsigma\fR parameter specifies the standard deviation of the background
+in a single pixel. \fBSigma\fR is used
+to estimate the signal to noise ratio in the centering subraster and to set
+the width and bin size of the histogram of sky pixels, the \fBkhist\fR and
+\fBbinsize\fR parameters in the pset \fBfitskypars\fR. Both \fBcthreshold\fR and
+\fBsigma\fR can be set interactively from inside the \fBphot\fR task.
+.PP
+APPHOT currently recognizes three image header keywords \fBccdread\fR,
+\fBgain\fR and \fBexposure\fR.  Knowledge of the instrument gain and
+readout noise is required for the correct computation of the magnitude
+errors but not required for the magnitude computation. The units of
+the gain and readout noise are assumed to be electrons per adu
+and electrons respectively.
+Exposure time information is required to normalize the magnitudes computed
+for a series of images to a common exposure time.
+The time units are arbitrary but must be consistent for a set of images.
+If this information is already in the
+image header the user can enter the appropriate header keywords.
+Otherwise the instrument constants gain and readout noise can be entered
+into the parameters \fBepadu\fR and \fBreadnoise\fR.
+If the exposure time information is not present in the image header, the
+user can either edit it in with the \fBhedit\fR task or change the \fBitime\fR
+parameter for each image reduced. If both image header keywords and
+default parameter values are defined the image header keywords take
+precedence.
+.PP
+The two parameters \fBdatamin\fP and \fBdatamax\fP which define the upper
+and lower good data limits respectively are not currently implemented by
+the APPHOT tasks.  They will be used in future versions of the package 
+to, for example, set the limits over which a detector is linear.
+.PP
+After editing, the new \fBdatapars\fR pset might look like the following.
+This user has chosen to wait and set \fBfwhmpsf\fR, \fBthreshold\fR,
+\fBcthreshold\fR, and \fBsigma\fR interactively from inside \fBphot\fR but
+has decided to set the
+image header parameters \fBccdread\fR, \fBgain\fR and \fBexposure\fR.
+
+.nf
+\f(CW
+                           IRAF
+             Image Reduction and Analysis Facility
+
+   PACKAGE = apphot
+   TASK = datapars
+   
+   (fwhmpsf=                   1.) FWHM of the PSF in scale units
+   (emissio=                  yes) Features are positive
+   (noise  =              poisson) Noise model
+   (thresho=                   0.) Detection threshold in counts above 
+                                   background
+   (cthresh=                   0.) Centering threshold in counts above
+                                   background
+   (sigma  =                INDEF) Standard deviation of background in counts
+   (scale  =                   1.) Image scale in units per pixel
+   (ccdread=              readout) CCD readout noise image header keyword
+   (readnoi=                INDEF) CCD readout noise in electrons
+   (gain   =                 gain) CCD gain image header keyword
+   (epadu  =                   1.) Gain in electrons per count
+   (exposur=              exptime) Exposure time image header keyword
+   (itime  =                INDEF) Integration time
+   (datamin=                INDEF) Minimum good data pixel
+   (datamax=                INDEF) Maximum good data pixel
+   (mode   =                   ql)
+   ($nargs =                    0)
+\fR
+.fi
+
+.NH 2
+The Centering Parameters
+.PP
+The centering algorithm parameters have been grouped together in a single
+parameter set \fBcenterpars\fR. To display and edit these parameters type
+the command.
+
+.nf
+	\f(CWap> centerpars\fR
+.fi
+
+The following menu will appear on the terminal.
+
+.nf
+\f(CW
+                              IRAF
+               Image Reduction and Analysis Facility
+
+   PACKAGE = apphot
+   TASK = centerpars
+   
+   (calgori=             centroid) Centering algorithm
+   (cbox   =                   5.) Centering box width in scale units 
+   (maxshif=                   1.) Maximum center shift in scale units
+   (minsnra=                   1.) Minimum SNR ratio for centering
+   (cmaxite=                   10) Maximum iterations for centering algorithm
+   (clean  =                   no) Symmetry clean before centering
+   (rclean =                   1.) Cleaning radius in scale units
+   (rclip  =                   2.) Clipping radius in scale units
+   (kclean =                   3.) K-sigma rejection criterion in skysigma
+   (mkcente=                   no) Mark the computed center
+   (mode   =                   ql)
+   ($nargs =                    0)
+\fR   
+.fi
+
+.PP
+APPHOT offers three choices for the  centering algorithm:
+the default "centroid", "gauss" and "ofilter".
+The default centering algorithm does not depend on \fBfwhmpsf\fR but the
+remaining two do. For reasons of simplicity and efficiency the author
+recommends the default algorithm. In cases where there is significant
+crowding or the data is very noisy users may wish to experiment with
+the other algorithms. Centering can be disabled by setting
+\fBcalgorithm\fR = "none". This option is useful if accurate centers
+have already been computed with the \fBdaofind\fR or \fBfitpsf\fR
+tasks. More detailed information on the APPHOT centering algorithms
+can be found in the document,  \fISpecifications for the Apphot Package\fR
+by Lindsey Davis.
+.PP
+The centering box \fBcbox\fR is defined in units of \fBscale\fR.
+Users  should try to set \fBcbox\fR as small as possible to avoid
+adding noisy pixels to the centering subraster.
+\fBCbox\fR can also be set interactively from inside the APPHOT \fBphot\fR
+task.
+.PP
+If the computed centers are more than \fBmaxshift\fR / \fBscale\fR pixels
+from the initial centers or the signal-to-noise ratio in the centering
+subraster is less than \fBminsnratio\fR the new center will be computed but
+flagged with a warning message.
+.PP
+For stars which are crowded or contaminated by bad pixels the user may
+wish to enable the cleaning algorithm by setting \fBclean\fR = yes.
+Its use is complicated and not recommended for most data.  The algorithm is
+described in the APPHOT specifications document.
+.PP
+If \fBmkcenter\fR=yes,  \fBphot\fR tasks will mark the initial
+and final centers and draw a line between them on the default display
+device. At present this option only works if \fBdisplay\fR="stdgraph".
+.PP
+In the above example we have elected to leave the \fBcalgorithm\fR parameter
+at its default value and set \fBcbox\fR interactively from inside the \fBphot\fR
+task.
+
+
+.NH 2
+The Sky Fitting Parameters
+.PP
+The sky fitting algorithm parameters have been grouped together in a single
+parameter set \fBfitskypars\fR. To display and edit these parameters type
+the following command.
+
+.nf
+	\f(CWap> fitskypars\fR
+.fi
+
+The following menu will appear on the terminal.
+
+.nf
+\f(CW
+                              IRAF
+               Image Reduction and Analysis Facility
+
+   PACKAGE = apphot
+   TASK = fitskypars
+   
+   (salgori=                 mode) Sky fitting algorithm
+   (annulus=                  10.) Inner radius of sky annulus in scale units
+   (dannulu=                  10.) Width of sky annulus in scale units
+   (skyvalu=                   0.) User sky value
+   (smaxite=                   10) Maximum number of sky fitting iterations
+   (snrejec=                   50) Maximum number of sky fitting rejection
+                                   iterations
+   (skrejec=                   3.) K-sigma rejection limit in sky sigma
+   (khist  =                   3.) Half width of histogram in sky sigma
+   (binsize=                  0.1) Binsize of histogram in sky sigma
+   (smooth =                   no) Lucy smooth the histogram
+   (rgrow  =                   0.) Region growing radius in scale units
+   (mksky  =                   no) Mark sky annuli on the display
+   (mode   =                   ql)
+   ($nargs =                    0)
+\fR
+.fi
+
+.PP
+APPHOT offers ten sky fitting algorithms. The algorithms can be grouped
+into 4 categories 1) user supplied sky values including "constant" and "file"
+2) sky pixel distribution algorithms including "median" and "mode",
+3) sky pixel histogram algorithms including "centroid", "crosscor",
+"gauss" and "ofilter" 4) interactive algorithms including "radplot"
+and "histplot".
+The definitions of the mode used by APPHOT is the following.
+
+.nf
+\f(CW	mode = 3.0 * median - 2.0 * mean\fP
+.fi
+
+Detailed descriptions of the algorithms can be found in the document,
+\fISpecifications for the Apphot Package\fR by the author. The author recommends
+"mode" the default, and one of the two histogram algorithms "centroid" and
+"crosscor".
+.PP
+The inner radius and width of the sky annulus in terms of \fBscale\fR
+are set by the parameters \fBannulus\fR and \fBdannulus\fR. These can
+easily be set interactively from within the \fBphot\fR task.
+Good statistics require several hundred sky pixels.
+The user should be aware that a circular sky region can be defined by
+setting \fBannulus\fR to 0.
+.PP
+The user should ensure that the parameter \fBsigma\fR in the
+\fBdatapars\fR parameter set is defined if one of the histogram dependent
+sky fitting algorithms is selected.
+The extent and resolution of the sky pixel histogram is determined
+by \fBkhist\fR and \fBbinsize\fR and their relation to \fBsigma\fR.
+If \fBsigma\fR is undefined then the standard deviation of the local
+sky background is used to parameterise \fBkhist\fR and \fBbinsize\fR
+and the histograms of different stars can deviate widely in resolution.
+.PP
+The sky rejection algorithms are controlled by the parameters \fBskreject\fR,
+\fBsnreject\fR and \fBrgrow\fR. It is strongly recommended that the user
+leave pixel rejection enabled. The user should experiment with the region
+growing radius if the local sky regions are severely crowded.
+.PP
+If \fBmksky\fR = yes, \fBphot\fR will mark the inner
+and outer sky annuli. At present this option
+will only work if \fBdisplay\fR = "stdgraph".
+
+.NH 2
+The Photometry Parameters
+.PP
+The photometry algorithm parameters have been grouped together in a single
+parameter set \fBphotpars\fR. To display and edit these parameters type.
+
+.nf
+	\f(CWap> photpars\fR
+.fi
+
+The following menu will appear on the terminal.
+
+.nf
+\f(CW
+                              IRAF
+               Image Reduction and Analysis Facility
+
+   PACKAGE = apphot
+   TASK = photpars
+   
+   (weighti=             constant) Photometric weighting scheme for wphot
+   (apertur=                   3.) List of aperture radii in scale units
+   (zmag   =                  26.) Zero point of magnitude scale
+   (mkapert=                   no) Draw apertures on the display
+   (mode   =                   ql)
+   ($nargs =                    0)
+\fR
+.fi
+
+.PP
+There are three weighting options inside APPHOT. The default is "constant".
+Inside the \fBphot\fR, \fBradprof\fR and \fBpolyphot\fR tasks only constant
+weighting is used. Two other weighting schemes are available for the
+experimental \fBwphot\fR task, "gauss" and "cone". "Gauss" is the more
+highly recommended.
+.PP
+The aperture list is specified by \fBapert\fR in terms of \fBscale\fR.
+The apertures can be entered in any order but are sorted on output.
+\fBApert\fR can be string or the name of a text file containing the
+list of apertures. Apertures can either be listed individually and
+separated by whitespace or commas or a ranges notation of the
+form apstart:apend:apstep can be used.
+These can be set interactively from within the \fBphot\fR task.
+.PP
+Examples of valid aperture strings are listed below.
+
+.nf
+\f(CW
+	1 2 3
+	1.0,2.0,3.0
+	1:10:1
+\fR
+.fi
+
+.PP
+An arbitrary zero point is applied to the magnitude scale with \fBzmag\fR.
+The user can accept the default or experiment with his/her data until
+a suitable value is found. The computation of the magnitude errors
+does not depend on the zero point.
+.PP
+If \fBmkapert\fR = yes, the \fBphot\fR task will draw the concentric
+apertures on the display.  At present this option
+works only if \fBdisplay\fR = "stdgraph".
+
+.NH 2
+The QPHOT Task
+.PP
+\fBQphot\fP computes accurate centers, sky values and magnitudes for a list
+of objects using a restricted subset of the full \fBphot\fP parameter set.
+It is intended to be a quick look photometer suitable for use when 
+observing on the mountain or in well behaved uncrowded stellar fields.
+.PP
+The user is automatically queried for the critical parameters \fBcbox\fP,
+\fBannulus\fP, \fBdannulus\fP and \fBapertures\fP which are defined in
+terms of pixels.  The noise characteristics of the detector are assumed
+to obey Poisson statistics.  \fBQphot\fP computes centers for each
+object using the "centroid" centering algorithm.  Sky values are
+calculated using the "mode" algorithm.  The user can set the zero point
+of the magnitude scale, \fBzmag\fP, the gain of the detector, \fBepadu\fP,
+and exposure time image header keyword, \fBexposure\fP, but all the
+remaining parameters are set to their default values.
+.PP
+\fBQphot\fP can be driven by the image cursor or a coordinate list in
+interactive mode or by a coordinate list in batch mode in exactly 
+the same manner as the \fBphot\fP task.
+
+.NH 2
+The \fBPOLYPHOT\fP Task
+.PP
+\fBPolyphot\fP computes accurate centers, sky values and magnitudes for
+a list of objects using polygonal shaped apertures.  It is most suitable
+for measuring the magnitudes of large extended irregularly shaped objects.
+.PP
+\fBPolyphot\fP uses \fBdatapars\fP, \fBcenterpars\fP, and
+\fBfitskypars\fP in exactly the same manner as the \fBphot\fP task.  In
+general users should set the task parameters in the same way as they
+set them in \fBphot\fP.  However users who have defined their polygonal
+apertures interactively may wish to set the centering algorithm
+parameter \fBcalgorithm =\fP "none", to avoid the task trying to center
+on the brightest feature in the aperture.
+.PP
+The apertures are defined either interactively with the image or graphics
+cursor or by two files \fBpolygons\fP and \fBcoords\fP.
+Polygons defines the shape of the polygonal aperture and coords defines the
+initial positions of the apertures.  The polygons file may contain
+more than one aperture and the flux through each aperture may be measured
+at more than one position.  A detailed description of the file formats
+is given in section 6.4
+
+.NH
+Creating A Coordinate List
+.PP
+All APPHOT tasks operate on either 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. The coordinate and
+polygon files required by the \fBpolyphot\fR task have a different
+format which is described below. List files may be
+created interactively with either the graphics or the image cursor, by a
+previously executed APPHOT task, by a previously executed IRAF task or by
+a user program. Various means of creating coordinate lists within IRAF
+are described below. Comments preceded by a # character and blank lines
+are ignored.
+
+.nf
+\f(CW
+                     #Sample Coordinate List
+                        53.6    83.25
+                        100.0   35.8
+                        2.134   86.89
+                        ....    ....
+\fR
+.fi
+
+.NH 2
+Daofind
+.PP
+\fBDaofind\fR is an APPHOT task which detects stellar objects in an image 
+automatically. The user sets the \fBfwhmpsf\fR of the psf for which the
+detection algorithm is to be
+optimized as well as an intensity threshold for detection. \fBDaofind\fR
+locates all the qualifying stars  and writes their positions, rough magnitudes
+and shape characteristics to a file. This file can then be assigned to
+the \fBphot\fR task \fBcoords\fR parameter and read directly.
+.PP
+For example if we have an image containing stars for which the \fBfwhmpsf\fR
+is 4.0 pixels and the sigma of the sky background is 10 we might run
+\fBdaofind\fR as follows,
+
+.nf
+	\f(CWcl> daofind image fwhmpsf=4.0 threshold=30.0\fR
+.fi
+
+where we have set our detection threshold at 3.0 * sigma.
+
+.NH 2
+Imtool On the SUN Machines
+.PP
+The SUN IRAF \fBimtool\fR facility supports both image world coordinate
+systems and output coordinate files.  Coordinate lists can be created
+interactively by the users in the following way.
+.PP
+Display the IRAF image in the imtool window using the \fBdisplay\fR task.
+Move the mouse to the top of the \fBimtool\fR window, press the right mouse
+button to enter the \fBimtool\fR menu, move the mouse to the setup option and
+release the mouse button. Press
+the return key until the black triangle is opposite the coordinate list file
+name parameter.
+Delete the default file name, enter the full host system path name of the 
+desired coordinate file and press return. This name should now appear at
+the top of the imtool window.
+Move the mouse to the quit option and press the left mouse button to
+quit the setup window.
+.PP
+To enter the \fBimtool\fR cursor readout mode type the \fBF6\fR key.
+The x, y and intensity values at the cursor position
+are displayed in the lower right corner of the image.
+To mark stars and output their coordinates to the coordinate file, move
+the image cursor a star and press the left mouse button. A sequence number
+will appear on the display next to the marked position. The numbers can
+be changed from black to white and vice versa by toggling the \fBF5\fR key.
+The coordinate files are opened in append mode in order that stars may be
+added to an already existing list. \fBImtool\fR coordinate files are directly
+readable by all APPHOT tasks.
+
+.NH 2
+Rgcursor and Rimcursor
+.PP
+The LISTS package tasks \fBrgcursor\fR and \fBrimcursor\fR can be used to
+generate coordinate lists interactively. For example a coordinate
+list can be created interactively using the display cursor and
+the image display.
+
+.nf
+\f(CW
+	cl> display image
+
+	... image appears on the display ...
+
+	cl> rimcursor > image.coo
+
+	... move display cursor to stars of interest and tape space bar ...
+
+	... type ^Z to terminate the list ...
+\fR
+.fi
+
+Similarly a coordinate list
+can be created using the graphics cursor and a contour
+plot as shown below.
+
+.nf
+\f(CW
+	cl> contour image
+
+	... contour plot appears on the terminal ...
+
+	cl> rgcursor > image.coo
+
+	... move cursor to stars of interest and tap space bar ...
+
+	... type ^Z to terminate the list ...
+\fR
+.fi
+
+The text file "image.coo" contains the x and y coordinates of the marked stars
+in image pixel units. The output of \fBrimcursor\fR or  \fBrgcursor\fR can
+be read directly by the APPHOT \fBphot\fR task.
+\fBRimcursor\fR is only available in IRAF versions 2.7 and later and
+only for selected devices.
+
+.NH 2
+The Polygon List
+.PP
+A utility routine \fBpolymark\fR has been added to the APPHOT package to
+generate polygon and initial center lists for the \fBpolyphot\fR task.
+The format of the polygon files is 1 vertex per line with the 
+x and y coordinates of the vertex in columns 1 and 2 respectively.
+A line containing the single character ';' terminates the lists of vertices.
+There can be more than one polygon in a single polygon file.
+
+.nf
+\f(CW
+            Sample Polygon File
+
+                1.0   1.0
+                1.0   51.0
+                51.0  51.0
+                51.0  1.0
+                ;
+                80.0  80.0
+                80.0  131.0
+                131.0 131.0
+                131.0 80.0
+                ;
+\fR
+.fi
+
+.PP
+The accompanying coordinate file is optional. If no coordinate file is given
+the initial center for the polygon is the mean of its vertices in the 
+polygon file. If a
+coordinate file is specified the initial center for the polygon is the
+position in the coordinate file. Each polygonal aperture may be moved
+to several positions.
+
+.nf
+\f(CW
+       Sample Polyphot Coords File
+
+               50. 30.
+               80. 100.
+               60. 33.
+               ;
+               90. 50.
+               55. 90.
+               12. 122.
+               ;
+\fR
+.fi
+
+For example all the coordinates in group 1 will be measured using the
+aperture defined by polygon 1 and all the coordinates
+in group 2 will be measured with the aperture defined by polygon 2.
+
+.NH 2
+User Program
+.PP
+Obviously any user program which produces a text file with the coordinates
+listed 1 per line with x and y in columns 1 and 2 can be used to produce
+APPHOT coordinate files.
+
+.NH 2
+Modifying an Existing Coordinate List
+.PP
+The LISTS package routine \fBlintran\fR has been linked into the APPHOT
+package. It can be used to perform simple coordinate transformations on
+coordinate lists including shifts, magnifications, and rotations.
+
+.NH
+Running Apphot in Interactive Mode Without a Coordinate List
+.PP
+There are currently three ways to run the \fBphot\fR interactively without
+a coordinate list:
+1) read image display cursor commands 2) read 
+graphics cursor commands 3) read commands
+from the standard input. The three methods are briefly discussed below.
+Detailed examples of all three methods of operation can be found in
+the manual pages for each task.
+
+.NH 2
+Reading Image Cursor Commands
+.PP
+The default method of running APPHOT. The user loads an image onto
+the display, types \fBphot\fR and enters the image name. The image cursor
+appears on the display and the program is ready to accept user commands.
+This option is not available under IRAF version 2.6 and earlier
+because interactive image cursor readback was not available.
+
+.NH 2
+Redirecting the Image Cursor to the Graphics Cursor
+.PP
+\fBPhot\fR reads the graphics cursor and executes various keystroke
+commands. The environment variable \fBstdimcur\fR must be set to "stdgraph".
+For full access
+to all the graphics commands the parameter \fBdisplay\fR must also be set
+to "stdgraph".
+The user creates a contour plot of the image on the graphics terminal
+with the \fBcontour\fR task, types \fBphot\fR and answers the image name query.
+The graphics cursor appears on the contour plot ready for input.
+The user can move around the plot with the cursor successively marking stars.
+
+.NH 2
+Redirecting the Image Cursor to the Standard Input
+.PP
+The user can enter cursor commands directly on the standard input.
+The environment variable \fBstdimcur\fR must be set to "text".
+When the user types the task name \fBphot\fR and enters the image
+name, the following prompt appears.
+
+.nf
+	\f(CWImage cursor [xcoord ycoord wcs] key [cmd]:\fR
+.fi
+
+\fIXcoord\fR and \fIycoord\fR are the coordinates of the object of
+interest, \fIwcs\fR is the current world coordinate system, always 1,
+\fIkey\fR is a single
+character and \fIcmd\fR is an APPHOT task command.
+To perform the default action of
+the \fBphot\fR task the user responds as follows.
+
+.nf
+	\f(CWImage cursor [xcoord ycoord wcs] key [cmd]: 36. 42. 1\fR
+.fi
+
+\fBPhot\fR measures the magnitude of the star near pixel coordinates
+x,y = (36.,42.) and writes the result to the output file.
+In IRAF version 2.5 all the cursor command fields must be typed.
+The square brackets
+indicate those fields which are optional under IRAF version 2.6 and later.
+Users with SUN
+workstations may wish to combine the IMTOOL coordinate list cursor readback
+facilities which generate coordinate lists  with this mode of running APPHOT
+interactively.
+
+.NH 2
+The Interactive Keystroke Commands
+.PP
+A conscious effort has been made to keep the definitions of all the
+keystroke commands within the APPHOT package as similar as possible.
+The following are the most commonly used  keystrokes in the APPHOT package.
+
+.NH 3
+The ? (Help) Keystroke Command
+.PP
+The ? key prints the help page describing the cursor keystroke and colon
+show commands for the specific APPHOT task. An abbreviated help page
+is typed by default when a user enters a task in interactive mode.
+The ? key can be typed at any point in the APPHOT task.
+
+.NH 3
+The :show (Set and Print parameter)  Commands
+.PP
+Any APPHOT parameter can be displayed by typing :\fIparameter\fR command
+in interactive mode.
+For example to show the current value of the \fBfwhmpsf\fR parameter
+type the following command.
+
+.nf
+	\f(CW:fwhmpsf\fR
+.fi
+
+To set any APPHOT parameter type :\fIparameter\fR "value". For example
+to set the \fBfwhmpsf\fR to 2.0 type.
+
+.nf
+	\f(CW:fwhmpsf 2.0\fR
+.fi
+
+To display all the centering parameters type.
+
+.nf
+	\f(CW:show center\fR
+.fi
+
+Similarly the sky fitting and photometry parameters can be displayed by
+typing. 
+
+.nf
+	\f(CW:show sky\fR
+	\f(CW:show phot\fR
+.fi
+
+All the parameters can be displayed with the following command.
+
+.nf
+	\f(CW:show\fR
+.fi
+
+.NH 3
+The i (Interactive Setup) Keystroke Command
+.PP
+This extremely useful key allows one to set up the principal APPHOT
+parameters interactively. To use this feature move the image cursor to a star on
+the display, or move the graphics cursor to a star on the contour plot
+and tap the i key,
+or enter the x and y  coordinates, and the world coordinate system
+of the star and the i key manually. The program will query the user for
+the size of the extraction box and plot a radial profile of the star
+on the terminal. The user sets the \fBfwhmpsf\fR, the centering
+aperture \fBcbox\fR, the inner sky annulus \fBannulus\fR and \fBdannulus\fR,
+the list of apertures \fBaperts\fR and the data \fBsigma\fR,
+\fBthreshold\fR and \fBcthreshold\fR using the graphics cursor and the
+radial profile plot.
+The cursor comes up on the plot at the position of the appropriate parameter.
+Typing return will preserve the old value.
+If the cursor is outside the range of values on the plot the old value
+is kept.
+.PP
+Setting \fBsigma\fP, \fBcthreshold\fP, and \fBthreshold\fP 
+interactively requires two keystrokes.  In each case the measured parameter
+is the difference between the two y coordinates of the graphics
+cursor. It is recommended in general that the user leave \fBcthreshold\fP
+at zero.
+
+.NH 3
+The v (Verify) Keystroke Command
+.PP
+The v key verifies that the values of the critical task parameters 
+currently in memory are the ones that the user wants.  To each verify query
+the user either types CR to verify the current value or enters a new
+value.
+
+.NH 3
+The w (Write to Psets) Keystroke Command
+.PP
+The w key writes the current values of the parameters in memory to the
+appropriate psets.
+This feature is useful for saving values marked with the
+i key. On exiting APPHOT a prompt will remind the user that the current
+parameters in memory must be stored in the psets or lost.
+
+.NH 3
+The d (Radial Profile Plot) Keystroke Command
+.PP
+The d key plots a centered radial profile of a star on the graphics device.
+
+.NH 3
+The f (Fit) Keystroke Command
+.PP
+This key performs the default action of each APPHOT task without writing
+any results
+to the output file. In the \fBphot\fR task the f key will center, fit the
+local sky and compute the magnitudes for a star. This key allows the user to
+experiment interactively with the data, changing the default parameters,
+remeasuring magnitudes and so on before actually writing out any data.
+
+.NH 3
+The Space Bar (Fit and Write out Results) Keystroke Command
+.PP
+This key performs the default action of the task and writes the results
+to the output catalog.
+
+.NH
+Running Apphot In Interactive Mode From A Coordinate List
+.PP
+This is currently the best method for running APPHOT interactively for users
+without image cursor readback facilities. APPHOT tasks
+can pick stars out of the list sequentially or by number,  measure stars
+sequentially or by number, rewind the coordinate lists and remeasure all
+the stars. Stars which are not in the coordinate list can still be
+measured and added to the output catalog.
+
+.IP [1] 
+The :m (Move) Keystroke Command
+.RS
+.LP
+This command moves the cursor to the next or a specified star in the
+coordinate list.  If the hardware cursor on the
+device being read from is enabled the actual physical cursor will move
+to the requested star. For
+example a user might decide that star # 10 in the coordinate list is the best
+setup star. He/she simply types a :m 10 to move to the star in
+question followed by the i key to setup the parameters interactively.
+.RE
+
+.IP [2]
+The :n (Next)  Keystroke Command
+.RS
+.LP
+This command moves to the next or specified star in the list, performs the
+default action of the task and writes the results to the output file.
+This key is particularly useful in examining the results of a large batch
+run.
+For example, a user measures the magnitudes of 500 stars using APPHOT in
+batch mode.  He/she is suspicious about the results for twenty of the most
+crowded stars. By rerunning APPHOT in interactive mode using the original
+coordinate list, the user can selectively call up the stars in question,
+plot their radial profiles, and examine the results interactively.
+.RE
+
+.IP [3]
+The l (List) Keystroke Command
+.RS
+.LP
+This command measures all the stars in the coordinate list sequentially from
+the current position in the file.
+.RE
+
+.IP [4]
+The r (Rewind) Keystroke Command
+.RS
+.LP
+This command rewinds the coordinate list.
+.RE
+
+.NH
+Running Apphot in Batch Mode
+.PP
+This is the simplest way to run APPHOT. Once the parameters are set and stored
+in the pset files the program can be run in batch by setting the parameter
+\fBinteractive\fR = no. The program will read the coordinate list
+sequentially computing results for each star and writing them to the
+output file.
+
+.NH
+Apphot Output
+.PP
+APPHOT tasks write their output to text and/or plot files as well as to the
+standard output and graphics terminals.
+
+.NH 2
+Text Files
+.PP
+All APPHOT records are written to text files.
+The parameters for the task are listed at the beginning of each APPHOT
+output text file and identified with a #K string.
+The header record is not written until the record
+for the first star is to be written to the database. Parameter changes  will
+generate a one line entry in the output text file.
+The data records follow the header record in the order in which they
+were computed.
+If the output file parameter \fBoutput\fR = "" no output file is written.
+This is  the default action for the \fBradprof\fR task.
+If \fBoutput\fR = "default",
+the output file name is constructed using the image name.
+
+.NH 2
+Plot Files
+.PP
+Some APPHOT tasks can optionally produce graphics output.
+These files are maintained as plot metacode and may contain many individual
+plots.
+A directory of plots in each metacode file can be obtained with
+\fBgkidir\fR. Individual plots can be extracted with \fBgkiextract\fR and
+combined and plotted with \fBgkimosaic\fR.  
+
+.NH 2
+Running Apselect on Apphot Output Files 
+.PP
+Individual fields can be extracted from the APPHOT output files using
+the \fBapselect\fR task and a keyword and expression scheme.
+For example the user may wish
+to extract the x and y center coordinates, the sky value and the
+magnitudes from the APPHOT \fBphot\fR catalog. Using apselect they
+would type.
+
+.nf
+	\f(CWcl> apselect output xc,yc,msky,mag yes > magsfile\fR
+.fi
+
+The selected fields would appear in the textfile "magsfile".
+
+.NH
+Apphot Recipes
+.PP
+In the following section three APPHOT reduction sessions which illustrate
+different methods of using the APPHOT package are described. In the
+first example the user wishes to compute magnitudes for a large number
+of stars in a single image. In the second example he/she wishes to
+measure the magnitude of a single standard star in each of a long list of
+images. Finally in the last example the user wishes to measure the
+magnitude of an elliptical galaxy through a list of apertures.
+Each example assumes that the user has started with the default set of
+package parameters.
+
+.NH 2
+Infrared photometry of a Star Field in Orion
+.PP
+An observer has an IRAF image on disk of a star forming region in Orion taken
+with the
+IR CCD camera. The Orion image is a composite formed from 64 separate
+IR images using the PROTO \fBirmosaic\fR and \fBiralign\fR tasks.
+The Orion image contains about 400 stars but is only moderately crowded. The
+observer decides to use the APPHOT package to reduce his data.
+.PP
+The observer decides to run the \fBdaofind\fR routines to create a coordinate
+list of stars, to run \fBphot\fR in interactive mode with the image cursor
+directed to the standard input to setup and store the \fBphot\fR task
+parameters and finally, to run \fBphot\fR in batch mode to do the photometry.
+.PP
+To create the coordinate list the user needs to supply the full width half
+maximum of the pointspread function and an intensity threshold
+above background to the
+\fBdaofind\fR program. Using the PLOT package task \fBimplot\fR the user
+examines several stars in the image and decides that the \fBfwhmpsf\fR
+should be 3.0
+pixels and that the standard deviation of the background should be 10.0
+counts.
+The user decides to include all stars with a peak intensity greater
+than five standard deviations above local background in the coordinate list.
+The user runs \fBdaofind\fR as follows.
+
+.nf
+	\f(CWap> daofind orion fwhmpsf=3.0 threshold=50.0\fR
+.fi
+
+The x and y coordinates, a magnitude estimate and some statistics on image
+sharpness and roundness are output to the file "orion.coo.1".
+The user can obtain a printout of the coordinate
+list by typing.
+
+.nf
+	\f(CWap> lprint orion.coo.1\fR
+.fi
+
+.PP
+Next the user decides to set up the parameters of the \fBphot\fR task.
+Using the \fBepar\fR task he enters the phot task parameter menu,
+types "orion" opposite the \fBimage\fR parameter and "orion.coo.1"
+opposite the \fBcoords\fR parameter. Next he moves the cursor opposite
+the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR
+menu. He sets the gain parameter \fBepadu\fR to 5.0 electrons per adu
+and the readout noise \fBreadnoise\fR to 5.0 electrons. He types \fB:q\fR to
+quit and save the \fBdatapars\fR parameters and \fB^Z\fR to quit and save the
+\fBphot\fR parameters.
+.PP
+Now the user is ready to enter the \fBphot\fR task in interactive mode to set
+up the remaining data dependent parameters. The user types  the following
+sequence of commands in response to the cursor prompt. Note that the
+example below assumes that the image cursor has been directed to the
+standard input. The image cursor comes up on the screen in the form of
+a prompt. This example could equally well be run from the image hardware
+cursor in which case the cursor would appear on the displayed image. The
+keystroke commands are identical in the two cases.
+
+.br
+
+.nf
+\f(CW
+	ap> phot orion
+
+	... \fIload the phot task\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: ?
+
+	... \fIprint help page for phot task\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: :radplots yes
+
+	... \fIenable radial profile plotting\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: :m 10
+
+	... \fImove to star 10 in the coordinate list\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: i
+
+	... \fIenter interactive setup mode using star 10\fR ...
+
+	... \fImark fwhmpsf, cbox, sky annulus, apertures on the plot\fR ...
+
+        ... \fIleave sigma and cthreshold at their default values\fR ...
+
+	... \fIcheck answers on radial profile plot of the results\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: v
+
+        ... \fIverify the critical parameters\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: :radplots no
+
+	... \fIdisable radial profile plotting\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: w
+
+	... \fIstore new parameters in the psets\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: q
+
+	... \fIquit interactive cursor loop\fR ...
+
+	q
+
+	... \fIquit the phot task\fR ...
+
+\fR
+.fi
+.PP
+The user decides he is happy with the current parameter set and decides
+to run the \fBphot\fR task in batch and submit it as a background task.
+
+.nf
+	\f(CWap> phot orion inter- verify- &\fR
+.fi
+
+The results will appear in the text file "orion.mag.1".
+
+.NH 2
+Landolt Standards 
+.PP
+The user has 100 UBVRI images of 20 Landolt Standards
+taken on a single night. These frames have been taken at various short
+exposures.
+The user wishes to process all this data
+in batch mode with the output records going to a single file.
+.PP
+The observer decides to run the \fBdaofind\fR task to create a coordinate
+list for each image, to run \fBphot\fR on a representative image
+in interactive mode with the image cursor
+directed to the standard input to set up and store the \fBphot\fR task
+parameters, and finally to run \fBphot\fR in batch mode on all the images
+to do the photometry.
+.PP
+Note that the example below assumes that the image cursor has been redirected
+to the standard input.  The image cursor comes up on the screen in the
+form of a prompt.  This example could equally well be run from the image 
+hardware cursor in which case the cursor would appear on the displayed
+image.  The keystroke commands are identical in the two cases.
+.PP
+To create the coordinate list the user needs to supply the full width half
+maximum of the point spread function and an intensity threshold above
+local background to the
+\fBdaofind\fR task. Using the PLOT package task \fBimplot\fR the user
+examines the Landolt standards in several images and decides that the
+average \fBfwhmpsf\fR is 4.3
+pixels and that the standard deviation of the background is 15.0 counts.
+Note that if the user has access to an image display \fBfwhmpsf\fP and
+\fBthreshold\fP can be determined interactively from inside the
+daofind task itself.
+The user decides to include all stars with a peak intensity greater
+than five standard deviations above local background in the coordinate list,
+which should include weak and spurious objects.
+The user runs \fBdaofind\fR as follows.
+
+.nf
+	\f(CWap> daofind lan*.imh fwhmpsf=4.3 threshold=75.0 verify- &\fP
+.fi
+
+The x and y coordinates, an initial guess at the magnitude and some
+sharpness and roundness characteristics are output to the files "lan*.coo.1".
+For example the image lan100350.imh will now have a corresponding 
+coordinate file lan100350.coo;1. The user may wish at this point
+to quickly check the coordinate files for spurious objects.
+.PP
+Next the user decides to set up the parameters of the phot task.
+Using the \fBepar\fR task he enters the phot task parameter set,
+enters "lan100350b" opposite the \fBimage\fR parameter and "lan100350b.coo.1"
+opposite the \fBcoords\fR parameter. Next he moves the cursor opposite
+the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR
+menu. He sets the gain parameter \fBepadu\fR to 10 electrons per adu
+and the readout noise \fBreadnoise\fR to 50.0 electrons. 
+Finally in order to normalize all the magnitudes the user enters
+the image header exposure time keyword "itime" opposite the
+\fBexposure\fP parameter.  He types \fB:q\fR to
+quit and save the \fBdatapars\fR parameters and \fB^Z\fR to quit and save the
+\fBphot\fR parameters.
+.PP
+Now the user is ready to enter the \fBphot\fR task in interactive mode to set
+up the remaining data dependent parameters. The user types  the following
+sequence of commands in response to the cursor prompt.
+
+.nf
+\f(CW
+	ap> phot lan100350.imh
+
+	... \fIload the phot task\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: ?
+
+	... \fIprint help page for phot task\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: :radplots yes
+
+	... \fIenable radial profile plotting\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: :m #n
+
+	... \fImove to star n in the coordinate list\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: i
+
+	... \fIenter interactive setup mode using star n\fR ...
+
+	... \fImark fwhmpsf, cbox, sky annulus, apertures on the plot\fR ...
+
+        ... \fIleave sigma and cthreshold at their default values\fR ...
+
+	... \fIcheck answers on radial profile plot of the results\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: v
+
+        ... \fIverify the critical parameters\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: :radplots no
+
+	... \fIdisable radial profile plotting\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: w
+
+	... \fIstore new parameters in the psets\fR ...
+
+	Image cursor [xcoord ycoord wcs] key [cmd]: q
+
+	... \fIquit interactive cursor loop\fR ...
+
+	q
+
+	... \fIquit the phot task\fR ...
+
+\fR
+.fi
+.PP
+Finally the user runs the \fBphot\fR task on the full list of images,
+with their corresponding parameter sets and dumps the output to a single
+text file named "output".
+
+.nf
+	\f(CWap> phot lan*.imh coords="lan*.coo.*" output=output veri- inter- &\fR
+.fi
+
+The results will appear in the text file "output".
+
+.NH 2
+Aperture Photometry of an Elliptical Galaxy
+.PP
+The user has a single image of the elliptical galaxy N315. She
+wishes to measure the magnitude of this galaxy through a list of apertures
+equal to those published in a well known catalogue of photoelectric photometry.
+Her data has been sky subtracted to give an average background value of 0.0
+and the standard deviation of the sky background is 20.0 counts.
+From the published aperture photometry
+and the scale of her telescope she knows that she wishes to measure
+the galaxy through aperture radii of 10.5, 15.2, 20.8, and 25.6 arc seconds.
+.PP
+The user wishes to work in interactive mode using a contour plot
+of the image and the graphics cursor to enter commands to the \fBphot\fR
+task. She therefore sets the image cursor to "stdgraph" as follows.
+
+.nf
+	\f(CWap> set stdimcur = stdgraph\fR
+.fi
+
+.PP
+Next she makes a contour plot of the image and  writes it to
+a plot metacode file as follows.
+
+.nf
+\f(CW
+	ap> contour N315 
+
+	... \fIcontour plot appears on the terminal\fR ...
+
+	ap> =gcur
+
+	... \fIenter cursor mode\fR ...
+
+	:.write n315.plot
+
+	... \fIwrite the plot to a file\fR ...
+
+	q
+
+	... \fIexit cursor mode\fR ...
+
+\fR
+.fi
+.PP
+Now the user is ready to set up the parameters of the \fBphot\fR task.
+Since she already knows the values of the parameters she wishes to use
+she types
+
+.nf
+	\f(CWap> epar phot\fR
+.fi
+
+to enter the phot task menu. She positions the cursor opposite
+\fBimage\fR parameter and types "N315", opposite \fBdispay\fR and
+types "stdgraph".
+Next she moves the cursor opposite
+the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR
+menu. She makes sure that \fBscale =\fP 0.75 arc-seconds per pixel the scale
+of the telescope, sets the standard deviation
+of the sky background \fBsigma\fR to 20.0, sets the gain
+parameter \fBepadu\fR to 5 electrons per adu
+and the readout noise \fBreadnoise\fR to 5.0 electrons. She types \fB:q\fR to
+quit and save the \fBdatapars\fR parameters. She decides to leave the
+centering parameters in \fBcenterpars\fR at their default values.
+\fBCbox\fP in particular will be 5.0 arcseconds wide.  The user
+has already removed a low order polynomial sky background from this image.
+She wishes to fix the sky value at 0.0. She moves the cursor opposite
+the \fBfitskypars\fR parameter and types \fB:e\fR to enter the sky fitting menu.
+She types "constant" opposite the \fBsalgorithm\fR parameter, "0.0"
+opposite the \fBskyvalue\fR parameter and \fB:e\fR to exit
+the sky fitting parameter menu. Finally she enters the \fBphotpars\fR
+menu and enters the aperture string "10.5,15.2,20.8,25.6" opposite
+the \fBapert\fR parameter. 
+.PP
+To measure the galaxy she types
+
+.nf
+	\f(CWap> phot N315\fR
+.fi
+
+to enter the phot task, positions the cursor on the center of the
+galaxy in the contour plot and taps the space bar to make the measurement.
+The results are  written to the file "N315.mag.1".