Initial commit

1 files changed, 365 insertions, 0 deletions

diff --git a/noao/digiphot/daophot/doc/addstar.hlp b/noao/digiphot/daophot/doc/addstar.hlp
new file mode 100644
index 00000000..f2e08a45
--- /dev/null
+++ b/noao/digiphot/daophot/doc/addstar.hlp
@@ -0,0 +1,365 @@
+.help addstar May00 noao.digiphot.daophot
+.ih
+NAME
+addstar -- add artificial stars to images
+.ih
+USAGE
+addstar image photfile psfimage addimage
+.ih
+PARAMETERS
+.ls image
+The list of images to which artificial stars are to be added.
+.le
+.ls photfile
+The list of photometry files containing the x and y coordinates and magnitudes
+of the artificial stars to be added to \fIimage\fR. If photfile is undefined,
+then \fInstar\fR artificial stars uniformly distributed in position, and  in
+magnitude between \fIminmag\fR and \fImaxmag\fR are added to \fIimage\fR. If
+photfile is defined, there must be one photometry file for every input image.
+Photfile may be a simple text file containing x, y, magnitude, and id number in
+columns 1, 2, 3, and 4 respectively (\fIsimple_text\fR = yes), an APPHOT/DAOPHOT
+text database file (\fIsimple_text\fR = no), or an STSDAS binary table file.
+.le
+.ls psfimage
+The list of images containing the PSF models computed by the DAOPHOT PSF task.
+The number of PSF images must be equal to the number of input images. If
+psfimage is "default", "dir$default", or a directory specification, then PEAK
+will look for an image with the name image.psf.?, where ? is the highest
+existing version number.
+.le
+.ls addimage
+The root name of the output images. There must be one output root image name
+ for every input image. If addimage is "default", "dir$default" or a directory
+specification, then an output artificial image and artificial star list called
+image.add.? and image.art.? respectively are created, where ? is the next
+available version number. If the DAOPHOT  package parameter \fItext\fR is "yes",
+then an APPHOT/DAOPHOT text database file is written, otherwise an STSDAS binary
+table is written.
+.le
+.ls minmag
+The minimum magnitude of the computer generated artificial stars to be
+added to the image. The actual intensities of the pixels in the artificial
+stars are computed with respect to the magnitude of the PSF stored in
+\fIpsfimage\fR.
+.le
+.ls maxmag
+The maximum magnitude of the computer generated artificial stars to be
+added to the image. The actual intensities of the pixels in the artificial
+stars are computed with respect to the magnitude of the PSF stored in
+\fIpsfimage\fR.
+.le
+.ls nstar
+The number of computer generated artificial stars to be added to the input
+image.
+.le
+.ls datapars = ""
+The text file in which the data dependent parameters are stored. The gain
+parameter \fIepadu\fR in electrons per ADU is stored here.  If datapars is
+undefined then the default parameter set in the user's uparm directory is used.
+.le
+.ls daopars = ""
+The text file in which the daophot fitting parameters are stored. The PSF
+radius parameter \fIpsfrad\fR in scale units is stored here. If daopars is
+undefined then the default parameter set in the user's uparm directory is used.
+.le
+.ls simple_text = no
+If \fIphotfile\fR is a text file and \fIsimple_text\fR = "no", then ADDSTAR
+expects an APPHOT/DAOPHOT database. Otherwise ADDSTAR expects a simple list
+format with x, y, magnitude, and id in columns 1, 2,3, and 4 respectively.
+.le
+.ls seed = 0
+The seed for the random number generator used to generate the positions
+and magnitudes of the artificial stars.
+.le
+.ls nimage = 1
+The number of output images to be created per input image.
+.le
+.ls idoffset = 0
+The integer offset to be added to the id numbers of stars in the output
+artificial photometry file. By default the artificial stars are numbered from 1
+to N where N is the number of artificial stars added to the input frame.
+.le
+.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf"
+The coordinate system of the input coordinates read from \fIphotfile\fR, of the
+psf model \fIpsfimage\fR, and of the output coordinates written to
+\fIaddimage\fR respectively. The image header coordinate system is used to
+transform from the input coordinate system to the "logical" pixel coordinate
+system used internally, from the internal logical system to the PSF model
+system, 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 PSF model and 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, wcspsf, and wcsout parameters default to the values of the package
+parameters of the same name. The default values of the package parameters
+wcsin, wcspsf,  and wcsout are "logical", "physical" 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 ADDSTAR task parameters? Verify may be set to the
+daophot package parameter value (the default), "yes", or "no".
+.le
+.ls update = ")_.update"
+Update the critical ADDSTAR task parameters if \fIverify\fR = "yes"?
+Update may be set to the daophot package parameter value (the default),
+"yes", or "no".
+.le
+.ls verbose = ")_.verbose"
+Print messages about the progress of ADDSTAR? Verbose may be set to the
+daophot package parameter value (the default), "yes", or "no".
+.le
+
+.ih
+DESCRIPTION
+
+ADDSTAR adds artificial stars, whose positions and magnitudes are listed in
+\fIphotfile\fR or generated at random by the computer, to the input image
+\fIimage\fR using the PSF in \fIpsfimage\fR, and writes the result to the
+output image and output photometry file \fIaddimage\fR. If \fIphotfile\fR is
+undefined then ADDSTAR generates an artificial photometry list containing
+\fInstar\fR stars uniformly distributed in position over the image and in
+magnitude between \fIminmag\fR and \fImaxmag\fR. The input photometry file
+may be an STSDAS binary table or an APPHOT/DAOPHOT text database file (the
+output of the PHOT, PSF, PEAK, NSTAR, or ALLSTAR tasks) or a simple text file
+with the x and y positions, magnitude, and id in columns 1, 2, 3 and 4
+respectively. The ids of stars in the output photometry file may be set to
+numbers outside the range of the real data by setting the parameter
+\fIoffset\fR. Several output images may be written for each input image by
+setting the parameter \fInimage\fR greater than 1.
+
+The coordinates read from \fIphotfile\fR are assumed to be in coordinate
+system defined by \fIwcsin\fR. If photfile is undefined the input coordinate
+system is logical. 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 coordinate system of the PSF model is the coordinate system defined by the
+\fIwcspsf\fR parameter. Normally the PSF model was derived from the input image
+and this parameter default to "logical". However if the PSF model was derived
+from a larger image which is a "parent" of the input image, then wcspsf should
+be set to "tv" or "physical" depending on the circumstances.
+
+The coordinates written to \fIaddimage\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.
+
+If \fIcache\fR is yes and the host machine physical memory and working set size
+are large enough, the output image pixels are cached in memory. If caching
+is enabled and the first artificial star addition will appear
+to take a long time as the entire input image must be read into the output
+image before the first artificial star addition is actually made. All
+subsequent measurements will be very fast because ADDSTAR 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.
+
+The intensities in the artificial stellar images are computed relative to the
+intensities in the PSF image, by scaling the magnitudes of the artificial stars
+to the magnitude of the PSF in \fIpsfimage\fR. Poisson noise is added to the
+artificial stars using the value of the gain stored in the image header keyword
+specified by the DATAPARS parameter \fIgain\fR if present, or the value of the
+DATAPARS parameter \fIepadu\fR.
+
+.ih
+OUTPUT
+
+If \fIverbose\fR = yes, a line of output is written to the terminal for each
+artificial star added to the input image.
+
+Full output is written to the output photometry file \fIaddimage\fR. At the
+beginning of each file is a header listing the current values of all the
+parameters. For each artificial star added to the input image the following
+record is written.
+
+.nf
+	id  xcenter  ycenter  mag
+.fi
+
+Id is the id number of the star, xcenter and ycenter are its coordinates, and
+mag is its magnitude.
+
+.ih
+EXAMPLES
+
+1. Add 30 stars uniformly distributed between 17 and 20th magnitude and in
+position to the input image m92. Display the new image and mark the
+artificial stars. Good stars for making the PSF model can be found at
+(442,410), (348,189), and (379,67).
+
+.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> display dev$ypix 1
+
+	... display the image
+
+    da> psf dev$ypix default "" default default default psfrad=9.0 \
+        fitrad=3.0 mkstars=yes display=imdr
+
+        ... verify the critical parameters
+
+        ... move the image cursor to a candidate star and hit the a key,
+            a plot of the stellar data appears
+
+        ... type ? for a listing of the graphics cursor menu
+
+        ... type a to accept the star, d to reject it
+
+        ... move to the next candidate stars and repeat the previous
+            steps
+
+        ... type l to list all the psf stars
+
+        ... type f to fit the psf
+
+        ... move cursor to first psf star and type s to see residuals,
+            repeat for all the psf stars
+
+        ... type w to save the PSF model
+
+        ... type q to quit, and q again to confirm
+
+        ... the output will appear in ypix.psf.1.imh, ypix.pst.1 and
+            ypix.psg.1
+
+    da> addstar dev$ypix "" default default 12.0 17.0 30 epadu=14.0
+
+	... verify the critical parameters
+
+    da> display ypix.add.1 2
+
+	... display the artificial image
+
+    da> pdump ypix.art.1 xcenter,ycenter yes | tvmark 2 STDIN col=204
+
+	... mark the stars on the artificial image
+.fi
+
+
+2. Repeat example 1 using the output starlist as input.
+
+.nf
+    da> addstar dev$ypix ypix.art.1  default default simple- epadu=14.0
+
+    ... the answers will appear in ypix.add.2 and ypix.art.2
+.fi
+
+
+3. Repeat example 1 using a simple text file as input.
+
+.nf
+    da> pdump ypix.art.1 xc,yc,mag yes > artdata
+
+    ... create a simple text file from the addstar output
+
+    da> addstar dev$ypix artdata default default simple+ epadu=14.0
+
+    ... the answers will appear in ypix.add.3 and ypix.art.3
+.fi
+
+
+4. Run addstar on a section of the input image using the PSF model derived in
+example 1 for the parent image, the artificial star list from examples 2 and
+3, and write the results in the coordinate system of the image section
+not the parent image.
+
+.nf
+   da> addstar dev$ypix[150:450,150:450] artdata default default simple+ \
+       epadu=14.0 wcsin=tv wcspsf=tv wcsout=logical
+
+        ... answer the verify prompts
+
+        ... fit the stars
+
+        ... the results will appear in ypix.add.4 and ypix.art.4
+
+    da> display ypix.add.4 1
+
+        ... display the image
+
+    da> pdump ypix.art.4 xc,yc yes | tvmark 1 STDIN col=204
+
+        ... mark the stars
+
+.fi
+
+
+.ih
+TIME REQUIREMENTS
+.ih
+BUGS
+.ih
+SEE ALSO
+datapars,daopars
+.endhelp