STScI Logo

addstar noao.digiphot.daophot


NAME · USAGE · PARAMETERS · DESCRIPTION · OUTPUT · EXAMPLES
TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

addstar -- add artificial stars to images

USAGE

addstar image photfile psfimage addimage

PARAMETERS

image
The list of images to which artificial stars are to be added.
photfile
The list of photometry files containing the x and y coordinates and magnitudes of the artificial stars to be added to image . If photfile is undefined, then nstar artificial stars uniformly distributed in position, and in magnitude between minmag and maxmag are added to image . If photfile is 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 (simple_text = yes), an APPHOT/DAOPHOT text database file (simple_text = no), or an STSDAS binary table file.
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.
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 text is "yes", then an APPHOT/DAOPHOT text database file is written, otherwise an STSDAS binary table is written.
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 psfimage .
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 psfimage .
nstar
The number of computer generated artificial stars to be added to the input image.
datapars = ""
The text file in which the data dependent parameters are stored. The gain parameter epadu in electrons per ADU is stored here. If datapars is undefined then the default parameter set in the user's uparm directory is used.
daopars = ""
The text file in which the daophot fitting parameters are stored. The PSF radius parameter psfrad in scale units is stored here. If daopars is undefined then the default parameter set in the user's uparm directory is used.
simple_text = no
If photfile is a text file and simple_text = "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.
seed = 0
The seed for the random number generator used to generate the positions and magnitudes of the artificial stars.
nimage = 1
The number of output images to be created per input image.
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.
wcsin = ")_.wcsin", wcsout = ")_.wcsout", wcspsf = ")_.wcspsf"
The coordinate system of the input coordinates read from photfile , of the psf model psfimage , and of the output coordinates written to addimage 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 logicial 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.
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).
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.
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.
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.
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.
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 cacheing is disabled.
verify = ")_.verify"
Verify the critical ADDSTAR task parameters? Verify may be set to the daophot package parameter value (the default), "yes", or "no".
update = ")_.update"
Update the critical ADDSTAR task parameters if verify = "yes"? Update may be set to the daophot package parameter value (the default), "yes", or "no".
verbose = ")_.verbose"
Print messages about the progress of ADDSTAR? Verbose may be set to the daophot package parameter value (the default), "yes", or "no".

DESCRIPTION

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 .

OUTPUT

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.

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).

    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

TIME REQUIREMENTS

BUGS

SEE ALSO

datapars,daopars


Search Form · STSDAS