path: root/noao/digiphot/daophot/doc/addstar.hlp

.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