diff options
Diffstat (limited to 'noao/digiphot/daophot/doc/addstar.hlp')
| -rw-r--r-- | noao/digiphot/daophot/doc/addstar.hlp | 365 |
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 |