Initial commit

1 files changed, 418 insertions, 0 deletions

diff --git a/noao/digiphot/daophot/doc/pstselect.hlp b/noao/digiphot/daophot/doc/pstselect.hlp
new file mode 100644
index 00000000..2dd110bd
--- /dev/null
+++ b/noao/digiphot/daophot/doc/pstselect.hlp
@@ -0,0 +1,418 @@
+.help pstselect May00 noao.digiphot.daophot
+.ih
+NAME
+pstselect -- select candidate psf stars from a photometry file
+.ih
+USAGE
+pstselect image photfile pstfile maxnpsf
+.ih
+PARAMETERS
+.ls image
+The list of images containing the candidate psf stars.
+.le
+.ls photfile
+The list of input  photometry files. The number of photometry files must
+be equal to the number of input images. If photfile is "default", "dir$default",
+or a directory specification PSTSELECT searches for a file called 
+dir$image.mag.#  where # is the highest available version number for the file.
+Photfile is normally the output of the PHOT task but may also be the  output
+of  the  PSF,  PEAK,  NSTAR and ALLSTAR tasks. Photfile may be a
+text file or an STSDAS binary table.
+.le
+.ls pstfile
+The  list  of  output  psf star photometry files. There must be one output
+psf star photometry file for every input image. If pstfile is "default",
+"dir$default",  or a  directory  specification  then  PSTSELECT writes
+a file called dir$image.pst.# where # is the next  available  version  number.
+Pstfile  inherits its file type, it may be either an APPHOT/DAOPHOT
+text or STSDAS binary file, from photfile.
+.le
+.ls maxnpsf = 25
+The maximum number of candidate psf stars to be selected.
+.le
+.ls mkstars = no
+Mark the selected or deleted psf stars on the image display ?
+.le
+.ls plotfile = ""
+The name of the output file containing mesh, contour, or profile plots of the
+selected PSF stars. If plotfile is undefined no plot file is created; otherwise
+a mesh, contour, or profile plot is written to this file for each PSF star
+selected. Plotfile is opened in append mode and may become very large.
+.le
+.ls datapars = ""
+The name of the file containing the data dependent parameters. The parameter
+\fIscale\fR is located here. If \fIdatapars\fR is undefined then the default
+parameter set in uparm directory is used.
+.le
+.ls daopars = ""
+The name of the file containing the daophot fitting parameters. The parameters
+\fIpsfrad\fR and \fIfitrad\fR are located here. If \fIdaopars\fR is undefined
+then the default parameter set in uparm directory is used.
+.le
+.ls interactive = no
+Select the psf stars interactively ? If interactive = yes and icommands is
+undefined, PSTSELECT reads in the star list from \fIphotfile\fR, sorts the
+stars by magnitude and waits for commands from the user. If interactive = no
+and icommands="", PSTSELECT selects candidate PSF stars from \fIphotfile\fR
+automatically. If icommands is not undefined then interactive is automatically
+set to "no", and commands are read from the image cursor command file.
+.le
+.ls plottype = "mesh"
+The default plot type displayed when a psf star is selected interactively.
+The choices are "mesh", "contour", or "radial".
+.le
+.ls icommands = ""
+The image display cursor or image cursor command file.
+.le
+.ls gcommands = ""
+The graphics cursor or graphics cursor command file.
+.le
+.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout"
+The coordinate system of the input coordinates read from \fIphotfile\fR and
+of the output coordinates written to \fIpstfile\fR respectively. The image
+header coordinate system is used to transform from the input coordinate
+system to the "logical" pixel coordinate system used internally,
+and from the internal "logical" pixel coordinate system to the output
+coordinate system. The input coordinate system options are "logical", "tv",
+"physical", and "world". The output coordinate system options are "logical",
+"tv", and "physical". The image cursor coordinate system is assumed to
+be the "tv" system.
+.ls logical
+Logical coordinates are pixel coordinates relative to the current image.
+The  logical coordinate system is the coordinate system used by the image
+input/output routines to access the image data on disk. In the logical
+coordinate system the coordinates of the first pixel of a  2D image, e.g.
+dev$ypix  and a 2D image section, e.g. dev$ypix[200:300,200:300] are
+always (1,1).
+.le
+.ls tv  
+Tv coordinates are the pixel coordinates used by the display servers. Tv
+coordinates  include  the effects of any input image section, but do not
+include the effects of previous linear transformations. If the input
+image name does not include an image section, then tv coordinates are
+identical to logical coordinates.  If the input image name does include a
+section, and the input image has not been linearly transformed or copied from
+a parent image, tv coordinates are identical to physical coordinates.
+In the tv coordinate system the coordinates of the first pixel of a
+2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300]
+are (1,1) and (200,200) respectively.
+.le
+.ls physical
+Physical coordinates are pixel coordinates invariant  with respect to linear
+transformations of the physical image data.  For example, if the current image
+was created by extracting a section of another image,  the  physical
+coordinates of an object in the current image will be equal to the physical
+coordinates of the same object in the parent image,  although the logical
+coordinates will be different.  In the physical coordinate system the
+coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D
+image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200)
+respectively.
+.le
+.ls world
+World coordinates are image coordinates in any units which are invariant
+with respect to linear transformations of the physical image data. For
+example, the ra and dec of an object will always be the same no matter
+how the image is linearly transformed. The units of input world coordinates
+must be the same as those expected by the image header wcs, e. g.
+degrees and degrees for celestial coordinate systems.
+.le
+The wcsin and wcsout parameters default to the values of the package
+parameters of the same name. The default values of the package parameters
+wcsin and wcsout are "logical" and "logical" respectively.
+.le
+.ls cache = ")_.cache"
+Cache the image pixels in memory. Cache may be set to the value of the apphot
+package parameter (the default), "yes", or "no". By default caching is
+disabled.
+.le
+.ls verify = ")_.verify"
+Verify the critical PSTSELECT parameters ?
+Verify can be set to the DAOPHOT package parameter value (the default),
+"yes", or "no".
+.le
+.ls update = ")_.update"
+Update the algorithm parameters if verify is "yes"?
+Update can be set to the DAOPHOT package parameter value (the default),
+"yes", or "no".
+.le
+.ls verbose = ")_.verbose"
+Print messages about the progress of the task in non-interactive mode ?
+Verbose can be set to the DAOPHOT package parameter value (the default),
+"yes", or "no".
+.le
+.ls
+graphics = ")_.graphics"
+The default graphics device.  Graphics can be set to the default
+daophot package parameter value, "yes", or "no".
+.le
+.ls display = ")_.display"
+The  default  image  display  device.  Display can be set to the DAOPHOT
+package parameter value (the default), "yes", or "no". By default graphics
+overlay is disabled.  Setting display to one of "imdr", "imdg", "imdb", or
+"imdy" enables graphics overlay with the IMD graphics kernel.
+.le
+
+.ih
+DESCRIPTION
+
+PSTSELECT reads the input photometry file \fIphotfile\fR, extracts the ID,
+XCENTER, YCENTER, MAG, and MSKY fields for up to \fImaxnpsf\fR psf stars,
+and the results to \fIpstfile\fR. \fIPstfile\fR automatically inherits the
+file format of \fIphotfile\fR.
+
+The coordinates read from \fIphotfile\fR are assumed to be in coordinate
+system defined by \fIwcsin\fR. The options are "logical", "tv", "physical",
+and "world" and the transformation from the input coordinate system to
+the internal "logical" system is defined by the image coordinate system.
+The simplest default is the "logical" pixel system. Users working on with
+image sections but importing pixel coordinate lists generated from the parent
+image must use the "tv" or "physical" input coordinate systems.
+
+The coordinates written to \fIpstfile\fR are in the coordinate system defined
+by \fIwcsout\fR. The options are "logical", "tv", and "physical". The simplest
+default is the "logical" system. Users wishing to correlate the output
+coordinates of objects measured in image sections or mosaic pieces with
+coordinates in the parent image must use the "tv" or "physical" coordinate
+systems.
+
+After reading the star list from \fIphotfile\fR, PSTSELECT sorts the list in
+order of increasing magnitude, after rejecting any stars that have INDEF
+valued magnitudes, or which lie less than \fIfitrad\fR / \fIscale\fR
+pixels from the edge of the \fIimage\fR. From this list the brightest
+\fImaxnpsf\fR stars which have no brighter neighbor stars within (\fIpsfrad\fR +
+\fIfitrad\fR) / \fIscale\fR + 1 pixels are selected as candidate psf stars.
+\fIPsfrad\fR and \fIfitrad\fR are the psf radius and fitting radius parameters
+respectively and are stored in the DAOPARS parameter set. \fIScale\fR is the
+image scale parameter and is located in the DATAPARS parameter set. Plots,
+either mesh, contour or radial profile depending on the value of
+\fIplottype\fR, of the selected stars may be saved in the file \fIplotfile\fR.
+
+If \fIinteractive\fR = "no", PSTSELECT reads the star list in \fIphotfile\fR,
+selects the candidate psf stars as described above, and writes the results to
+\fIpstfile\fR automatically. If interactive = "yes", PSTSELECT reads
+the star list, selects the candidate psf stars and waits for further
+instruction from the user. At this point the user can step through the stars
+chosen by PSTSELECT, check their surface, contour, or radial profile plots
+for blemishes, neighbors etc, and accept the good candidates and reject
+the poor ones, or use the image cursor and/or id number to select psf
+stars until a maximum of \fImaxnpsf\fR stars is reached. At any point in
+this process a previously selected psf star can be deleted.
+
+If \fIcache\fR is yes and the host machine physical memory and working set size
+are large enough, the input image pixels are cached in memory. If caching
+is enabled and PSTSELECT is run interactively the first data access will appear
+to take a long time as the entire image must be read in before the data
+is actually fetched. All subsequent measurements will be very fast because
+PSTSELECT is accessing memory not disk. The point of caching is to speed up
+random image access by making the internal image i/o buffers the same size as
+the image itself. However if the input object lists are sorted in row order and
+sparse caching may actually worsen not improve the execution time. Also at
+present there is no point in enabling caching for images that are less than
+or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the
+default image i/o buffer is exactly that size. However if the size of dev$ypix
+is doubled by converting it to a real image with the chpixtype task then the
+effect of caching in interactive is can be quite noticeable if measurements
+of objects in the top and bottom halves of the image are alternated.
+
+
+.ih
+CURSORS
+
+    The  following  cursor  commands are available once the image cursor
+    has been activated.
+
+.nf
+
+	Keystroke Commands 
+
+?	Print help
+p	Print photometry for star nearest the cursor
+l	List the current psf stars
+n	Select the next good candidate psf star from the list
+a	Add star nearest cursor to psf star list
+d	Delete psf star nearest cursor from psf star list
+q	Quit task
+
+	Colon Commands
+
+:p [n]	Print photometry for star n
+:a [n]	Add star n to psf star list
+:d [n]	Delete star n from psf star list
+
+The following cursor commands are available once a star has been selected
+and the graphics cursor has been activated.
+
+        Interactive Graphics Keystroke Commands
+
+?       Print help
+p       Print the photometry for this star
+t       Print the plot parameters and data minimum and maximum
+a       Accept star and proceed
+d       Reject star and select another with image cursor
+m       Plot the default mesh plot for this star
+n       Increase vertical angle by 15 degrees (mesh plot only)
+s       Decrease vertical angle by 15 degrees (mesh plot only)
+w       Decrease horizontal angle by 15 degrees (mesh plot only)
+e       Increase horizontal angle by 15 degrees (mesh plot only)
+c       Plot the default contour plot for this star
+r       Plot the radial profile for this star
+
+
+        Colon Graphics Commands
+
+:m [val] [val]  Set the mesh plot vertical and horizontal viewing angles
+:v [val]        Set the mesh plot vertical viewing angle
+:h [val]        Set the mesh plot horizontal viewing angle
+:c [val] [val]  Set the contour plot floor and ceiling levels
+:l [value]      Set the contour plot floor level
+:u [value]      Set the contour plot ceiling level
+.fi
+
+.ih
+OUTPUT
+
+If \fIverbose\fR = "yes" a single line is written to the terminal for each
+star added to the candidate psf star list. Full output is written to the
+file \fIpstfile\fR. At the beginning of this file is a header listing the
+values of all the important parameters. For each star included in the candidate
+psf star list the following quantities are written.
+
+.nf
+	id  xcenter ycenter mag msky
+.fi
+
+Id, xcenter, ycenter, mag, and msky are the id, x and y coordinates,
+magnitudes and sky values for the candidate psf stars listed in
+\fIphotfile\fR.
+
+.ih
+EXAMPLES
+
+1. Select up to 10 psf stars from the PHOT task output non-interactively. 
+Save surface plots of the selected stars in the file "psf.plots".
+
+.nf
+    da> daofind dev$ypix default fwhmpsf=2.5 sigma=5.0 threshold=20.0
+
+        ... answer verify prompts
+
+        ... find stars in the image
+
+	... answer will appear in ypix.coo.1
+
+    da> phot dev$ypix default default annulus=10. dannulus=5.       \
+	apertures = 5.0
+
+        ... answer verify prompts
+
+        ... do aperture photometry on the detected stars
+
+	... answer will appear in ypix.mag.1
+
+    da> pstselect dev$ypix default default 10 psfrad=9.0 fitrad=3.0 \
+        plotfile=psf.plots
+
+        ... answer verify prompts
+
+        ... select candidate psf stars
+
+        ... the output will appear in ypix.pst.1 
+
+    da> display dev$ypix 1
+
+        ... display the image
+
+    da> pdump ypix.pst.1 xc,yc yes | tvmark 1 STDIN col=204
+
+        ... mark the stars
+
+    da> gkiextract psf.plots 1 | stdgraph
+
+	... make a surface plot of the first candidate psf star
+.fi
+
+
+2. Repeat the previous results for an image section while preserving the
+coordinate system of the original image.
+
+
+.nf
+    da> daofind dev$ypix[150:450,150:450] default wcsout=tv fwhmpsf=2.5 \
+        sigma=5.0 threshold=20.0
+
+	... answer verify prompts
+
+        ... find stars in the image
+
+	... answer will appear in ypix.coo.2
+
+    da> phot dev$ypix[150:450,150:450] default default wcsin=tv wcsout=tv \
+        annulus=10.  dannulus=5. apertures = 5.0
+
+	... answer verify prompts
+
+        ... do aperture photometry on the detected stars
+
+	... answer will appear in ypix.mag.2
+
+    da> pstselect dev$ypix[150:450,150:450] default default 10 wcsin=tv \
+        wcsout=tv psfrad=9.0 fitrad=3.0 plotfile=psf.plots2
+
+	... answer verify prompts
+
+        ... select candidate psf stars
+
+        ... the output will appear in ypix.pst.2 
+
+    da> display dev$ypix[150:450,150:450] 1
+
+        ... display the image
+
+    da> pdump ypix.pst.2 xc,yc yes | tvmark 1 STDIN col=204
+
+        ... mark the stars
+
+    da> gkiextract psf.plots2 4 | stdgraph
+
+	... make a surface plot of the 4th candidate psf star
+.fi
+
+
+3. Repeat example 1 but run pstselect in interactive mode and do not save the
+plots.
+
+.nf
+    da> display dev$ypix 1
+
+        ... display the image 
+
+    da> pstselect dev$ypix ypix.mag.1 default 10 psfrad=9. fitrad=3. \
+        interactive+ mkstars+ display=imdr
+
+	... verify the critical parameters as instructed
+
+	... when the image cursor appears type the n keystroke
+	    command to select the first suitable candidate psf
+	    star, examine its surface plot, and type a or d to
+	    accept or reject the candidate
+
+	... repeat the previous command until 10 psf stars have
+    	    been selected, the end of the star list is reached,
+	    or a sufficient number of stars but fewer than maxnpsf
+	    have been selected
+
+	... if fewer than maxnpsf stars are found automatically
+	    add psf stars to the list with the a keystroke command
+
+	... type q to quit
+
+.fi
+
+.ih
+TIME REQUIREMENTS
+.ih
+BUGS
+.ih
+SEE ALSO
+datapars,daopars,phot,psf
+.endhelp