| addstar | noao.digiphot.daophot | addstar |
addstar -- add artificial stars to images
addstar image photfile psfimage addimage
ADDSTAR adds artificial stars, whose positions and magnitudes are listed in photfile or generated at random by the computer, to the input image image using the PSF in psfimage , and writes the result to the output image and output photometry file addimage . If photfile is undefined then ADDSTAR generates an artificial photometry list containing nstar stars uniformly distributed in position over the image and in magnitude between minmag and maxmag . 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 offset . Several output images may be written for each input image by setting the parameter nimage greater than 1.
The coordinates read from photfile are assumed to be in coordinate system defined by wcsin . 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 wcspsf 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 addimage are in the coordinate system defined by wcsout . 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 cache is yes and the host machine physical memory and working set size are large enough, the output image pixels are cached in memory. If cacheing is enabled and the first artificial star addtion 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 cacheing 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 cacheing may actually worsen not improve the execution time. Also at present there is no point in enabling cacheing 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 cacheing in interactive is can be quite noticeable if measurements of objects in the top and bottom halfs 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 psfimage . 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 gain if present, or the value of the DATAPARS parameter epadu .
If verbose = 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 addimage . At the beginning of each file is a header listing the current values of all the parameters. For each artifical star added to the input image the following record is written.
id xcenter ycenter mag
Id is the id number of the star, xcenter and ycenter are its coordinates, and mag is its magnitude.
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).
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
2. Repeat example 1 using the output starlist as input.
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
3. Repeat example 1 using a simple text file as input.
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
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.
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