diff options
Diffstat (limited to 'noao/digiphot/apphot/doc')
29 files changed, 15806 insertions, 0 deletions
diff --git a/noao/digiphot/apphot/doc/apsums.apps b/noao/digiphot/apphot/doc/apsums.apps new file mode 100644 index 00000000..ea5843bf --- /dev/null +++ b/noao/digiphot/apphot/doc/apsums.apps @@ -0,0 +1,19 @@ +The apphot and daophot package aperture photometry tasks have been modified +to compute the aperture sums and areas in double precision instead of real +precision. This change minimizes machine precision errors that can become +significant for large apertures and very low noise or synthetic data. + +These tasks have also been modified to output negative values of the total +flux should they occur. Formerly these values were being artificially set to +0.0. This change makes it easier to see the effects of any sky value and machine +errors. + +The modified apertures photometry tasks are available as part of the +external addon package digiphotx. To retrieve and install digiphotx, ftp +to 140.252.1.1, login as anonymous, cd to iraf/extern, retrieve the file +digiphotx.readme, and follow the installation instructions. + + + + Lindsey Davis + davis@noao.edu diff --git a/noao/digiphot/apphot/doc/apsums.noao b/noao/digiphot/apphot/doc/apsums.noao new file mode 100644 index 00000000..fd920b49 --- /dev/null +++ b/noao/digiphot/apphot/doc/apsums.noao @@ -0,0 +1,17 @@ +The apphot and daophot package aperture photometry tasks have been modified +to compute the aperture sums and areas in double precision instead of real +precision. This change minimizes machine precision errors that can become +significant for large apertures and very low noise or synthetic data. + +These tasks have also been modified to output negative values of the total +flux should they occur. Formerly these values were being artificially set to +0.0. This change makes it easier to see the effects of any sky value and machine +errors. + +The modified apertures photometry tasks are available under irafx. Let me +know if you have any questions about the modified tasks or encounter and +problems using them. + + + Lindsey Davis + davis@noao.edu diff --git a/noao/digiphot/apphot/doc/aptest.hlp b/noao/digiphot/apphot/doc/aptest.hlp new file mode 100644 index 00000000..85fad0d9 --- /dev/null +++ b/noao/digiphot/apphot/doc/aptest.hlp @@ -0,0 +1,68 @@ +.help aptest Dec92 noao.digiphot.apphot +.ih +NAME +aptest -- run basic tests on the apphot package tasks +.ih +USAGE +aptest imname +.ih +PARAMETERS +.ls imname +The name of the output test image. The actual test image is stored in fits +format in the APPHOT package subdirectory test. If the image already exists +APTEST will exit with a warning message. +.le +.ls aplogfile = "" +The name of the output log file. By default all the text output is logged +in a file called \fI"imname.log"\fR. If the log file already exists APTEST will +exit with a warning message. +.le +.ls applotfile = "" +The name of the output log file. By default all the plot output is logged in +a file called \fI"imname.plot"\fR. If the plot file already exists APTEST will +exit with a warning message. +.le +.ih +DESCRIPTION +APTEST is a simple script which exercises each of the tasks in the APPHOT +package in turn. At startup APTEST reads a small fits image stored in the +APPHOT test subdirectory and creates the image \fIimname\fR in the user's +working directory. APTEST initializes the APPHOT package by returning +all the parameters to their default state, runs each of the APPHOT +tasks in non-interactive mode, spools the text output to the file +\fIaplogfile\fR, and spools the plot output from the RADPROF task to the plot +metacode file \fIapplotfile\fR. +.ih +EXAMPLES + +1. Check to see that all the APPHOT tasks are functioning correctly. + +.nf + ap> apphot + + ... load the apphot package + + ap> aptest testim + + ... run the test script + + ap> lprint testim.log + + ... print the text output + + ap> gkidir testim.plot + + ... list the contents of the plot file + + ap> gkiextract testim.plot 1-N | stdplot + + ... send the plots to the plotter +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +.endhelp diff --git a/noao/digiphot/apphot/doc/center.hlp b/noao/digiphot/apphot/doc/center.hlp new file mode 100644 index 00000000..c409c49b --- /dev/null +++ b/noao/digiphot/apphot/doc/center.hlp @@ -0,0 +1,638 @@ +.help center May00 noao.digiphot.apphot +.ih +NAME +center -- compute accurate centers for a list of objects +.ih +USAGE +center image +.ih +PARAMETERS +.ls image +The list of images containing the objects to be centered. +.le +.ls coords = "" +The list of text files containing initial coordinates for the objects to +be centered. Objects are listed in coords one object per line with the +initial coordinate values in columns one and two. The number of coordinate +files must be zero, one, or equal to the number of images. +If coords is "default", "dir$default", or a directory specification then an +coords file name of the form dir$root.extension.version is constructed and +searched for, where dir is the directory, root is the root image name, +extension is "coo" and version is the next available version number for the +file. +.le +.ls output = "default" +The name of the results file or results directory. If output is +"default", "dir$default", or a directory specification then an output file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "ctr" and version is +the next available version number for the file. The number of output files +must be zero, one, or equal to the number of image files. In both interactive +and batch mode full output is written to output. In interactive mode +an output summary is also written to the standard output. +.le +.ls plotfile = "" +The name of the file containing radial profile plots of the stars written +to the output file. If plotfile is defined then a radial profile plot +is written to plotfile every time a record is written to \fIoutput\fR. +The user should be aware that this can be a time consuming operation. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. +The critical parameters \fIfwhmpsf\fR and \fIsigma\fR are located in +datapars. If datapars is undefined then the default parameter set in +uparm directory is used. +.le +.ls centerpars = "" +The name of the file containing the centering algorithm parameters. +The critical parameters \fIcalgorithm\fR and \fIcbox\fR are located in +centerpars. If centerpars is undefined then the default parameter +set in uparm is used. +.le +.ls interactive = yes +Interactive or non-interactive mode? +.le +.ls radplots = no +If \fIradplots\fR is "yes" and CENTER is run in interactive mode, a radial +profile of each star is plotted on the screen after the center is fit. +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" 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 cacheing is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical parameters in non-interactive mode ? Verify may be set to +the apphot package parameter value (the default), "yes", or "no. +.le +.ls update = ")_.update" +Update the critical parameters in non-interactive mode if \fIverify\fR is +set to yes? Update may be set to the apphot package parameter value (the +default), "yes", or "no. +.le +.ls verbose = ")_.verbose" +Print messages on the terminal in non-interactive mode ? Verbose may be set +to the apphot package parameter value (the default), "yes", or "no. +.le +.ls graphics = ")_.graphics" +The default graphics device. +Graphics may be set to the apphot package parameter value (the default), "yes", +or "no. +.le +.ls display = ")_.display" +The default display device. Display may be set to the apphot package +parameter value (the default), "yes", or "no. By default graphics overlay +is disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" +enables graphics overlay with the IMD graphics kernel. Setting display to +"stdgraph" enables CENTER to work interactively from a contour plot. +.le + +.ih +DESCRIPTION +CENTER computes accurate centers for a set of objects in the IRAF image +\fIimage\fR, whose initial coordinates are read from the image display cursor, +from the text file \fIcoords\fR, or from a cursor command file. +The computed x and y coordinates, the errors, and the fitting parameters +are written to the text file \fIoutput\fR. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\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 input image pixels are cached in memory. If cacheing +is enabled and CENTER is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because CENTER +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 halves of the image are alternated. + +CENTER can be run either interactively or in batch mode by setting the +parameter \fIinteractive\fR. In interactive mode starting x and y positions +can either be read directly from the image cursor or read from the text +file \fIcoords\fR. In interactive mode the user can examine, adjust, and +save the algorithm parameters, change ojects interactively, query for +the next or nth object in the list, or fit the entire coordinate list with +the chosen parameter set. In batch mode the positions can be read from the +text file \fIcoords\fR or the image cursor can be redirected to a text file +containing a list of cursor commands as specified by the parameter +\fIicommands\fR. + +.ih +CURSOR COMMANDS + +The following cursor commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify the critical parameters +w Save the current parameters +d Plot radial profile of current star +i Interactively set parameters using current star +f Fit center of current star +spbar Fit center of current star, output results +m Move to next star in coordinate list +n Center next star in coordinate list, output results +l Center remaining stars in coordinate list, output results +e Print error messages +r Rewind the coordinate list +q Exit task + + + Colon Commands + +:show [data/center] List the parameters +:m [n] Move to next [nth] star in coordinate list +:n [n] Center next [nth] star in coordinate list, + output results + + + Colon Parameter Editing Commands + +# Image and file name parameters + +:image [string] Image name +:coords [string] Coordinate file name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full-width half-maximum of PSF (scale units) +:emission [y/n] Emission feature (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good data value (counts) +:datamax [value] Maximum good data value (counts) + +# Noise parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readout noise (electrons) + +# Observations parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Exposure time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Centering parameters + +:calgorithm [string] Centering algorithm +:cbox [value] Width of centering box (scale units) +:cthreshold [value] Centering intensity threshold (sigma) +:cmaxiter [value] Maximum number of iterations +:maxshift [value] Maximum center shift (scale units) +:minsnratio [value] Minimum signal to noise for centering +:clean [y/n] Clean subraster before centering +:rclean [value] Cleaning radius (scale units) +:rclip [value] Clipping radius (scale units) +:kclean [value] Clean K-sigma rejection limit (sigma) + +# Plotting and marking parameters + +:mkcenter [y/n] Mark computed centers on the display +:radplot [y/n] Plot radial profile of object + + +The following keystroke commands are available from the interactive setup +menu. + + Interactive Center Setup Menu + + v Mark and verify the critical center parameters (f,s,c) + + f Mark and verify the full-width half-maximum of the psf + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + + c Mark and verify the centering box half-width + n Mark and verify the cleaning radius + p Mark and verify the clipping radius +.fi + +.ih +ALGORITHMS + +Descriptions of the data dependent parameters and the centering +algorithm parameters can be found in the online manual pages for +\fIdatapars\fR and \fIcenterpars\fR. + +.ih +OUTPUT + +In interactive mode the following quantities are written to the terminal +as each object is measured. Error is a simple string which indicates +whether an error condition has been flagged. The centers and their errors are +in pixel units. + +.nf + image xinit yinit xcenter ycenter xerr yerr error +.fi + +In both interactive and batch mode the full output is written to the +text file \fIoutput\fR. At the beginning of each file is a header +listing the current values of the parameters when the first stellar +record was written. These parameters can be subsequently altered. +For each star measured the following record is written + +.nf + image xinit yinit id coords lid + xcenter ycenter xshift yshift xerr yerr cier error +.fi + +Image and coords are the name of the image and coordinate file respectively. +Id and lid are the sequence numbers of stars in the output and coordinate +files respectively. Cier and error are the centering error code and accompanying +error message respectively. Xinit, yinit, xcenter, ycenter, xshift, yshift, +and xerr, yerr are self explanatory and output in pixel units. The sense of +the xshift and yshift definitions is the following. + +.nf + xshift = xcenter - xinit + yshift = ycenter - yinit +.fi + +In interactive mode a radial profile of each measured object is plotted +in the graphics window if \fIradplots\fR is "yes". + +In interactive and batchmode a radial profile plot is written to +\fIplotfile\fR if it is defined each time the result of an object +measurement is written to \fIoutput\fR . + +.ih +ERRORS + +If the object centering was error free then the field cier will be zero. +Non-zero values in the cier column flag the following error conditions. + +.nf + 0 # No error + 101 # The centering box is off the image + 102 # The centering box is partially off the image + 103 # The S/N ratio is low in the centering box + 104 # There are two few points for a good fit + 105 # The x or y center fit is singular + 106 # The x or y center fit did not converge + 107 # The x or y center shift is greater than maxshift + 108 # There is bad data in the centering box +.fi + +.ih +EXAMPLES + +1. Compute the centers for a few stars in dev$ypix using the image display +and the image cursor. Setup the task parameters using the interactive +setup menu defined by the i keystroke command and a radial profile plot. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> center dev$ypix + + ... type ? to see help screen + + ... move image cursor to a star + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to get the default menu + ... set the fwhmpsf, sigma, and centering box half-width using the + graphics cursor and the stellar radial profile plot + ... typing <CR> after a prompt leaves the parameter at its default + value + ... type q to exit setup menu + + ... type the v key to verify the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... move the image cursor to the stars of interest and tap + the space bar + + ... type q to quit followed by q to confirm the quit + + ... the output will appear in ypix.ctr.1 + +.fi + +2. Compute the centers for a few stars in dev$ypix using the contour plot +and the graphics cursor. This option is only useful for those (now very few) +users who have access to a graphics terminal but not to an image display +server. Setup the task parameters using the interactive setup menu defined by +the i key command as in example 1. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... make a contour plot of dev$ypix + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of ypix in the file ypix.plot + + ap> center dev$ypix display=stdgraph + + ... type ? to see the help screen + + ... move graphics cursor to a star + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v key to get the default setup menu + ... enter maximum radius in pixels of the radial profile + ... set the fwhmpsf, sigma, and centering box half-width + using the graphics cursor and the stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its + default value + ... type q to quit the setup menu + + ... type the v key to verify critical parameters + + ... type the w key to save the parameters in the parameter files + + ... retype :.read ypix.plot1 to reload the contour plot + + ... move the graphics cursor to the stars of interest and tap + the space bar + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... full output will appear in the text file ypix.ctr.2 + + ap> set stdimcur = <default> + + ... reset stdimcur to its previous value +.fi + + +3. Setup and run CENTER interactively on a list of objects temporarily +overriding the fwhmpsf, sigma, and cbox parameters determined in examples +1 or 2. + +.nf + ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify- + + ... make a coordinate list + + ... the output will appear in the text file ypix.coo.1 + + ap> center dev$ypix cbox=7.0 coords=ypix.coo.1 + + ... type ? for optional help + + + ... move the graphics cursor to the stars and tap space bar + + or + + ... select stars from the input coordinate list with m / :m # + and measure with spbar + + ... measure stars selected from the input coordinate list + with n / n # + + ... a one line summary of results will appear on the standard output + for each star measured + + ... the output will appear in ypix.ctr.3 ... +.fi + + +4. Display and measure some stars in an image section and write the output +coordinates in the coordinate system of the parent image. + +.nf + ap> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + ap> center dev$ypix[150:450,150:450] wcsout=tv + + ... move cursor to stars and type spbar + + ... type q to quit and q again to confirm quit + + ... output will appear in ypix.ctr.4 + + ap> pdump ypix.ctr.4 xc,yc yes | tvmark 1 STDIN col=204 +.fi + + +5. Run CENTER in batch mode using the coordinate file and the previously +saved parameters. Verify the critical parameters. + +.nf + ap> center dev$ypix coords=ypix.coo.1 verify+ inter- + + ... output will appear in ypix.ctr.5 ... +.fi + + +6. Repeat example 5 but assume that the input coordinate are ra and dec +in degrees and degrees, turn off verification, and submit the task to to +the background. + +.nf + ap> display dev$ypix + + ap> rimcursor wcs=world > radec.coo + + ... move to selected stars and type any key + + ... type ^Z to quit + + ap> center dev$ypix coords=radec.coo wcsin=world verify- inter- & + + ... output will appear in ypix.ctr.6 + + ap> pdump ypix.ctr.6 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars on the display + + +7. Run CENTER interactively without using the image display. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = text + + ... set the image cursor to the standard input + + ap> center dev$ypix coords=ypix.coo.1 + + ... type ? for optional help + + ... type :m 3 to set the initial coordinates to those of the + third star in the list + + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to enter the default menu + ... set the fwhmpsf, sigma, and centering box half-width + using the graphics cursor and the stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its default + value + + ... type r to rewind the coordinate list + + ... type l to measure all the stars in the coordinate list + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... full output will appear in the text file ypix.ctr.7 + + ap> set stdimcur = <default> + + ... reset the value of stdimcur +.fi + +8. Use a image cursor command file to drive the CENTER task. The cursor command +file shown below sets the fwhmpsf, calgorithm, and cbox parameters, computes +the centers for 3 stars, updates the parameter files, and quits the task. + +.nf + ap> type cmdfile + : calgorithm gauss + : fwhmpsf 2.5 + : cbox 9.0 + 442 410 101 \040 + 349 188 101 \040 + 225 131 101 \040 + w + q + + ap> center dev$ypix icommands=cmdfile verify- + + ... full output will appear in ypix.ctr.8 +.fi + +.ih +BUGS + +It is the responsibility of the user to make sure that the image displayed +in the image display is the same as the image specified by the image parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the centerpars mkcenter switch to +"yes". It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO +datapars, centerpars +.endhelp diff --git a/noao/digiphot/apphot/doc/centerpars.hlp b/noao/digiphot/apphot/doc/centerpars.hlp new file mode 100644 index 00000000..008869f4 --- /dev/null +++ b/noao/digiphot/apphot/doc/centerpars.hlp @@ -0,0 +1,206 @@ +.help centerpars May00 noao.digiphot.apphot +.ih +NAME +centerpars -- edit the centering algorithm parameters +.ih +USAGE +centerpars +.ih +PARAMETERS +.ls calgorithm = "centroid" +The centering algorithm. The "gauss" and "ofilter" options depend critically +on the value of the fwhmpsf parameter in the DATAPARS task. The centering +options are: +.ls none +The initial positions are assumed to be the true centers. Users +may select this option if the initial centers are know to be accurate, +e.g. they were computed by DAOFIND task. +.le +.ls centroid +The object centers are determined by computing the intensity weighted means +of the marginal profiles in x and y. This is the recommended default algorithm +for APPHOT users. +.le +.ls gauss +The object centers are computed by fitting a Gaussian of fixed fwhmpsf, +specified by the DATAPARS fwhmpsf parameter, to the marginal profiles in +x and y using non-linear least squares techniques. +.le +.ls ofilter +The object centers are computed using optimal filtering techniques, +a triangular weighting function of half width equal to fwhmpsf as +specified by the DATAPARS fwhmpsf parameter, and the marginal distributions +in x and y. +.le +.le +.ls cbox = 5.0 (scale units) +The width of the subraster used for object centering in units of the +DATAPARS scale parameter. Cbox must be big enough to include a reasonable +number of pixels for center determination but not so large so as to include +a lot of noise. Recommended initial values are 2.5-4.0 * the FWHM of the PSF +value. +.le +.ls cthreshold = 0.0 (sigma units) +Pixels cthreshold * sigma above (emission features) or below (absorption +features) the data minimum or maximum respectively are used by the centering +algorithms where sigma is equal to the value of the DATAPARS sigma parameter. +Most APPHOT users should leave this value at 0.0 which invokes the appropriate +default thresholding technique for each centering algorithm. Setting cthreshold +to INDEF turns off thresholding altogether for all the centering algorithms. +.le +.ls minsnratio = 1.0 +The minimum signal to noise ratio for object centering. If the estimated signal +to noise ratio is less than minsnratio the computed center will be returned +with an error flag. +.le +.ls cmaxiter = 10 +The maximum number of iterations performed by the centering algorithm. +All the centering algorithms use this parameter. +.le +.ls maxshift = 1.0 (scale units) +The maximum permissible shift of the center with respect to the initial +coordinates in units of the scale parameter. If the shift produced by the +centering algorithms is larger than maxshift, the computed center is returned +with an error flag. +.le +.ls clean = no +Symmetry-clean the centering subrater before centering? APPHOT users should +leave clean set to "no". +.le +.ls rclean = 1.0 (scale units) +The cleaning radius for the symmetry-clean algorithm in units of the scale +parameter. +.le +.ls rclip = 2.0 (scale units) +The clipping radius for the symmetry-clean algorithm in units of the scale +parameter. +.le +.ls kclean = 3.0 (sigma) +The number of sky background standard deviations for the symmetry-clean +algorithm where sigma is the value of the DATAPARS parameter sigma. +.le +.ls mkcenter = no +Mark the fitted object centers on the displayed image ? +.le +.ih +DESCRIPTION + +The centering algorithm parameters control the action of the centering +algorithms. The default parameters values have been proven to produce +reasonable results in the majority of cases. Several of the centering +parameters are defined in terms of the DATAPARS parameter \fIscale\fR, +the scale of the image, and \fIsigma\fR the standard deviation of +the sky pixels. + +For each object to be measured a subraster of data \fIcbox\fR / \fIscale\fR +pixels wide around the initial position supplied by the user is extracted +from the IRAF image. If scale is defined in units of the number +the half-width half-maximum of the psf per pixel, then a single value of +cbox can be used for centering objects in images with different psfs. + +If \fIclean\fR is "yes" the symmetry-clean algorithm is applied to the +centering subraster prior to centering. The cleaning algorithm attempts +to correct defects in the centering subraster by assuming that the image +is radially symmetric and comparing pixels on opposite sides of the center +of symmetry. The center of symmetry is assumed to be the maximum pixel +in the subraster, unless the maximum pixel is more than \fImaxshift / +scale\fR from the initial center, in which case the initial center is used +as the center of symmetry. Pixels inside the cleaning radius are not edited. +Pairs of pixels in the cleaning region, r > \fIrclean\fR / \fIscale\fR +and r <= \fIrclip\fR / \fIscale\fR and diametrically opposed about the +center of symmetry are tested for equality. If the difference between the +pixels is greater than \fIkclean * sigma\fR, the larger value is replaced +by the smaller. In the cleaning region the sigma is determined by the +noise model assumed for the data. Pairs of pixels in the clipping region, +r > \fIrclip\fR / \fIscale\fR are tested in the same manner as those in +the cleaning region. However the sigma employed is the sigma of the +sky background. Most APPHOT users should leave clean set to "no". + +New centers are computed using the centering algorithm specified by +\fIcalgorithm\fR, the data specified by \fIcbox / scale\fR, and pixels +that are some threshold above (below) an estimate of the local minimum +(maximum). \fICthreshold\fR values of 0.0, a positive number, and INDEF +invoke the default thresholding algorithm, a threshold equal to the +local minimum (maximum) plus (minus) \fIdatapars.sigma * cthreshold\fR, +and a threshold exactly equal to the local minimum (maximum) respectively. + +After thresholding the signal to noise ratio of the subraster is estimated. +If the SNR < \fIminsnratio\fR the new center is still computed but an error +flag is set. + +The default centering algorithm is \fIcentroid\fR. Centroid computes the +intensity weighted mean and mean error of the centering box x and y marginal +distributions using points in the marginal arrays above (below) the minimum +(maximum) data pixel plus (minus) a threshold value. + +The threshold value is either the mean, \fIdatapars.sigma * cthreshold\fR +above (below) the local minimum (maximum) if \fIcthreshold\fR is greater +than zero, or zero above (below) the local minimum (maximum) if +\fIcthreshold\fR is INDEF. The centroid algorithm is similar to that +by the old KPNO Mountain Photometry Code. Note that centroid is the only +centering algorithm which does not depend on the value of +\fIdatapars.fwhmpsf\fR. + +The centering algorithm \fIgauss\fR computes the new centers by fitting a +1D Gaussian function to the marginal distributions in x and y using a +fixed fwhmpsf set by \fIdatapars.fwhmpsf\fR. Initial guesses for the fit +parameters are derived from the data. The gauss algorithm iterates until +a best fit solution is achieved. + +The final centering algorithm choice \fIofilter\fR employs a variation of the +optimal filtering technique in which the profile is simulated by a triangle +function of width \fIdatapars.fwhmpsf\fR. + +The default thresholding algorithm for all centering algorithms other +than "centroid" is no thresholding. + +If the computed shift in either coordinate > \fImaxshift\fR / \fIscale\fR, +the new center is returned but an error flag is set. + +.ih +EXAMPLES +1. List the centering parameters. + +.nf + ap> lpar centerpars +.fi + +2. Edit the centering parameters + +.nf + ap> centerpars +.fi + +3. Edit the CENTERPARS parameters from with the PHOT task. + +.nf + da> epar phot + + ... edit a few phot parameters + + ... move to the centerpars parameter and type :e + + ... edit the centerpars parameters and type :wq + + ... finish editing the phot parameters and type :wq +.fi + +4. Save the current CENTERPARS parameter set in a text file ctrnite1.par. +This can also be done from inside a higher level task as in the +previous example. + +.nf + da> centerpars + + ... edit the parameters + + ... type ":w ctrnite1.par" from within epar +.fi + +.ih +BUGS + +.ih +SEE ALSO +center,phot,wphot,polyphot,radprof +.endhelp diff --git a/noao/digiphot/apphot/doc/daofind.hlp b/noao/digiphot/apphot/doc/daofind.hlp new file mode 100644 index 00000000..ad9687e5 --- /dev/null +++ b/noao/digiphot/apphot/doc/daofind.hlp @@ -0,0 +1,579 @@ +.help daofind May00 noao.digiphot.apphot +.ih +NAME +daofind -- automatically detect objects in an image +.ih +USAGE +daofind image +.ih +PARAMETERS +.ls image +The list of images in which objects are to be detected. +.le +.ls output = "default" +The name of the results file or the results directory. If output is +"default", "dir$default" or a directory specification then a results file +name of the form dir$root.extension.version is constructed, where +dir is the directory, root is the root image name, extension is "coo" +and version is the next available version number for the file. If the +output string is undefined then no output file is created. One output +file is created for every input image. +.le +.ls starmap = "" +The name of the image prefix and/or directory where the density enhancement +image will be stored. If starmap is undefined or a directory, +DAOFIND will create a temporary image which is deleted on exit from +the program. Otherwise starmap is prefixed to the image name +and the density enhancement image will be saved for use in a subsequent +run of DAOFIND. +.le +.ls skymap = "" +The name of the image prefix and/or directory where the mean density +image will be stored. If skymap is undefined or a directory, no mean density +image is created. Otherwise skymap is prefixed to the image name +and the mean density image will be saved on disk. Skymap is not used by +the DAOFIND algorithms, but may be used by the user as a check on DAOFIND, +since the sum of starmap and skymap is a type of best fit to the original +image. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The critical +parameters \fIfwhmpsf\fR and \fIsigma\fR are located here. If \fIdatapars\fR +is undefined then the default parameter set in the user's uparm directory is +used. +.le +.ls findpars = "" +The name of the file containing the object detection parameters. The +parameter \fIthreshold\fR is located here. If findpars is undefined then +the default parameter set in the user's uparm directory is used. +.le +.ls boundary = "nearest" +The type of boundary extension. The choices are: +.ls nearest +Use the value of the nearest boundary pixel. +.le +.ls constant +Use a constant value. +.le +.ls reflect +Generate a value by reflecting around the boundary. +.le +.ls wrap +Generate a value by wrapping around to the other side of the image. +.le +.le +.ls constant = 0 +The constant for constant boundary extension. +.le +.ls interactive = no +Interactive or batch mode? +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsout = ")_.wcsout" +The coordinate system of the output coordinates written to \fIoutput\fR. The +image header coordinate system is used to transform from the internal "logical" +pixel coordinate system to the output coordinate system. The 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 +The wcsout parameter defaults to the value of the package parameter of the same + name. The default values of the package parameters wcsin and wcsout are +"logical" 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 cacheing is +disabled. +.le +.ls verify = ")_.verify" +Automatically confirm the critical parameters when running in non-interactive +mode? Verify may be set to the apphot package parameter value (the default), +"yes", or "no". +.le +.ls update = ")_.update" +Automatically update the algorithm parameters in non-interactive mode if +verify is "yes". Update may be set to the apphot package parameter value +(the default), "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print out information about the progress of the task in non-interactive mode. +Verbose may be set to the apphot package parameter value (the default), "yes", +or "no". +.le +.ls graphics = ")_.graphics" +The standard graphics device. Graphics may be set to the apphot package +parameter value (the default), "yes", or "no". +.le +.ls display = ")_.display" +The standard image display device. Display may be set to the apphot package +parameter value (the default), "yes", or "no". By default graphics overlay is +disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables +graphics overlay with the IMD graphics kernel. Setting display to "stdgraph" +enables DAOFIND to work interactively from a contour plot. + +.le + +.ih +DESCRIPTION + +DAOFIND searches the IRAF images \fIimage\fR for local density maxima, +which have a full-width half-maximum of \fIdatapars.fwhmpsf\fR and a peak +amplitude greater than \fIfindpars.threshold\fR * \fIdatapars.sigma\fR above +the local background, and writes a list of detected objects in the file +\fIoutput\fR. The detected objects are also listed on the standard output +if the program is running in interactive mode, or in non-interactive mode +with the \fIverbose\fR switch is turned on. + +The coordinates written to \fIoutput\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 input and output image pixels are cached in memory. If +cacheing is enabled and DAOFIND is run interactively the first measurement +will appear to take a long time as the entire image must be read in before the +measurement is actually made. All subsequent measurements will be very fast +because DAOFIND 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. + +DAOFIND can be run either interactively or in batch mode by setting the +parameter \fIinteractive\fR. In interactive mode the user can examine, +adjust, and save algorithm parameters, and fit or refit the entire coordinate +list with the chosen parameter set. The \fIverify\fR parameter can be used +to automatically enable confirmation of the critical parameters +\fIdatapars.fwhmpsf\fR and \fIdatapars.sigma\fR when running in +non-interactive mode. + + +.ih +CURSOR COMMANDS + +.nf + + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify the critical parameters +w Save the current parameters +d Plot radial profile of star near cursor +i Interactively set parameters using star near cursor +f Find stars in the image +spbar Find stars in the image, output results +q Exit task + + + Colon Commands + +:show [data/find] List the parameters + + Colon Parameter Editing Commands + +# Image and file name parameters + +:image [string] Image name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full width half maximum of psf (scale units) +:emission [y/n] Emission feature (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good data value (counts) +:datamax [value] Maximum good data value (counts) + +# Noise description parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readout noise (electrons) + +# Observation parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Exposure time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Object detection parameters + +:nsigma [value] Size of Gaussian kernel (sigma) +:threshold [value] Detection intensity threshold (counts) +:ratio [value] Sigmay / sigmax of Gaussian kernel +:theta [value] Position angle of Gaussian kernel +:sharplo [value] Lower bound on sharpness +:sharphi [value] Upper bound on sharpness +:roundlo [value] Lower bound on roundness +:roundhi [value] Upper bound on roundness + +# Plotting and marking commands + +:mkdetections [y/n] Mark detections on the image display + + +The following commands are available inside the interactive setup menu. + + + Interactive Daofind Setup Menu + + v Mark and verify critical daofind parameters (f,s) + + f Mark and verify the full-width half-maximum of the psf + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value +.fi + +.ih +ALGORITHMS + +DAOFIND approximates the stellar point spread function with an elliptical +Gaussian function, whose sigma along the semi-major axis is 0.42466 * +\fIdatapars.fwhmpsf\fR / \fIdatapars.scale\fR pixels, semi-minor to semi-major +axis ratio is \fIratio\fR, and major axis position angle is \fItheta\fR. +Using this model, a convolution kernel, truncated at \fInsigma\fR sigma, +and normalized so as to sum to zero, is constructed. + +The density enhancement image \fIstarmap\fR is computed by convolving the input +image with the Gaussian kernel. This operation is mathematically equivalent to +fitting, in the least-squares sense, the image data at each point with a +truncated, lowered elliptical Gaussian function. After convolution each point +in \fIstarmap\fR contains as estimate of the amplitude of the best fitting +Gaussian function at that point. Each point in \fIskymap\fR, if the user +chooses to compute it, contains an estimate of the best fitting sky value +at that point. + +After image convolution , DAOFIND steps through \fIstarmap\fR searching +for density enhancements greater than \fIfindpars.threshold\fR * +\fIdatapars.sigma\fR, and brighter than all other density enhancements within +a semi-major axis of 0.42466 \fIfindpars.nsigma\fR * \fIdatapars.fwhmpsf\fR. +As the program selects candidates, it computes three shape characteristics, +sharpness and 2 estimates of roundness. The sharpness statistic measures the +ratio of, the difference between the height of the central pixel and the mean +of the surrounding non-bad pixels, to the height of the best fitting Gaussian +function at that point. The first roundness characteristic computes the ratio +of a measure of the bilateral symmetry of the object to a measure of the +four-fold symmetry of the object. The second roundness statistic measures the +ratio of, the difference in the height of the best fitting Gaussian function +in x minus the best fitting Gaussian function in y, over the average of the +best fitting Gaussian functions in x and y. The limits on these parameters +\fIfindpars.sharplo\fR, \fIfindpars.sharphi\fR \fIfindpars.roundlo\fR, and +\fIfindpars.roundhi\fR, are set to weed out non-astronomical objects and +brightness enhancements that are elongated in x and y respectively. + +Lastly the x and y centroids of the detected objects are computed by estimating +the x and y positions of the best fitting 1D Gaussian functions in x and y +respectively, a rough magnitude is estimated by computing the ratio of the +amplitude of the best fitting Gaussian at the object position to +\fIfindpars.threshold\fR * \fIdatapars.sigma\fR, and the object is added to +the output coordinate file. + +.ih +OUTPUT + +In interactive mode or in non-interactive with the verbose switch turned on +the following quantities are written to the terminal as each object is +detected. + +.nf + xcenter ycenter mag sharpness sround ground id + + where + + mag = -2.5 * log10 (peak density / detection threshold) +.fi + +The object centers are in pixels and the magnitude estimate measures the +ratio of the maximum density enhancement to the detection threshold. +Sharpness is typically around .5 to .8 for a star with a fwhmpsf similar to +the pattern star. Both sround and ground are close to zero for a truly +round star. Id is the sequence number of the star in the list. + +In both interactive and batch mode the full output is written to the text +file \fIoutput\fR. At the beginning of each file is a header, listing +the current values of the parameters when the first stellar record was +written. The parameters can subsequently be altered. + +.ih +EXAMPLES + +1. Run daofind interactively on dev$ypix using the image display +and image display cursor. Set the fwhmpsf and sigma parameters +with the graphics cursor, radial profile plot, and the interactive +setup key i. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> daofind dev$ypix interactive+ + + ... type ? to see help screen + + ... move display cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or + accept default with a CR + ... set the fwhmpsf and sigma using the graphics cursor and the + radial profile plot + ... typing <CR> leaves the parameters at their default values + ... type q to quit setup menu + + ... type the v key to verify the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... type the space bar to detect stars in the image + + ... a 1 line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit and q again to confirm the quit + + ... full output will appear in the text file ypix.coo.1 + +.fi + +2. Run daofind interactively on a single image using a contour plot in place +of the image and the graphics cursor in place of the image cursor. +This option is only useful for those (now very few) users who have access to +a graphics terminal but not to an image display server. Set the fwhmpsf and +sigma parameters with the graphics cursor and radial profile plot and the +interactive setup key i. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... make a contour plot of dev$ypix + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of ypix in the file ypix.plot + + ap> daofind dev$ypix display=stdgraph interactive+ + + ... type ? to see the help screen + + ... move graphics cursor to a setup star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or + accept the default with a CR + ... set the fwhmpsf and sigma using the graphics cursor and the + radial profile plot + ... typing <CR> leaves the parameters at their default values + ... type q to quit the setup menu + + ... type the v key to confirm the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... retype :.read ypix.plot1 to reload the contour plot + + ... type the space bar to detect stars in the image + + ... a 1 line summary of the answers will appear on the standard + output for each star measured + + ... full output will appear in the text file ypix.coo.2 + + ap> set stdimcur = <default> + + ... reset the image cursor to its default value + +.fi + + +3. Run DAOFIND interactively without using the image display cursor. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = text + + ... set the image cursor to the standard input + + ap> display dev$ypix 1 + + ... display the image + + ap> daofind dev$ypix interactive+ + + ... type ? for help + + ... type "442 409 101 i" in response to the image cursor query where + x and y are the coordinates of the star to be used as setup, + 101 is the default world coordinate system, and i enters the + interactive setup menu. + ... enter maximum radius in pixels of the radial profile or + type CR to accept the default + ... set the fwhmpsf and sigma using the graphics cursor and the + radial profile plot + ... typing <CR> leaves the parameters at their default values + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... type the space bar to detect stars in the image + + ... a 1 line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit and q again to confirm + + ... full output will appear in the text file ypix.coo.3 + + ap> set stdimcur = <default> + + ... reset the image cursor to its default value +.fi + + +4. Run daofind on a list of 3 images contained in the file imlist in batch mode. +The program will ask the user to verify that the fwhmpsf and the threshold are +correct before beginning execution. + +.nf + ap> type imlist + dev$ypix + dev$wpix + dev$pix + + ap> daofind @imlist + + ... the output will appear in ypix.coo.4, wpix.coo.1, pix.coo.1 +.fi + + +5. Display and find stars in an image section. Write the output coordinates +in the coordinate system of the parent image. Mark the detected stars on +the displayed image. + +.nf + ap> display dev$ypix[150:450,150:450] + + ... display the image section + + ap> daofind dev$ypix[150:450,150:450] wcsout=tv + + ... output will appear in ypix.coo.5 + + ap> tvmark 1 ypix.coo.5 col=204 +.fi + + +6. Repeat example 4 but submit the job to the background and turn off the +verify switch. + +.nf + ap> daofind @imlist verify- & + + ... the output will appear in ypix.coo.6, wpix.coo.2, pix.coo.2 +.fi + + +7. Use an image cursor command file to drive the daofind task. The cursor +command file shown below sets the fwhmpsf, sigma, and threshold parameters, +located stars in the image, updates the parameter files, and quits the task. + +.nf + ap> type cmdfile + : fwhmpsf 2.5 + : sigma 5.0 + : threshold 10.0 + \040 + w + q + + ap> daofind dev$ypix icommands=cmdfile verify- + + ... full output will appear in ypix.coo.7 +.fi + + +.ih +TIME REQUIREMENTS + +.ih +BUGS + +It is currently the responsibility of the user to make sure that the +image displayed in the frame is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the findpars mkdetections switch to +"yes". It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO +datapars, findpars +.endhelp diff --git a/noao/digiphot/apphot/doc/daofind.noao b/noao/digiphot/apphot/doc/daofind.noao new file mode 100644 index 00000000..74cc8f00 --- /dev/null +++ b/noao/digiphot/apphot/doc/daofind.noao @@ -0,0 +1,21 @@ + + +There is a bug in the iraf/daophot ii daofind centering code which results in +incorrect fractional pixel corrections being computed for the detected objects. +This error can most easily be detected by plotting the histogram of the +fractional pixel corrections for an image with a large number of detected +objects. The histogram will be modulated at around the 20% level with "peaks" +around the 0.33 and 0.66 fractional pixel values. + +This bug is fixed for the next release of iraf and in the external addon +package digiphotx version of daofind. There is no workaround although it +should be emphasized that this bug does not affect the centers computed by +the psf fitting code in the peak, nstar, and allstar tasks. Users concerned +with precision in the daofind results should upgrade their software, or +recenter the objects with the phot "centroid" (fast) or "gauss" (more precise) +routines. + +This bug is also present in the standalone version of daophot ii. I have +reported this problem to Peter Stetson and he has fixed it. Users concerned +about this bug in the standalone version of daophot ii should obtain a fix +from Peter Stetson. diff --git a/noao/digiphot/apphot/doc/datapars.hlp b/noao/digiphot/apphot/doc/datapars.hlp new file mode 100644 index 00000000..bacc5c77 --- /dev/null +++ b/noao/digiphot/apphot/doc/datapars.hlp @@ -0,0 +1,290 @@ +.help datapars May00 noao.digiphot.apphot +.ih +NAME +datapars -- edit the data dependent parameters +.ih +USAGE +datapars +.ih +PARAMETERS +.ls scale = 1.0 +The scale of the image in user units, e.g arcseconds per pixel. +All APPHOT distance dependent parameters are assumed to be in units of scale. +If scale = 1.0 these parameters are assumed to be in units of pixels. +Most APPHOT users should leave scale set to 1.0 unless they intend to +compare their aperture photometry results directly with data +in the literature. +.le +.ls fwhmpsf = 2.5 (scale units) +The full-width at half-maximum of the point spread function in scale units. +The DAOFIND, FITPSF and WPHOT tasks and the "gauss" and "ofilter" centering +algorithms depend on the value of fwhmpsf. APPHOT users can either determine +a value for fwhmpsf using an external task such as IMEXAMINE, or make use of +the interactive capabilities of the APPHOT tasks to set and store it. +.le +.ls emission = yes +The features to be measured are above sky. By default the APPHOT package +considers all features to be emission features. However all the package tasks +measure absorption features if emission is set to no. +.le +.ls sigma = INDEF +The standard deviation of the sky pixels. The DAOFIND task and the "constant" +sky fitting algorithm error estimate depend on the value of sigma. APPHOT +users should set sigma to a value which is representative of the noise +in the sky background. +.le +.ls datamin = INDEF +The minimum good pixel value. Datamin defaults to -MAX_REAL, the minimum +floating point number supported by the host computer. APPHOT users should +set this parameter if they wish to remove bad data from the sky pixel +distribution before the sky is fit or if they wish to flag stars with +bad data in the centering and / or photometry apertures. +.le +.ls datamax = INDEF +The maximum good pixel value. Datamax defaults to MAX_REAL the maximum +floating point number supported by the host computer. +APPHOT users should set this parameter if they wish to flag +saturated stars or stars with bad data in the centering and / or +photometry apertures. +.le +.ls noise = "poisson" +The noise model used to estimate the uncertainties in the computed APPHOT +magnitudes. The options are the following: +.ls poisson +Poisson statistics in the object and the sky background are used to estimate +the error in the object measurement. There are two components to the sky +noise measurement the sky noise in the object aperture and the mean error +in the estimated sky value. +.le +.ls constant +The standard deviation of the sky background is used to estimate the +error in the object measurement. There are two components to the error +estimate the sky noise in the object aperture and the mean error in the +estimated sky value. +.le + +Most APPHOT users should use the Poisson model appropriate for CCD detectors. +APPHOT users should also be aware that one or other of the parameters +gain or epadu must be set correctly in order to compute the magnitude +errors correctly. +.le +.ls ccdread = "" +The image header keyword defining the readout noise parameter whose units are +assumed to be electrons. +.le +.ls gain = "" +The image header keyword defining the gain parameter whose units are assumed +to be electrons per adu. +.le +.ls readnoise = 0.0 +The readout noise of the image in electrons. APPHOT users should set this +parameter or the ccdread parameter to its correct value before running any +of the APPHOT tasks. +.le +.ls epadu = 1.0 +The gain in electrons per adu. APPHOT users should set epadu or ain to its +correct value before running any of the APPHOT tasks in order to insure that +the magnitude error estimates are correct. +.le +.ls exposure = "" +The image header exposure time keyword. The time units are arbitrary but +must be consistent for any list of images whose magnitudes are to be compared. +The computed magnitudes are normalized to 1 timeunit. Setting the exposure +parameter will greatly simplify future reduction steps. The value of exposure +is recorded in the APPHOT output file. +.le +.ls airmass = "" +The image header airmass keyword. The airmass parameter is not used +directly by APPHOT but the airmass value is stored in the output file +and its presence there will simplify future calibration steps. +.le +.ls filter = "" +The image header filter id keyword. The filter parameter is not used +directly by APPHOT but the filter id is stored in the output file +and its presence there will simplify future calibration steps. +.le +.ls obstime = "" +The image header time of observation keyword. The obstime parameter is not used +directly by APPHOT but the obstime value is stored in the output file +and its presence there will simplify future calibration steps. +.le +.ls itime = 1.0 +The exposure time for the image in arbitrary units. The APPHOT magnitudes are +normalized to 1 timeunit using the value of exposure in the image header +if exposure is defined or the value of itime. +.le +.ls xairmass = INDEF +The airmass value. The airmass is read from the image header if airmass +is defined or from xairmass. The airmass value is stored in the APPHOT +output files. +.le +.ls ifilter = "INDEF" +The filter id string. The filter id is read from the image header if filter +is defined otherwise from ifilter. The filter id is stored in the APPHOT +output files. +.le +.ls otime = "INDEF" +The value of the time of observation. The time of observation is read from +the image header if obstime is defined otherwise from otime. The time of +observation is stored in the APPHOT output files. +.le +.ih +DESCRIPTION +\fIDatapars\fR sets the image data dependent parameters. These parameters are +functions, of the instrument optics, the noise characteristics and range of +linearity of the detector, and the observing conditions. Many of the +centering, sky fitting, and photometry algorithm parameters in the CENTERPARS, +FITSKYPARS and PHOTPARS parameter sets scale with the data dependent +parameters. + +The parameter \fIscale\fR sets the scale of the apertures used by the +centering, sky fitting and photometry algorithms. Scale converts radial +distance measurements in pixel units to radial distance measurements in +scale units. The APPHOT parameters, cbox, maxshift, rclean and rclip +in the CENTERPARS parameter set; annulus, dannulus, and rgrow in +the FITSKYPARS parameter set; and apertures in the PHOTPARS +parameter set are expressed in units of the scale. The scale parameter is +useful in cases where the observations are to be compared to published +aperture photometry measurements in the literature. + +The parameter \fIfwhmpsf\fR defines the full-width at half-maximum of the +stellar point spread function. Most APPHOT tasks and algorithms do not +require this parameter. The exceptions are the DAOFIND task, the centering +algorithms "gauss" and "ofilter", the FITPSF task, and the WPHOT task. + +By setting the \fIscale\fR and \fIfwhmpsf\fR appropriately the aperture +sizes and radial distances may be expressed in terms of the half-width +at half-maximum of the stellar point spread function. The way to do this +is to define the scale parameter in units of the number of half-width at +half-maximum per pixel, set the fwhmpsf parameter to 2.0, and then +set the remaining scale dependent centering, sky fitting and photometry +algorithm parameters in CENTERPARS, FITSKYPARS and PHOTPARS to +appropriate values in units of the half-width at half-maximum of the +point-spread function. Once an optimum set of algorithm parameters is +chosen, the user need only alter the DATAPARS scale parameter before +executing an APPHOT task on a new image. + +If \fIemission\fR is "yes", the features to be measured are assumed to be +above sky. By default the APPHOT package considers all measurements to +be measurements of emission features. In most cases APPHOT users should +leave emission set to "yes". + +The parameter \fIsigma\fR estimates the standard deviation of the sky +background pixels. The star finding algorithm in DAOFIND uses sigma +and the \fIfindpars.threshold\fR parameter to define the stellar +detection threshold in adu. The centering algorithms uses sigma, +1) with the \fIcenterpars.kclean\fR parameter to define deviant pixels +if \fIcenterpars.clean\fR is enabled; 2) to estimate the signal to +noise ratio in the centering box; 3) and with the \fIcenterpars.cthreshold\fR +parameter to define the lower intensity limit for the pixels to be used +for centering. If sigma is undefined or <= 0.0 1) no cleaning is performed +regardless of the value of centerpars.clean; 2) the background +noise in the centering box is assumed to be 0; and 3) default cutoff +intensity intensity is used for centering. + +The \fIdatamin\fR and \fIdatamax\fR parameters define the good data range. +If datamin or datamax are defined bad data is removed from the sky pixel +distribution before the sky is fit, data containing bad pixels in the +photometry apertures is flagged, and the corresponding aperture photometry +magnitudes are set to INDEF. APPHOT users should set datamin and datamax +to appropriate values before running the APPHOT tasks. + +Two noise models are available "constant" and "poisson". If \fInoise\fR = +constant, the total noise is assumed to be due to noise in the sky background +alone. If \fInoise\fR = poisson, the total noise includes Poisson noise from +the object and the sky noise. + +The parameters \fIgain\fR and \fIepadu\fR define the image gain. +The gain parameter specifies which keyword in the image header contains +the gain value. If gain is undefined or not present in the image header +the value of epadu is used. Epadu must be in units of electrons per adu. +APPHOT users should set either gain or epadu before running any +APPHOT tasks to insure the magnitude error computations are correct. + +The two parameters \fIccdread\fR and \fIreadnoise\fR define the image +readout noise. The ccdread parameter specifies which keyword in the +image header contains the readout noise value. If ccdread is undefined or +not present in the image header the value of readnoise is used. +Readnoise is assumed to be in units of electrons. +APPHOT users should set either ccdread or readnoise before running any +APPHOT tasks to insure the magnitude error computations are correct. + +The magnitudes are normalized to an exposure time of 1 timeunit using +the value of the exposure time in the image header parameter \fIexposure\fR +or \fIitime\fR. If exposure is undefined or not present in the image header +the value of itime is used. Itime can be in arbitrary units. +Setting either exposure or itime will simplify future analysis steps. + +The parameters \fIairmass\fR and \fIxairmass\fR define the airmass +of the observation. The airmass parameter specifies which keyword in the +image header contains the airmass value. If airmass is undefined or +not present in the image header the value of xairmass is used. +The airmass values are not used in any APPHOT computations, however their +presence in the APPHOT output files will simplify future reduction steps. + +The parameters \fIfilter\fR and \fIifilter\fR define the filter +of the observation. The filter parameter specifies which keyword in the +image header contains the filter id. If filter is undefined or not present +in the image header the value of ifilter is used. The filter id values are +not used in any APPHOT computations, however their presence in the APPHOT +output files can will simplify future reduction steps. + +The parameters \fIobstime\fR and \fIotime\fR define the time +of the observation (e.g. UT). The obstime parameter specifies which keyword +in the image header contains the time stamp of the observation. If obstime is +undefined or not present in the image header the value of otime is used. +The time of observations values are not used in any APPHOT +computations, however their presence in the APPHOT output files can +greatly simplify future reduction steps. + +.ih +EXAMPLES + +1. List the data dependent parameters. + +.nf + ap> lpar datapars +.fi + +2. Edit the data dependent parameters. + +.nf + ap> datapars +.fi + +3. Edit the DATAPARS parameters from within the PHOT task. + +.nf + da> epar phot + + ... edit a few parameters + + ... move to the datapars parameter and type :e + + ... edit the datapars parameters and type :wq + + ... finish editing the phot parameters and type :wq +.fi + +4. Save the current DATAPARS parameter set in a text file datnite1.par. +This can also be done from inside a higher level task as in the +previous example. + +.nf + da> datapars + + ... edit a few parameters + + ... type ":w datnite1.par" from within epar +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS + +.ih +SEE ALSO +epar,lpar,daofind,center,fitsky,phot,wphot,polyphot,radprof,fitpsf +.endhelp diff --git a/noao/digiphot/apphot/doc/findpars.hlp b/noao/digiphot/apphot/doc/findpars.hlp new file mode 100644 index 00000000..22fa7668 --- /dev/null +++ b/noao/digiphot/apphot/doc/findpars.hlp @@ -0,0 +1,134 @@ +.help findpars May00 noao.digiphot.apphot +.ih +NAME +findpars -- edit the star detection parameters +.ih +USAGE +findpars +.ih +PARAMETERS +.ls threshold = 4.0 (sigma) +The object detection threshold above local background in units of +\fIdatapars.sigma\fR. +.le +.ls nsigma = 1.5 +The semi-major axis of the Gaussian convolution kernel used to computed the +density enhancement and mean density images in Gaussian sigma. This semi- +major axis is equal to min (2.0, 0.42466 * \fInsigma\fR * +\fIdatapars.fwhmpsf\fR / \fIdatapars.scale\fR) pixels. +.le +.ls ratio = 1.0 +The ratio of the sigma of the Gaussian convolution kernel along the minor axis +direction to the sigma along the major axis direction. \fIRatio\fR defaults +to 1.0 in which case the image is convolved with a circular Gaussian. +.le +.ls theta = 0.0 +The position angle of the major axis of the Gaussian convolution kernel. +\fITheta\fR is measured in degrees counter-clockwise from the x axis. +.le +.ls sharplo = .2, sharphi = 1.0 +\fISharplo\fR and \fIsharphi\fR are numerical cutoffs on the image sharpness +statistic designed to eliminate brightness maxima which are due to bad pixels +rather than to astronomical objects. +.le +.ls roundlo = -1.0 roundhi = 1.0 +\fIRoundlo\fR and \fIroundhi\fR are numerical cutoffs on the image roundness +statistic designed to eliminate brightness maxima which are due to bad rows or +columns, rather than to astronomical objects. +.le +.ls mkdetections = no +Mark the positions of the detected objects on the displayed image ? +.le + +.ih +DESCRIPTION + +DAOFIND approximates the stellar point spread function with an elliptical +Gaussian function, whose sigma along the semi-major axis is 0.42466 * +\fIdatapars.fwhmpsf\fR / \fIdatapars.scale\fR pixels, semi-minor to semi-major +axis ratio is \fIratio\fR, and major axis position angle is \fItheta\fR. +Using this model, a convolution kernel, truncated at \fInsigma\fR sigma, +and normalized to sum to zero, is constructed. + +The density enhancement image \fIstarmap\fR is computed by convolving the input +image with the Gaussian kernel. This operation is mathematically equivalent to +fitting, in the least-squares sense, the image data at each point with a +truncated, lowered elliptical Gaussian function. After convolution each point +in \fIstarmap\fR contains as estimate of the amplitude of the best fitting +Gaussian function at that point. Each point in \fIskymap\fR, if the user +chooses to compute it, contains an estimate of the best fitting sky value +at that point. + +After image convolution DAOFIND steps through \fIstarmap\fR searching +for density enhancements greater than \fIfindpars.threshold\fR * +\fIdatapars.sigma\fR, and brighter than all other density enhancements +within a semi-major axis of 0.42466 \fIfindpars.nsigma\fR * +\fIdatapars.fwhmpsf\fR. As the program selects candidates, it computes two +shape characteristics sharpness and roundness. The sharpness statistic +measures the ratio of the difference between the height of the central pixel +and the mean of the surrounding non-bad pixels, to the height of the best +fitting Gaussian function at that point. The roundness statistics measures +the ratio of, the difference in the height of the best fitting Gaussian +function in x minus the best fitting Gaussian function in y, over the average +of the best fitting Gaussian functions in x and y. The limits on these +parameters \fIfindpars.sharplo\fR, \fIfindpars.sharphi\fR, +\fIfindpars.roundlo\fR, and \fIfindpars.roundhi\fR, are set to weed out +non-astronomical objects and brightness enhancements that are elongated in +x and y respectively. + +Lastly the x and y centroids of the detected objects are computed by +estimating the x and y positions of the best fitting 1D Gaussian +functions in x and y respectively, a rough magnitude is estimated +by computing the ratio of the amplitude of the best fitting Gaussian at +the object position to \fIfindpars.threshold\fR * \fIdatapars.sigma\fR, +and the object is added to the output coordinate file. + + +.ih +EXAMPLES + +1. List the object detection parameters. + +.nf + da> lpar findpars +.fi + +2. Edit the object detection parameters. + +.nf + da> findpars +.fi + +3. Edit the FINDPARS parameters from within the DAOFIND task. + +.nf + da> epar daofind + + ... edit a few daofind parameters + + ... move to the findpars parameter and type :e + + ... edit the findpars parameter and type :wq + + ... finish editing the daofind parameters and type :wq +.fi + +4. Save the current FINDPARS parameter set in a text file fndnite1.par. +This can also be done from inside a higher level task as in the previous +example. + +.nf + da> findpars + + ... edit the parameters + + ... type ":w fndnite1.par" from within epar +.fi + +.ih +BUGS + +.ih +SEE ALSO +daofind, datapars +.endhelp diff --git a/noao/digiphot/apphot/doc/fitpsf.hlp b/noao/digiphot/apphot/doc/fitpsf.hlp new file mode 100644 index 00000000..8a229508 --- /dev/null +++ b/noao/digiphot/apphot/doc/fitpsf.hlp @@ -0,0 +1,680 @@ +.help fitpsf May00 noao.digiphot.apphot +.ih +NAME +fitpsf -- model the point spread function with an analytic function +.ih +USAGE +fitpsf image box +.ih +PARAMETERS +.ls image +The list of images containing the objects to be measured. +.le +.ls box +The width of the fitting box in scale units. +.le +.ls coords = "" +The list of text files containing initial coordinates for the objects to +be centered. Objects are listed in coords one object per line with the +initial coordinate values in columns one and two. The number of coordinate +files must be zero, one, or equal to the number of images. +If coords is "default", "dir$default", or a directory specification then an +coords file name of the form dir$root.extension.version is constructed and +searched for, where dir is the directory, root is the root image name, +extension is "coo" and version is the next available version number for the +file. +.le +.ls output = "default" +The name of the results file or results directory. If output is +"default", "dir$default", or a directory specification then an output file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "psf" and version is +the next available version number for the file. The number of output files +must be zero, one, or equal to the number of image files. In both interactive +and batch mode full output is written to output. In interactive mode +an output summary is also written to the standard output. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. +The critical parameters \fIfwhmpsf\fR and \fIsigma\fR are located in +datapars. If datapars is undefined then the default parameter set in +uparm directory is used. +.le +.ls function = "radgauss" +The function to be fit. The options are: +.ls radgauss +A 2D radial Gaussian function is fit. The parameters of the fitting function +are: x and y center, sigma of the Gaussian, amplitude of the Gaussian and +the local sky value. +.le +.ls elgauss +A 2D elliptical Gaussian function is fit. The parameters of the fitting +function are: x and y center, x and y sigma of the Gaussian, amplitude of +the Gaussian and the local sky value. +.le +.ls moments +The 0th, 1st and 2nd order moments are computed and used to derive +estimates of the +x and y center values, radius of gyration, ellipticity and position +angle of the object. +.le +.le +.ls maxiter = 50 +The maximum number of iterations that the non-linear fitting routines will +perform in an attempt to find a satisfactory fit. +.le +.ls nreject = 0 +The maximum number of rejection cycles performed after the fit. +The default is no rejection. +.le +.ls kreject = 3.0 +The k-sigma rejection limit in units of sigma. +.le +.ls mkbox = no +Draw the fitting box on the image display? +.le +.ls interactive = yes +Run the task interactively ? +.le +.ls icommands = "" +The image cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.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 cacheing is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical parameters in non-interactive mode ? Verify may be set to +the apphot package parameter value (the default), "yes", or "no. +.le +.ls update = ")_.update" +Update the critical parameters in non-interactive mode if verify is set of +"yes" ? Update may be set to the apphot package parameter value (the default), +"yes", or "no. + +.le +.ls verbose = ")_.verbose" +Print messages on the terminal in non-interactive mode ? Verbose may be set +to the apphot package parameter value (the default), "yes", or "no. + +.le +.ls graphics = ")_.graphics" +The default graphics device. Graphics may be set to the apphot package +parameter value (the default), "yes", or "no. +.le +.ls display = ")_.display" +The default display device. Display may be set to the apphot package +parameter value (the default), "yes", or "no. By default graphics overlay +is disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" +enables graphics overlay with the IMD graphics kernel. Setting display to +"stdgraph" enables FITPSF to work interactively from a contour plot. +.le + +.ih +DESCRIPTION + +FITPSF models the stellar brightness distribution of objects in the IRAF image +\fIimage\fR using non-linear least squares techniques and writes the +list of model parameters and associated errors to the file \fIoutput\fR. +Initial coordinates for the objects are read from the image cursor or +the text file \fIcoords\fR. Pixels in a subraster of width \fIbox * scale\fR +are extracted and used in the fit. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\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 input image pixels are cached in memory. If cacheing +is enabled and FITPSF is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because FITPSF +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. + +FITPSF can be run either interactively or in batch mode by setting the +parameter \fIinteractive\fR. In interactive mode starting x and y positions +can either be read directly from the image cursor or read from the text +file specified by \fIcoords\fR. In batch mode the estimated +positions can be read from the text file \fIcoords\fR or the image cursor +parameter \fIicommands\fR can be redirected to a text file containing +a list of cursor commands. + +.ih +CURSOR COMMANDS + +The currently available cursor commands are listed below. + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify the critical parameters +w Save the current parameters +d Plot radial profile of current star +i Interactively set parameters using current star +f Fit current star +spbar Fit current star, output results +m Move to next star in coordinate list +n Fit next star in coordinate list, output results +l Fit remaining stars in coordinate list, output results +e Print error messages +r Rewind the coordinate list +q Exit task + + + + Colon Commands + +:show [data/fit] List the parameters +:m [n] Move to next [nth] star in coordinate list +:n [n] Fit next [nth] star in coordinate list, output results + + + Colon Parameter Editing Commands + +# Image and file name parameters + +:image [string] Image name +:coords [string] Coordinate file name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Scale factor (scale units) +:emission [y/n] Emission feature (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good data value (counts) +:datamax [value] Maximum good data value (counts) + +# Noise description parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readnoise (electrons) + +# Observation parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Exposure time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Fitting parameters + +:function [string] PSF model (radgauss|elgauss|moments) +:box [value] Width of the fitting box (scale units) +:maxiter [value] Maximum number of iterations +:nreject [value] Maximum number of rejection cycles +:kreject [value] Rejection limit (sigma) + +# Plotting and marking functions + +:mkbox [y/n] Mark the fitting box on the display + + +The following command are available from within the interactive setup menu. + + + Interactive Fitpsf Setup Menu + + v Mark and verify the critical fitpsf parameters (f,s,b) + + f Mark and verify the full-width half-maximum of the psf + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + + b Mark and verify the half-width of the fitting box +.fi + +.ih +ALGORITHMS + +The fitting parameters are \fIfunction\fR, the functional form of the model +to be fit, \fImaxiter\fR, the maximum number of iterations per fit, +\fIkreject\fR, the K-sigma rejection limit and \fInreject\fR, the maximum +number of rejection cycles. The currently available functions are a 2D +moments analysis "moments", a 2D radial Gaussian "radgauss", and a +2D elliptical Gaussian "elgauss". + +The weighting of the fit is determined by the parameter \fInoise\fR in the +\fIdatapars\fR file. The two options are \fIconstant\fR, in which all the +weights are set to 1 and \fIpoisson\fR in which the weights are equal to +the inverse of the counts divided by the image gain read from the datapars +\fIgain\fR or \fIepadu\fR parameters plus the square of the readout noise +determined from the datapars parameters \fIccdread\fR or \fIreadnoise\fR. +If \fIfunction\fR is either "radgauss" or "ellgauss" then the datapars +parameter \fIfwhmpsf\fR is used to determine the initial guess for the +Gaussian sigma. The datapars parameter \fIthreshold\fR determines the +intensity threshold above which the moment analysis is performed. + +.ih +OUTPUT + +In interactive mode the following quantities are printed on the +terminal as shown below, for the radial Gaussian, elliptical Gaussian and +moments functions respectively. + +.nf + image xcenter ycenter rsigma amplitude sky err + + image xcenter ycenter xsigma ysigma rot amplitude sky err + + image xcenter ycenter rgyrat ellip pa amplitude sky err + +.fi + +In both interactive and batch mode the full output is written to the +text file \fIoutput\fR. At the beginning of each file is a header +listing the values of the parameters when the first stellar +record was written. These parameters can be subsequently altered. +For each star measured the following record is written for the radial +Gaussian, elliptical Gaussian, and moments functions respectively. + +.nf + image xinit yinit id coords lid + xcenter ycenter rsigma amplitude sky + excenter eycenter ersigma eamplitude esky ier error + + image xinit yinit id coords lid + xcenter ycenter xsigma ysigma rot amplitude sky + excenter eycenter exsigma eysigma erot eamplitude esky ier\ + error + + image xinit yinit id coords lid + xcenter ycenter rgyrat ellip pa amplitude sky + excenter eycenter ergyrat eellip epa eamplitude esky ier\ + error +.fi + +Image and coords are the name of the image and coordinate files respectively. +Id and lid are the sequence numbers of stars in the output and coordinate +files respectively and xinit and yinit are the initial positions. +Xcenter and ycenter are the computed x and y +positions of the object. Rsigma, xsigma and ysigma are the distance from +the center of the Gaussian at which the Gaussian is equal to exp (-0.5) +of its central value. Xsigma and ysigma refer to those values along the major +and minor axes of the ellipse respectively. The amplitude and sky refer to +the amplitude of +the Gaussian function and a constant background value respectively. +If function = "moments" amplitude and sky refer to the total intensity +above threshold and sky is the threshold value. Rot and pa are position angles +of the major axis measured counter-clockwise with respect to the x axis. +Rgyrat is the radius +of gyration of the object and ellip its ellipticity. +Quantities prefixed by an e represent the errors in the corresponding +fitted parameters. + +.ih +ERRORS + +If all went well in the fitting process the error code stored in the ier +field described above is 0. Non-zero values of ier flag the following error +conditions. + +.nf + 0 # No error + 401 # The fitting box is off the image + 402 # The fitting box is partially off the image + 403 # There are too few points to fit the function + 404 # The fit is singular + 405 # The fit did not converge +.fi + +.ih +EXAMPLES + +1. Compute the radial Gaussian function parameters for a few stars in dev$ypix +using the display and the image cursor. Setup the task parameters using +the interactive setup menu defined by the i key command. Use uniform +weighting. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> fitpsf dev$ypix 11 noise=constant + + ... type ? to see the help screen + + ... move the image cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or type + CR to accept the default value + ... set the fitting box width, fwhmpsf, and sigma using the graphics + cursor and the stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... move the image cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and another q to confirm the quit + + ... the full output will appear in ypix.psf.1 +.fi + +2. Compute the radial Gaussian function parameters for a few stars in +dev$ypix using the contour plot and the graphics cursor. Setup the task +parameters using the interactive setup menu defined by the i key command. +Use uniform weighting. + +.nf + ap> show stdimcur + + ... save the current value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of dev$ypix in the file ypix.plot1 + + ap> fitpsf dev$ypix 11.0 noise=constant display=stdgraph + + ... type ? to get a short help page on the screen + + ... move the graphics cursor to a star + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels of the radial profile or + type CR to accept the default value + ... set the fitting box width, fwhmpsf, and sigma using the graphics + cursor and the stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify critical parameters + + ... type the w key to save the parameters in the parameter files + + ... retype :.read ypix.plot1 to reload the contour plot + + ... move the graphics cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to confirm the quit + + ... full output will appear in the text file ypix.psf.2 +.fi + + +3. Setup and run FITPSF interactively on a list of objects temporarily +overriding the fwhmpsf and sigma parameters determined in examples 1 or 2. +Use uniform weighting. + +.nf + ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify- + + ... make a coordinate list + + ... the output will appear in the text file ypix.coo.1 + + ap> fitpsf dev$ypix 11.0 fwhmpsf=2.6 noise=constant coords=ypix.coo.1 + + ... type ? for optional help + + + ... move the graphics cursor to the stars and tap space bar + + or + + ... select stars from the input coordinate list with m / :m # + and measure with spbar + + ... measure stars selected from the input coordinate list + with n / n # + + ... a one line summary of results will appear on the standard output + for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.psf.3 ... +.fi + + +4. Display and fit some stars in an image section and write the output +coordinates in the coordinate system of the parent image. Use uniform +weighting. + +.nf + ap> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + ap> fitpsf dev$ypix[150:450,150:450] 11.0 noise=constant wcsout=tv + + ... move cursor to stars and type spbar + + ... type q to quit and q again to confirm quit + + ... output will appear in ypix.psf.4 + + ap> pdump ypix.psf.4 xc,yc yes | tvmark 1 STDIN col=204 +.fi + + +5. Run FITPSF in batch mode using the coordinate file and the previously +saved parameters. Use uniform weighting. Verify the critical parameters. + +.nf + ap> fitpsf dev$ypix 11.0 coords=ypix.coo.1 noise=constant verify+ \ + inter- + + ... output will appear in ypix.psf.5 ... +.fi + +6. Repeat example 5 but assume that the input coordinate are ra and dec +in degrees and degrees, turn off verification, and submit the task to to +the background. Use uniform weighting. + +.nf + ap> display dev$ypix 1 + + ap> rimcursor wcs=world > radec.coo + + ... move to selected stars and type any key + + ... type ^Z to quit + + ap> fitpsf dev$ypix 11.0 coords=radec.coo noise=constant \ + wcsin=world verify- inter- & + + ... output will appear in ypix.psf.6 + + ap> pdump ypix.psf.6 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars on the display +.fi + +7. Run FITPSF interactively without using the image display. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = text + + ... set the image cursor to the standard input + + ap> fitpsf dev$ypix 11.0 coords=ypix.coo.1 noise=constant + + ... type ? for optional help + + ... type :m 3 to set the initial coordinates to those of the + third star in the list + + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to enter the default menu + ... set the fwhmpsf, sigma, and fitting box size using the + graphics cursor and the stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its default + value + ... type q to quit the setup menu + + ... type r to rewind the coordinate list + + ... type l to measure all the stars in the coordinate list + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... full output will appear in the text file ypix.psf.7 + + ap> set stdimcur = <default> + + ... reset the value of stdimcur +.fi + +8. Use an image cursor command file to drive the FITPSF task. The cursor command +file shown below sets the fwhmpsf, sigma, and noise, computes the model +fit parameter values for 3 stars, updates the parameter files, and quits +the task. + +.nf + ap> type cmdfile + : fwhmpsf 2.6 + : sigma 5.0 + : noise constant + 442 410 101 \040 + 349 188 101 \040 + 225 131 101 \040 + w + q + + ap> fitpsf dev$ypix 11.0 icommands=cmdfile verify- + + ... full output will appear in ypix.psf.8 +.fi + + +.ih +BUGS + +In interactive mode the user should not change the type function to be fit +after the first record is written to the output file. In this case the file +header and record structure will not match. + +It is currently the responsibility of the user to make sure that the +image displayed in the frame is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the mkbox switch to"yes". +It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO + +datapars, radprof +.endhelp diff --git a/noao/digiphot/apphot/doc/fitsky.hlp b/noao/digiphot/apphot/doc/fitsky.hlp new file mode 100644 index 00000000..5fc07de9 --- /dev/null +++ b/noao/digiphot/apphot/doc/fitsky.hlp @@ -0,0 +1,632 @@ +.help fitsky Dec92 noao.digiphot.apphot +.ih +NAME +fitsky - determine the mode, sigma and skew of the sky pixels +.ih +USAGE +fitsky image +.ih +PARAMETERS +.ls image +The list of images containing the sky regions to be fit. +.le +.ls coords = "" +The list of text files containing initial coordinates for the objects to +be centered. Objects are listed in coords one object per line with the +initial coordinate values in columns one and two. The number of coordinate +files must be zero, one, or equal to the number of images. +If coords is "default", "dir$default", or a directory specification then an +coords file name of the form dir$root.extension.version is constructed and +searched for, where dir is the directory, root is the root image name, +extension is "coo" and version is the next available version number for the +file. +.le +.ls output = "default" +The name of the results file or results directory. If output is +"default", "dir$default", or a directory specification then an output file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "sky" and version is +the next available version number for the file. The number of output files +must be zero, one, or equal to the number of image files. In both interactive +and batch mode full output is written to output. In interactive mode +an output summary is also written to the standard output. +.le +.ls plotfile = "" +The name of the file containing radial profile plots of the stars written +to the output file. If plotfile is defined then a radial profile plot +is written to plotfile every time a record is written to \fIoutput\fR. +The user should be aware that this can be a time consuming operation. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. +The critical parameters \fIfwhmpsf\fR and \fIsigma\fR are located in +datapars. If datapars is undefined then the default parameter set in +uparm directory is used. +.le +.ls fitskypars = "" +The name of the text file containing the sky fitting parameters. The critical +parameters \fIsalgorithm\fR, \fIannulus\fR, and \fIdannulus\fR are located here. +If \fIfitskypars\fR is undefined then the default parameter set in uparm +directory is used. +.le +.ls interactive = yes +Run the task interactively ? +.le +.ls radplots = no +If \fIradplots\fR is "yes" and PHOT is run in interactive mode, a radial +profile of each star is plotted on the screen after the star is measured. +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.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 cacheing is +disabled. +.le +.ls verify = ")._verify" +Verify the critical parameters in non-interactive mode ? Verify may be set to + the apphot package parameter value (the default), "yes", or "no. +.le +.ls update = ")_.update" +Update the critical parameters in non-interactive mode if verify is yes ? +Update may be set to the apphot package parameter value (the default), "yes", +or "no. + +.le +.ls verbose = ")_.verbose" +Print messages on the terminal in non-interactive mode ? Verbose may be set to +the apphot package parameter value (the default), "yes", or "no. + +.le +.ls graphics = ")_.graphics" +The default graphics device. Graphics may be set to the apphot package +parameter value (the default), "yes", or "no. +.le +.ls display = ")_.display" +The default display device. Display may be set to the apphot package parameter +value (the default), "yes", or "no. By default graphics overlay is disabled. +Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables graphics +overlay with the IMD graphics kernel. Setting display to "stdgraph" enables +FITSKY to work interactively from a contour plot. +.le + +.ih +DESCRIPTION +FITSKY computes accurate sky values for a set of objects in the IRAF image +\fIimage\fR, whose coordinates are read from the text file \fIcoords\fR or +the image display cursor, and writes the computed sky values to the text +file \fIoutput\fR. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\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 input image pixels are cached in memory. If cacheing +is enabled and FITSKY is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because FITSKY +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. + +FITSKY can be run either interactively or in batch mode by setting the parameter +\fIinteractive\fR. In interactive mode the user may either define the +list of objects to be measured interactively with the image cursor or +create an object list prior to running FITSKY. In either case the user may +adjust the sky fitting parameters until a satisfactory measurement is achieved. +coordinate list with that set of parameters. In batch mode +positions are read from the text file \fIcoords\fR or the image cursor +parameter \fIicommands\fR can be redirected to a cursor command file. + +.ih +CURSOR COMMANDS + +The following cursor commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify the critical parameters +w Save the current parameters +d Plot radial profile of current star +i Interactively set parameters using current star +f Fit sky for current star +spbar Fit sky for current star, output results +m Move to next star in coordinate list +m Fit sky for next star in coordinate list, output results +l Fit sky for remaining stars in coordinate list, output results +e Print error messages +r Rewind the coordinate list +q Exit task + + + Colon commands + +:show [data/sky] List the parameters +:m [n] Move to the next [nth] star in coordinate list +:n [n] Fit sky to next [nth] star in coordinate list, output results + + Colon Parameter Editing Commands + +# Image and file name parameters + +:image [string] Image name +:coords [string] Coordinate file name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full width half maximum PSF (scale units) +:emission [y/n] Emission feature (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good pixel value (counts) +:datamax [value] Maximum good pixel value (counts) + +# Noise parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readout noise (electrons) + +# Observations parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Exposure time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Sky fitting algorithm parameters + +:salgorithm [string] Sky fitting algorithm +:skyvalue [value] User supplied sky value (counts) +:annulus [value] Inner radius of sky annulus (scale units) +:dannulus [value] Width of sky annulus (scale units) +:khist [value] Sky histogram extent (+/- sky sigma) +:smooth [y/n] Lucy smooth the sky histogram +:binsize [value] Resolution of sky histogram (sky sigma) +:smaxiter [value] Maximum number of iterations +:sloclip [value] Low side clipping factor (percent) +:shiclip [value] High side clipping factor (percent) +:snreject [value] Maximum number of rejection cycles +:sloreject [value] Low side pixel rejection limits (sky sigma) +:shireject [value] High side pixel rejection limits (sky sigma) +:rgrow [value] Region growing radius (scale units) + +# Marking and plotting parameters + +:mksky [y/n] Mark sky annuli on the display +:radplot [y/n] Plot radial profile of sky pixels + + +The following commands are available from within the interactive setup menu. + + + Interactive Fitsky Setup Menu + + v Mark and verify the critical parameters (a,d,s) + + s Mark and verify the standard deviation of the sky + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + + a Mark and verify the inner radius of the sky annulus + d Mark and verify the width of the sky annulus + g Mark and verify the region growing radius +.fi + +.ih +ALGORITHMS +A brief description of the data dependent parameters and the sky fitting +parameters can be found in the online manual pages for the DATAPARS +and FITSKYPARS tasks. + +.ih +OUTPUT +In interactive mode the following quantities are printed on the standard +output as each object is measured. + +.nf + image xinit yinit msky stdev sskew nsky nsrej error +.fi + +In both interactive and batch mode full output is written to the +text file \fIoutput\fR. At the beginning of each file is a header listing +the current values of the parameters when the first stellar record was +written. These parameters can be subsequently altered. For each star +measured the following record is written. + +.nf + image xinit yinit id coords lid + msky stdev sskew nsky nsrej sier error +.fi + +Image and coords are the name of the image and coordinate file respectively. +Id and lid are the sequence numbers of stars in the output and coordinate +files respectively. Sier and error are the error code and accompanying +error message respectively. Xinit and yinit are the center coordinates +of the sky annulus in pixels. Msky, stdev and sskew are the sky value, +standard deviation and skew respectively. Nsky and nsrej are the number of +sky pixels used and the number of sky pixels rejected respectively. + +In interactive mode a radial profile of each measured object is plotted +in the graphics window if \fIradplots\fR is "yes". + +In interactive and batch mode a radial profile plot is written to +\fIplotfile\fR if it is defined each time the result of an object +measurement is written to \fIoutput\fR . + +.ih +ERRORS +If all goes well during the sky fitting process then the error code sier +will be 0. Non-zero values of sier flag the following error conditions. + +.nf + 0 # No error + 201 # There are no sky pixels in the sky annulus + 202 # Sky annulus is partially off the image + 203 # The histogram of sky pixels has no width + 204 # The histogram of sky pixels is flat or concave + 205 # There are too few points for a good sky fit + 206 # The sky fit is singular + 207 # The sky fit did not converge + 208 # The graphics stream is undefined + 209 # The file of sky values does not exist + 210 # The sky file is at EOF + 211 # Cannot read the sky value correctly + 212 # The best fit parameters are non-physical +.fi + +.ih +EXAMPLES + +1. Compute the sky values for a few stars in dev$ypix using the display +and the image cursor. Setup the task parameters using the interactive +setup menu defined by the i key command and a radial profile plot. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> fitsky dev$ypix + + ... type ? to print an optional help page + + ... move the image cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or hit + CR to accept the default + ... set the inner and outer sky annuli, and sigma using the + graphics cursor and the stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... move the image cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.sky.1 +.fi + +2. Compute the sky values for a few stars in dev$ypix using a contour plot +and the graphics cursor. This option is only useful for those (now very few) +users who have access to a graphics terminal but not to an image display +server. Setup the task parameters using the interactive setup menu defined by +the i key command as in example 1. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... make a contour plot of dev$ypix + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of dev$ypix in the file ypix.plot1 + + ap> fitsky dev$ypix display=stdgraph + + ... type ? to get an optional help page + + ... move graphics cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or CR + to accept the default value + ... set the inner and outer sky annuli, and sigma using the + graphics cursor and the stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... retype :.read ypix.plot1 to reload the contour plot + + ... move the graphics cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to verify + + ... full output will appear in the text file ypix.sky.2 + + ap> set stdimcur = <default> + + ... reset stdimcur to its previous value +.fi + +3. Setup and run FITSKY interactively on a list of objects temporarily +overriding the fwhmpsf, sigma, annulus, and dannulus parameters determined +in examples 1 or 2. + +.nf + ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify- + + ... make a coordinate list + + ... the output will appear in the text file ypix.coo.1 + + ap> fitsky dev$ypix annulus=12.0 dannulus=5.0 coords=ypix.coo.1 + + ... type ? for optional help + + + ... move the graphics cursor to the stars and tap space bar + + or + + ... select stars from the input coordinate list with m / :m # + and measure with spbar + + ... measure stars selected from the input coordinate list + with n / n # + + ... a one line summary of results will appear on the standard output + for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.sky.3 ... +.fi + + +4. Display and measure some stars in an image section and write the output +coordinates in the coordinate system of the parent image. + +.nf + ap> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + ap> fitsky dev$ypix[150:450,150:450] wcsout=tv + + ... move cursor to stars and type spbar + + ... type q to quit and q again to confirm quit + + ... output will appear in ypix.sky.4 + + ap> pdump ypix.sky.4 xi,yi yes | tvmark 1 STDIN col=204 +.fi + +5. Run FITSKY in batch mode using the coordinate file and the previously +saved parameters. Verify the critical parameters. + +.nf + ap> fitsky dev$ypix coords=ypix.coo.1 verify+ inter- + + ... output will appear in ypix.sky.5 ... +.fi + +6. Repeat example 5 but assume that the input coordinate are ra and dec +in degrees and degrees, turn off verification, and submit the task to to +the background. + +.nf + ap> display dev$ypix 1 + + ap> rimcursor wcs=world > radec.coo + + ... move to selected stars and type any key + + ... type ^Z to quit + + ap> fitsky dev$ypix coords=radec.coo wcsin=world verify- inter- & + + ... output will appear in ypix.sky.6 + + ap> pdump ypix.sky.6 xi,yi yes | tvmark 1 STDIN col=204 + + ... mark the stars on the display +.fi + +7. Run FITSKY interactively without using the image display. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = text + + ... set the image cursor to the standard input + + ap> fitsky dev$ypix coords=ypix.coo.1 + + ... type ? for optional help + + ... type :m 3 to set the initial coordinates to those of the + third star in the list + + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to enter the default menu + ... set the inner and outer sky annuli, and sigma using the + graphics cursor and the stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its default + value + ... type q to quit the setup menu + + ... type r to rewind the coordinate list + + ... type l to measure all the stars in the coordinate list + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... full output will appear in the text file ypix.sky.7 + + ap> set stdimcur = <default> + + ... reset the value of stdimcur +.fi + +8. Use an image cursor command file to drive the FITSKY task. The cursor command +file shown below sets the annulus and dannulus parameters, computes the sky +values for 3 stars, updates the parameter files, and quits the task. + +.nf + ap> type cmdfile + : annulus 12.0 + : dannulus 5.0 + 442 410 101 \040 + 349 188 101 \040 + 225 131 101 \040 + w + q + + ap> fitsky dev$ypix icommands=cmdfile verify- + + ... full output will appear in ypix.sky.8 +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS +It is currently the responsibility of the user to make sure that the +image displayed in the frame is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the fitskypars mksky switch to"yes". +It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO +datapars, fitskypars, phot, polyphot, radprof +.endhelp diff --git a/noao/digiphot/apphot/doc/fitskypars.hlp b/noao/digiphot/apphot/doc/fitskypars.hlp new file mode 100644 index 00000000..cdb541ba --- /dev/null +++ b/noao/digiphot/apphot/doc/fitskypars.hlp @@ -0,0 +1,219 @@ +.help fitskypars May00 noao.digiphot.apphot +.ih +NAME +fitskypars - edit the sky fitting algorithm parameters +.ih +USAGE +fitskypars +.ih +PARAMETERS +.ls salgorithm = "centroid" +The sky fitting algorithm to be employed. The sky fitting options are: +.ls constant +Use a user supplied constant value \fIskyvalue\fR for the sky. +This algorithm is useful for measuring large resolved objects on flat +backgrounds such as galaxies or comments. +.le +.ls file +Read sky values from a text file. This option is useful for importing +user determined sky values into APPHOT. +.le +.ls mean +Compute the mean of the sky pixel distribution. This algorithm is useful +for computing sky values in regions with few background counts. +.le +.ls median +Compute the median of the sky pixel distribution. This algorithm is a useful +for computing sky values in regions with rapidly varying sky backgrounds +and is a good alternative to "centroid". +.le +.ls mode +Compute the mode of the sky pixel distribution using the computed mean and +median. This is the recommended algorithm for APPHOT users trying to +measuring stellar objects in crowded stellar fields. Mode may not perform +well in regions with rapidly varying sky backgrounds. +.le +.ls centroid +Compute the intensity-weighted mean or centroid of the sky pixel histogram. +This is the algorithm recommended for most APPHOT users. It is reasonably +robust in rapidly varying and crowded regions. +.le +.ls gauss +Fit a single Gaussian function to the sky pixel histogram using non-linear +least-squares techniques. +.le +.ls ofilter +Compute the sky using the optimal filtering algorithm and a triangular +weighting function and the histogram of the sky pixels. +.le +.ls crosscor +Compute the sky value using the cross-correlation function of the sky pixel +histogram and a Gaussian noise function with a sigma equal to the +computed sigma of the sky pixel distribution. +.le +.ls histplot +Mark the peak of the histogram of the sky pixels on a plot of the histogram. +This algorithm is useful for making careful interactive sky measurements +for a small number of objects in complicated regions or for checking the +behavior of other sky algorithms. +.le +.ls radplot +Mark the sky value on a radial distribution plot of the sky pixels. +This algorithm is useful for making careful interactive sky measurements +for a small number of objects in complicated regions or for checking the +behavior of other sky algorithms. +.le +.le +.ls annulus = 10.0 (scale units) +The inner radius of the annular sky fitting region in units of the DATAPARS +scale parameter. +.le +.ls dannulus = 10.0 (scale units) +The width of the annular sky fitting region in units of the DATAPARS +scale parameter. +.le +.ls skyvalue +The constant for constant sky subtraction. +.le +.ls smaxiter = 10 +The maximum number of iterations performed by the sky fitting algorithm. +\fISmaxiter\fR is required by the "gauss" and "ofilter" sky fitting algorithms. +.le +.ls sloclip = 0.0 (percent) +The low-side clipping factor in percentage points of the total number of +sky pixels. +.le +.ls shiclip = 0.0 (percent) +The high-side clipping factor in percentage points of the total number of +sky pixels. +.le +.ls snreject = 50 +The maximum number of pixel rejection cycles. +.le +.ls sloject = 3.0 +The ksigma low-side clipping factor for the pixel rejection phase of the +sky fitting algorithm. \fIsloreject\fR is in units of the computed sky +sigma. +.le +.ls shiject = 3.0 +The ksigma high-side clipping factor for the pixel rejection phase of the +sky fitting algorithm. \fIshireject\fR is in units of the computed sky +sigma. +.le +.ls khist = 3.0 +The ksigma clipping factor for computing the histogram of the sky pixels. +\fIKhist\fR is in units of the computed sky sigma. +The computed histogram will be 2.0 * khist * sigma wide. +.le +.ls binsize = 0.10 +The width of a single bin of the histogram of sky values. +\fIBinsize\fR is in units of the computed sky sigma. +.le +.ls smooth = no +Boxcar smooth the histogram before computing a sky value ? +.le +.ls rgrow = 0.0 (scale units) +The region growing radius for pixel rejection in the sky region, in units +of the DATAPARS \fIscale\fR parameter. When a bad sky pixel is detected, +all pixels within rgrow / scale will be rejected. If rgrow is 0.0 +region growing is not performed. +.le +.ls mksky = no +Mark the sky annulus on the displayed image ? +.le +.ih +DESCRIPTION +The sky fitting algorithm parameters control the action of the sky fitting +algorithms. The default parameter settings should give reasonable results in +the majority of cases. Several of the sky fitting parameters scale with +image scale, \fIscale\fR which is data dependent. \fIScale\fR is defined in +the DATAPARS parameter set. + +Sky pixels in an annular region of inner radius \fIannulus / scale\fR pixels +and a width of \fIdannulus / scale\fR pixels are extracted from the IRAF image. +If the \fIscale\fR parameter is defined in terms of the number of half-width +at half-maximum of the point spread function per pixel, then single values of +annulus and dannulus will work well for images with different seeing and +detector characteristics. + +Pixels outside of the good data range specified by \fIdatamin\fR and +\fIdatamax\fR are rejected from the sky pixel distribution. After bad +data rejection \fIPloclip\fR and \fIphiclip\fR percent pixels are rejected +from the low and high sides of the sorted pixel distribution before any +sky fitting is done. + +Sky values are computed using the sky fitting algorithm specified by +\fIsalgorithm\fR. The default value is "centroid". If \fIsalgorithm\fR += "mean", "median" or "mode", the sky value is computed directly from the +array of sky pixels. The remaining sky fitting algorithms use the histogram +of the object sky pixels. The computed histogram is \fIkhist\fR * sigma wide +with a bin width of \fIbinsize\fR * sigma where sigma is the computed +standard deviation of the sky pixels for each object. If \fIsmooth\fR = yes, +boxcar smoothing is performed on the computed histogram before sky fitting. +The mode of the histogram is computed using, a non-linear least squares +fit to a Gaussian (salgorithm = "gauss"), optimal filtering of the histogram +(salgorithm = "ofilter"), computing the intensity weighted mean of the +histogram (salgorithm = "centroid"), or by cross-correlation techniques +(salgorithm = "crosscor"). + +Two interactive methods of fitting sky are also available. If \fIsalgorithm\fR +is "radplot" or "histplot", the user must interactively set the value of the +sky using a radial profile or a histogram profile plot. + +Pixels which deviate from the sky value by more than \fIkreject\fR times the +computed sky sigma are rejected from the fit. If \fIrgrow\fR > 0, pixels +within a radius of rgrow / scale of the rejected pixel are also rejected from +the fit. The rejection procedure iterates until no further pixels are rejected, +all pixels are rejected, or the maximum number of rejection cycles +\fIsnreject\fR iterations is reached. + +.ih +EXAMPLES +1. List the sky fitting parameters. + +.nf + ap> lpar fitskypars +.fi + +2. Edit the sky fitting parameters. + +.nf + ap> fitskypars +.fi + +3. Edit the FITSKYPARS parameters from within the PHOT task. + +.nf + da> epar phot + + ... edit a few phot parameters + + ... move to the fitskypars parameter and type :e + + ... edit the fitskypars parameters and type :wq + + ... finish editing the phot parameters and type :wq +.fi + +4. Save the current FITSKYPARS parameter set in a text file skynite1.par. +This can also be done from inside a higher level task as in the +above example. + +.nf + da> fitskypars + + ... edit some parameters + + ... type ":w skynite1.par" from within epar +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS + +.ih +SEE ALSO +radprof,fitsky,phot,wphot,polyphot +.endhelp diff --git a/noao/digiphot/apphot/doc/pexamine.hlp b/noao/digiphot/apphot/doc/pexamine.hlp new file mode 100644 index 00000000..f3a031ec --- /dev/null +++ b/noao/digiphot/apphot/doc/pexamine.hlp @@ -0,0 +1,836 @@ +.help pexamine May00 noao.digiphot.apphot +.ih +NAME +pexamine -- interactively examine or edit a photometry catalog +.ih +USAGE +pexamine input output image +.ih +PARAMETERS +.ls input +The name of the input photometry catalog. \fIInput\fR may be either an +APPHOT/DAOPHOT text database file or an STSDAS binary table database. +.le +.ls output +The name of the edited output catalog. \fIOutput\fR is either an +APPHOT/DAOPHOT text database or an STSDAS binary table database +depending on the file type of \fIinput\fR. If \fIoutput\fR = "" no output +catalog is written. +.le +.ls image +The name of the input image corresponding to the input photometry +catalog. If \fIimage\fR is "" no image will be attached to PEXAMINE +and some interactive catalog examining commands will not be available. +All the catalog editing commands however are still available. +.le +.ls deletions = "" +The name of an optional output deletions photometry catalog. \fIDeletions\fR +is either an APPHOT/DAOPHOT text database or an STSDAS binary +table database depending on the file type of \fIinput\fR. If \fIdeletions\fR +is "" no deletions file is written. +.le +.ls photcolumns = "apphot" +The list of standard photometry columns that are loaded when pexamine is +run. The options are listed below. +.ls "apphot" +The standard columns for the APPHOT package. The current list is ID, +XCENTER, YCENTER, MSKY, MAG, and MERR. +If any of these +columns are multi-valued, (as in the case of magnitudes measured through +more than one aperture), the first value is selected. +The standard list may easily be extended at user request. +.le +.ls "daophot" +The standard columns for the DAOPHOT package. The current list is GROUP, ID, +XCENTER, YCENTER, MSKY, MAG, MERR, CHI, SHARP and NITER. +If any of these +columns are multi-valued, (as in the case of magnitudes measured through +more than one aperture), the first value is selected. +The standard list may easily be extended at user request. +.le +.ls user list +A user supplied list of standard columns. +Column names are listed in full in either upper or +lower case letters, separated by commas. If more than one value of +a multi-valued column is requested +the individual values +must be listed separately as in the following example +ID, XCENTER, YCENTER, MAG[1], MERR[1], MAG[2], MERR[2]. +.le + +\fIPhotcolumns\fR can be changed interactively from within PEXAMINE at +the cost of rereading the database. +.le +.ls xcolumn = "mag" (magnitude), ycolumn = "merr" (magnitude error) +The names of the two columns which define the default X-Y plot. +\fIXcolumn\fR and \fIycolumn\fR must be listed in \fIphotcolumns\fR or +\fIusercolumns\fR but may be changed interactively by the user. +If either \fIxcolumn\fR or \fIycolumn\fR is a multi-valued quantity +and more than one value is listed in \fIphotcolumns\fR or \fIusercolumns\fR +then the desired value number must be specified explicitly in, e.g. +MAG[2] or MERR[2]. +.le +.ls hcolumn = "mag" (magnitude) +The name of the column which defines the default histogram plot. +\fIHcolumn\fR must be listed in \fIphotcolumns\fR or +\fIusercolumns\fR but may be changed interactively by the user. +If \fIhcolumn\fR is a multi-valued quantity and more than one value is +listed in \fIphotcolumns\fR or \fIusercolumns\fR then the desired value +must be specified explicitly in \fIhcolumn\fR, e.g. MAG[2]. +.le +.ls xposcolumn = "xcenter", yposcolumn = "ycenter" +The names of the two columns which define the X and Y coordinates in +\fIimage\fR of the objects in the catalog. This information is +required if the image display and image cursor are to be used to visually +identify objects in the image with objects in the catalog or if plots +of image data are requested. \fIXposcolumn\fR and \fIyposcolumn\fR must +be listed in \fIphotcolumns\fR or \fIusercolumns\fR but may +be changed interactively by the user. +.le +.ls usercolumns = "" +The list of columns loaded into memory in addition to the +standard photometry columns \fIphotcolumns\fR. The column +names are listed in full in upper or lower case letters and separated by +commas. +\fIUsercolumns\fR can be changed interactively from within PEXAMINE at +the cost of rereading the database. +.le +.ls first_star = 1 +The index of the first object to be read out of the catalog. +.le +.ls max_nstars = 5000 +The maximum number of objects that are loaded into memory at task +startup time, beginning at object \fIfirst_star\fR. If there are more +than \fImax_nstars\fR in the catalog only the first \fImax_nstars\fR +objects are read in. +.le +.ls match_radius = 2.0 +The tolerance in pixels to be used for matching objects in the catalog with +objects marked on the display with the image cursor. +.le +.ls graphics = "stdgraph" +The default graphics device. +.le +.ls use_display = yes +Use the image display? Users without access to an image display should +set \fIuse_display\fR to "no". +.le +.ls icommands = "" +The image display cursor. If null the standard image cursor is used whenever +image cursor input is requested. A cursor file in the appropriate +format may be substituted by specifying the name of the file. +Also the image cursor may be changed to query the graphics device or the +terminal by setting the environment variable "stdimcur" to "stdgraph" +or "text" respectively. +.le +.ls gcommands = "" +The graphics cursor. If null the standard graphics cursor is used whenever +graphics cursor input is requested. A cursor file in the appropriate +format may be substituted by specifying the name of the file. +.le + +.ih +PLOTTING PARAMETERS + +PEXAMINE supports five types of plots 1) an X-Y column plot +2) a histogram column plot 3) a radial profile plot 4) a surface +plot and 5) a contour plot. +Each supported plot type has its own parameter set which +controls the appearance of the plot. +The names of the five parameter sets are listed below. + +.nf + cntrplot Parameters for the contour plot + histplot Parameters for the column histogram plot + radplot Parameters for radial profile plot + surfplot Parameters for surface plot + xyplot Parameters for the X-Y column plot +.fi + +The same parameters dealing with graph formats occur in many of the parameter +sets while some are specific only to one parameter set. In the +summary below those common to more than one parameter set are shown +only once. The characters in parenthesis are the graph key prefixes +for the parameter sets in which the parameter occurs. + +.ls angh = -33., angv = 25. (s) +Horizontal and vertical viewing angles in degrees for surface plots. +.le +.ls axes = yes (s) +Draw axes along the edge of surface plots? +.le +.ls banner = yes (chrsx) +Add a standard banner to a graph? The standard banner includes the +IRAF user and host identification and the date and time. +.le +.ls box = yes (chrx) +Draw graph box and axes? +.le +.ls ceiling = INDEF (cs) +Ceiling data value for contour and surface plots. A value of INDEF does +not apply a ceiling. In contour plots a value of 0. also does not +apply a ceiling. +.le +.ls dashpat = 528 (c) +Dash pattern for negative contours. +.le +.ls fill = no (yes) (c) (hrx) +Fill the output viewport regardless of the device aspect ratio? +.le +.ls floor = INDEF (cs) +Floor data value for contour and surface plots. A value of INDEF does +not apply a floor. In contour plots a value of 0. also does not +apply a floor. +.le +.ls grid = no (rx) +Draw grid lines at major tick marks? +.le +.ls interval = 0.0 (c) +Contour interval. If 0.0, a contour interval is chosen which places 20 to 30 +contours spanning the intensity range of the image. +.le +.ls label= no (c) +Label the major contours in the contour plot? +.le +.ls logx = no, logy = no (rx) (hrx) +Plot the x or y axis logarithmically? The default for histogram plots is +to plot the y axis logarithmically. +.le +.ls majrx=5, minrx=5, majry=5, minry=5 (chrx) +Maximum number of major tick marks on each axis and number of minor tick marks +between major tick marks. +.le +.ls marker = "box" (rx) +Marker to be drawn. Markers are "point", "box", +"cross", "plus", "circle", "hline", "vline" or "diamond". +.le +.ls nbins = 512 (h) +The number of bins in, or resolution of, histogram plots. +.le +.ls ncolumns = 21, nlines = 21 (cs) +Number of columns and lines used in contour and surface plots. +.le +.ls ncontours = 5 (c) +Number of contours to be drawn. If 0, the contour interval may be specified, +otherwise 20 to 30 nicely spaced contours are drawn. A maximum of 40 contours +can be drawn. +.le +.ls nhi = -1 (c) +If -1, highs and lows are not marked. If 0, highs and lows are marked +on the plot. If 1, the intensity of each pixel is marked on the plot. +.le +.ls rinner = 0, router = 8 +The inner and outer radius of the region whose radial profile is to +be plotted. +.le +.ls round = no (chrx) +Extend the axes up to "nice" values? +.le +.ls szmarker = 1 (rx) +Size of mark except for points. A positive size less than 1 specifies +a fraction of the device size. Values of 1, 2, 3, and 4 signify +default sizes of increasing size. +.le +.ls ticklabels = yes (chrx) +Label the tick marks? +.le +.ls top_closed = no (h) +Include z2 in the top histogram bin? Each bin of the histogram is a +subinterval that is half open at the top. \fITop_closed\fR decides whether +those pixels with values equal to z2 are to be counted in the histogram. If +\fBtop_closed\fR is yes, the top bin will be larger than the other bins. +.le +.ls x1 = INDEF, x2 = INDEF, y1 = INDEF, y2 = INDEF (hrx) +Range of graph along each axis. If INDEF the range is determined from +the data range. The default y1 for histogram plots is 0. +.le +.ls zero = 0. (c) +Greyscale value of the zero contour, i.e., the value of a zero point shift +to be applied to the image data before plotting. Does not affect the values +of the floor and ceiling parameters. +.le +.ls z1 = INDEF, z2 = INDEF (h) +Range of pixel values to be used in histogram. INDEF values default to +the range in the region being histogramed. +.le + +.ih +DESCRIPTION + +PEXAMINE is a general purpose tool for interactively examining and editing +photometry catalogs produced by the APPHOT or DAOPHOT packages. It is +intended to aid the user in assessing the accuracy of the photometry, +in diagnosing problems with particular catalog objects, +in searching the photometry data for relationships +between the computed quantities, and in editing the catalog based on +those observed relationships. PEXAMINE is intended to complement the +more batch oriented editing facilities of the SELECT task. + +PEXAMINE takes the input catalog \fIinput\fR and the corresponding +image \fIimage\fR (if defined) and produces an output catalog of selected +objects \fIoutput\fR (if defined) and an output catalog of deleted objects +\fIdeletions\fR (if defined). The input catalog may be either an +APPHOT/DAOPHOT text database or an ST binary table database. +The file type of the output catalogs \fIoutput\fR and \fIdeletions\fR +is the same as that of \fIinput\fR. + +READING IN THE DATA + +PEXAMINE reads the column data specified by \fIphotcolumns\fR and +\fIusercolumns\fR for up to \fImax_nstars\fR beginning at star +\fIfirst_star\fR into memory. +The \fIphotcolumns\fR parameter +defines the list of standard photometry columns to be loaded. If +"daophot" or "apphot" is selected then the standard columns +are GROUP, ID, XCENTER, YCENTER, MSKY, MAG, MERR, CHI, SHARP and NITER +and ID, XCENTER, YCENTER, MSKY, MAG and MERR respectively. +Otherwise the user must set \fIphotcolumns\fR to his or her own preferred +list of standard photometry columns. Non-standard columns may also be +specified using the parameter \fIusercolumns\fR. +Valid column lists contain the full names of the specified columns +in upper or lower case letters, separated by commas. +Either \fIphotcolumns\fR or +\fIusercolumns\fR may be redefined interactively by the user after +the task has started up, but only at the +expense of rereading the data from \fIinput\fR. + +PEXAMINE will fail to load a specified column if that column is +not in the photometry database, is of a datatype other than +integer or real, or adding that column would exceed the maximum +number of columns limit currently set at twenty. The user can +interactively examine the list of requested and loaded standard +photometry columns, as well as list all the columns in the input +after the task has started up. + +GRAPHICS AND IMAGE COMMAND MODE + +PEXAMINE accepts commands either from the graphics cursor \fIgcommands\fR +(graphics command mode) or the image display cursor \fIicommands\fR +if available (image command mode). +PEXAMINE starts up in graphics command mode, but all the +interactive commands are accessible from both modes and the user can +switch modes at any time assuming that the \fIuse_display\fR parameter +is set to "yes". + +PEXAMINE interprets the cursor position in graphics command mode +differently from how it interprets it in image command mode. +In graphics command mode the cursor coordinates are the position +of the cursor in the current plot, whereas in image command mode they +are the x and y coordinates of the cursor in the displayed image. +For example, if the user issues a command to PEXAMINE to locate the object +in the catalog nearest the point in the current X-Y plot marked by +the graphics cursor, PEXAMINE does so by searching +the data for the object whose values of \fIxcolumn\fR and \fIycolumn\fR +most closely match those of the current cursor position. +If the user issues a command to PEXAMINE to locate the +object in the catalog corresponding to the object marked on the image +display with the image cursor, +PEXAMINE does so by searching the data for +the object whose values of \fIxposcolumn\fR and \fIyposcoumn\fR +most closely match and fall within \fImatch_radius\fR of the current +cursor position. + +Input to PEXAMINE is through single keystroke commands or colon +commands. Keystroke commands are simple commands that may +optionally use the cursor position but otherwise require no arguments. +The PEXAMINE keystroke commands fall into three categories, basic +commands, data examining commands and data editing commands, all +described in detail in the following sections. Colon commands +take an optional argument and function differently depending on +the presence or absence of that argument. When the argument is absent +colon commands are used to display the +current value of a parameter or list of parameters. When the argument is +present they change their current value to that argument. +The basic colon commands are described in detail below. + +BASIC KEYSTROKE COMMANDS + +These keystroke commands are used to display the help page, switch from +graphics to image command mode and quit the task. + +.ls ? +Page through the help for the PEXAMINE task +.le +.ls : +Execute a PEXAMINE colon command. +.le +.ls g +Change to graphics command mode. Throughout PEXAMINE graphics command mode +is the default. All PEXAMINE commands are available in graphics command +mode. +.le +.ls i +Change to image command mode. +All the PEXAMINE commands are available in image command mode. +However if \fIuse_display\fR is no and the image +cursor has not been aliased to the standard input or a text file +image command mode is disabled. +.le +.ls q +Quit PEXAMINE without writing an output catalog. +PEXAMINE queries the user for confirmation of this option. +.le +.ls e +Quit PEXAMINE and write the output catalog. +.le + +DATA EXAMINING COMMANDS + +The data examining commands fall into two categories, those that examine +the catalog data including 'l' (catalog listing), 'o' (object listing), +'x' (Y column versus X column plot) and 'h' (histogram column plot) +commands, and those which examine the image data around specific catalog +objects including 'r' (radial profile plotting), 's' (surface plotting), +'c' (contour plotting) and 'm' (pixel dumping). The latter group +require that \fIimage\fR be defined. A brief summary of each data +examining command is given below. +.ls l +Print out the name, datatype, and units for all the columns in the input +catalog. The list command can be used to check the contents of the input +catalog and/or determine why a particualar column was not loaded. +.le +.ls o +Print out the names and values of the stored columns of the object +nearest the cursor. In graphics mode the current plot type must be +X-Y. In image command mode the object nearest the cursor must also be +no more than \fImatch-radius\fR pixels away from the image cursor to be +found. If an object is found and the current plot type is X-Y +the graphics cursor is moved to the position of the selected object +in the X-Y plot. +.le +.ls x +Plot the data in \fIycolumn\fR versus the data in \fIxcolumn\fR excluding +any already deleted points and identifying objects marked for deletion +with a cross. X-Y plotting is undefined if \fIxcolumn\fR or \fIycolumn\fR +is undefined. +.le +.ls h +Plot the histogram of the data in \fIhcolumn\fR excluding any already +deleted points and those marked for deletion. Histogram plotting is +disabled if \fIhcolumn\fR is undefined. +.le +.ls r +Plot the radial profile of the object nearest the cursor including +only pixels within a distance of \fIrinner\fR and \fRrouter\R of +the object center. Radial profile plotting is disabled if \fIimage\fR +or \fIxposcolumn\fR or \fIyposcolumn\fR is undefined. +.le +.ls s +Plot the surface plot of the object nearest the cursor including +only pixels within an image section \fIncols\fR by \fInlines\fR +around the object center. Surface plotting is disabled if \fIimage\fR +or \fIxposcolumn\fR or \fIyposcolumn\fR is undefined. +.le +.ls c +Plot the contour plot of the object nearest the cursor including +only pixels within an image section \fIncols\fR by \fInlines\fR +around the object center. Contour plotting is disabled if \fIimage\fR +or \fIxposcolumn\fR or \fIyposcolumn\fR is undefined. +.le +.ls m +Dump the pixel values of a grid of 10 by 10 pixels around the object +nearest the cursor. Pixel value dumping is disabled if \fIimage\fR +or \fIxposcolumn\fR or \fIyposcolumn\fR is undefined. +.le +.ls p +Replot the current graph. +.le + +DATA EDITING COMMANDS + +Data points can be deleted from the catalog in either graphics command +mode or image +command mode. In graphics command mode the +graphics cursor and either the X-Y or histogram plot is used to delete points. +In image command mode the image cursor and the displayed +image are used to delete points. A data point has three possible states +good, marked for deletion and deleted. +Any one of the keystroke commands 'd' (delete point), '(' (delete points +with x less than x cursor), ')' (delete points with x greater than x cursor, +'^' (delete points with y > y cursor), 'v' (delete points with y < y cursor) +or 'b' (delete points in a box) can be used to mark points for deletion. +The 'f' key is used to actually delete the points and replot the data. +In between marking the points for deletion and actually deleting the marked +points the 't' (toggle) key can be used to undelete the last set marked. +The full list of the data editing keystroke commands is given below. + +.ls z +Undelete not just unmark all the data points replot. +.le +.ls f +Delete points marked for deletion and replot. Points marked for deletion +but not actually deleted will be written to the output catalog and not +written to the deletions catalog. +.le +.ls d +Mark the point nearest the cursor for deletion. +.le +.ls u +Undelete the marked point nearest the cursor. +.le +.ls ( +Mark all points with x values less than the x value of the cursor for +deletion. In graphics command mode points can only be marked for deletion if +the current plot type is "xyplot" or "histplot". In image command +mode \fIxposcolumn\fR and \fIyposcolumn\fR must be defined before +points can be marked for deletion. +.le +.ls ) +Mark all points with x values greater than the x value of the cursor for +deletion. In graphics command mode points can only be marked for deletion if +the current plot type is "xyplot" or "histplot". In image command +mode \fIxposcolumn\fR and \fIyposcolumn\fR must be defined before +points can be marked for deletion. +.le +.ls v +Mark all points with y values less than the y value of the cursor for +deletion. In graphics command mode points can only be marked for deletion if +the current plot type is "xyplot". In image command +mode \fIxposcolumn\fR and \fIyposcolumn\fR must be defined before +points can be marked for deletion. +.le +.ls ^ +Mark all points with y values greater than the y value of the cursor for +deletion. In graphics command mode points can only be marked for deletion if +the current plot type is "xyplot". In image command +mode \fIxposcolumn\fR and \fIyposcolumn\fR must be defined before +points can be marked for deletion. +.le +.ls b +Mark all points within a box whose lower left and upper right hand corners +are marked by the cursor for deletion. +In graphics mode points can only be marked for deletion if the current +plot type is "xyplot". In image command mode \fIxposcolumn\fR and +\fIyposcolumn\fR must be defined before points can be marked for +deletion. +.le +.ls t +Toggle between marking points for deletion or undeletion. The default +is to mark points for deletion. +.le + +BASIC COLON COMMANDS + +All the PEXAMINE parameters can be changed interactively with colon +commands, including those which determine which data is read in, +which data is plotted and the parameters of each plot. A brief description +of the basic commands is given here. The full list is given in the +following section. + +.ls :photcolumns [col1,col2,...] +Show or set the list of requested standard photometry columns and the list +of loaded +photometry columns. If the user supplies a new list of columns the data will be +reread from disk. +.le +.ls :usercolumns [col1,col2,...] +Show or set the list of requested user columns and the list of loaded +user columns. If the user supplies a new list of columns the data will be +reread from disk. +.le +.ls :xcolumn [colname] +Show or set the name of the column to be plotted along the x axis of the +X-Y plot. +.le +.ls :ycolumn [colname] +Show or set the name of the column to be plotted along the y axis of the +X-Y plot. +.le +.ls :hcolumn [colname] +Show or set the name of the column to be whose histogram is to be plotted. +.le +.ls :eparam [cntrplot/histplot/radplot/surfplot/xyplot] +Review or edit the list of parameters for the various plot types. +.le +.ls :unlearn [cntrplot/histplot/radplot/surfplot/xyplot] +Return the list of parameters for the various plot types to their default +values. +.le +.ls :x y key cmd +Execute any defined keystroke "key" supplying the appropriate x and y +value in place of the cursor position. In graphics command mode the x +and y position are assumed to be the position in the current graph. +In image command mode the x and y position are assumed to be the x and +y coordinate in the image display. +.le + +.ih +CURSOR COMMANDS + +.nf + PEXAMINE Interactive Cursor Keystroke Commands + + Basic Commands + +? Print help for the PEXAMINE task +: PEXAMINE colon commands +g Activate the graphics cursor +i Activate the image cursor +e Exit PEXAMINE and save the edited catalog +q Quit PEXAMINE and discard the edited catalog + + Data Examining Commands + +l List the name, datatype and units for all columns in the catalog +o Print out the names and values of the stored columns for the + object nearest the cursor +x Replot the current y column versus the current x column +h Replot the current histogram +r Plot the radial profile of the object nearest the cursor +s Plot the surface of the object nearest the cursor +c Plot the contour plot of the object nearest the cursor +m Print the data values of the object nearest the cursor +p Replot the current graph + + Data Editing Commands + +z Reinitialize the data by removing all deletions and replot +d Mark the point nearest the cursor for deletion +u Undelete the marked point nearest the cursor +t Toggle between marking points for deletion or undeletion +( Mark points with X < X (cursor) for deletion or undeletion +) Mark points with X > X (cursor) for deletion or undeletion +v Mark points with Y < Y (cursor) for deletion or undeletion +^ Mark points with Y > Y (cursor) for deletion or undeletion +b Mark points inside a box for deletion or undeletion +f Actually delete the marked points and replot + + + PEXAMINE Interactive Colon Commands + +:xcolumn [name] Show/set the X-Y plot X axis quantity +:ycolumn [name] Show/set the X-Y plot Y axis quantity +:hcolumn [name] Show/set the histogram plot quantity +:photcolumns [col1,col2,...] Show/set the list of photometry columns +:usercolumns [col1,col2,...] Show/set the list of user columns +:delete [yes/no] Delete or undelete points +:eparam [x/h/r/s/c] Edit/unlearn the specified plot pset + or +:unlearn + + + PEXAMINE Interactive X-Y Plotting Commands + +:x1 [value] Left world x-coord if not autoscaling +:x2 [value] Right world x-coord if not autoscaling +:y1 [value] Lower world y-coord if not autoscaling +:y2 [value] Upper world y-coord if not autoscaling +:szmarker [value] Marker size +:marker [point|box|plus|cross|circle|diamond|hline|vline] Marker type +:logx [yes/no] Log scale the x axis? +:logy [yes/no] Log scale the y axis? +:box [yes/no] Draw box around periphery of window? +:ticklabels [yes/no] Label tick marks? +:grid [yes/no] Draw grid lines at major tick marks? +:majrx [value] Number of major divisions along x axis +:minrx [value] Number of minor divisions along x axis +:majry [value] Number of major divisions along y axis +:minry [value] Number of minor divisions along y axis +:round [yes/no] Round axes to nice values? +:fill [yes/no] Fill viewport vs enforce unity aspect ratio? + + + PEXAMINE Interactive Histogram Plotting Commands + +:nbins [value] Number of bins in the histogram +:z1 [value] Minimum histogram intensity +:z2 [value] Maximum histogram intensity +:top_closed [y/n] Include z in the top bin? +:x1 [value] Left world x-coord if not autoscaling +:x2 [value] Right world x-coord if not autoscaling +:y1 [value] Lower world y-coord if not autoscaling +:y2 [value] Upper world y-coord if not autoscaling +:logy [yes/no] Log scale the y axis? +:box [yes/no] Draw box around periphery of window? +:ticklabels [yes/no] Label tick marks? +:majrx [value] Number of major divisions along x axis +:minrx [value] Number of minor divisions along x axis +:majry [value] Number of major divisions along y axis +:minry [value] Number of minor divisions along y axis +:round [yes/no] Round axes to nice values? +:fill [yes/no] Fill viewport vs enforce unity aspect ratio? + + PEXAMINE Interactive Radial Profile Plotting Commands + +:rinner [value] Inner radius of the region to be plotted +:router [value] Outer radius of the region to be plotted +:x1 [value] Left world x-coord if not autoscaling +:x2 [value] Right world x-coord if not autoscaling +:y1 [value] Lower world y-coord if not autoscaling +:y2 [value] Upper world y-coord if not autoscaling +:szmarker [value] Marker size +:marker [point|box|plus|cross|circle|diamond|hline|vline] Marker type +:logx [yes/no] Log scale the x axis? +:logy [yes/no] Log scale the y axis? +:box [yes/no] Draw box around periphery of window? +:ticklabels [yes/no] Label tick marks? +:grid [yes/no] Draw grid lines at major tick marks? +:majrx [value] Number of major divisions along x axis +:minrx [value] Number of minor divisions along x axis +:majry [value] Number of major divisions along y axis +:minry [value] Number of minor divisions along y axis +:round [yes/no] Round axes to nice values? +:fill [yes/no] Fill viewport vs enforce unity aspect ratio? + + + PEXAMINE Interactive Surface Plotting Commands + +:ncolumns [value] Number of columns to be plotted +:nlines [value] Number of lines to be plotted +:axes [yes/no] Draw axes? +:angh [value] Horizontal viewing angle +:angv [value] Vertical viewing angle +:floor [value] Minimum value to be plotted +:ceiling [value] Maximum value to be plotted + + + PEXAMINE Interactive Contour Plotting Commands + +:ncolumns [value] Number of columns to be plotted +:nlines [value] Number of lines to be plotted +:floor [value] Minimum value to be plotted +:ceiling [value] Maximum value to be plotted +:zero [value] Greyscale value of zero contour +:ncontours [value] Number of contours to be drawn +:interval [value] Contour interval +:nhi [value] Hi/low marking option +:dashpat [value] Bit pattern for generating dashed lines +:label [yes/no] Label major contours with their values? +:box [yes/no] Draw box around periphery of window? +:ticklabels [yes/no] Label tick marks? +:majrx [value] Number of major divisions along x axis +:minrx [value] Number of minor divisions along x axis +:majry [value] Number of major divisions along y axis +:minry [value] Number of minor divisions along y axis +:round [yes/no] Round axes to nice values? +:fill [yes/no] Fill viewport vs enforce unity aspect ratio? +.fi + +.ih +EXAMPLES + +1. Examine and edit an APPHOT aperture photometry catalog and a DAOPHOT +allstar catalog without either attaching the associated image or using the +image display. + +.nf + pt> pexamine m92.mag.1 m92.mag.ed use_display- + + ... a plot of magnitude error versus magnitude appears on + the screen and the graphics cursor comes up ready to accept + commands + + ... the user sees a generally smooth trend of increasing + magnitude error with increasing magnitude except for a + single deviant point at the bright end of the plot + + ... the user decides to remove the deviant point using the + 'd' keystroke command to mark the point and the 'f' + keystroke command to actually delete and replot the graph + + ... after examining the plot further the user decides to delete + all objects for which the magnitude error is > 0.1 magnitudes + using the '^' keystroke command, followed by the 'f' + keystroke command to actually replot and delete the data. + + ... after deciding that this new plot is satisfactory the user + issues the 'e' keystroke command to exit pexamine and save + the good data in m92.mag.ed + + pt> pexamine m92.als.1 m92.als.ed use_display- + + ... a plot of magnitude error versus magnitude appears on the + screen and the graphics cursor comes up ready to accept + commands + + ... after looking at the plot the user decides that what they + really want to see is a plot of the goodness of fit parameter + chi versus magnitude + + ... the user issues the colon command :ycol chi followed by 'p' + keystroke command to replot the data + + ... the user sees a generally smooth trend of increasing + chi with increasing magnitude + + ... after examining the plot further the user decides to delete + all objects for which the chi value > 2.0 and the + magnitude is > 25 using the '^' key and ')' keystroke + commands followed by 'f' to save the deletions and replot + the data + + ... after deciding that this new plot is satisfactory the user + issues the 'e' keystroke command to exit pexamine and save + the good data in m92.als.ed +.fi + +2. Examine and edit a DAOPHOT allstar catalog using the subracted image, the +original image and the image display. + +.nf + pt> display image.sub 1 + + ... display the subtracted image + + pt> pexamine orionk.als.1 orionk.als.ed image xcol=mag ycol=chi + + ... a plot of the goodness of fit versus magnitude appears + on the terminal and the graphics cursor comes up ready to + accept commands + + ... the user notices some very anomalous chi values and decides + to see if these correspond to objects which have poor + subtraction on the displayed image + + ... the user switches to image command mode by tapping the 'i' + key, moves to the first poorly subtracted object and taps + the 'o' key + + ... a list of the values of the loaded columns including chi + appears in the text window , the program switchs to graphics + mode and places the graphics cursor on the corresponding + point in the X-Y plot + + ... the point in question indeed has a very high chi value + and the user decides to try and investigate the reason for the + anomalous value + + ... the user taps the 'r' key to get a radial profile of the + object in the original image + + ... after carefully examining the profile it appears that the + object's profile is too broad and that it is not a star + + ... the user switches back to the X-Y plot with the 'x' key, + marks the point with the 'd' key and saves the deletions + and replots with the 'f' key. + + ... the user goes back to image command mode with the 'i' key + and begins investigating the next object + + ... finally after examining the image and making all the changes + the user decides to quit and save the changes with the 'e' key + +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS +If the display device is on a remote resource the first image cursor +request will cause PEXAMINE to hang. The remote resource is expecting +the appropriate password which the user must type in to cause the +the image cursor to appear. The normal password prompt is +not being issued or flushed to the terminal. The solution to the problem +is to put the password in the .irafhosts file + +INDEF valued points cannot be accessed by +PEXAMINE. INDEF valued points should be removed from the input catalog +with SELECT prior to entering PEXAMINE. + +.ih +SEE ALSO +ptools.select, ptools.txselect,ptools.tselect + +.endhelp diff --git a/noao/digiphot/apphot/doc/phot.hlp b/noao/digiphot/apphot/doc/phot.hlp new file mode 100644 index 00000000..a4ee6ffb --- /dev/null +++ b/noao/digiphot/apphot/doc/phot.hlp @@ -0,0 +1,767 @@ +.help phot May00 noao.digiphot.apphot +.ih +NAME +phot -- do aperture photometry on a list of stars +.ih +USAGE +phot image +.ih +PARAMETERS +.ls image +The list of images containing the objects to be measured. +.le +.ls skyfile = "" +The list of text files containing the sky values, of the measured objects, +one object per line with x, y, the sky value, sky sigma, sky skew, number of sky +pixels and number of rejected sky pixels in columns one to seven respectively. +The number of sky files must be zero, one, or equal to the number of input +images. A skyfile value is only requested if \fIfitskypars.salgorithm\fR = +"file" and if PHOT is run non-interactively. +.le +.ls coords = "" +The list of text files containing initial coordinates for the objects to +be centered. Objects are listed in coords one object per line with the +initial coordinate values in columns one and two. The number of coordinate +files must be zero, one, or equal to the number of images. If coords is +"default", "dir$default", or a directory specification then a coords file name +of the form dir$root.extension.version is constructed and searched for, +where dir is the directory, root is the root image name, extension is "coo" +and version is the next available version number for the file. +.le +.ls output = "default" +The name of the results file or results directory. If output is +"default", "dir$default", or a directory specification then an output file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "mag" and version is +the next available version number for the file. The number of output files +must be zero, one, or equal to the number of image files. In both interactive +and batch mode full output is written to output. In interactive mode +an output summary is also written to the standard output. +.le +.ls plotfile = "" +The name of the file containing radial profile plots of the stars written +to the output file. If plotfile is defined then a radial profile plot +is written to plotfile every time a record is written to \fIoutput\fR. +The user should be aware that this can be a time consuming operation. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The critical +parameters \fIfwhmpsf\fR and \fIsigma\fR are located here. If \fIdatapars\fR +is undefined then the default parameter set in uparm directory is used. +.le +.ls centerpars = "" +The name of the file containing the centering parameters. The critical +parameters \fIcalgorithm\fR and \fIcbox\fR are located here. +If \fIcenterpars\fR is undefined then the default parameter set in +uparm directory is used. +.le +.ls fitskypars = "" +The name of the text file containing the sky fitting parameters. The critical +parameters \fIsalgorithm\fR, \fIannulus\fR, and \fIdannulus\fR are located here. +If \fIfitskypars\fR is undefined then the default parameter set in uparm +directory is used. +.le +.ls photpars = "" +The name of the file containing the photometry parameters. The critical +parameter \fIapertures\fR is located here. If \fIphotpars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls interactive = yes +Run the task interactively ? +.le +.ls radplots = no +If \fIradplots\fR is "yes" and PHOT is run in interactive mode, a radial +profile of each star is plotted on the screen after the star is measured. +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.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 cacheing is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical parameters in non-interactive mode. Verify may +be set to the value of the apphot package parameter (the default), "yes", or +"no". +.le +.ls update = ")_.update" +Automatically update the algorithm parameters in non-interactive mode +if verify is "yes". Update may be set to the value of the apphot +package parameter (the default), "yes", or "no". +.le +.ls verbose = ")_.verbose" +Print results on the screen in non-interactive mode? Verbose may +be set to the value of the apphot package parameter (the default), +"yes", or "no". +.le +.ls graphics = ")_.graphics" +The default graphics device. Graphics may be set to the value of the apphot +package parameter (the default), "yes", or "no". +.le +.ls display = ")_.display" +The default display device. Display may be set to the apphot package +parameter value (the default), "yes", or "no. By default graphics overlay is +disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables +graphics overlay with the IMD graphics kernel. Setting display to +"stdgraph" enables PHOT to work interactively from a contour plot. +.le + +.ih +DESCRIPTION + +PHOT computes accurate centers, sky values, and magnitudes for a list of +objects in the IRAF image \fIimage\fR whose coordinates are read from +the text file \fIcoords\fR or the image display cursor, and writes the +computed x and y coordinates, sky values, and magnitudes to the text +file \fIoutput\fR. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\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. + +In interactive mode the user may either define the list of objects to be +measured interactively with the image curspr or create an object list prior +to running PHOT. In either case the user may adjust the centering, sky fitting, + and photometry algorithm parameters until a satisfactory fit is achieved +and optionally store the final results in \fIoutput\fR. In batch mode the +initial positions are read from the text file \fIcoords\fR or the image +cursor parameter \fIicommands\fR can be redirected to a text file containing +a list of cursor commands. In batch mode the current set of algorithm +parameters is used. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If cacheing +is enabled and PHOT is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because PHOT +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. + +PHOT computes accurate centers for each object using the centering +parameters defined in \fIcenterpars\fR, computes an accurate sky value +for each object using the sky fitting parameters defined in \fIfitskypars\fR, +and computes magnitudes using the photometry parameters defined in +\fIphotpars\fR. The image data characteristics of the data are specified +in \fIdatapars\fR. + +.ih +CURSOR COMMANDS + +The following list of cursor commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify the critical parameters +w Save the current parameters +d Plot radial profile of current star +i Interactively set parameters using current star +c Fit center for current star +t Fit sky around the cursor +a Average sky values fit around several cursor positions +s Fit sky around current centered star +p Do photometry for current star, using current sky +o Do photometry for current star, using current sky, output results +f Do photometry for current star +spbar Do photometry for current star, output results +m Move to next star in coordinate list +n Do photometry for next star in coordinate list, output results +l Do photometry for remaining stars in coordinate list, output results +e Print error messages +r Rewind coordinate list +q Exit task + + +Photometry parameters are listed or set with the following commands. + + Colon commands + +:show [data/center/sky/phot] List the parameters +:m [n] Move to next [nth] star in coordinate list +:n [n] Do photometry for next [nth] star in coordinate list, output results + + Colon Parameter Editing Commands + +# Image and file name parameters + +:image [string] Image name +:coords [string] Coordinate file name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full width half maximum of PSF (scale units) +:emission [y/n] Emission feature (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good data value (counts) +:datamax [value] Maximum good data value (counts) + +# Noise parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readout noise (electrons) + +# Observations parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Integration time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Centering algorithm parameters + +:calgorithm [string] Centering algorithm +:cbox [value] Width of the centering box (scale units) +:cthreshold [value] Centering intensity threshold (sigma) +:cmaxiter [value] Maximum number of iterations +:maxshift [value] Maximum center shift (scale units) +:minsnratio [value] Minimum S/N ratio for centering +:clean [y/n] Clean subraster before centering +:rclean [value] Cleaning radius (scale units) +:rclip [value] Clipping radius (scale units) +:kclean [value] Clean K-sigma rejection limit (sigma) + +# Sky fitting algorithm parameters + +:salgorithm [string] Sky fitting algorithm +:skyvalue [value] User supplied sky value (counts) +:annulus [value] Inner radius of sky annulus (scale units) +:dannulus [value] Width of sky annulus (scale units) +:khist [value] Sky histogram extent (+/- sky sigma) +:binsize [value] Resolution of sky histogram (sky sigma) +:smooth [y/n] Lucy smooth the sky histogram +:sloclip [value] Low-side clipping factor in percent +:shiclip [value] High-side clipping factor in percent +:smaxiter [value] Maximum number of iterations +:snreject [value] Maximum number of rejection cycles +:sloreject [value] Low-side pixel rejection limits (sky sigma) +:shireject [value] High-side pixel rejection limits (sky sigma) +:rgrow [value] Region growing radius (scale units) + +# Photometry parameters + +:apertures [string] List of aperture radii (scale units) +:zmag [value] Zero point of magnitude scale + +# Plotting and marking parameters + +:mkcenter [y/n] Mark computed centers on display +:mksky [y/n] Mark the sky annuli on the display +:mkapert [y/n] Mark apertures on the display +:radplot [y/n] Plot radial profile of object + + + Interactive Phot Setup Menu + + v Mark and verify the critical parameters (f,s,c,a,d,r) + + f Mark and verify the full-width half-maximum of psf + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + + c Mark and verify the centering box width + n Mark and verify the cleaning radius + p Mark and verify the clipping radius + + a Mark and verify the inner radius of the sky annulus + d Mark and verify the width of the sky annulus + g Mark and verify the region growing radius + + r Mark and verify the aperture radii +.fi + +.ih +ALGORITHMS + +A brief description of the data dependent parameters, centering algorithms, +sky fitting algorithms and photometry parameters can be found in the +online help pages for the DATAPARS, CENTERPARS, FITSKYPARS, and PHOTPARS +tasks. + +.ih +OUTPUT + +In interactive mode the following quantities are printed on the standard +output as each object is measured. Err is a simple string indicating whether +or not an error was detected in the centering algorithm, the sky fitting +algorithm or the photometry algorithm. Mag are the magnitudes in apertures 1 +through N respectively and xcenter, ycenter and msky are the x and y centers +and the sky value respectively. + +.nf + image xcenter ycenter msky mag[1 ... N] error +.fi + +In both interactive and batch mode full output is written to the text file +\fIoutput\fR. At the beginning of each file is a header listing the +current values of the parameters when the first stellar record was written. +These parameters can be subsequently altered. For each star measured the +following record is written + +.nf + image xinit yinit id coords lid + xcenter ycenter xshift yshift xerr yerr cier error + msky stdev sskew nsky nsrej sier serror + itime xairmass ifilter otime + rapert sum area flux mag merr pier perr +.fi + +Image and coords are the name of the image and coordinate file respectively. +Id and lid are the sequence numbers of stars in the output and coordinate +files respectively. Cier and cerror are the centering algorithm error code +and accompanying error message respectively. Xinit, yinit, xcenter, ycenter, +xshift, yshift, and xerr, yerr are self explanatory and output in pixel units. +The sense of the xshift and yshift definitions is the following. + +.nf + xshift = xcenter - xinit + yshift = ycenter - yinit +.fi + +Sier and serror are the sky fitting error code and accompanying error +message respectively. Msky, stdev and sskew are the best estimate of the sky +value (per pixel), standard deviation and skew respectively. Nsky and nsrej +are the number of sky pixels and the number of sky pixels rejected respectively. + +Itime is the exposure time, xairmass is self-evident, ifilter is an +id string identifying the filter used in the observations, and otime is +a string containing the time of the observation in whatever units the +user has set up. + +Rapert, sum, area, and flux are the radius of the aperture in scale units, +the total number of counts including sky in the aperture, the area of the +aperture in square pixels, and the total number of counts excluding sky +in the aperture. Mag and merr are the magnitude and error in the magnitude +in the aperture (see below). + +.nf + flux = sum - area * msky + mag = zmag - 2.5 * log10 (flux) + 2.5 * log10 (itime) + merr = 1.0857 * error / flux + error = sqrt (flux / epadu + area * stdev**2 + + area**2 * stdev**2 / nsky) +.fi + +Pier and perror are photometry error code and accompanying error message. + +In interactive mode a radial profile of each measured object is plotted +in the graphics window if \fIradplots\fR is "yes". + +In interactive and batchmode a radial profile plot is written to +\fIplotfile\fR if it is defined each time the result of an object +measurement is written to \fIoutput\fR . + +.ih +ERRORS + +If the object centering was error free then the field cier will be zero. +Non-zero values of cier flag the following error conditions. + +.nf + 0 # No error + 101 # The centering box is off image + 102 # The centering box is partially off the image + 103 # The S/N ratio is low in the centering box + 104 # There are two few points for a good fit + 105 # The x or y center fit is singular + 106 # The x or y center fit did not converge + 107 # The x or y center shift is greater than maxshift + 108 # There is bad data in the centering box +.fi + +If all goes well during the sky fitting process then the error code sier +will be 0. Non-zero values of sier flag the following error conditions. + +.nf + 0 # No error + 201 # There are no sky pixels in the sky annulus + 202 # Sky annulus is partially off the image + 203 # The histogram of sky pixels has no width + 204 # The histogram of sky pixels is flat or concave + 205 # There are too few points for a good sky fit + 206 # The sky fit is singular + 207 # The sky fit did not converge + 208 # The graphics stream is undefined + 209 # The file of sky values does not exist + 210 # The sky file is at EOF + 211 # Cannot read the sky value correctly + 212 # The best fit parameter are non-physical +.fi + +If no error occursor during the measurement of the magnitudes then pier is +0. Non-zero values of pier flag the following error conditions. + +.nf + 0 # No error + 301 # The aperture is off the image + 302 # The aperture is partially off the image + 303 # The sky value is undefined + 305 # There is bad data in the aperture +.fi + +.ih +EXAMPLES + +1. Compute the magnitudes for a few stars in dev$ypix using the display +and the image cursor. Setup the task parameters using the interactive +setup menu defined by the i key command and a radial profile plot. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> phot dev$ypix + + ... type ? to print an optional help page + + ... move the image cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or hit + CR to accept the default + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + photometry apertures, and sigma using the graphics cursor and + the stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... move the image cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.mag.1 +.fi + +2. Compute the magnitudes for a few stars in dev$ypix using a contour plot +and the graphics cursor. This option is only useful for those (now very few) +users who have access to a graphics terminal but not to an image display +server. Setup the task parameters using the interactive setup menu defined by +the i key command as in example 1. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... make a contour plot of dev$ypix + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of dev$ypix in the file ypix.plot1 + + ap> phot dev$ypix display=stdgraph + + ... type ? to get an optional help page + + ... move graphics cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or CR + to accept the default value + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + apertures, and sigma using the graphics cursor and the + stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... retype :.read ypix.plot1 to reload the contour plot + + ... move the graphics cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to verify + + ... full output will appear in the text file ypix.mag.2 + + ap> set stdimcur = <default> + + ... reset stdimcur to its previous value +.fi + + +3. Setup and run PHOT interactively on a list of objects temporarily +overriding the fwhmpsf, sigma, cbox, annulus, dannulus, and apertures +parameters determined in examples 1 or 2. + +.nf + ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify- + + ... make a coordinate list + + ... the output will appear in the text file ypix.coo.1 + + ap> phot dev$ypix cbox=7.0 annulus=12.0 dannulus=5.0 \ + apertures="3.0,5.0" coords=ypix.coo.1 + + ... type ? for optional help + + + ... move the graphics cursor to the stars and tap space bar + + or + + ... select stars from the input coordinate list with m / :m # + and measure with spbar + + ... measure stars selected from the input coordinate list + with n / n # + + ... a one line summary of results will appear on the standard output + for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.mag.3 ... +.fi + + +4. Display and measure some stars in an image section and write the output +coordinates in the coordinate system of the parent image. + +.nf + ap> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + ap> phot dev$ypix[150:450,150:450] wcsout=tv + + ... move cursor to stars and type spbar + + ... type q to quit and q again to confirm quit + + ... output will appear in ypix.mag.4 + + ap> pdump ypix.mag.4 xc,yc yes | tvmark 1 STDIN col=204 +.fi + +5. Run PHOT in batch mode using the coordinate file and the previously +saved parameters. Verify the critical parameters. + +.nf + ap> phot dev$ypix coords=ypix.coo.1 verify+ inter- + + ... output will appear in ypix.mag.5 ... +.fi + +6. Repeat example 5 but assume that the input coordinate are ra and dec +in degrees and degrees, turn off verification, and submit the task to to +the background. + +.nf + ap> display dev$ypix 1 + + ap> rimcursor wcs=world > radec.coo + + ... move to selected stars and type any key + + ... type ^Z to quit + + ap> phot dev$ypix coords=radec.coo wcsin=world verify- inter- & + + ... output will appear in ypix.mag.6 + + ap> pdump ypix.mag.6 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars on the display +.fi + + +7. Run PHOT interactively without using the image display. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = text + + ... set the image cursor to the standard input + + ap> phot dev$ypix coords=ypix.coo.1 + + ... type ? for optional help + + ... type :m 3 to set the initial coordinates to those of the + third star in the list + + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to enter the default menu + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + apertures, and sigma using the graphics cursor and the + stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its default + value + ... type q to quit the setup menu + + ... type r to rewind the coordinate list + + ... type l to measure all the stars in the coordinate list + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... full output will appear in the text file ypix.mag.7 + + ap> set stdimcur = <default> + + ... reset the value of stdimcur +.fi + +8. Use a image cursor command file to drive the PHOT task. The cursor command +file shown below sets the cbox, annulus, dannulus, and apertures parameters +computes the centers, sky values, and magnitudes for 3 stars, updates the +parameter files, and quits the task. + +.nf + ap> type cmdfile + : cbox 9.0 + : annulus 12.0 + : dannulus 5.0 + : apertures 5.0 + 442 410 101 \040 + 349 188 101 \040 + 225 131 101 \040 + w + q + + ap> phot dev$ypix icommands=cmdfile verify- + + ... full output will appear in ypix.mag.8 +.fi + + +.ih +BUGS + +It is currently the responsibility of the user to make sure that the +image displayed in the frame is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the centerpars mkcenter switch to +"yes", the fitskypars mksky switch to"yes", or the photpars mkapert +switch to "yes". It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO +datapars, centerpars, fitskypars, photpars, qphot, wphot, polyphot +.endhelp diff --git a/noao/digiphot/apphot/doc/photpars.hlp b/noao/digiphot/apphot/doc/photpars.hlp new file mode 100644 index 00000000..0a172ba3 --- /dev/null +++ b/noao/digiphot/apphot/doc/photpars.hlp @@ -0,0 +1,102 @@ +.help photpars May00 noao.digiphot.apphot +.ih +NAME +photpars -- edit the photometry parameters +.ih +USAGE +photpars +.ih +PARAMETERS +.ls weighting = "constant" +The type of weighting for the WPHOT task. The weighting parameter is +ignored by the PHOT task. The options are: +.ls constant +Uniform weights of 1 for each pixel are used. +.le +.ls cone +A conical weighting function of full width half maximum \fIfwhmpsf\fR as +defined in the DATAPARS parameter set is used. +.le +.ls gauss +A Gaussian weighting function of full width half maximum \fIfwhmpsf\fR as +defined in the DATAPARS parameter set is used. +.le +.le +.ls apertures = "3" (scale units) +A list of aperture radii in units of the scale parameter or the name of the +file containing the list of aperture radii. List elements may be separated by +whitespace or commas. A range syntax of the form ap1:apN:apstep is also +supported. +.le +.ls zmag = 25.00 +The zero point offset for the magnitude scale. +.le +.ls mkapert = no +Mark the photometry apertures on the displayed image ? +.le + +.ih +DESCRIPTION + +The integral of the flux within the circular apertures specified by +\fIapertures\fR is computed by summing pixels in the aperture with +the specified weighting function \fIweighting\fR. The fraction of each pixel +lying within the aperture is computed by an approximation and all the +approximations are summed. The zero point of the magnitude +scale is determined by \fIzmag\fR. + +\fRApertures\fR is specified in units of the image scale. If \fIscale\fR +is specified in units of the half-width at half-maximum of the point +spread function the aperture per pixel a single value of apertures +will work well on images with differing psfs. + +.ih +EXAMPLES + +1. List the PHOTPARS parameters. + +.nf + da> lpar photpars +.fi + +2. Edit the PHOTPARS parameters. + +.nf + da> photpars +.fi + +3. Edit the PHOTPARS parameters from within the PHOT task. + +.nf + da> epar phot + + ... edit a few phot parameters + + ... move to the photpars parameter and type :e + + ... edit the photpars parameters and type :wq + + ... finish editing the phot parameters and type :wq + +.fi + +4. Save the current PHOTPARS parameter set in a text file photnite1.par. +This can also be done from inside a higher level task as in the +above example. + +.nf + da> photpars + + ... edit some parameters + + ... type ":w photnite1.par" from within epar +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +phot,wphot,radprof +.endhelp diff --git a/noao/digiphot/apphot/doc/polymark.hlp b/noao/digiphot/apphot/doc/polymark.hlp new file mode 100644 index 00000000..e88bc089 --- /dev/null +++ b/noao/digiphot/apphot/doc/polymark.hlp @@ -0,0 +1,430 @@ +.help polymark May00 noao.digiphot.apphot +.ih +NAME +polymark -- create or review polygon and coordinate lists for input to the +polyphot task +.ih +USAGE +polymark image +.ih +PARAMETERS +.ls images +The list of input images used to define the polygons. +.le +.ls coords = "default" +The input / output center positions file. The center positions for each +polygonal aperture are read from or written to coords. There may more than one +center position per polygon. Center positions are written to coords 1 center +position per line. When the current polygon changes POLYMARK inserts a line +containing a single ';' after the last center position. If coords is +"default", "dir$default" or a directory specification then a center position +file name of the form dir$root.extension.version is constructed, where dir is +the directory, root is the root image name, extension is "coo" and version is +the next available version of the file. +.le +.ls polygons = "default" +The name of the polygons file. The vertices of each polygon are read from or +written to the polygons file. The polygons file contains a list of the +polygon vertices. Each vertex list is terminated by a line containing a ';' +after the last vertex. If polygons is "default", "dir$default" or a directory +specification then an output name of the form dir$root.extension.version is +constructed, where dir is the directory, root is the root image name, extension +is "ver" and the version is next available version of the file. The number of +polygon files must be equal to the number of image files. +.le +.ls icommands = "" +The image cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from or written +to \fIcoords\fR and \fIpolygons\fR. The image header coordinate system is +used to transform from the input coordinate system to the "logical" pixel +coordinate system used internally, 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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" 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 cacheing is +disabled. +.le +.ls graphics = ")_.graphics" +The standard graphics device. +.le +.ls display = ")_.display" +The default display device. Display may be set to the apphot package +parameter value (the default), "yes", or "no. By default graphics overlay is +disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables +graphics overlay with the IMD graphics kernel. Setting display to +"stdgraph" enables POLYMARK to work interactively from a contour plot. +.le + +.ih +DESCRIPTION + +POLYMARK creates and / or displays center position and polygons files +suitable for input to POLYPHOT. For each image in the input list POLYMARK +creates a polygons file \fIpolygons\fR and center positions file \fIcoords\fR, +if these do not already exist. The format of the polygons and center +position files is described in the OUTPUT section. + +Polygonal apertures are defined and drawn on the image display using +the image display cursor and then shifted to the desired center +using the image display cursor. At any point in the marking process +the user may rewind the polygon and coordinate file and draw the previously +defined polygons on the display. + +The coordinates read from \fIpolygons\fR or \fIcoords\fR are assumed to be +in coordinate system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIpolygons\fR or \fIcoords\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 input image pixels are cached in memory. If cacheing +is enabled and POLYMARK is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because POLYMARK +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. +.ih +CURSOR COMMANDS + +The following interactive keystroke and colon commands are available. + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +d Plot radial profile of star near cursor +g Define the current polygonal aperture +f Draw the current polygon on the display +spbar Draw the current polygon on the display, output the polygon +r Rewind the polygon list +m Draw the next polygon in the polygon list on the display +l Draw all the remaining polygons in the list on the display +q Exit + + Colon commands + +:m [n] Draw the next [nth] polygon in the polygon list on the display +.fi + +.ih +OUTPUT + +A sample polygons file and accompanying coordinates file is listed below. + +.nf + # Sample Polygons File (2 polygons) + + 200.5 200.5 + 300.5 200.5 + 300.5 300.5 + 200.5 300.5 + ; + 100.4 100.4 + 120.4 100.4 + 120.4 120.4 + 100.4 120.4 + ; +.fi + +.nf + # Sample Coordinates File (2 groups, 1 for each polygon) + + 123.4 185.5 + 110.4 130.4 + 150.9 200.5 + ; + 85.6 35.7 + 400.5 300.5 + 69.5 130.5 + ; +.fi + +.ih +EXAMPLES + +1. Create a coordinate list and polygon file using the image display and +image display cursor. Use polymark to both create and display the +polygon and polygon center lists. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> polymark dev$ypix display=imdg + + ... type ? for an optional help page + + ... type g to enter the "define a polygon" menu + ... move the cursor to the first vertex, tap the space bar + to mark the vertex, and repeat for each vertex + ... type q to quit the "define a polygon" menu + ... mark each vertex only once, POLYPHOT will close the + polygon for you + + ... move the cursor to the desired polygon center and + tap the space bar to record the polygon + ... repeat for all desired polygon centers + + ... type g to define the next polygon + ... move the cursor to the first vertex, tap the space bar + to mark the vertex and repeat for each vertex + ... type q to quit the polygon menu + ... mark each vertex only once, POLYPHOT will close the + polygon for you + + ... move the cursor to the desired polygon center and + tap the space bar + ... repeat for all desired polygon centers + + ... type q to quit and q to confirm the quit + + ... output will appear in ypix.coo.1 and ypix.ver.1 + + + ap> display dev$ypix 2 fi+ + + ... display the image + + ap> polymark dev$ypix coords=ypix.coo.1 polygons=ypix.ver.1 \ + display=imdg + + ... type m to mark the first polygon / polygon center on the display + + ... type m to mark the next polygon / polygon center on the display + + ... type l to mark the remaining polygons + + ... type q to quit and q to confirm the quit + + + ap> display dev$ypix 2 fi+ + + ... redisplay the image + + ap> polymark dev$ypix coords="" polygons=ypix.ver.1 \ + display=imdg + + ... type l to mark the polygon list, note that since there is + no coords file the polygons are not shifted + + ... type q to quit and q to confirm the quit +.fi + + +2. Repeat the previous example using an image section. + +.nf + ap> display dev$ypix[150:450,150:450] 1 fi+ + + ... display the image + + + ap> polymark dev$ypix[150:450,150:450]] display=imdg wcsout=tv + + ... type ? for an optional help page + + ... type g to enter the "define a polygon" menu + ... move the cursor to the first vertex, tap the space bar + to mark the vertex, and repeat for each vertex + ... type q to quit the "define a polygon" menu + ... mark each vertex only once, POLYPHOT will close the + polygon for you + + ... move the cursor to the desired polygon center and + tap the space bar to record the polygon + ... repeat for all desired polygon centers + + ... type g to define the next polygon + ... move the cursor to the first vertex, tap the space bar + to mark the vertex and repeat for each vertex + ... type q to quit the polygon menu + ... mark each vertex only once, POLYPHOT will close the + polygon for you + + ... move the cursor to the desired polygon center and + tap the space bar + ... repeat for all desired polygon centers + + ... type q to quit and q to confirm the quit + + ... output will appear in ypix.coo.2 and ypix.ver.2 + + + ap> display dev$ypix[150:450,150:450] 2 fi+ + + ... display the image + + + ap> polymark dev$ypix[150:450,150:450] coords=ypix.coo.2 \ + polygons=ypix.ver.2 display=imdg wcsin=tv + + ... type m to mark the first polygon / polygon center on the display + + ... type m to mark the next polygon / polygon center on the display + + ... type l to mark the remaining polygons + +.fi + + +3. Repeat example 1 using a contour plot instead of the image display. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... draw a contour plot on the screen + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of dev$ypix in the file ypix.plot1 + + ap> polymark dev$ypix display=stdgraph + + ... type g to enter the define a polygon menu + ... move the cursor to the first vertex, tap the space bar + to mark the vertex, and repeat for each vertex + ... type q to quit the define a polygon menu + ... mark each vertex only once, POLYPHOT will close the + polygon for you + + ... move the cursor to the desired polygon center and + tap the space bar to record the polygon + ... repeat for all desired polygon centers + + ... type g to define the next polygon + ... move the cursor to the first vertex, tap the space bar + to mark the vertex and repeat for each vertex + ... type q to quit the define a polygon menu + ... mark each vertex only once, POLYPHOT will close the + polygon for you + + ... move the cursor to the desired polygon center and + tap the space bar + ... repeat for all desired polygon centers + + ... type r to rewind the coordinate and polygon lists + + ... type :.read ypix.plot1 to reread the contour plot + + ... type l to display all the polygons ... + + ... type q to quit and q again to confirm the quit + + ... output will appear in ypix.ver.3 and ypix.coo.3 + + ap> contour dev$ypix + + ... redraw the contour plot + + ap> polymark dev$ypix coords="ypix.coo.3" polygons=ypix.ver.3 \ + display=stdgraph + + ap> set stdimcur = <default> + + ... reset the value of the stdimcur parameter +.fi + +.ih +BUGS + +It is the responsibility of the user to make sure that the image displayed +in the image display is the same as the image specified by the image parameter. + +Commands which draw to the image display are disabled by default. To enable +graphics overlay on the image display, set the display parameter to "imdr", +"imdg", "imdb", or "imdy" to get red, green, blue or yellow overlays. It +may be necessary to run gflush and to redisplay the image to get the overlays +position correctly. + +There are no restrictions on the shape of the polygon but the vertices +must be listed in order either clockwise or counterclockwise in the +polygons file. + +It is not necessary to close the polygon when drawing on the display. +POLYMARK will complete the polygon for you. + +.ih +SEE ALSO +polyphot +.endhelp diff --git a/noao/digiphot/apphot/doc/polypars.hlp b/noao/digiphot/apphot/doc/polypars.hlp new file mode 100644 index 00000000..e31e4dcd --- /dev/null +++ b/noao/digiphot/apphot/doc/polypars.hlp @@ -0,0 +1,69 @@ +.help polypars May00 noao.digiphot.apphot +.ih +NAME +polypars -- edit the polygonal aperture photometry parameters +.ih +USAGE +polypars +.ih +PARAMETERS +.ls zmag = 25.00 +The zero point offset for the magnitude scale. +.le +.ls mkpolygon = no +Draw the polygons on the screen. +.le +.ih +DESCRIPTION +The zero point of the magnitude scale is determined by \fIzmag\fR. + +If the \fImkpolygon\fR switch is enabled polygons are marked on the screen. +.ih +EXAMPLES + +1. List the polygonal aperture photometry parameters. + +.nf + ap> lpar polypars +.fi + +2. Edit the polygonal aperture photometry parameters. + +.nf + ap> polypars +.fi + +3. Edit the POLYPARS parameters from within the POLYPHOT task. + +.nf + da> epar polyphot + + ... edit a few polyphot parameters + + ... move to the polypars parameter and type :e + + ... edit the polypars parameters and type :wq + + ... finish editing the polyphot parameters and type :wq +.fi + +4. Save the current POLYPARS parameter set in a text file polynite1.par. +This can also be done from inside a higher level task as in the +above example. + +.nf + da> polypars + + ... edit some parameters + + ... type ":w polynite1.par" from within epar + +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +polyphot. polymark +.endhelp diff --git a/noao/digiphot/apphot/doc/polyphot.hlp b/noao/digiphot/apphot/doc/polyphot.hlp new file mode 100644 index 00000000..8bec19d4 --- /dev/null +++ b/noao/digiphot/apphot/doc/polyphot.hlp @@ -0,0 +1,791 @@ +.help polyphot May00 noao.digiphot.apphot +.ih +NAME +polyphot -- compute magnitudes inside polygonal apertures +.ih +USAGE +polyphot image +.ih +PARAMETERS +.ls image +The list of images containing the objects to be measured. +.le +.ls coords = "" +The list of text files containing the center coordinates of the polygons +to be measured. Polygon centers are listed one per line with the x and y +coordinates in columns one and two. A ";" character in column terminates +the polygon center list for the current polygon and tells POLYPHOT to skip +to the next polygon listed in \fIpolygons\fR. If coords is undefined the +polygons are not shifted. The number of polygon center files must be +zero, one, or equal to the number of images. If coords is "default", +"dir$default", or a directory specification then a coords file name +of the form dir$root.extension.version is constructed and searched for, +where dir is the directory, root is the root image name, extension is "coo" +and version is the next available version number for the file. +.le +.ls polygons = "" +The list of text files containing the vertices of the polygons to be +measured. The polygon vertices are listed 1 vertext per line with the x and y +coordinates of each vertex in columns 1 and 2. The vertices list is terminated +a ';' in column 1. The number of polygon files must be zero, one, or +equal to the number of images. If polygons is "default", "dir$default", or +a directory specification then a coords file name of the form +dir$root.extension.version is constructed and searched for, where dir is the +directory, root is the root image name, extension is "ver" +and version is the next available version number for the file. +.le +.ls output = "default" +The name of the results file or results directory. If output is +"default", "dir$default", or a directory specification then an output file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "ply" and version is +the next available version number for the file. The number of output files +must be zero, one, or equal to the number of image files. In both interactive +and batch mode full output is written to output. In interactive mode +an output summary is also written to the standard output. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The critical +parameters \fIfwhmpsf\fR and \fIsigma\fR are located here. If \fIdatapars\fR +is undefined then the default parameter set in uparm directory is used. +.le +.ls centerpars = "" +The name of the file containing the centering parameters. The critical +parameters \fIcalgorithm\fR and \fIcbox\fR are located here. +If \fIcenterpars\fR is undefined then the default parameter set in +uparm directory is used. +.le +.ls fitskypars = "" +The name of the text file containing the sky fitting parameters. The critical +parameters \fIsalgorithm\fR, \fIannulus\fR, and \fIdannulus\fR are located here. +If \fIfitskypars\fR is undefined then the default parameter set in uparm +directory is used. +.le +.ls polypars = "" +The name of the text file containing the polygon photometry parameters, +If \fIpolypars\fR is undefined then the default parameter set in + uparm directory is used. +.le +.ls interactive = yes +Run the task interactively ? +.le +.ls icommands = "" +The image cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.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 cacheing is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical parameters in non-interactive mode ? Verify may be set to +the apphot package parameter value (the default), "yes", or "no. +.le +.ls update = ")_.update" +Update the critical parameters in non-interactive mode if verify is yes ? +Update may be set to the apphot package parameter value (the default), "yes", +or "no. +.le +.ls verbose = ")_.verbose" +Print messages in non-interactive mode? Verbose may be set to the apphot +package parameter value (the default), "yes", or "no. +.le +.ls graphics = ")_.graphics" +The default graphics device. Graphics may be set to the apphot package +parameter value (the default), "yes", +or "no. +.le +.ls display = ")_.display" +The default display device. By default graphics overlay is disabled. Display +may be set to the apphot package parameter value (the default), "yes", or "no. +Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables graphics +overlay with the IMD graphics kernel. Setting display to "stdgraph" enables +POLYPHOT to work interactively from a contour plot. +.le + +.ih +DESCRIPTION + +POLYPHOT computes the magnitude of objects in the IRAF image \fIimage\fR +inside a list of polygonal apertures whose vertices are listed in the text file +\fIpolygons\fR or are marked on the display interactively with the +image cursor. The polygon centers may be read from the polygon center +file \fIcoords\fR or set interactively with the image cursor. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\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 input image pixels are cached in memory. If cacheing +is enabled and POLYPHOT is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because POLYPHOT +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. + +In interactive mode the user may either define the list of objects to be +measured interactively with the image cursor or create a polygon and polygon +center list prior to running POLYPHOT. In either case the user may adjust +the centering, sky fitting, and photometry algorithm parameters until a +satisfactory fit is achieved and optionally store the final results +in \fIoutput\fR. In batch mode the polygon and polygon centers are read +from the text files \fIpolygons\fR and \fIcoords\fR or the image cursor +parameter \fIicommands\fR can be redirected to a text file containing +a list of cursor commands. In batch mode the current set of algorithm +parameters is used. + +.ih +THE POLYGON and POLYGON CENTERS FILES + +A sample polygons file and accompanying coordinates file is listed below. + +.nf + # Sample Polygons File (2 polygons) + + 200.5 200.5 + 300.5 200.5 + 300.5 300.5 + 200.5 300.5 + ; + 100.4 100.4 + 120.4 100.4 + 120.4 120.4 + 100.4 120.4 + ; +.fi + +.nf + # Sample Coordinates File (2 groups, 1 for each polygon) + + 123.4 185.5 + 110.4 130.4 + 150.9 200.5 + ; + 85.6 35.7 + 400.5 300.5 + 69.5 130.5 + ; +.fi + + +.ih +CURSOR COMMANDS + +The following polyphot commands are currently available. + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify the critical parameters +w Store the current parameters +d Plot radial profile of current object +i Define current polygon, graphically set parameters using current object +g Define current polygon +c Fit center for current object +t Fit sky around cursor +a Average sky values fit around several cursor positions +s Fit sky around current object +h Do photometry for current polygon +j Do photometry for current polygon, output results +p Do photometry for current object using current sky +o Do photometry for current object using current sky, output results +f Do photometry for current object +spbar Do photometry for current object, output results +m Move to next object in coordinate list +n Do photometry for next object in coordinate list, output results +l Do photometry for remaining objects in list, output results +r Rewind the polygon list +e Print error messages +q Exit task + + + Colon Commands + +:show [data/center/sky/phot] List the parameters +:m [n] Move to next [nth] object in coordinate list +:n [n] Do photometry for next [nth] object in coordinate list, output results + + + Colon Parameter Editing Commands + +# Image and file name parameters + +:image [string] Image name +:polygon [string] Polygon file +:coords [string] Coordinate file +:output [string] Results file + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full-width half-maximum of PSF (scale units) +:emission [y/n] Emission feature (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good pixel value (counts) +:datamax [value] Maximum good pixel value (counts) + +# Noise parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per count) +:epadu [value] Readout noise (electrons) + +# Observing parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Integration time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Centering algorithm parameters + +:calgorithm [string] Centering algorithm +:cbox [value] Width of centering box (scale units) +:cthreshold [value] Centering intensity threshold (sigma) +:cmaxiter [value] Maximum number of iterations +:maxshift [value] Maximum center shift (scale units) +:minsnratio [value] Minimum S/N ratio for centering +:clean [y/n] Clean subraster before centering +:rclean [value] Cleaning radius (scale units) +:rclip [value] Clipping radius (scale units) +:kclean [value] Clean K-sigma rejection limit (sigma) + +# Sky fitting algorithm parameters + +:salgorithm [string] Sky fitting algorithm +:skyvalue [value] User supplied sky value (counts) +:annulus [value] Inner radius of sky annulus (scale units) +:dannulus [value] Width of sky annulus (scale units) +:khist [value] Sky histogram extent (+/- sigma) +:binsize [value] Resolution of sky histogram (sigma) +:sloclip [value] Low-side clipping factor in percent +:shiclip [value] High-side clipping factor in percent +:smooth [y/n] Lucy smooth the sky histogram +:smaxiter [value] Maximum number of iterations +:snreject [value] Maximum number of rejection cycles +:sloreject [value] Low-side pixel rejection limits (sky sigma) +:shireject [value] High-side pixel rejection limits (sky sigma) +:rgrow [value] Region growing radius (scale units) + +# Photometry parameters + +:zmag [value] Zero point of magnitude scale + +# Plotting and marking parameters + +:mkcenter [y/n] Mark computed centers on the display +:mksky [y/n] Mark the sky annuli on the display +:mkpolygon [y/n] Mark the polygon on the display + + + +The following commands are available from inside the interactive setup menu. + + + Interactive Photometry Setup Menu + + v Mark and verify the critical parameters (f,c,s,a,d) + + f Mark and verify the psf full-width half-maximum + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + + c Mark and verify the centering box width + n Mark and verify the cleaning radius + p Mark and verify the clipping radius + + a Mark and verify the inner radius of the sky annulus + d Mark and verify the width of the sky annulus + g Mark and verify the region growing radius +.fi + +.ih +ALGORITHMS + +A brief description of the data dependent parameters, the centering +algorithms and the sky fitting algorithms can be found in the online +manual pages for the DATAPARS, CENTERPARS, and FITSKYPARS tasks. +User measuring extended "fuzzy" features may wish to set the CENTERPARS +\fIcalgorithm\fR parameter to "none", the FITSKYPARS parameters +\fIsalgorithm\fR and \fIskyvalue\fR to "constant" and <uservalue> before +running POLYPHOT. + +POLYPHOT computes the intersection of each image line with the line segments +composing the polygon in order to determine the extent of the polygon. A one +dimensional summation including a fractional approximation for the end pixels +is performed over those regions of the image line which intersect the polygon. +All the 1D summations are summed to give the total integral. The vertices of +the polygon must be specified in order either clockwise or counterclockwise. + +.ih +OUTPUT + +In interactive mode the following quantities are printed on the standard +output as each object is measured. Error is a simple string which indicates +whether the task encountered an error in the centering algorithm, the sky +fitting algorithm or the photometry algorithm. Mag are the magnitudes in +the polygonal aperture and xcenter, ycenter and msky are the x and y centers +and the sky value respectively. + +.nf + image xcenter ycenter msky mag merr error +.fi + +In both interactive and batch mode full output is written to the text file +\fIoutput\fR. At the beginning of each file is a header listing the current +values of the parameters when the first stellar record was written. These +parameters can be subsequently altered. For each star measured the following +record is written + +.nf + image xinit yinit id coords lid + xcenter ycenter xshift yshift xerr yerr cier error + msky stdev sskew nsky nsrej sier serror + itime xairmass ifilter otime + sum area flux mag merr pier perr + polygons pid oldxmean oldymean xmean ymean maxrad nver + xvertex yvertex +.fi + +Image and coords are the name of the image and coordinate file respectively. +Id and lid are the sequence numbers of objects in the output and coordinate +files respectively. Cier and cerror are the centering error code and +accompanying error message respectively. Xinit, yinit, xcenter, ycenter, +xshift, yshift, and xerr, yerr are self explanatory and output in pixel units. +The sense of the xshift and yshift definitions is the following. + +.nf + xshift = xcenter - xinit + yshift = ycenter - yinit +.fi + +Sier and serror are the sky fitting error code and accompanying error +message respectively. Msky, stdev and sskew are the best estimate of the +sky value (per pixel), standard deviation and skew respectively. Nsky and +nsrej are the number of sky pixels used and the number of sky pixels rejected +from the fit respectively. + +Itime is the exposure time, xairmass is self-evident, ifilter is an id string +identifying the filter used during the observation, and otime is a string +specifying the time of the observation in whatever units the user has chosen. + +Sum, area, and flux are the total number of counts including sky in the +polygonal aperture, the area of the aperture in square pixels, and the total +number of counts in the aperture excluding sky. Mag and merr are the magnitude +and error in the magnitude in the aperture after subtracting the sky value +(see below). + +.nf + flux = sum - area * msky + mag = zmag - 2.5 * log10 (flux) + 2.5 * log10 (itime) + merr = 1.0857 * error / flux + error = sqrt (flux / epadu + area * stdev**2 + + area**2 * stdev**2 / nsky) +.fi + +Pier and perror are photometry error code and accompanying error message. + +Polygons and pid are the name of the polygons file and the polygon id +respectively. Oldxmean, oldymean, xmean and ymean are the original and +current average coordinates of the current polygon. Oldxmean and oldymean +are the values in the polygons file or the values which correspond to the +polygon drawn on the display. Xinit and yinit define the position to +which the polygonal aperture was shifted. Xmean and ymean are generally +identical to xcenter and ycenter and describe the position of the +centered polygonal aperture. Maxrad is the maximum +distance of a polygon vertex from the average of the vertices. Nver, xvertex +and yvertex are the number of vertices and the coordinates of the vertices +of the polygonal aperture. + +.ih +ERRORS + +If the object centering was error free then the field cier will be zero. +Non-zero values of cier flag the following error conditions. + +.nf + 0 # No error + 101 # The centering box is off image + 102 # The centering box is partially off the image + 103 # The S/N ratio is low in the centering box + 104 # There are two few points for a good fit + 105 # The x or y center fit is singular + 106 # The x or y center fit did not converge + 107 # The x or y center shift is greater than maxshift + 108 # There is bad data in the centering box +.fi + +If all goes well during the sky fitting process then the error code sier +will be 0. Non-zero values of sier flag the following error conditions. + +.nf + 0 # No error + 201 # There are no sky pixels in the sky annulus + 202 # Sky annulus is partially off the image + 203 # The histogram of sky pixels has no width + 204 # The histogram of sky pixels is flat or concave + 205 # There are too few points for a good sky fit + 206 # The sky fit is singular + 207 # The sky fit did not converge + 208 # The graphics stream is undefined + 209 # The file of sky values does not exist + 210 # The sky file is at EOF + 211 # Cannot read the sky value correctly + 212 # The best fit parameter are non-physical +.fi + +If no error occurs during the measurement of the magnitudes then pier is +0. Non-zero values of pier flag the following error conditions. + +.nf + 0 # No error + 801 # The polygon is undefined + 802 # The polygon is partially off the image + 803 # The polygon is off the image + 804 # The sky value is undefined + 805 # There is bad data in the aperture +.fi + +.ih +EXAMPLES + +1. Compute the magnitudes inside 2 polygonal aperture for a few regions in +dev$ypix using the display and the image cursor. Turn off centering and set +the sky background to 0.0. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> polyphot dev$ypix calgorithm=none salgorithm=constant \ + skyvalue=0.0 display=imdg mkpolygon+ + + ... type ? to print a help page + + ... move image cursor to a region of interest + + ... type g to enter the polygon definition menu + ... use the image cursor and spbar key to mark the vertices of + the polygonal aperture + ... mark each vertex only once, POLYPHOT will close the polygon + for you + ... type q to quit the polygon definition menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... move the image cursor to the objects of interest and tap + the space bar, the polygon will be marked on the image + display + + ... type g to enter the polygon definition menu + ... use the image cursor and spbar key to mark the vertices of + the polygonal aperture + ... mark each vertex only once, POLYPHOT will close the polygon + for you + ... type q to quit the polygon definition menu + + ... move the image cursor to the objects of interest and tap + the space bar, the polygon will be marked on the image + display + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... the output will appear in ypix.ply.1 +.fi + + +2. Repeat the previous example but use a contour plot and the graphics +cursor in place of the image display and image cursor. This option is +really only useful for users (very few these days) with access to a graphics +terminal but not an image display server. + +.nf + ap> show stdimcur + + ... determine the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... create a contour plot of dev$ypix + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of dev$ypix in the file ypix.plot1 + + ap> polyphot dev$ypix calgorithm=none salgorithm=constant \ + skyvalue=0.0 display=stdgraph mkpolygon+ + + ... type ? to print a help page + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... move image cursor to a region of interest + ... type g to enter the polygon definition menu + ... use the image cursor and spbar key to mark the vertices of + the polygonal aperture + ... mark each vertex only once, POLYPHOT will close the polygon + for you + ... type q to quit the polygon definition menu + + ... move the image cursor to the objects of interest and tap + the space bar, the polygon will be marked on the contour + plot + + ... move image cursor to a region of interest + ... type g to enter the polygon definition menu + ... use the image cursor and spbar key to mark the vertices of + the polygonal aperture + ... mark each vertex only once, POLYPHOT will close the polygon + for you + ... type q to quit the polygon definition menu + + ... move the image cursor to the objects of interest and tap + the space bar, the polygon will be marked on the image + display + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured and the polygons will + be drawn on the display + + ... full output will appear in the text file ypix.ply.2 + + ap> reset stdimcur = <default> + + ... reset stdimcur to its default value + + +.fi + +3. Setup and run POLYPHOT interactively on a list of objects created with +POLYMARK. + +.nf + ap> display dev$ypix 1 + + ... display the image + + ap> polymark dev$ypix display=imdg + + ... type g to enter the polygon definition menu + ... mark each vertex with the spbar + ... mark each vertex only once, POLYPHOT will close the + polygon for you + ... type q to quit the polygon definition menu + + ... move the cursor to the regions of interest and tap + the space bar, the polygon will be marked on the image + display + + ... the polygon and polygon centers will be written to the text + files ypix.ver.1 and ypix.coo.1 respectively + + ... type q to quit and q again to confirm the quit + + ap> display dev$ypix 2 + + ... redisplay the image + + ap> polyphot dev$ypix calgorithm=none salgorithm=constant skyvalue=0.0 \ + coords=default polygon=default display=imdg mkpolygon+ + + ... type n to measure the first polygon in the list + + ... if everything looks okay type l to measure the rest of the stars + + ... a one line summary of results will appear on the standard output + for each star measured and the aperture will be drawn on the + image display + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.ply.3 +.fi + + +4. Repeat example 3 but work on a section of the input image while +preserving the coordinate system of the original image. + +.nf + ap> display dev$ypix[150:450,150:450] 1 + + ... display the image + + p> polymark dev$ypix[150:450,150:450] wcsout=tv display=imdg + + ... type g to enter the polygon definition menu + ... mark each vertex with the spbar + ... mark each vertex only once, POLYPHOT will close the + polygon for you + ... type q to quit the polygon definition menu + + ... move the cursor to the regions of interest and tap + the space bar, the polygon will be marked on the image + display + + ... the polygon and polygon centers will be written to the text + files ypix.ver.1 and ypix.coo.1 respectively + + ... type q to quit and q again to confirm the quit + + ap> display dev$ypix[150:450,150:450] 2 + + ... redisplay the image + + ap> polyphot dev$ypix[150:450,150:450] calgorithm=none \ + salgorithm=constant skyvalue=0.0 coords=default polygon=default \ + display=imdg mkpolygon+ wcsin=tv wcsout=tv + + ... type n to measure the first polygon in the list + + ... if everything looks okay type l to measure the rest of the stars + + ... a one line summary of results will appear on the standard output + for each star measured and the aperture will be drawn on the + image display + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.ply.4 + + ap> pdump ypix.ply.4 xc,yc yes | tvmark 2 STDIN col=204 + + ... mark the centers of the polygons on the display +.fi + + +5. Run POLYPHOT in batch mode using a polygon and coordinate file and the +default parameters. Verify the critical parameters. + +.nf + ap> polyphot dev$ypix coords=default polygon=default inter- verify+ + + ... output will appear in ypix.ply.5 +.fi + + +.ih +TIMINGS +.ih +BUGS +There are no restrictions on the shape of the polygon but the vertices +must be listed or marked in order. + +When marking the polygon on the display it is not necessary to close +the polygon. When the user types q to quit the marking the program +will automatically close the polygon. + +It is currently the responsibility of the user to make sure that the +image displayed on the display is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the centerpars mkcenter switch to +"yes", the fitskypars mksky switch to"yes", or the polypars mkpolygon +switch to "yes". It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO +datapars,centerpars,fitskypars,polypars,qphot,phot,wphot +.endhelp diff --git a/noao/digiphot/apphot/doc/qphot.hlp b/noao/digiphot/apphot/doc/qphot.hlp new file mode 100644 index 00000000..42e3f5bf --- /dev/null +++ b/noao/digiphot/apphot/doc/qphot.hlp @@ -0,0 +1,647 @@ +.help qphot May00 noao.digiphot.apphot +.ih +NAME +qphot -- quick aperture photometer +.ih +USAGE +qphot image cbox annulus dannulus apertures +.ih +PARAMETERS +.ls image +The list of images containing the objects to be measured. +.le +.ls cbox +The width of the centering box in pixels. +.le +.ls annulus +The inner radius of the sky annulus in pixels. +.le +.ls dannulus +The width of the sky annulus in pixels. +.le +.ls apertures +The list of aperture radii in pixels. Apertures is a string parameter +specifying either a single aperture radius e.g. "3.0", a list of aperture +radii separated by commas e.g. "3.0,5.0,10.0", or a range of aperture radii +e.g. "1.0:20.0:1.0". +.le +.ls coords = "" +The list of text files containing initial coordinates for the objects to +be measured. Objects are listed in coords one object per line with the +initial coordinate values in columns one and two. The number of coordinate +files must be zero, one, or equal to the number of images. If coords is +"default", "dir$default", or a directory specification then a coords file name +of the form dir$root.extension.version is constructed and searched for, +where dir is the directory, root is the root image name, extension is "coo" +and version is the next available version number for the file. +.le +.ls output = "default" +The name of the results file or results directory. If output is +"default", "dir$default", or a directory specification then an output file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "mag" and version is +the next available version number for the file. The number of output files +must be zero, one, or equal to the number of image files. In both interactive +and batch mode full output is written to output. In interactive mode +an output summary is also written to the standard output. +.le +.ls plotfile = "" +The name of the file containing radial profile plots of the stars written +to the output file. If plotfile is defined then a radial profile plot +is written to plotfile every time a record is written to \fIoutput\fR. +The user should be aware that this can be a time consuming operation. +.le +.ls zmag = 25.0 +The zero point of the magnitude scale. +.le +.ls exposure = "" +The image header keyword containing the exposure time. +.le +.ls airmass = "" +The image header keyword containing the airmass of the observation. +.le +.ls filter = "" +The image header keyword containing the filter id of the observation. +.le +.ls obstime = "" +The image header keyword containing the time of the observation. +.le +.ls epadu = 1.0 +The gain in photons per adu. Epadu is used to compute the magnitude errors. +.le +.ls interactive = yes +Interactive or batch mode. +.le +.ls radplots = no +If radplots is "yes" and QPHOT is run in interactive mode then a radial profile +of each star is plotted on the screen after it is measured. +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.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 cacheing is +disabled. +.le +.ls verbose = ")_.verbose" +Print messages in non-interactive mode ? Verbose may be set to the apphot +package parameter value (the default), "yes", or "no. +.le +.ls graphics = ")_.graphics" +The default graphics device. Graphics may be set to the apphot package +parameter value (the default), "yes", or "no. +.le +.ls display = ")_.display" +The default display device. Display may be set to the apphot package parameter +value (the default), "yes", or "no. By default graphics overlay is disabled. +Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables graphics +overlay with the IMD graphics kernel. Setting display to "stdgraph" enables +QPHOT to work interactively from a contour plot. +.le + +.ih +DESCRIPTION +QPHOT computes accurate centers, sky values, and magnitudes for a list of +objects in the IRAF image \fIimage\fR whose initial coordinates are +read from the image cursor or the coordinate file \fIcoords\fR, +and writes the computed x and y coordinates, sky values, and +magnitudes to the text file \fIoutput\fR. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\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. + +In interactive mode the user measure objects interactively with the image +cursor, or select them interactively from the coordinate list \fIcoords\fR. +In batch mode the coordinates can be read directly from \fIcoords\fR, or from +the cursor command file specified by the parameter \fIicommands\fR. + +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If cacheing +is enabled and QPHOT is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because QPHOT +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. + +QPHOT computes accurate centers for each object using the centroid +centering algorithm, pixels inside \fIcbox\fR and the default values of the +\fIcenterpars\fR parameters. Accurate sky values for each object are +computed using the \fIcentroid\fR sky fitting algorithm with histogram +smoothing turned on, pixels inside the sky annulus defined by \fIannulus\fR +and \fIdannulus\fR, and the default values of the remaining sky fitting +parameters as defined in the \fIfitskypars\fR parameter set. Magnitudes +are computed using pixels inside the apertures defined by \fIapertures\fR. +The user must set the gain \fIepadu\fR to ensure that the magnitude error +estimates are correctly computed and \fIexposure\fR to normalize the computed +magnitudes to an exposure time of 1 time unit. The zero point of the magnitude +scale can be adjusted by setting \fIzmag\fR. \fIAirmass\fR, \fIfilter\fR, +and \fIobstime\fR are book-keeping parameters. Setting them to appropriate +values will simplify future analysis and calibration steps. + +.ih +CURSOR COMMANDS + +The following list of cursor commands are currently available. + +.nf + Interactive Photometry Commands + +? Print help +: Colon commands +w Save the current parameters +d Plot radial profile of current star +i Interactively set parameters using current star +c Fit center of current star +t Fit sky around the cursor +a Average sky values fit around several cursor positions +s Fit sky for current centered star +p Do photometry for current star, using current sky +o Do photometry for current star, using current sky, output results +f Do photometry for current star +spbar Do photometry for current star, output results +e Print error messages +m Move to next star in coordinate list +n Do photometry for next star in coordinate list, output results +l Do photometry for remaining stars in coordinate list, output results +r Rewind the coordinate list +q Exit task + + + Colon Commands + +:show List the parameters +:m [n] Move to next [nth] star in coordinate list +:n [n] Do photometry for next [nth] star in coordinate list, output results + + Colon Parameter Editing Commands + +:image [string] Image name +:output [string] Output file name +:coords [string] Coords file name + +:cbox [value] Width of the centering box (pixels) +:annulus [value] Inner radius of sky annulus (pixels) +:dannulus [value] Width of sky annulus (pixels) +:apertures [string] List of aperture radii (pixels) +:zmag [value] Zero point of magnitude scale (magnitudes) +:epadu [value] Gain (electrons per adu) + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword + +:radplot [y/n] Plot radial profile of object + + +The following commands are available from inside the interactive setup menu +using the i key. + + + Interactive Qphot Setup Menu + + v Mark and verify the critical parameters (c,a,d,r) + + c Mark and verify the centering box width + a Mark and verify the inner radius of the sky annulus + d Mark and verify the width of the sky annulus + r Mark and verify the aperture radii +.fi + +.ih +OUTPUT +In interactive mode the following quantities are printed on the standard +output as each object is measured. Error is a simple string which indicates +whether the task encountered an error condition from +the centering algorithm, the sky fitting algorithm or the photometry +algorithm respectively. Mag are the magnitudes in +apertures 1 through N respectively and xcenter, ycenter and msky are the +x and y centers and the sky value respectively. + +.nf + image xcenter ycenter msky mag[1 ... N] error +.fi + +In both interactive and batch mode full output is written to the text file +\fIoutput\fR. At the beginning of each file is a header listing the +current values of the parameters when the first stellar record was written. +These parameters can be subsequently altered. For each star measured the +following record is written. + +.nf + image xinit yinit id coords lid + xcenter ycenter xshift yshift xerr yerr cier cerror + msky stdev sskew nsky nsrej sier serror + itime xairmass ifilter otime + rapert sum area flux mag merr pier perror +.fi + +Image and coords are the name of the image and coordinate file respectively. +Id and lid are the sequence numbers of stars in the output and coordinate +files respectively. Cier and cerror are the error code and accompanying +error message for the center computation. Xinit, yinit, xcenter, ycenter, +xshift, yshift, and xerr, yerr are self explanatory and output in pixel units. +The sense of the xshift and yshift definitions is the following. + +.nf + xshift = xcenter - xinit + yshift = ycenter - yinit +.fi + +Sier and serror are the sky fitting error code and accompanying error message +respectively. Msky, stdev and sskew are the best estimate of the sky value +(per pixel), standard deviation and skew respectively. Nsky and nsrej are +the number of sky pixels used and the number of sky pixels rejected +respectively. + +Itime is the exposure time, xairmass is self-evident, ifilter is an +id string used to identify the filter used during the observation, and +otime is a string containing the time stamp in whatever units the +user has written into the image header or the otime parameter. + +Rapert, sum, area, and flux are the radius of the aperture in pixels, the +total number of counts including sky in the aperture, the area of the aperture +in square pixels, and the total number of counts in the aperture excluding +sky. Mag and merr are the magnitude and error in the magnitude in the aperture. + +.nf + flux = sum - area * msky + mag = zmag - 2.5 * log10 (flux) + 2.5 * log10 (itime) + merr = 1.0857 * err / flux + err = sqrt (flux / epadu + area * stdev**2 + + area**2 * stdev**2 / nsky) +.fi + +Pier and perror are photometry error code and accompanying error message. + +In interactive mode a radial profile of each measured object is plotted +in the graphics window if \fIradplots\fR is "yes". + +In interactive and batchmode a radial profile plot is written to +\fIplotfile\fR if it is defined each time the result of an object +measurement is written to \fIoutput\fR . + + +.ih +ERRORS +If the object centering was error free then the field cier will be zero. +Non-zero values of cier flag the following error conditions. + +.nf +0 # No error +101 # The centering box is off image +102 # The centering box is partially off the image +103 # The S/N ratio is low in the centering box +104 # There are two few points for a good fit +105 # The x or y center fit is singular +106 # The x or y center fit did not converge +107 # The x or y center shift is greater than 1 pixel +108 # There is bad data in the centering box + +.fi + +If all goes well during the sky fitting process then the error code sier +will be 0. Non-zero values of sier flag the following error conditions. + +.nf +0 # No error +201 # There are no sky pixels in the sky annulus +202 # Sky annulus is partially off the image +203 # The histogram of sky pixels has no width +204 # The histogram of sky pixels is flat or concave +205 # There are too few points for a good sky fit +206 # The sky fit is singular +207 # The sky fit did not converge +208 # The graphics stream is undefined +209 # The file of sky values does not exist +210 # The sky file is at EOF +211 # Cannot read the sky value correctly +212 # The best fit parameter are non-physical + +.fi + +If no error occurs during the measurement of the magnitudes then pier is +0. Non-zero values of pier flag the following error conditions. + +.nf +0 # No error +301 # The aperture is off the image +302 # The aperture is partially off the image +303 # The sky value is undefined +305 # There is bad data in the aperture +.fi + +.ih +EXAMPLES + +1. Perform aperture photometry interactively for a few stars in dev$ypix using +the display and the image cursor. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> qphot dev$ypix 5. 10. 5. 2.,4.,6.0 + + ... move image cursor to objects of interest and tap space bar + + ... a 1 line summary will be printed on the standard output + for each object measured + + ... type q to quit and q again to confirm the quit + + ... full output will appear in ypix.mag.1 +.fi + + +2. Perform aperture photometry interactively for a few stars in dev$ypix +using the contour plot and the graphics cursor. This option is only useful +for those (now very few) users who have access to a graphics terminal but +not to an image display server. Setup the task parameters using the +interactive setup menu defined by the i key command as in example 1. + + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... make a contour plot of dev$ypix + + ap> contour dev$pix >G ypix.plot1 + + ... store the contour plot of dev$ypix in the file ypix.plot1 + + ap> qphot dev$ypix 5. 10. 5. 2.,4.,6.0 + + ... type ? to see the help screen + + ... move image cursor to objects of interest and tap space bar + + ... a 1 line summary will be printed on the standard output + for each object measured + + ... type q to quit and q again to confirm the quit + + ... full output will be written to ypix.mag.2 + + ap> set stdimcur = <default> + + ... reset stdimcur to its previous value +.fi + + + +3. Setup and run QPHOT interactively on a list of objects temporarily +overriding the fwhmpsf, sigma, cbox, annulus, dannulus, and apertures + parameters determined in examples 1 or 2. + +.nf + ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify- + + ... make a coordinate list + + ... the output will appear in the text file ypix.coo.1 + + ap> qphot dev$ypix 7.0 12.0 5.0 "3.0,5.0" coords=ypix.coo.1 + + ... type ? for optional help + + + ... move the graphics cursor to the stars and tap space bar + + or + + ... select stars from the input coordinate list with m / :m # + and measure with spbar + + ... measure stars selected from the input coordinate list + with n / n # + + ... a one line summary of results will appear on the standard output + for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.mag.3 ... +.fi + + +4. Display and measure some stars in an image section and write the output +coordinates in the coordinate system of the parent image. + +.nf + ap> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + ap> qphot dev$ypix[150:450,150:450] 7.0 12.0 5.0 "3.0,5.0" wcsout=tv + + ... move cursor to stars and type spbar + + ... type q to quit and q again to confirm quit + + ... output will appear in ypix.mag.4 + + ap> pdump ypix.mag.4 xc,yc yes | tvmark 1 STDIN col=204 +.fi + + +5. Run QPHOT in batch mode using the coordinate file and the previously +saved parameters. + +.nf + ap> qphot dev$ypix 7. 12.0 5.0 "3.0,5.0" coords=ypix.coo.1 inter- + + ... output will appear in ypix.mag.5 ... +.fi + + +6. Repeat example 5 but assume that the input coordinate are ra and dec +in degrees and degrees and submit the task to the background. + +.nf + ap> display dev$ypix + + ap> rimcursor wcs=world > radec.coo + + ... move to selected stars and type any key + + ... type ^Z to quit + + ap> qphot dev$ypix 7.0 12.0 5.0 "3.0,5.0" coords=radec.coo \ + wcsin=world inter- & + + ... output will appear in ypix.ctr.6 + + ap> pdump ypix.mag.6 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars on the display +.fi + + +7. Run QPHOT interactively without using the image display. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = text + + ... set the image cursor to the standard input + + ap> qphot dev$ypix 7.0 12.0 5.0 "3.0,5.0" coords=ypix.coo.1 + + ... type ? for optional help + + ... type :m 3 to set the initial coordinates to those of the + third star in the list + + ... type "442 409 101 i" to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to enter the default menu + ... reset cbox, annulus, dannulus, and apertures using the graphics + cursor and the stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its default + value + ... type q to quit the setup menu + + ... type r to rewind the coordinate list + + ... type l to measure all the stars in the coordinate list + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... full output will appear in the text file ypix.mag.7 + + ap> set stdimcur = <default> + + ... reset the value of stdimcur +.fi + +8. Use a image cursor command file to drive the qphot task. The cursor command +file shown below computes the centers, sky values, and magnitudes for 3 stars +and quits the task. + +.nf + ap> type cmdfile + 442 410 101 \040 + 349 188 101 \040 + 225 131 101 \040 + q + + ap> qphot dev$ypix 7.0 12.0 5.0 "3.0,5.0" icommands=cmdfile + + ... full output will appear in ypix.mag.8 +.fi + + +.ih +BUGS + +It is the responsibility of the user to make sure that the image displayed +in the image display is the same as that specified by the image parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays. It may be necessary to run gflush and to +redisplay the image to get the overlays position correctly. + +.ih +SEE ALSO +phot,wphot,polyphot +.endhelp diff --git a/noao/digiphot/apphot/doc/radprof.hlp b/noao/digiphot/apphot/doc/radprof.hlp new file mode 100644 index 00000000..c6d79251 --- /dev/null +++ b/noao/digiphot/apphot/doc/radprof.hlp @@ -0,0 +1,813 @@ +.help radprof May00 noao.digiphot.apphot +.ih +NAME +radprof -- compute the radial profile of an object +.ih +USAGE +radprof image radius step +.ih +PARAMETERS +.ls image +The name of the image containing the objects to be measured. +.le +.ls radius, step +The size and resolution of the computed radial profile in scale units which is +equal to radius * \fIscale\fR and step * \fIscale\fR in pixels. +.le +.ls coords = "" +The list of text files containing initial coordinates for the objects to +be centered. Objects are listed in coords one object per line with the +initial coordinate values in columns one and two. The number of coordinate +files must be zero, one, or equal to the number of images. If coords is +"default", "dir$default", or a directory specification then a coords file name +of the form dir$root.extension.version is constructed and searched for, +where dir is the directory, root is the root image name, extension is "prf" +and version is the next available version number for the file. +.le +.ls output = "" +The name of the results file or results directory. +If output is "default", "dir$default" or a directory specification then an +output file name of the form dir$root.extension.version is constructed, where +dir is the directory, root is the root image name, extension is "prf" and +version is the next available version of the file. If output is undefined, +then no output file is created. If output is defined, the number of output files +is either 1 or the same as the number of input images. +.le +.ls plotfile = "" +The name of the file containing radial profile plots of the stars written +to the output file. If plotfile is defined then a radial profile plot +is written to plotfile every time a record is written to \fIoutput\fR. +The user should be aware that this can be a time consuming operation. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The critical +parameters \fIfwhmpsf\fR and \fIsigma\fR are located here. If \fIdatapars\fR +is undefined then the default parameter set in uparm directory is used. +.le +.ls centerpars = "" +The name of the file containing the centering parameters. The critical +parameters \fIcalgorithm\fR and \fIcbox\fR are located here. +If \fIcenterpars\fR is undefined then the default parameter set in +uparm directory is used. +.le +.ls fitskypars = "" +The name of the text file containing the sky fitting parameters. The critical +parameters \fIsalgorithm\fR, \fIannulus\fR, and \fIdannulus\fR are located here. +If \fIfitskypars\fR is undefined then the default parameter set in uparm +directory is used. +.le +.ls photpars = "" +The name of the file containing the photometry parameters. The critical +parameter \fIapertures\fR is located here. If \fIphotpars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls order = 5 +The number of pieces in the spline fit. +.le +.ls nreject = 1 +The maximum number of rejection cycles. +.le +.ls kreject = 3.0 +The k-sigma rejection limit for the radial profile fit. +.le +.ls interactive = yes +Run the task interactively ? +.le +.ls radplots = yes +If \fIradplots\fR is "yes" and RADPROF is run in interactive mode, a radial +profile of each star is plotted on the screen after the star is measured. +.le +.ls icommands = "" +The image cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.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 cacheing is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical parameters in non-interactive mode ? Verify may be set to +the apphot package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the critical parameter in non-interactive mode if verify is yes ? +Update may be set to the apphot package parameter value (the default), "yes", +or "no". +.le +.ls verbose = ")_.verbose" +Print messages on the screen in non-interactive mode ? Verbose may be set +to the apphot package parameter value (the default), "yes", or "no". + +.le +.ls graphics = ")_.graphics" +The default graphics device. Graphics may be set to the apphot package +parameter value (the default), "yes", or "no. +.le +.ls display = ")_.display" +The default display device. Display may be set to the apphot package +parameter value (the default), "yes", or "no. By default graphics overlay +is disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" +enables graphics overlay with the IMD graphics kernel. Setting display to +"stdgraph" enables RADPROF to work interactively from a contour plot. +.le + +.ih +DESCRIPTION + +The radial profiles of objects in the image \fIimage\fR are computed +the object center out to the radius \fIradius * scale\fR, in steps of +\fIstep * scale\fR pixels, and plotted. The initial positions are +read from the image cursor or the text file \fIcoords\fR. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\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 input image pixels are cached in memory. If cacheing +is enabled and RADPROF is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because RADPROF +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. + +RADPROF can be run either interactively or in batch mode by setting the +interactive switch to yes. In interactive mode starting x and y coordinates +can either be read directly from the image cursor or read from the text +file specified by \fIcoords\fR. In interactive mode the results are +plotted on the terminal. In batch mode the estimated positions +are read from the text file \fIcoords\fR or the image cursor parameter +\fIicommands\fR is redirected to a text file containing a list of cursor +commands. + +.ih +CURSOR COMMANDS + +The RADPROF cursor commands are listed below. + +.nf + Interactive Keystroke Commands + +? Print help +: Colon commands +v Verify the critical parameters +w Store the current parameters +d Plot radial profile of current star +i Interactively set parameters using current star +c Fit center of current star +t Fit sky around the cursor position +a Average sky values fit around several cursor positions +s Fit sky around the current star +p Fit star using current sky +o Fit star using current sky, output results +f Fit current star +spbar Fit current star, output results +m Move to next star in coordinate list +n Fit next star in coordinate list, output results +l Fit remaining stars in coordinate list, output results +r Rewind the coordinate list +e Print error messages +q Exit task + + + Colon Commands + +:show [data/center/sky/fit] List the parameters +:m [n] Move to next [nth] object in coordinate list +:n [n] Fit next [nth] object in coordinate list, output results + + + Colon Parameter Editing Commands + +# Image and file name parameters + +:image [string] Image name +:coords [string] Coordinate file name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full-width half-maximum of psf (scale units) +:emission [y/n] Emission features (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good pixel value (counts) +:datamax [value] Maximum good pixel value (counts) + +# Noise parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readout noise (electrons) + +# Observing parameters + +:exposure [value] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Integration time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observation (time units) + +# Centering algorithm parameters + +:calgorithm [string] Centering algorithm +:cbox [value] Width of the centering box (scale units) +:cthreshold [value] Centering intensity threshold (sigma) +:cmaxiter [value] Maximum number of iterations +:maxshift [value] Maximum center shift (scale units) +:minsnratio [value] Minimum S/N ratio for centering +:clean [y/n] Clean subraster before centering +:rclean [value] Cleaning radius (scale units) +:rclip [value] Clipping radius (scale units) +:kclean [value] Clean K-sigma rejection limit (sigma) + +# Sky fitting algorithm parameters + +:salgorithm [string] Sky fitting algorithm +:skyvalue [value] User supplied sky value (counts) +:annulus [value] Inner radius of sky annulus (scale units) +:dannulus [value] Width of sky annulus (scale units) +:khist [value] Sky histogram extent (+/- sigma) +:binsize [value] Resolution of sky histogram (sigma) +:sloclip [value] Low-side clipping factor in percent +:shiclip [value] High-side clipping factor in percent +:smaxiter [value] Maximum number of iterations +:smooth [y/n] Lucy smooth the sky histogram +:snreject [value] Maximum number of rejection cycles +:sloreject [value] Low-side pixel rejection limits (sky sigma) +:shireject [value] High-side pixel rejection limits (sky sigma) +:rgrow [value] Region growing radius (scale units) + +# Photometry parameters + +:apertures [string] List of apertures (scale units) +:zmag [value] Zero point of magnitude scale + +# Profile fitting parameters + +:radius [value] Maximum profile radius (scale units) +:step [value] Step size for computed profile (scale units) +:order [value] Number of spline pieces in fit +:kreject [value] K-sigma rejection for fit (fit sigma) +:nreject [value] Maximum number of rejection cycles + +# Marking and plotting parameters + +:mkcenter [y/n] Mark computed centers on display +:mksky [y/n] Mark the sky annuli on the display +:mkapert [y/n] Mark apertures on the display +:radplot [y/n] Plot the radial profile + + + +The following commands are available from inside the interactive setup menu. + + + Interactive Radprof Setup Menu + + v Mark and verify the critical parameters (f,c,s,a,d,r,w,x) + + f Mark and verify the psf full-width half-maximum + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + + c Mark and verify the centering box width + n Mark and verify the cleaning radius + p Mark and verify the clipping radius + + a Mark and verify the inner radius of the sky annulus + d Mark and verify the width of the sky annulus + g Mark and verify the region growing radius + + r Mark and verify the photometry aperture radii + w Mark and verify the radius of the radial profile + x Mark and verify the step size of radial profile +.fi + +.ih +ALGORITHMS + +Prior to computing the radial profile of the star, RADPROF computes the +center, estimates a sky value, and does aperture photometry on the star +using the parameters in the DATAPARS, CENTERPARS, FITSKYPARS, and +PHOTPARS tasks. + +Next the radial and intensity coordinates of all the pixels inside +\fIradius * scale\fR are computed using the calculated center and sky +values and fit to a least squares cubic spline of order \fIorder\fR with +optional bad data rejection. The fit is interpolated at intervals of +\fIstep_size * scale\fR to derive the output profile and estimate the +full width at half maximum of the object. The fit noise model parameters +are defined in DATAPARS. + +.ih +OUTPUT + +In interactive mode the following quantities are printed on the standard +output as each object is measured. Error is a simple string which +indicates whether an error was encountered in the +the centering algorithm, the sky fitting algorithm, the photometry +algorithm or the spline fitting algorithm respectively. +Mag and merr are the magnitudes and errors in +aperture N and xcenter, ycenter and msky are the +x and y centers and the sky value respectively. +Pfwhm is the fitted full width half maximum of the fitted radial profile. + +.nf + image xcenter ycenter msky pfwhm mag[N] merr[N] iers +.fi + +In both interactive and batch mode full output is written to the text file +\fIoutput\fR. At the beginning of each file is a header listing the +current values of the parameters when the first stellar record was written. +These parameters can be subsequently altered. For each star measured the +following record is written + +.nf + image xinit yinit id coords lid + xcenter ycenter xshift yshift xerr yerr cier error + msky stdev sskew nsky nsrej sier serror + itime xairmass ifilter otime + rapert sum area flux mag merr pier perr + pfwhm inorm tinorm rier rerror + pradius intensity tintensity +.fi + +Image and coords are the name of the image and coordinate file respectively. +Id and lid are the sequence numbers of stars in the output and coordinate +files respectively. Cier and cerror are the error code and accompanying +error message respectively. Xinit, yinit, xcenter, ycenter, xshift, yshift, +and xerr, yerr are self explanatory and output in pixel units. The sense of +the xshift and yshift definitions is the following. + +.nf + xshift = xcenter - xinit + yshift = ycenter - yinit +.fi + +Sier and serror are the error code and accompanying error message respectively. +Msky, stdev and sskew are the best estimate of the sky value (per pixel), +standard deviation and skew respectively. Nsky and nsrej are the number of +sky pixels and the number of sky pixels rejected respectively. + +Itime is the exposure time, xairmass is self-evident, filter is an id +string specifying the filter used during the observation and otime is +a string containing the time of observation in whatever units the user +has defined. + +Rapert, sum, area and flux are the radius of the aperture in pixels, the total +number of counts including sky in the aperture, the area of the aperture in +square pixels, and the total number of counts in the aperture excluding sky. +Mag and merr are the magnitude and error in the magnitude in the aperture +(see below). + +.nf + flux = sum - area * msky + mag = zmag - 2.5 * log10 (flux) + 2.5 * log10 (itime) + merr = 1.0857 * error / flux + error = sqrt (flux / epadu + area * stdev**2 + + area**2 * stdev**2 / nsky) +.fi + +Pier and perror are photometry error code and accompanying error message. + +Pfwhm is the full width at half intensity of the fitted profile. Inorm and +tinorm are the normalization factors for the fitted radial profile and the +fitted total intensity profile respectively. Rier and rerror are the spline +fitting error code and accompanying error message. Pradius, intensity +and tintensity are the computed radii, intensity and total intensity +values at each radial step. + + +.ih +ERRORS + +If the object centering was error free then the field cier will be zero. +Non-zero values of cier flag the following error conditions. + +.nf + 0 # No error + 101 # The centering box is off image + 102 # The centering box is partially off the image + 103 # The S/N ratio is low in the centering box + 104 # There are two few points for a good fit + 105 # The x or y center fit is singular + 106 # The x or y center fit did not converge + 107 # The x or y center shift is greater than maxshift + 108 # There is bad data in the centering box +.fi + +If all goes well during the sky fitting process then the error code sier +will be 0. Non-zero values of sier flag the following error conditions. + +.nf + 0 # No error + 201 # There are no sky pixels in the sky annulus + 202 # Sky annulus is partially off the image + 203 # The histogram of sky pixels has no width + 204 # The histogram of sky pixels is flat or concave + 205 # There are too few points for a good sky fit + 206 # The sky fit is singular + 207 # The sky fit did not converge + 208 # The graphics stream is undefined + 209 # The file of sky values does not exist + 210 # The sky file is at EOF + 211 # Cannot read the sky value correctly + 212 # The best fit parameter are non-physical +.fi + +If no error occurs during the measurement of the magnitudes then pier is +0. Non-zero values of pier flag the following error conditions. + +.nf + 0 # No error + 301 # The aperture is off the image + 302 # The aperture is partially off the image + 303 # The sky value is undefined + 305 # There is bad data in the aperture +.fi + +If no error occurs during the profile fitting then rier is 0. +Non-zero values of rier flag the following error conditions. + +.nf + 0 # No error + 901 # The profile region is off the image + 902 # The profile region is partially off the image + 903 # There are too few points in the profile + 904 # The fit is singular + 905 # The sky value is undefined +.fi + +.ih +EXAMPLES + +1. Compute the radial profiles for a few stars in dev$ypix using the +display and the image cursor. Setup the task parameters using the +interactive setup menu defined by the i key command. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> radprof dev$ypix 7.0 0.5 + + ... type ? to print a short help page + + ... move the image cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or + CR to accept the default value + ... set the fwhmpsf, centering radius, inner and outer sky + annuli, apertures, sigma, profile radius and step size + using the graphics cursor and the stellar radial profile + plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... move the image cursor to the star of interest and tap + the space bar + + ... type :order 3 to change the spline order and see if the + fit improves, if it does type w + + ... a radial profile plot will appear on the graphics terminal + + ... type q to quit and q to confirm the quit + + ... by default radprof does not create an output file +.fi + +2. Compute the radial profiles for a few stars in dev$ypix using a contour +plot and the graphics cursor. Setup the task parameters using the interactive +setup menu defined by the i key command. This option is only useful for +those users (now very few) who do not have access to an image display server +but do have access to a graphics terminal. + +.nf + ap> show stdimcur + + ... determine the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... make a contour plot of dev$ypix + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of dev$ypix in ypix.plot1 + + ap> radprof dev$ypix 7.0 0.5 + + ... type ? to print the help page + + ... move graphics cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or + hit CR to accept the default value + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + apertures, sigma, profile radius and step size using the + graphics cursor and the stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... type :.read ypix.plot1 to reload the contour plot + + ... move the graphics cursor to the star of interest and tap + the space bar + + ... a radial profile plot will appear on the graphics terminal + + ... repeat the above sequence for each additional star + + ... type q to quit and q to confirm the quit + + ... by default radprof does not create an output file +.fi + +3. Setup and run RADPROF interactively on a list of objects temporarily +overriding the fwhmpsf, sigma, cbox, annulus, dannulus, apertures, +radius, and step parameters determined in examples 1 or 2. + +.nf + ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify- + + ... make a coordinate list + + ... the output will appear in the text file ypix.coo.1 + + ap> radprof dev$ypix 7.0 0.5 fwhmpsf=2.6 sigma=5.0 cbox=7.0 \ + annulus=10.0 dannulus=5.0 apertures=5.0 coords=ypix.coo.1 + + ... type ? for optional help + + + ... move the graphics cursor to the stars and tap space bar + + or + + ... select stars from the input coordinate list with m / :m # + and measure with spbar + + ... measure stars selected from the input coordinate list + with n / n # + + ... a one line summary of results will appear on the standard output + for each star measured + + ... type q to quit and q again to confirm the quit + + ... by default radprof does not create an output file +.fi + +4. Display and fit some stars in an image section and write the output +coordinates in the coordinate system of the parent image. + +.nf + ap> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + ap> radprof dev$ypix[150:450,150:450] 7.0 0.5 output=default \ + wcsout=tv + + ... move cursor to stars and type spbar + + ... type q to quit and q again to confirm quit + + ... output will appear in ypix.prf.1 + + ap> pdump ypix.prf.1 xc,yc yes | tvmark 1 STDIN col=204 +.fi + + +5. Run RADPROF in batch mode using the coordinate file and the previously +saved parameters. Save the text and plot output. + +.nf + ap> radprof dev$ypix 7. 0.5 coords=ypix.coo.1 output="default" \ + plotfile=ypix.rplots inter- verify- + + ... output will appear in m92.prf.2 and ypix.rplots + + ap> gkidir ypix.rplots + + ... get a listing of the plots in ypix.rplots + + ap> gkiextract ypix.rplots 1-3 | stdplot dev=lw16 + + ... extract plots 1-3 and plot them on device lw16 +.fi + +6. Repeat example 5 but assume that the input coordinates are ra and dec +in degrees and degrees, turn off verification, and submit the task to to +the background. + +.nf + ap> display dev$ypix 1 + + ap> rimcursor wcs=world > radec.coo + + ... move to selected stars and type any key + + ... type ^Z to quit + + ap> radprof dev$ypix 7.0 0.5 coords=radec.coo output=default \ + plotfile=ypix.rplots2 wcsin=world verify- inter- & + + ... output will appear in ypix.prf.3, plots will appear in + ypix.rplots2 + + ap> pdump ypix.prf.3 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars on the display +.fi + + +7. Run RADPROF interactively without using the image display. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = text + + ... set the image cursor to the standard input + + ap> radprof dev$ypix 7.0 0.5 coords=ypix.coo.1 + + ... type ? for optional help + + ... type :m 3 to set the initial coordinates to those of the + third star in the list + + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to enter the default menu + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + apertures, and sigma using the graphics cursor and the + stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its default + value + ... type q to quit the setup menu + + ... type r to rewind the coordinate list + + ... type n to measure the next star + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... by default no output file is written + + ap> set stdimcur = <default> + + ... reset the value of stdimcur +.fi + +8. Use a image cursor command file to drive the RADPROF task. The cursor +command file shown below sets the cbox, annulus, dannulus, and apertures +parameters computes the centers, sky values, magnitudes, and readial profiles +for 3 stars, updates the parameter files, and quits the task. + +.nf + ap> type cmdfile + : cbox 9.0 + : annulus 12.0 + : dannulus 5.0 + : apertures 5.0 + 442 410 101 \040 + 349 188 101 \040 + 225 131 101 \040 + w + q + + ap> radprof dev$ypix 7.0 0.5 icommands=cmdfile \ + plotfile=ypix.rplots3 verify- + + ... by default no output file is written, plots will appear in + ypix.rplots3 +.fi + + +.ih +BUGS + +It is currently the responsibility of the user to make sure that the +image displayed in the frame is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the centerpars mkcenter switch to +"yes", the fitskypars mksky switch to"yes", or the photpars mkapert +witch to "yes". It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + +.ih +SEE ALSO +datapars, centerpars, fitskypars, photpars +.endhelp diff --git a/noao/digiphot/apphot/doc/specs/Ap.doc b/noao/digiphot/apphot/doc/specs/Ap.doc new file mode 100644 index 00000000..66744d58 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/Ap.doc @@ -0,0 +1,1071 @@ + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +1. Introduction + + The APPHOT package will provide a set of routines for performing +aperture photometry on uncrowded or moderately crowded fields, in +either interactive or batch mode. The basic photometry technique +employed shall be fractional-pixel aperture integration; no PSF +fitting techniques shall be employed, and no knowledge of the PSF +shall be required. This document presents the formal requirements and +specifications for the package, and describes the algorithms to be +used. + + + +2. Requirements + + (1) The program shall take as input an IRAF imagefile containing a + starfield which has been corrected for pixel to pixel gain + variations, high frequency fluctuations in the background, + nonlinearity, and any other instrumental defects affecting the + intensity value of a pixel. + + (2) Given as input the approximate coordinates of a single object + in the image, the program shall perform the following + operations: + + o Determine a constant background value by analysis of + an annular region surrounding the object. The + background is assumed to be flat in the region of the + object, but may contain contaminating objects or + defects which shall be detected and eliminated by the + fitting algorithm. It shall be permissible for the + background region to extend beyond the boundaries of + the image; the out of bounds region of the annulus + shall be excluded from the fit. + + o Determine the center of the object, taking the + approximate object coordinates given as input as a + starting point. The center determination shall be + resistant to the affects of nearby contaminating + objects. The centering algorithm may assume that the + object is circularly symmetric, or nearly so, and that + the object flux is positive. + + o Determine the integral of object minus background + within one or more circular apertures centered upon + the object. The integration shall be performed using + partial pixel techniques, to minimize the effects of + sampling. If the aperture contains any indefinite + pixels, or if the aperture extends beyond the boundary + of the image, an indefinite result shall be returned. + + (3) The following options shall be provided to modify the + operation of the above functions: + + + -1- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + + o Use a user supplied constant background value and + background noise estimate instead of fitting the + background. + + o Use the starting center as the actual center in all + cases. + + o Use the starting center as the actual center if the + object is very faint, but tweak up the center if the + signal to noise is above a certain threshold. + + o Allow the object aperture to extend beyond the image + boundary, using only that portion of the aperture + which is in bounds when computing the aperture + integral. + + (4) At a minimum, the following parameters shall be calculated and + output for each object: + + o The coordinates of the object, and the estimated error + in these coordinates. + + o The mode and standard deviation of the background; the + number of pixels left in the background region after + pixel rejection. + + o The magnitude of the object, to within an arbitary + zero-point, and the statistical uncertainty of the + magnitude. If multiple concentric apertures are used, + a magnitude and uncertainty shall be given for each. + + (5) The program shall be usable both interactively and in batch + mode. In interactive use, the user shall be able to mark the + positions of the objects by interactively positioning a cursor + on a 2-dim display device. It shall be possible to enter the + control parameters for the analysis routines interactively for + each object. In batch mode, the control parameters shall be + fixed, and object coordinates shall be taken from a user + supplied list. The display device shall not be required in + batch mode. + + (6) The APPHOT package shall be written in the SPP language in + conformance with the standards and conventions of IRAF. The + code shall be portable and device independent. + + + +2.1 Summary of the Limitations of APPHOT + + The APPHOT package is designed to perform simple aperture +photometry subject to the following restrictions: + + (1) Objects must be circular or nearly circular, since the + + + -2- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + + aperture is circular. + + (2) All pixels within the object aperture are weighted equally. + All pixels in the object aperture must be present; the object + aperture may not normally extend outside the image. Defective + pixels within the object aperture may not be detected. + + (3) The background must be approximately flat in the neighborhood + of the object being measured. The background must have a + unique mode, or the background fitting routine will reject the + object. Any low frequency fluctuations in the background + should be removed before using APPHOT. + + (4) The object aperture must be kept small to minimize the + degradation of signal to noise caused by sky pixels within the + aperture, and to minimize the effects of crowding. Therefore, + the wings of the object will extend beyond the aperture. Good + photometric results will be obtained only if the aperture is + consistently well centered, and if the shape and diameter of + an object is constant throughout the image and invariant with + respect to magnitude. + + + +3. Specifications + + The APPHOT package performs aperture photometry on digitized +starfields maintained as IRAF imagefiles. Input to the package +consists of an imagefile, a list of object coordinates, and numerous +parameters controlling the analysis algorithms. Output consists of +successive lines of text, where each line summarizes the results of +the analysis for a particular object. The output may be saved in a +textfile, which may easily be printed or written onto a card image +tape for export. The package routines may be used either +interactively or in batch mode. + +The CL callable part of the APPHOT package consists of the following +routines: + + apphot -- the main aperture photometry routine. + coordtr -- translations and rotations of coord lists. + fitsky -- computes mode and sigma of a sky region. + fitpsf -- compute the FWHM of the PSF. + imcursor -- reads the image cursor; used to make lists. + immark -- marks objects on the display device. + radprof -- computes the radial profile of an object. + +Routines for general list manipulation, reading and writing card image +tapes, reading and writing images to FITS tapes, removing the +instrumental signature from the data, and so on are available +elsewhere in the IRAF system. The package is easily extended to +include peak finding, matching of object lists from different images, +background fitting and removal, and so on. The APPHOT package shall + + + -3- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +eventually supplant both the KPNO AUTOPHOT and KPNO "Mountain +Photometry Code" packages. + + + +3.1 Standard Analysis Procedures + + Before performing aperture photometry one must determine the radius +of the object aperture to be used, the inner radius and size of the +annulus to be used to fit the background, the full width at half max +(FWHM) of the point spread function (PSF), and so on. Additional +parameters are required by the centering algorithm. A list of object +centers must be prepared if APPHOT is to be used in batch mode. The +standard procedure is as follows: + + (1) Use RADPROF to determine values for the following parameters: + + - the object aperture radius or radii, in pixels + - the inner radius of the annular (sky) region + - the width of the annular region + + (2) Use FITPSF to fit gaussians to isolated, high signal to noise + data objects, to determine the FWHM of the point spread + function. + + (3) Use FITSKY to determine the sky sigma (standard deviation). + APPHOT assumes that sigma is approximately constant throughout + the image. + + (4) If one does not wish to manually mark object positions with + the cursor during analysis, i.e. when the analysis is to be + done in batch, a list of object coordinates must be prepared. + This may be done in many ways: + + o By running RCURSOR with the standard output redirected + into the list file. + + o By transforming an existing list with COORDTR, OPSTRM, + MATCH, SORT, WINDOW, the editor, or some other filter. + + o By an automatic object finding procedure, if one is + available. + + o By any other program which generates a list of object + coordinates, where each line of the list describes one + object, and where x and y in pixel coordinates are + given in columns one and two. Additional columns, if + present, are ignored. + + o APPHOT output may be used as coordinate input in a + subsequent run. + + (5) Finally, APPHOT is run to measure the objects. The user + + + -4- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + + should be familiar with the algorithms used to fit the + background, measure the object center, and compute the + aperture integral, magnitude, and errors. The values of all + visible and hidden APPHOT parameters should be inspected + before doing any serious processing. + +The general purpose IRAF list processing tools may be used for further +analysis of APPHOT output. Output lists may be filtered to select +objects based on the value of a list column, i.e., all the objects +within a certain magnitude range may be selected, objects with +estimated errors larger than a certain value may be deleted, or a list +may be sorted using the value in any column. Columns may be extracted +from a list to form new lists or to provide input to a plot filter, +and lists may be merged. Arithmetic may be performed on lists to +calculate colors, etc. + +The remainder of this section presents detailed specifications for the +analysis procedures in the APPHOT package. + + + +3.2 The APPHOT Program + + The function of the APPHOT procedure is to perform aperture +photometry on isolated objects within an image. The principal input +operands are the name of the imagefile and the rough coordinates of +the objects to be processed. The principal output operands are the +coordinates and magnitudes of the objects. + +In order to perform aperture photometry APPHOT must perform the +following sequence of operations (the algorithms employed are +explained in more detail later in this section): + + (1) The mode and sigma of an annular background region centered on + the object is calculated. + + (2) The center of the object is determined. + + (3) The background is subracted from the object, and the total + flux within the object aperture or apertures is calculated. + +Steps (1) and (2) above are optional; the background and center may be +determined externally, rather than by APPHOT, if desired. + + +3.2.1 APPHOT parameters + + APPHOT has quite a few parameters due to the complexity of the +algorithms employed. All data dependent parameters are query mode to +ensure that they get set properly when a new image is processed. The +data independent algorithm control parameters are hidden mode, and are +given reasonable default values. The names, datatypes, and default +values of the APPHOT parameters are shown below. + + + -5- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +Positional or query mode parameters: + + image filename + apertures string + annulus real + width_annulus real + fwhm_psf real + sky_sigma real + + +List structured parameters (filename may be given on command line): + + sky_mode *real + coords *imcur + + +Hidden parameters: + + spool boolean no + output filename "apphot.out" + fitsky boolean yes + max_sky_iter integer 50 + growing_radius real 1.0 (fwhm_psf units) + k1 real 5.0 + k2 real 2.0 + center boolean yes + clean boolean yes + cleaning_radius real 0.8 (fwhm_psf units) + clipping_radius real 1.5 (fwhm_psf units) + max_cen_shift real 1.0 (fwhm_psf units) + min_snratio real 0.5 + zmag real 26.0 + verbose boolean yes + + +The function and format of each of these parameters is explained in +more detail below. + + + image The name of the image or image section to be + processed. + + output The name of the output textfile used to spool + APPHOT output. If null, output will not be + spooled. Note that output always appears on the + standard output, whether or not spooling is in + effect. + + apertures The radii in pixels of the concentric object + apertures, given all on the same line, delimited + by blanks. At least one aperture must be given; + the maximum number of apertures is limited by the + length of a line. A sample input string might be + + + -6- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + + "5.0 5.5 6.0 6.5 7.0". If only a single aperture + is to be used, a real expression may be used + instead of a string type argument. The apertures + need not be given in any particular order. The + average radius will be used to compute the + uncertainty in the object magnitude. + + annulus The inner radius of the annular sky region, in + pixels. + + width_annulus The width of the annular sky region, in pixels. + + fwhm_psf The FWHM of the psf, in pixels. Used as a scale + factor to control the internal algorithms. + + sky_sigma The standard deviation (noise value) of a typical + region of sky in the image. Used for pixel + rejection in the sky fitting algorithm. + + sky_mode The name of a list file containing the mode of the + background of each of the objects to be + processed. Required only if FITSKY is switched + off. If sky fitting is disabled, and no list file + is given, APPHOT will query for the sky value. + + coords The name of a list file containing the coordinates + of the objects to be processed. If absent, + objects may be marked interactively with the + cursor. + + fitsky A switch used to specify whether or not the + background will be fitted. If background fitting + is disabled, the mode and sigma of the background + will be read from the SKY_FILE list each time an + object is processed. + + max_sky_iter The maximum number of iterations for the sky + fitting algorithm. Since the sky fitting + algorithm is guaranteed to converge, this + parameter should normally have a large value. If + the value is zero, the median of the sky region + will be used instead of the mode. + + growing_radius The region growing radius for pixel rejection in + the sky region, in units of FWHM_PSF. When a bad + sky pixel is detected, all pixels within + (growing_radius * fwhm_psf) pixels of the bad + pixel will be rejected. Used to exclude the wings + of contaminating objects from the sky sample, to + avoid biasing the mode. + + k1 The k-sigma clipping factor for the first phase of + the sky fitting algorithm. + + + -7- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + + k2 The k-sigma clipping factor for the second, + iterative, phase of the sky fitting algorithm. + + center A switch used to specify whether or not centering + is to be performed. If centering is disabled, the + initial center will be used as the object center. + + clean A switch used to specify whether or not the + symmetry-clean algorithm is to be employed during + centering. + + cleaning_radius The cleaning radius for the symmetry-clean + algorithm, in units of FWHM_PSF. + + clipping_radius The clipping radius for the symmetry-clean + algorithm, in units of FWHM_PSF. + + max_cen_shift The maximum permissible shift of center, in units + of FWHM_PSF. If the shift produced by the + centering algorithm is larger than this value, the + fit will terminate and no magnitude will be + calculated. + + min_snratio Centering will be skipped if the signal to noise + of the object, as calculated from the initial + center, is less than the value given by this + parameter. + + zmag Zero point for the output magnitude scale. + + verbose If enabled, the output columns are labeled. Note + that the presence of column labels in the output + may interfere with the use of the list processing + tools. + + + +3.2.2 The APPHOT Background Fitting Algorithm + + A good background fit is essential to aperture photometry. Fitting +the background is trivial in a sparse field, but difficult in a crowded +field. In general the background region will contain contaminating +objects which must be detected and excluded if a good fit is to be +obtained. + +The algorithm employed here is based on the fact that contaminated +pixels are almost always spatially correlated. Background fitting +algorithms which work with a one dimensional sample (mode, median), or +with the one dimensional histogram (mode of hgm) have difficulty +rejecting the faint wings of contaminated regions. This is a serious +defect of one dimensional fitting algorithms, because it is these +faint wings, not the bright central pixels, which are most likely to +bias the calculated background value. + + + -8- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +The algorithm used in APPHOT is as follows: + + + algorithm fit_sky + + begin + # Reject gross deviants. + compute the median of the annular region + detect pixels more than (k1*sky_sigma) from the median + reject all such pixels, without region growing + + # Detect and reject contaminating objects. + while (number of iterations <= max_sky_iter) { + compute the histogram of the reduced sample + compute the sigma and mode of the histogram + detect pixels more than k2*sigma from the mode + reject all such pixels, with region growing + if (no pix rejected or all pix rejected) + terminate loop + } + + return the final mode, sigma, and sample size + end + + +The mode of the histogram is found by cross correlating the noise +function with the histogram. The width of the the noise function is +given by the standard deviation of the current sample. Pixel +rejection is performed by locating all pixels more than k2*sigma from +the mode, and blindly rejecting all pixels within a certain radius of +each deviant pixel. This simple algorithm works well because the +sample is large, and therefore there is little penalty for discarding +pixels that might not be deviant. Region growing also tends to +accelerate convergence significantly. + +Very faint contaminating objects are difficult to detect and reject. +If there are enough such objects, they should not be rejected, because +there are probably a few in the object aperture as well. A higher sky +sigma will be calculated and the computed uncertainty in the magnitude +will increase. The best solution to this problem may be to increase +the size of the annulus to minimize the bias and maximize the liklihood +of a detection. + + + +3.2.3 The APPHOT Centering Algorithm + + The centering algorithm used in APPHOT is that of Auer and Van +Altena, with the addition of the symmetry-clean algorithm developed by +Barry Newell. The main algorithm is as follows: + + + + + + -9- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + + algorithm get_center + + begin + if (centering is disabled) { + return initial center, zero uncertainty estimate + + } else if (signal to noise of object < MIN_SNRATIO) { + compute uncertainty using initial center + return initial center, computed uncertainty + + } else { + call measure_center + return image center and estimated uncertainty + } + end + + +The actual center determination is carried out by the following +algorithm: + + + algorithm measure_center + + begin + extract subarray from the main data array + + # Perform symmetry-cleaning. + if (cleaning is enabled) { + for (each pair of pixels diametrically opposed about + the image center beyond the cleaning radius) + if (i2 > i1 + 2*sky_sigma) + replace i2 by i1 + else if (i1 > i2 + 2*sky_sigma) + replace i1 by i2 + + perform 2*sky_sigma noniterative clip of all pixels + beyond the clipping radius, to remove any remaining + radially symmetric structures + } + + # Compute the image center and uncertainty. + compute x and y marginals of the cleaned subarray + fit a gaussian of width FWHM_PSF to each marginal + compute the centering error from the covariance matrix + + return image center and estimated uncertainty + end + + +The effect of the symmetry-clean algorithm is to edit the raster, +removing any contaminating objects in the vicinity of the primary +object. This simplifies the fitting algorithm and increases its +reliability, since it does not have to deal with multipeak marginal + + + -10- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +distributions. + +A gaussian is fitted to the marginal distributions because it is +expected to yield a better center determination for undersampled +data. An alternative is to empirically derive the marginal +distributions of the psf and fit these to each data object. This is a +better approach in some cases, but in the case of undersampled data it +is difficult to derive the marginal distributions due to sampling +effects, and fitting is difficult due to interpolation error. The use +of a gaussian eliminates interpolation error. Eventually, both +techniques should be made available. + + + +3.2.4 The APPHOT Aperture Integration Algorithm + + The integral of the flux within a circular aperture is computed by +fractional pixel techniques. Pixels are assumed to be square apertures +arranged in a rectangular grid. The fraction of a pixel which lies +within the circular APPHOT aperture is computed by an approximation, +and all such contributions are summed to produce the total integral. + +The simplicity of aperture photometry limits the amount of information +available for error analysis. Using only the noise value for the +background, the estimated error in the aperture integral is given by + + flux_error = sky_sigma * sqrt (aperture_area) + +where "sky_sigma" is either the sigma calculated by the background +fitting algorithm or the parameter SKY_SIGMA, depending on whether sky +fitting is enabled, and where "aperture_area" is the fractional pixel +area of the aperture. + +It is possible, however, to produce a more useful error estimate if we +include some information about the psf. For the purposes of an +improved error estimate, we assume that the PSF is a gaussian. Given +the object center, the background, and the FWHM of the PSF, it is +trivial to fit a two dimensional gaussian to the object. An estimate +of the average noise value for the pixels within the aperture may then +be obtained by computing the standard deviation of the residual formed +by subtracting the fitted two-dimensional gaussian from the data. +This value is used in place of SKY_SIGMA in the above equation for an +improved estimate of the actual flux error. + +In the limit as the gaussian goes to zero, both uncertainty estimates +tend to the same value, as they should. For bright objects, the +uncertainty produced by analysis of the residual will tend to be +pessimistic, since it is unlikely that the PSF can actually be modeled +by a simple gaussian. Nonetheless, a plot of uncertainty versus +magnitude should reveal objects which are blended, which contain bad +pixels, and so on. The accuracy of the gaussian model will determine +how reliably deviant objects can be discriminated. + + + + -11- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +3.2.5 APPHOT Output + + For each object processed, APPHOT prints a single line of text on +the standard output. If desired, APPHOT will simultaneously spool +output into a user specified text file. Each output line will contain +the following information (excluding the commas): + + + x,y,cenerr,shift, mode,sigma,nskypix, mag1,...,magn,magerr + +where + + x,y object coordinates in pixels + cenerr estimated uncertainty in the object center + shift shift of center from initial coordinates + mode mode of the background + sigma sigma of the background + nskypix number of sky pixels left after rejection + mag1 magnitude within the first annulus + magn magnitude within the Nth annulus + magerr estimated mag. uncertainty at the average radius + + +Note that the estimated uncertainty in the magnitude is given only for +the average object aperture radius. The uncertainty for the other +apertures can easily be calculated given SIGMA and the area of each +aperture. The zero point for the magnitude scale is given by the +hidden parameter ZMAG. + +Additional information could be calculated and output (such as the +moments of the object and the skew of the background), but in our +experience few people ever look at such information, and a more complex +output format would be required. Probably the calculation of anything +but object centers, magnitudes, and errors should be left to other +programs. + + + +3.3 The COORDTR Program + + The function of COORDTR is to effect a linear translation and/or +rotation of a coordinate list. COORDTR is a filter; coordinate lines +are read from the standard input and written to the standard output. +COORDTR is concerned only with coordinate transformations, and knows +nothing about image boundaries. A transformed coordinate may no longer +lie within an image. + + x y other_stuff + +The format of a coordinate line is shown above. COORDTR operates only +on the coordinate pair x,y. Any additional information on the line is +passed on to the output without modification. + + + + -12- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +COORDTR is actually a general purpose list processing operator, and +belongs in a list processing package, rather than in the APPHOT +package. When a list processing package is developed, COORDTR will be +moved to that package. + +A COORDTR transformation consists of a linear translation followed by +a rotation. Either the translation, the rotation, or both may be +skipped. The COORDTR parameters are summarized below. + + +positional arguments: + + xshift real + yshift real + xcenter real + ycenter real + theta real + + +hidden parameters: + + translate boolean yes + rotate boolean no + + +If more than two positional arguments are given, COORDTR knows that +both a translation and a rotation are desired. Otherwise the boolean +parameters TRANSLATE and ROTATE are read to determine what additional +parameters are needed. Thus a simple linear translation of +2.5 +pixels in X and -0.2 pixels in Y would be specified by the command + + coordtr (2.5, -.2, < "input", > "output") + +which transforms the list in file "input", writing the output into the +new file "output". + +If a rotation is desired, XCENTER, YCENTER, and THETA must be given. +The first two parameters specify the pixel coordinates of the point +about which the rotation is to be performed, while THETA specifies the +rotation angle in degrees. Positive THETA produces a counterclockwise +rotation, if positive X is to the right and positive Y is up. + + + +3.4 The FITSKY Program + + The function of the FITSKY program is to determine the mode and +sigma of the specified annular regions, printing the results (mode, +sigma, and npix) on the standard output. FITSKY is similar in +operation to APPHOT, except that its function is to fit sky, not +perform aperture photometry. The FITSKY parameters are the following: + + + + + -13- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +Positional or query mode parameters: + + image filename + annulus real + width_annulus real + fwhm_psf real + + +List structured parameters (filename may be given on command line): + + coords *imcur + + +Hidden parameters: + + spool boolean no + output filename "fitsky.out" + max_sky_iter integer 50 + growing_radius real 1.0 (fwhm_psf units) + k1 real 5.0 + k2 real 2.0 + verbose boolean yes + + +The names and functions of the FITSKY parameters are the same as those +for APPHOT. Note that ANNULUS may be set to zero to measure the +background within a circular aperture. The maximum number of +iterations may be set to zero to measure the median of the sky sample. +FITSKY output may be spooled into a file and used as input to APPHOT. + + + +3.5 The FITPSF Program + + The function of the FITPSF program is to determine the FWHM of the +point spread function. This is done by selecting an isolated, high +signal to noise object, computing the x and y marginal profiles, and +fitting a gaussian to each profile. Output consists of the object +center, the error in the center, and the FWHM of the fitted gaussians. +Note that the sigma of a gaussian may be obtained by dividing the FWHM +by 2.354. + + x y err x_fwhm y_fwhm + +The input parameters for the FITPSF program are shown below. + + + + + + + + + + + -14- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +Positional parameters: + + image filename + aperture real + annulus real + width_annulus real + sky_mode real + coords *imcur + + +Hidden parameters: + + fitsky boolean yes + center boolean yes + spool boolean no + output filename "fitpsf.out" + verbose boolean yes + + +If background fitting is disabled, the parameter SKY_MODE defines the +sky level. The background fitting algorithm is a simple median +calculation without pixel rejection or iteration. This should be +sufficient, since FITPSF is expected to be used mainly in uncrowded +regions on high signal to noise objects. + +Note that FITPSF is set up to process a list of input objects. The +list processing tools (i.e., AVERAGE) may be used to average the +results to produce the final FWHM of the PSF for the image. + + + +3.6 The IMCURSOR Program + + The function of the IMCURSOR program is to read the STDIMAGE +cursor, writing the cursor coordinates on the standard output. The +cursor is read until the EOF character is entered to terminate the +loop. The standard output may be redirected into a file to generate a +coordinate list. IMCURSOR has no parameters. + + + +3.7 The IMMARK Program + + The function of IMMARK is to draw marks on the diplay device. +IMMARK is useful for verifying coordinate lists. + + +parameters: + + mark_type string + mark_size real + coords *imcur + + + + -15- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + +Output is the current frame of the STDIMAGE device. Mark types +include "circle", "box", "cross", "plus", and "diamond". The size of +a mark is given in pixels. The third parameter is a standard +coordinate list. If no list is given, the image cursor will be read +instead. + + + +3.8 The RADPROF Program + + The function of the RADPROF program is to compute the radial +profile of an object. The output of RADPROF consists of a sequence of +lines of text, each line defining the profile at a single radius. +Since RADPROF may generate many lines of output for a single input +object, it is set up to process only a single input object. A CL +while loop may be written to process multiple objects, if desired. + + +positional arguments: + + image filename + aperture real + step_size real + annulus real + width_annulus real + sky_mode real + + +hidden parameters: + + fitsky boolean yes + center boolean yes + verbose boolean yes + + +The radial profile is calculated from the image center out to the +radius specified by the parameter APERTURE, in steps of STEP_SIZE +pixels. The remaining RADPROF parameters are similar to those of +APPHOT and will not be discussed in detail. If background fitting is +disabled, the parameter SKY_MODE defines the sky level. The +background fitting algorithm is a simple median calculation without +pixel rejection or iteration. This should be sufficient, since +RADPROF is expected to be used mainly in uncrowded regions on high +signal to noise objects. Centering is via gaussian fits to the +marginal profiles, without cleaning. + +RADPROF output lines contain the following fields: + + r, i(r), inorm(r), fraction(r) + +where + + r radius in pixels + + + -16- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + + i(r) raw intensity at r + inorm(r) normalized intensity at r (range 0-1) + fraction(r) fraction of total integral at r + + +RADPROF does not generate any plots. If one wishes to plot the +contents of an output column, the column may be extracted with a list +processing filter and piped to a graphics task. + + + +4.0 Example + + A brief example may help illustrate the use of the package. +Suppose we want to process a few hundred stars on images "blue" and +"red". We start by analyzing the blue image. + + ap> radprof blue,15,0.5,20,10 + +This gives us a radial profile printout for one of the "blue" stars. +We decide that an aperture radius of 2.5 pixels is about right. The +annulus will start at a radius of 10.0 pixels and extend to 20.0 +pixels. The next step is to determine the FWHM of the PSF: + + ap> fitpsf blue,3,10,20 | tee spoolfile + +By default, the program will take coordinate input by reading the image +display cursor. When the program is waiting for cursor input, it will +cause the display cursor to blink rapidly; normally the cursor does not +blink. One has to be aware of this, because no other prompt is issued. +We postion the cursor on several stars, and tap the space bar to +measure each one. When finished we type the EOF character (<ctrl/z> +on our systems) to terminate the loop. The screen will now look like +this (the output column labels are ommitted): + + ap> fitpsf blue,3,10,20 | tee spoolfile + 283.12 157.40 0.035 2.887 2.751 + 546.08 213.45 0.023 2.833 2.902 + 318.32 354.73 0.064 2.791 2.824 + +Since we elected to use TEE to spool the output, rather than the SPOOL +parameter of FITPSF, we will not see the results until all stars have +been measured. The next step is to average the results, to determine +the final FWHM (the FITPSF output could have been piped directly to +GETCOLS without using an intermediate spoolfile, if desired). + + ap> getcols spoolfile,"4-5" | getcols | average + 2.83133 0.0569725 6 + +There are many ways this average could have been computed, of course; +this is only one example. Next, to avoid having to write down the +FWHM value, we put it into the appropriate APPHOT parameter (note that +the parameter name is abbreviated). + + + -17- + APPHOT (Aug83) Digital Aperture Photometry Package APPHOT (Aug83) + + + + ap> apphot.fwhm = 2.831 + +Finally, we must determine a representative backround sigma value for +the image. This is done by using FITSKY to measure several sky areas, +and averaging column two of the output, much as we did for FITPSF. The +final value may be saved in "apphot.sky_sigma". + +By this point we have determined all the necessary parameters, and it +is time to do some photometry. The only APPHOT argument we are sure +of is the image name parameter, so that is all we include on the +command line: + + ap> apphot blue + aperture radii, pixels: 2.4 2.5 2.75 3.0 + inner radius of sky annulus: 10 + width of sky annulus (1 - ): 10 + full width at half max of psf (2.831): + standard deviation of the image noise function (23.733): + +After responding to the prompts shown above, APPHOT will ask for the +first pair of object coordinates, and the cursor blink prompt will +again be given. Several objects may be measured to verify that all is +working. + +The last step is to prepare a list of objects to be processed. The +simplest way to do this is to interactively mark the objects with the +cursor. Later, when we process the "red" image, the same coordinate +list may again be used, possibly after filtering with COORDTR. + + ap> imcursor > objlist + +At this point, all of the APPHOT parameters have been set, we have a +list of objects to be processed, and we are ready to run APPHOT in +batch mode. We decide to save the output in the file "blue.out". To +ensure that we have a record of the parameters used for the fit, we +first print the APPHOT parameters into the output file, then we start +up the APPHOT batch run. + + ap> lparam apphot > blue.out + ap> apphot >> blue.out & + [1] + +The batch job is now running, appending output lines to the file +"blue.out". We can proceed to set up the job for the red image, in +much the same way that we set up the job for the blue image. When +both jobs finish, we can use the list processing tools to filter out +the good objects and calculate colors. diff --git a/noao/digiphot/apphot/doc/specs/Ap.spc b/noao/digiphot/apphot/doc/specs/Ap.spc new file mode 100644 index 00000000..911d04f1 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/Ap.spc @@ -0,0 +1,1032 @@ +.help apphot Aug83 "Digital Aperture Photometry Package" +.sh +1. Introduction + + The APPHOT package will provide a set of routines for performing +aperture photometry on uncrowded or moderately crowded fields, in either +interactive or batch mode. The basic photometry technique employed +shall be fractional-pixel aperture integration; no PSF fitting techniques +shall be employed, and no knowledge of the PSF shall be required. +This document presents the formal requirements and specifications for +the package, and describes the algorithms to be used. + +.sh +2. Requirements +.ls 4 +.ls (1) +The program shall take as input an IRAF imagefile containing a starfield +which has been corrected for pixel to pixel gain variations, high frequency +fluctuations in the background, nonlinearity, and any other instrumental +defects affecting the intensity value of a pixel. +.le +.ls (2) +Given as input the approximate coordinates of a single object in the image, +the program shall perform the following operations: +.ls 4 +.ls o +Determine a constant background value by analysis of an annular region +surrounding the object. The background is assumed to be flat in the region +of the object, but may contain contaminating objects or defects which +shall be detected and eliminated by the fitting algorithm. +It shall be permissible for the background region to extend beyond the +boundaries of the image; the out of bounds region of the annulus shall +be excluded from the fit. +.le +.ls o +Determine the center of the object, taking the approximate object +coordinates given as input as a starting point. +The center determination shall be resistant to the affects of nearby +contaminating objects. The centering algorithm may assume that the object +is circularly symmetric, or nearly so, and that the object flux is positive. +.le +.ls o +Determine the integral of object minus background within one or more +circular apertures centered upon the object. The integration shall be +performed using partial pixel techniques, to minimize the effects of +sampling. If the aperture contains any indefinite pixels, or if the +aperture extends beyond the boundary of the image, an indefinite result +shall be returned. +.le +.le +.le +.ls (3) +The following options shall be provided to modify the operation of the +above functions: +.ls +.ls o +Use a user supplied constant background value and background noise estimate +instead of fitting the background. +.le +.ls o +Use the starting center as the actual center in all cases. +.le +.ls o +Use the starting center as the actual center if the object is very faint, +but tweak up the center if the signal to noise is above a certain threshold. +.le +.ls o +Allow the object aperture to extend beyond the image boundary, +using only that portion of the aperture which is in bounds when computing +the aperture integral. +.le +.le +.le +.ls (4) +At a minimum, the following parameters shall be calculated and output +for each object: +.ls +.ls o +The coordinates of the object, and the estimated error in these coordinates. +.le +.ls o +The mode and standard deviation of the background; the number of pixels +left in the background region after pixel rejection. +.le +.ls o +The magnitude of the object, to within an arbitary zero-point, and +the statistical uncertainty of the magnitude. If multiple concentric +apertures are used, a magnitude and uncertainty shall be given for each. +.le +.le +.le +.ls (5) +The program shall be usable both interactively and in batch mode. +In interactive use, the user shall be able to mark the positions of the +objects by interactively positioning a cursor on a 2-dim display device. +It shall be possible to enter the control parameters for the analysis +routines interactively for each object. In batch mode, the control +parameters shall be fixed, and object coordinates shall be taken from +a user supplied list. The display device shall not be required in +batch mode. +.le +.ls (6) +The APPHOT package shall be written in the SPP language in conformance +with the standards and conventions of IRAF. The code shall be portable +and device independent. +.le +.le + +.sh +2.1 Summary of the Limitations of APPHOT + + The APPHOT package is designed to perform simple aperture photometry +subject to the following restrictions: +.ls +.ls (1) +Objects must be circular or nearly circular, since the aperture is +circular. +.le +.ls (2) +All pixels within the object aperture are weighted equally. All pixels +in the object aperture must be present; the object aperture may not normally +extend outside the image. Defective pixels within the object +aperture may not be detected. +.le +.ls (3) +The background must be approximately flat in the neighborhood of the +object being measured. The background must have a unique mode, +or the background fitting routine will reject the object. Any low +frequency fluctuations in the background should be removed before +using APPHOT. +.le +.ls (4) +The object aperture must be kept small to minimize the degradation of +signal to noise caused by sky pixels within the aperture, and to +minimize the effects of crowding. Therefore, the wings of the object +will extend beyond the aperture. Good photometric results will be +obtained only if the aperture is consistently well centered, and if the +shape and diameter of an object is constant throughout the image and +invariant with respect to magnitude. +.le +.le + +.sh +3. Specifications + + The APPHOT package performs aperture photometry on digitized starfields +maintained as IRAF imagefiles. Input to the package consists of an imagefile, +a list of object coordinates, and numerous parameters controlling the analysis +algorithms. Output consists of successive lines of text, where each line +summarizes the results of the analysis for a particular object. The output +may be saved in a textfile, which may easily be printed or written onto a +card image tape for export. The package routines may be used either +interactively or in batch mode. + +The CL callable part of the APPHOT package consists of the following +routines: + +.ks +.nf + apphot -- the main aperture photometry routine. + coordtr -- translations and rotations of coord lists. + fitsky -- computes mode and sigma of a sky region. + fitpsf -- compute the FWHM of the PSF. + imcursor -- reads the image cursor; used to make lists. + immark -- marks objects on the display device. + radprof -- computes the radial profile of an object. +.fi +.ke + +Routines for general list manipulation, reading and writing card image tapes, +reading and writing images to FITS tapes, removing the instrumental signature +from the data, and so on are available elsewhere in the IRAF system. +The package is easily extended to include peak finding, +matching of object lists from different images, +background fitting and removal, and so on. The APPHOT package shall eventually +supplant both the KPNO AUTOPHOT and KPNO "Mountain Photometry Code" packages. + +.sh +3.1 Standard Analysis Procedures + + Before performing aperture photometry one must determine the radius +of the object aperture to be used, the inner radius and size of the annulus +to be used to fit the background, the full width at half max (FWHM) of +the point spread function (PSF), and so on. +Additional parameters are required by the centering algorithm. +A list of object centers must be prepared if APPHOT is to be used in +batch mode. The standard procedure is as follows: +.ls +.ls (1) +Use RADPROF to determine values for the following parameters: + +.nf + - the object aperture radius or radii, in pixels + - the inner radius of the annular (sky) region + - the width of the annular region +.fi +.le +.ls (2) +Use FITPSF to fit gaussians to isolated, high signal to noise data objects, +to determine the FWHM of the point spread function. +.le +.ls (3) +Use FITSKY to determine the sky sigma (standard deviation). +APPHOT assumes that sigma is approximately constant throughout the image. +.le +.ls (4) +If one does not wish to manually mark object positions with the cursor +during analysis, i.e. when the analysis is to be done in batch, a list +of object coordinates must be prepared. This may be done in many ways: +.ls +.ls o +By running RCURSOR with the standard output redirected into the list file. +.le +.ls o +By transforming an existing list with COORDTR, OPSTRM, MATCH, SORT, WINDOW, +the editor, or some other filter. +.le +.ls o +By an automatic object finding procedure, if one is available. +.le +.ls o +By any other program which generates a list of object coordinates, +where each line of the list describes one object, and where x and y +in pixel coordinates are given in columns one and two. Additional +columns, if present, are ignored. +.le +.ls o +APPHOT output may be used as coordinate input in a subsequent run. +.le +.le +.le +.ls (5) +Finally, APPHOT is run to measure the objects. The user should be familiar +with the algorithms used to fit the background, measure the object center, +and compute the aperture integral, magnitude, and errors. The values of +all visible and hidden APPHOT parameters should be inspected before doing +any serious processing. +.le +.le + +The general purpose IRAF list processing tools may be used for further +analysis of APPHOT output. +Output lists may be filtered to select objects based on the value of a +list column, i.e., all the objects within a certain magnitude range may +be selected, objects with estimated errors larger than a certain value +may be deleted, or a list may be sorted using the value in any column. +Columns may be extracted from a list to form new lists or to provide input +to a plot filter, and lists may be merged. +Arithmetic may be performed on lists to calculate colors, etc. + +The remainder of this section presents detailed specifications for the analysis +procedures in the APPHOT package. + +.sh +3.2 The APPHOT Program + + The function of the APPHOT procedure is to perform aperture photometry +on isolated objects within an image. The principal input operands are the +name of the imagefile and the rough coordinates of the objects to be processed. +The principal output operands are the coordinates and magnitudes of the +objects. + +In order to perform aperture photometry APPHOT must perform the following +sequence of operations (the algorithms employed are explained in +more detail later in this section): +.ls +.ls (1) +The mode and sigma of an annular background region centered on the object +is calculated. +.le +.ls (2) +The center of the object is determined. +.le +.ls (3) +The background is subracted from the object, and the total flux within +the object aperture or apertures is calculated. +.le +.le + +Steps (1) and (2) above are optional; the background and center may be +determined externally, rather than by APPHOT, if desired. +.sh +3.2.1 APPHOT parameters + + APPHOT has quite a few parameters due to the complexity of the +algorithms employed. All data dependent parameters are query mode to +ensure that they get set properly when a new image is processed. +The data independent algorithm control parameters are hidden mode, +and are given reasonable default values. The names, datatypes, and +default values of the APPHOT parameters are shown below. + + +.ks +.nf +Positional or query mode parameters: + + image filename + apertures string + annulus real + width_annulus real + fwhm_psf real + sky_sigma real +.fi +.ke + + +.ks +.nf +List structured parameters (filename may be given on command line): + + sky_mode *real + coords *imcur +.fi +.ke + + +.ks +.nf +Hidden parameters: + + spool boolean no + output filename "apphot.out" + fitsky boolean yes + max_sky_iter integer 50 + growing_radius real 1.0 (fwhm_psf units) + k1 real 5.0 + k2 real 2.0 + center boolean yes + clean boolean yes + cleaning_radius real 0.8 (fwhm_psf units) + clipping_radius real 1.5 (fwhm_psf units) + max_cen_shift real 1.0 (fwhm_psf units) + min_snratio real 0.5 + zmag real 26.0 + verbose boolean yes +.fi +.ke + + +The function and format of each of these parameters is explained in more +detail below. + +.ls +.ls 16 image +The name of the image or image section to be processed. +.le +.ls output +The name of the output textfile used to spool APPHOT output. +If null, output will not be spooled. Note that output always appears on +the standard output, whether or not spooling is in effect. +.le +.ls apertures +The radii in pixels of the concentric object apertures, given all on the +same line, delimited by blanks. At least one aperture must be given; +the maximum number of apertures is limited by the length of a line. +A sample input string might be "5.0 5.5 6.0 6.5 7.0". If only a single +aperture is to be used, a real expression may be used instead of a string +type argument. The apertures need not be given in any particular order. +The average radius will be used to compute the uncertainty in the +object magnitude. +.le +.ls annulus +The inner radius of the annular sky region, in pixels. +.le +.ls width_annulus +The width of the annular sky region, in pixels. +.le +.ls fwhm_psf +The FWHM of the psf, in pixels. Used as a scale factor to control the +internal algorithms. +.le +.ls sky_sigma +The standard deviation (noise value) of a typical region of sky in +the image. Used for pixel rejection in the sky fitting algorithm. +.le +.ls sky_mode +The name of a list file containing the mode of the background of each of +the objects to be processed. Required only if FITSKY is switched off. +If sky fitting is disabled, and no list file is given, APPHOT will query +for the sky value. +.le +.ls coords +The name of a list file containing the coordinates of the objects to +be processed. If absent, objects may be marked interactively with the +cursor. +.le +.ls fitsky +A switch used to specify whether or not the background will be fitted. +If background fitting is disabled, the mode and sigma of the background +will be read from the SKY_FILE list each time an object is processed. +.le +.ls max_sky_iter +The maximum number of iterations for the sky fitting algorithm. +Since the sky fitting algorithm is guaranteed to converge, +this parameter should normally have a large value. If the value +is zero, the median of the sky region will be used instead of the mode. +.le +.ls growing_radius +The region growing radius for pixel rejection in the sky region, in units +of FWHM_PSF. When a bad sky pixel is detected, all pixels within +(growing_radius * fwhm_psf) pixels of the bad pixel will be rejected. +Used to exclude the wings of contaminating objects from the sky sample, +to avoid biasing the mode. +.le +.ls k1 +The k-sigma clipping factor for the first phase of the sky fitting algorithm. +.le +.ls k2 +The k-sigma clipping factor for the second, iterative, phase of the +sky fitting algorithm. +.le +.ls center +A switch used to specify whether or not centering is to be performed. +If centering is disabled, the initial center will be used as the object center. +.le +.ls clean +A switch used to specify whether or not the symmetry-clean algorithm +is to be employed during centering. +.le +.ls cleaning_radius +The cleaning radius for the symmetry-clean algorithm, in units of +FWHM_PSF. +.le +.ls clipping_radius +The clipping radius for the symmetry-clean algorithm, in units of +FWHM_PSF. +.le +.ls max_cen_shift +The maximum permissible shift of center, in units of FWHM_PSF. +If the shift produced by the centering algorithm is larger than this value, +the fit will terminate and no magnitude will be calculated. +.le +.ls min_snratio +Centering will be skipped if the signal to noise of the object, +as calculated from the initial center, is less than the value given +by this parameter. +.le +.ls zmag +Zero point for the output magnitude scale. +.le +.ls verbose +If enabled, the output columns are labeled. Note that the presence +of column labels in the output may interfere with the use of the list +processing tools. +.le +.le + +.sh +3.2.2 The APPHOT Background Fitting Algorithm + + A good background fit is essential to aperture photometry. Fitting +the background is trivial in a sparse field, but difficult in a crowded +field. In general the background region will contain contaminating objects +which must be detected and excluded if a good fit is to be obtained. + +The algorithm employed here is based on the fact that contaminated pixels +are almost always spatially correlated. Background fitting algorithms +which work with a one dimensional sample (mode, median), or with the one +dimensional histogram (mode of hgm) have difficulty rejecting the faint +wings of contaminated regions. This is a serious defect of one dimensional +fitting algorithms, because it is these faint wings, not the bright +central pixels, which are most likely to bias the calculated background value. + +The algorithm used in APPHOT is as follows: + + +.ks +.nf + algorithm fit_sky + + begin + # Reject gross deviants. + compute the median of the annular region + detect pixels more than (k1*sky_sigma) from the median + reject all such pixels, without region growing + + # Detect and reject contaminating objects. + while (number of iterations <= max_sky_iter) { + compute the histogram of the reduced sample + compute the sigma and mode of the histogram + detect pixels more than k2*sigma from the mode + reject all such pixels, with region growing + if (no pix rejected or all pix rejected) + terminate loop + } + + return the final mode, sigma, and sample size + end +.fi +.ke + + +The mode of the histogram is found by cross correlating the noise function +with the histogram. The width of the the noise function is given by the +standard deviation of the current sample. Pixel rejection is +performed by locating all pixels more than k2*sigma from the mode, +and blindly rejecting all pixels within a certain radius of each deviant +pixel. This simple algorithm works well because the sample is large, +and therefore there is little penalty for discarding pixels that might +not be deviant. Region growing also tends to accelerate convergence +significantly. + +Very faint contaminating objects are difficult to detect and reject. +If there are enough such objects, they should not be rejected, because +there are probably a few in the object aperture as well. A higher sky +sigma will be calculated and the computed uncertainty in the magnitude +will increase. The best solution to this problem may be to increase +the size of the annulus to minimize the bias and maximize the liklihood +of a detection. + +.sh +3.2.3 The APPHOT Centering Algorithm + + The centering algorithm used in APPHOT is that of Auer and Van Altena, +with the addition of the symmetry-clean algorithm developed by Barry Newell. +The main algorithm is as follows: + + +.ks +.nf + algorithm get_center + + begin + if (centering is disabled) { + return initial center, zero uncertainty estimate + + } else if (signal to noise of object < MIN_SNRATIO) { + compute uncertainty using initial center + return initial center, computed uncertainty + + } else { + call measure_center + return image center and estimated uncertainty + } + end +.fi +.ke + + +The actual center determination is carried out by the following +algorithm: + + +.ks +.nf + algorithm measure_center + + begin + extract subarray from the main data array + + # Perform symmetry-cleaning. + if (cleaning is enabled) { + for (each pair of pixels diametrically opposed about + the image center beyond the cleaning radius) + if (i2 > i1 + 2*sky_sigma) + replace i2 by i1 + else if (i1 > i2 + 2*sky_sigma) + replace i1 by i2 + + perform 2*sky_sigma noniterative clip of all pixels + beyond the clipping radius, to remove any remaining + radially symmetric structures + } + + # Compute the image center and uncertainty. + compute x and y marginals of the cleaned subarray + fit a gaussian of width FWHM_PSF to each marginal + compute the centering error from the covariance matrix + + return image center and estimated uncertainty + end +.fi +.ke + + +The effect of the symmetry-clean algorithm is to edit the raster, +removing any contaminating objects in the vicinity of the primary object. +This simplifies the fitting algorithm and increases its reliability, +since it does not have to deal with multipeak marginal distributions. + +A gaussian is fitted to the marginal distributions because it is expected +to yield a better center determination for undersampled data. +An alternative is to empirically derive the marginal distributions of +the psf and fit these to each data object. This is a better approach in +some cases, but in the case of undersampled data it is difficult to derive +the marginal distributions due to sampling effects, and fitting is difficult +due to interpolation error. The use of a gaussian eliminates interpolation +error. Eventually, both techniques should be made available. + +.sh +3.2.4 The APPHOT Aperture Integration Algorithm + + The integral of the flux within a circular aperture is computed by +fractional pixel techniques. Pixels are assumed to be square apertures +arranged in a rectangular grid. The fraction of a pixel which lies within +the circular APPHOT aperture is computed by an approximation, and all +such contributions are summed to produce the total integral. + +The simplicity of aperture photometry limits the amount of information +available for error analysis. Using only the noise value for the background, +the estimated error in the aperture integral is given by + + flux_error = sky_sigma * sqrt (aperture_area) + +where "sky_sigma" is either the sigma calculated by the background fitting +algorithm or the parameter SKY_SIGMA, depending on whether sky fitting +is enabled, and where "aperture_area" is the fractional pixel area of the +aperture. + +It is possible, however, to produce a more useful error estimate if we +include some information about the psf. For the purposes of an improved +error estimate, we assume that the PSF is a gaussian. Given the object center, +the background, and the FWHM of the PSF, it is trivial to fit a two dimensional +gaussian to the object. An estimate of the average noise value for the +pixels within the aperture may then be obtained by computing the standard +deviation of the residual formed by subtracting the fitted two-dimensional +gaussian from the data. This value is used in place of SKY_SIGMA in the +above equation for an improved estimate of the actual flux error. + +In the limit as the gaussian goes to zero, both uncertainty estimates tend +to the same value, as they should. For bright objects, the uncertainty +produced by analysis of the residual will tend to be pessimistic, since +it is unlikely that the PSF can actually be modeled by a simple gaussian. +Nonetheless, a plot of uncertainty versus magnitude should reveal objects +which are blended, which contain bad pixels, and so on. The accuracy of +the gaussian model will determine how reliably deviant objects can be +discriminated. + +.sh +3.2.5 APPHOT Output + + For each object processed, APPHOT prints a single line of text on the +standard output. If desired, APPHOT will simultaneously spool output into +a user specified text file. Each output line will contain the following +information (excluding the commas): + + +.nf + x,y,cenerr,shift, mode,sigma,nskypix, mag1,...,magn,magerr + +where + + x,y object coordinates in pixels + cenerr estimated uncertainty in the object center + shift shift of center from initial coordinates + mode mode of the background + sigma sigma of the background + nskypix number of sky pixels left after rejection + mag1 magnitude within the first annulus + magn magnitude within the Nth annulus + magerr estimated mag. uncertainty at the average radius +.fi + + +Note that the estimated uncertainty in the magnitude is given only for +the average object aperture radius. The uncertainty for the other +apertures can easily be calculated given SIGMA and the area of each +aperture. The zero point for the magnitude scale is given by the +hidden parameter ZMAG. + +Additional information could be calculated and output (such as the +moments of the object and the skew of the background), but in our +experience few people ever look at such information, and a more complex +output format would be required. Probably the calculation of anything +but object centers, magnitudes, and errors should be left to other +programs. + +.sh +3.3 The COORDTR Program + + The function of COORDTR is to effect a linear translation and/or +rotation of a coordinate list. COORDTR is a filter; coordinate lines +are read from the standard input and written to the standard output. +COORDTR is concerned only with coordinate transformations, and knows +nothing about image boundaries. A transformed coordinate may no longer +lie within an image. + + x y other_stuff + +The format of a coordinate line is shown above. COORDTR operates only +on the coordinate pair x,y. Any additional information on the line is +passed on to the output without modification. + +COORDTR is actually a general purpose list processing operator, and +belongs in a list processing package, rather than in the APPHOT package. +When a list processing package is developed, COORDTR will be moved to +that package. + +A COORDTR transformation consists of a linear translation followed +by a rotation. Either the translation, the rotation, or both may be +skipped. The COORDTR parameters are summarized below. + + +.ks +.nf +positional arguments: + + xshift real + yshift real + xcenter real + ycenter real + theta real +.fi +.ke + + +.ks +.nf +hidden parameters: + + translate boolean yes + rotate boolean no +.fi +.ke + + +If more than two positional arguments are given, COORDTR knows +that both a translation and a rotation are desired. Otherwise the +boolean parameters TRANSLATE and ROTATE are read to determine +what additional parameters are needed. Thus a simple linear translation +of +2.5 pixels in X and -0.2 pixels in Y would be specified by the +command + + coordtr (2.5, -.2, < "input", > "output") + +which transforms the list in file "input", writing the output into the +new file "output". + +If a rotation is desired, XCENTER, YCENTER, and THETA must be given. +The first two parameters specify the pixel coordinates of the point +about which the rotation is to be performed, while THETA specifies +the rotation angle in degrees. Positive THETA produces a counterclockwise +rotation, if positive X is to the right and positive Y is up. + +.sh +3.4 The FITSKY Program + + The function of the FITSKY program is to determine the mode and sigma +of the specified annular regions, printing the results (mode, sigma, and npix) +on the standard output. FITSKY is similar in operation to APPHOT, except +that its function is to fit sky, not perform aperture photometry. The +FITSKY parameters are the following: + + +.ks +.nf +Positional or query mode parameters: + + image filename + annulus real + width_annulus real + fwhm_psf real +.fi +.ke + + +.ks +.nf +List structured parameters (filename may be given on command line): + + coords *imcur +.fi +.ke + + +.ks +.nf +Hidden parameters: + + spool boolean no + output filename "fitsky.out" + max_sky_iter integer 50 + growing_radius real 1.0 (fwhm_psf units) + k1 real 5.0 + k2 real 2.0 + verbose boolean yes +.fi +.ke + + +The names and functions of the FITSKY parameters are the same as those +for APPHOT. Note that ANNULUS may be set to zero to measure the +background within a circular aperture. The maximum number of iterations +may be set to zero to measure the median of the sky sample. +FITSKY output may be spooled into a file and used as input to APPHOT. + +.sh +3.5 The FITPSF Program + + The function of the FITPSF program is to determine the FWHM of the +point spread function. This is done by selecting an isolated, high +signal to noise object, computing the x and y marginal profiles, +and fitting a gaussian to each profile. Output consists of the object +center, the error in the center, and the FWHM of the fitted gaussians. +Note that the sigma of a gaussian may be obtained by dividing the FWHM +by 2.354. + + x y err x_fwhm y_fwhm + +The input parameters for the FITPSF program are shown below. + + +.ks +.nf +Positional parameters: + + image filename + aperture real + annulus real + width_annulus real + sky_mode real + coords *imcur +.fi +.ke + + +.ks +.nf +Hidden parameters: + + fitsky boolean yes + center boolean yes + spool boolean no + output filename "fitpsf.out" + verbose boolean yes +.fi +.ke + + +If background fitting is disabled, the parameter SKY_MODE defines +the sky level. The background fitting algorithm is a simple median +calculation without pixel rejection or iteration. +This should be sufficient, since FITPSF is expected to be used mainly +in uncrowded regions on high signal to noise objects. + +Note that FITPSF is set up to process a list of input objects. +The list processing tools (i.e., AVERAGE) may be used to average the +results to produce the final FWHM of the PSF for the image. + +.sh +3.6 The IMCURSOR Program + + The function of the IMCURSOR program is to read the STDIMAGE cursor, +writing the cursor coordinates on the standard output. The cursor is read +until the EOF character is entered to terminate the loop. The standard +output may be redirected into a file to generate a coordinate list. +IMCURSOR has no parameters. + +.sh +3.7 The IMMARK Program + + The function of IMMARK is to draw marks on the diplay device. +IMMARK is useful for verifying coordinate lists. + + +.ks +.nf +parameters: + + mark_type string + mark_size real + coords *imcur +.fi +.ke + + +Output is the current frame of the STDIMAGE device. Mark types +include "circle", "box", "cross", "plus", and "diamond". The size of +a mark is given in pixels. The third parameter is a standard coordinate +list. If no list is given, the image cursor will be read instead. + +.sh +3.8 The RADPROF Program + + The function of the RADPROF program is to compute the radial profile +of an object. The output of RADPROF consists of a sequence of lines of +text, each line defining the profile at a single radius. Since RADPROF +may generate many lines of output for a single input object, it is set up +to process only a single input object. A CL while loop may be written +to process multiple objects, if desired. + + +.ks +.nf +positional arguments: + + image filename + aperture real + step_size real + annulus real + width_annulus real + sky_mode real +.fi +.ke + + +.ks +.nf +hidden parameters: + + fitsky boolean yes + center boolean yes + verbose boolean yes +.fi +.ke + + +The radial profile is calculated from the image center out to the radius +specified by the parameter APERTURE, in steps of STEP_SIZE pixels. +The remaining RADPROF parameters are similar to those of APPHOT and will not be +discussed in detail. If background fitting is disabled, the parameter +SKY_MODE defines the sky level. The background fitting algorithm is +a simple median calculation without pixel rejection or iteration. +This should be sufficient, since RADPROF is expected to be used mainly +in uncrowded regions on high signal to noise objects. +Centering is via gaussian fits to the marginal profiles, without cleaning. + +RADPROF output lines contain the following fields: + + r, i(r), inorm(r), fraction(r) + +.nf +where + + r radius in pixels + i(r) raw intensity at r + inorm(r) normalized intensity at r (range 0-1) + fraction(r) fraction of total integral at r +.fi + + +RADPROF does not generate any plots. If one wishes to plot the contents +of an output column, the column may be extracted with a list processing +filter and piped to a graphics task. + +.sh +4.0 Example + + A brief example may help illustrate the use of the package. Suppose +we want to process a few hundred stars on images "blue" and "red". We +start by analyzing the blue image. + + ap> radprof blue,15,0.5,20,10 + +This gives us a radial profile printout for one of the "blue" stars. +We decide that an aperture radius of 2.5 pixels is about right. +The annulus will start at a radius of 10.0 pixels and extend to 20.0 pixels. +The next step is to determine the FWHM of the PSF: + + ap> fitpsf blue,3,10,20 | tee spoolfile + +By default, the program will take coordinate input by reading the image +display cursor. When the program is waiting for cursor input, it will +cause the display cursor to blink rapidly; normally the cursor does not +blink. One has to be aware of this, because no other prompt is issued. +We postion the cursor on several stars, and tap the space bar to measure +each one. When finished we type the EOF character (<ctrl/z> on our systems) +to terminate the loop. The screen will now look like this (the output +column labels are ommitted): + +.nf + ap> fitpsf blue,3,10,20 | tee spoolfile + 283.12 157.40 0.035 2.887 2.751 + 546.08 213.45 0.023 2.833 2.902 + 318.32 354.73 0.064 2.791 2.824 +.fi + +Since we elected to use TEE to spool the output, rather than the SPOOL +parameter of FITPSF, we will not see the results until all stars have been +measured. The next step is to average the results, to determine the +final FWHM (the FITPSF output could have been piped directly to GETCOLS +without using an intermediate spoolfile, if desired). + +.nf + ap> getcols spoolfile,"4-5" | getcols | average + 2.83133 0.0569725 6 +.fi + +There are many ways this average could have been computed, of course; +this is only one example. Next, to avoid having to write down the FWHM value, +we put it into the appropriate APPHOT parameter (note that the parameter +name is abbreviated). + + ap> apphot.fwhm = 2.831 + +Finally, we must determine a representative backround sigma value for +the image. This is done by using FITSKY to measure several sky areas, +and averaging column two of the output, much as we did for FITPSF. The +final value may be saved in "apphot.sky_sigma". + +By this point we have determined all the necessary parameters, and it is +time to do some photometry. The only APPHOT argument we are sure of is +the image name parameter, so that is all we include on the command line: + +.nf + ap> apphot blue + aperture radii, pixels: 2.4 2.5 2.75 3.0 + inner radius of sky annulus: 10 + width of sky annulus (1 - ): 10 + full width at half max of psf (2.831): + standard deviation of the image noise function (23.733): +.fi + +After responding to the prompts shown above, APPHOT will ask for the +first pair of object coordinates, and the cursor blink prompt will again +be given. Several objects may be measured to verify that all is working. + +The last step is to prepare a list of objects to be processed. The simplest +way to do this is to interactively mark the objects with the cursor. +Later, when we process the "red" image, the same coordinate list may again +be used, possibly after filtering with COORDTR. + + ap> imcursor > objlist + +At this point, all of the APPHOT parameters have been set, we have +a list of objects to be processed, and we are ready to run APPHOT in +batch mode. We decide to save the output in the file "blue.out". +To ensure that we have a record of the parameters used for the fit, +we first print the APPHOT parameters into the output file, then we +start up the APPHOT batch run. + +.nf + ap> lparam apphot > blue.out + ap> apphot >> blue.out & + [1] +.fi + +The batch job is now running, appending output lines to the file "blue.out". +We can proceed to set up the job for the red image, in much the same way +that we set up the job for the blue image. When both jobs finish, we +can use the list processing tools to filter out the good objects and +calculate colors. diff --git a/noao/digiphot/apphot/doc/specs/apphot.db b/noao/digiphot/apphot/doc/specs/apphot.db new file mode 100644 index 00000000..df5dc2f3 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/apphot.db @@ -0,0 +1,366 @@ +# APPHOT.DDF -- Data definition for apphot package output + +builtin catalog functions +builtin domain statements + +------------------------------------------------------------------------------- + +# domain statements + +domain bool type=short format="%b" +domain posint type=short format="%5d" +domain pixels type=real format="%9.3f" +domain fwhmpsf type=real format="%9.3f" +domain counts type=real format="%15.7g" +domain sigma type=real format="%15.7g" +domain mag type=real format="%7.3f" +domain pars type=real format="%15.7g" +domain electrons type=short format="%5d" +domain ratio type=real format=%15.7g" + +# Apphot database descriptor +record apphot { + iraf char[] "current version of iraf" + host char[] "host machine" + user char[] "user name" + package char[] "package name" + version char[] "package version" +} + +-------------------------------------------------------------------------------- + +# History record (1 per modification of the apphot database) +record history { + task char[] "task name" + date ltime "date dask was run" + firstrec posint "first record written by task" + lastrec posint "last record written by task" +} + +------------------------------------------------------------------------------ + +# Data dependent parameter set (>= 1 per task execution) +record datapars { + fwhmpsf pixels "full width half max of the psf" + emission bool "emission/absorption" + noise model char[] "data noise mode" + threshold counts "intensity threshold" + sigma counts "sigma of sky pixels" + gain char[] "image gain keyword" + epadu ratio "gain electrons/adu" + ccread char[] "image readout noise keyword" + readnoise electrons "readout noise electrons" +} + +# Centering algorithm parameter set (>= 1 per task execution) +record centerpars { + calgorithm char[] "centering algoritm" + cboxwidth fwhmpsf "centering box width" + maxshift fwhmpsf "maximum shift" + cmaxiter posint "maximum number of iterations" + minsnratio ratio "minimum signal to noise ratio" + clean bool "use clean algorithm" + rclean fwhmpsf "cleaning radius" + rclip fwhmpsf "clipping radius" + kclean sigma "sigma clean" +} + +# Sky fitting algorithm parameter set (>= 1 per task execution) +record fitskypars { + salgorithm char[] "sky fitting algorithm" + annulus fwhmpsf "inner sky annulus" + dannulus fwhmpsf[] "width of inner sky annulus" + smaxiter posint "maximum number od iterations" + skreject sigma "ksigma rejection" + snreject posint "maximum number of rejections" + khist sigma "half width of histogram" + binsize sigma "binsize of histogram" + smooth bool "smooth the histogram" + rgrow fwhmpsf "region growing radius" + skyvalue counts "user supplied sky value" +} + +# Photometry parameter set (>= 1 per task execution) +record photpars { + weighting char[] "weighting scheme" + apertures fwhmpsf "list of apertures" + zmagnitude mag "magnitude zero point" + exposure char[] "image exposure time keyword" + itime "" "exposure time" +} + +# Polygonal photometry parameter set (>= 1 per task execution) +record polypars { + zmagnitude mag "magnitude zero point" + exposure char[] "image exposure time keyword" + itime "" "exposure time" +} + +# Radial profile fitting parameters (>= 1 per task execution) +record radprofpars { + radius fwhmpsf "maximum profile radius" + stepsize fwhmpsf "profile step size" + order posint "number of spline pieces in fit" + kreject sigma "k sigma rejection" + nreject posint "max number of rejection cycles" +} + +# Point spread function modeling parameters (>= 1 per task execution) +record psfpars { + function char[] "analytic function" + box fwhmpsf "fitting box size" + kreject sigma "sigma rejection limit" + nreject posint "max number of rejections" +} + +-------------------------------------------------------------------------------- + +# Computed center answers (1 per star) +record center { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + +} + +# Computed fitsky answers (1 per star) +record fitsky { + + datapars posint "record id of datapars record" + fitskypars posint "record id of fitskyprs record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + +} + +# Computed phot answers (1 per star) +record phot { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + photpars posint "record id of photometry record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + + aperts pixels[] "list of apertures" + sums counts[] "list of sums" + areas pixels[] "list of areas" + mags mag[] "list of magnitudes" + magerrs mag[] "list of mag errors + merrcodes posint[] "list of errcodes + merrstrings char[] "list of error messages" + +} + +# Computed wphot answers (1 per star) +record wphot { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + fitskypars posint "record id of fitskypars record" + photpars posint "record id of photpars record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + + aperts pixels[] "list of apertures" + sums counts[] "list of sums" + areas pixels[] "list of areas" + mags mag[] "list of magnitudes" + magerrs mag[] "list of mag errors + merrcode posint[] "list of errcodes + merrstrings char[] "list of error messages" +} + +# Computed polyphot answers (1 per star) +record polyphot { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + fitskypars posint "record id of fitskypars record" + polypars posint "record id of polypars record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + + sum counts[] "aperture sum" + area pixels[] "aperture area" + mag mag[] "magnitude" + magerr mag[] "magnitude error" + merrcode posint[] "error code" + merrstring char[] "error message" + + polygons char[] "name of polygons files" + pid posint "polygon sequence number" + oldxmean pixels "original mean x of polygon" + oldymean pixels "original mean y of polygon" + minradius pixels "min sky radius to exclude polygon" + nver posint "number of vertices" + xvertices pixels[] "list of x vertices coords" + yvertices pixels[] "list of y vertices coords" +} + +# Computed radprof answers (1 per star) +record radprof { + + datapars posint "record id of datapars record" + centerpars posint "record id of centerpars record" + fitskypars posint "record id of fitskypars record" + photpars posint "record id of photpars record" + radprofpars posint "record id of radprofpars record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + xcenter pixels "x center position" + ycenter pixels "y center position" + xshift pixels "x position shift" + yshift pixels "y position shift" + xerror pixels "x position error" + yerror pixels "y position error" + cerrcode posint "centering error code" + cerrstring char[] "centering error message" + + skyvalue counts "sky value" + skysigma counts "standard deviation of sky" + skyskew counts "skew of sky pixels" + nskypix posint "number of sky pixels" + nskyreject posint "number of rejected pixels" + serrcode posint "sky fitting error code" + serrstring char[] "sky fitting error message" + + aperts pixels[] "list of apertures" + sums counts[] "list of sums" + areas pixels[] "list of areas" + mags mag[] "list of magnitudes" + magerrs mag[] "list of mag errors + merrs posint[] "list of error codes + merrstrings char[] "list of error messages" + + pfwhm pixels "fitted profile fwhmpsf" + inorm counts "intensity normalization factor" + tinorm counts "total intensity normalization factor" + errcode posint "error code" + errstring char[] "error message" + rlist pixels[] "radii" + intensities counts[] "fitted intensities" + tintensities counts[] "integral of fitted total intensities" +} + +# Computed fitpsf answers (1 per star) +record fitpsf { + + datapars posint "record id of datapars record" + fitpsfpars posint "record id of fitpsf record" + + image char[] "image name" + xinit pixels "initial x position" + yinit pixels "initial y position + id posint "sequence number in table" + coords char[] "coordinate list filename" + lid posint "sequence number in coord list" + + npars posint "number of parameters" + params pars[] "list of parameters" + parerrs pars[] "list of parameter errors" + +} + +------------------------------------------------------------------------------- diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc b/noao/digiphot/apphot/doc/specs/apphot.spc new file mode 100644 index 00000000..ecfdf364 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/apphot.spc @@ -0,0 +1,1296 @@ +.EQ +delim $$ +.EN + +.RP +.TL +Specifications for the Aperture Photometry Package +.AU +Lindsey Davis +.AI +.K2 "" "" "*" +Revised October 1987 + +.AB +The APPHOT package is a set of tasks for performing aperture photometry +on uncrowded or moderately crowded fields, in either interactive or batch mode. +The photometric technique employed is fractional pixel aperture +integration. Point spread function fitting techniques are not used and no +knowledge of the point spread function is required for the computation of +magnitudes. Separate tasks are provided for creating and modifying object lists, +computing accurate centers for a list of objects, computing sky values for +a list of objects and performing aperture photometry inside circular or +polygonal apertures. +.AE + +.NH +Introduction +.PP +The APPHOT package is a set of tasks for performing +aperture photometry on uncrowded or moderately crowded fields. +The photometric technique employed is fractional pixel integration. Point +spread function techniques are not used and no knowledge of the point spread +function is required for the computation of magnitudes. +.PP +The APPHOT package performs multi-aperture photometry on digitized starfields +maintained as IRAF image files. Input to the package consists of an +image file, a list of object coordinates, numerous parameters controlling +the analysis algorithms and, optionally, the graphics terminal and/or +display. APPHOT output consists of successive lines of text where each line +summarizes the results of the analysis for a particular object. +.PP +Given starting coordinates and an IRAF image, the principal APPHOT +task computes accurate centers, sky values and magnitudes +for a list of objects. Separate +IRAF callable tasks in APPHOT exist to create and modify object +lists, to determine image characteristics such as the full width half maximum +of the point spread function or standard deviation of the sky pixels, +to compute accurate centers for a list of objects, to compute accurate local sky +values for a list of objects, and to compute magnitudes inside a polygonal +aperture. + +.NH +APPHOT Package Requirements +.NH 2 +APPHOT Package Input +.NH 3 +The IRAF Image +.PP +APPHOT assumes that images exist on disk in IRAF format. Facilities for reading +and writing images exist elsewhere in IRAF such as in package DATAIO or +MTLOCAL. +.PP +APPHOT assumes that the image data is linear. +The input image is assumed to have been corrected for those instrumental +defects which affect the intensity of a pixel. These include pixel to +pixel variations in the bias values, pixel to pixel gain variations, +cosmic rays, cosmetic defects, geometric distortion, +and detector non-linearities. +.PP +APPHOT assumes that the local sky background is approximately flat in the +vicinity of the object being measured. This assumption is equivalent to +assuming that the local sky region has a unique mode. Therefore any +variations in the sky background which occur at the same scale as the +sky region should be removed prior to entering APPHOT. +.PP +The point spread function of the image is assumed to be constant for all +regions of the image. This is particularly critical in the case of faint objects +for which small apertures which minimize the effects of crowding and +sky noise in the aperture are used. The wings of the object will +almost certainly extend beyond the aperture and good results will only be +obtained if +objects are consistently well centered and the shape and diameter of an object +is constant throughout the image and invariant to magnitude. + +.NH 3 +The Coordinate Lists +.PP +All APPHOT tasks operate on lists of object coordinates or interactive cursor +input. Lists are maintained as text files, +one object per line with the x and y coordinates in +columns one and two respectively. List files may be created interactively +with either the graphics or image cursor, by a previously executed APPHOT +task, by a previously executed IRAF task or by a user task. +.PP +The x and y coordinates contained in the list file can be either the +starting centers for the objects of interest or the true centers. +In either case the aperture centered around the object position must +not extend beyond the boundary of the image. To obtain reliable results +from the centering algorithm the starting centers should not be more than +1 fwhmpsf pixels from the true centers. + +.NH 3 +Algorithm Parameters +.PP +Many tasks in the APPHOT package have an associated set of algorithm parameters +which control the operation of the analysis routines. For example the +centering and sky fitting algorithms each have an associated group of +parameters. +The APPHOT tasks supply reasonable defaults for these parameters. However +the user may alter them at any time in interactive mode or by editing the +appropriate parameter file before running the task in batch. + +.NH 3 +Terminal Graphics and the Image Display +.PP +Most APPHOT programs may be run in either interactive or batch mode. +In interactive mode, the user can mark the positions of objects by +interactively, positioning the image cursor on the display device. +Simple cursor commands can interactively alter the algorithm parameters. +In batch mode the algorithm parameters are +fixed and object coordinates are taken from the user supplied coordinate list. +The display device is not required in batch mode. +.PP +At present there is no high level IRAF display interface. Therefore the present +version of APPHOT replaces the display device with terminal +graphics. For example it is possible to load a contour plot of an image +or image section, and run the APPHOT tasks, interactively marking +positions on the plot. This is a temporary measure to tide thing over until +the display interface is available. Furthermore this option is only +really suitable for those terminal which have both text and graphics +windows displayed at the same time. +.PP +Certain APPHOT tasks such as FITSKY occasionally require an interactive graphics +capability. For example it is sometimes desirable to plot the histogram +of the sky pixels and mark the peak of the histogram interactively rather +than using the automatic sky fitting routines. +Graphics capablity has been added to APPHOT tasks as deemed useful. + +.NH 2 +APPHOT Package Functions +.NH 3 +Creating Coordinate Lists +.PP +APPHOT task(s) shall exist to create coordinate lists interactively within +APPHOT by loading the IRAF image into the image display +and successively marking the objects to be measured with the image cursor. +It shall be possible to mark the positions of objects on the display, and draw +circles of arbitrary size around the objects of interest. +It shall be possible to verify existing coordinate lists by marking the object +coordinates on the image display. +.PP +At present the full image display cababilities do not exist in IRAF. +Therefore as a temporary measure most tasks will run with a contour +plot and the graphics cursor as a substitute for the image display and +image cursor by setting the image cursor to stdgraph and the display +parameter for each task to stdgraph. +The output coordinates will be written to a text file and may be used as +starting coordinates for the APPHOT routines. +.PP +Those sites which have SUN workstations can use the IMTOOL facilites to +create cursor lists. +.PP +APPHOT tasks shall exist to automatically detect objects by specifying the IRAF +image to be searched, plus a few image characteristics such as a detection +threshold and the full width half maximum of the point spread function. +The output coordinates plus a few object statistics will be written to a +text file. + +.NH 3 +Coordinate List Operations +.PP +General list processing tasks are or will be available in the IRAF lists +package. Examples of useful currently existing tasks are list sorting by for +example magnitude and performing a linear transformations +on coordinate lists. +.PP +It may eventually be necessary to add some specialized list processing tasks +to APPHOT. One example is a list matching facility in which objects in +common to two lists are combined and output to a third list. + +.NH 3 +Determining the Image Characteristics +.PP +APPHOT tasks shall exist to estimate certain image +characteristics such as the full width half maximum of the image point spread +function and the standard deviation of the background. In order to obtain +meaningful error estimates it is also necessary to specify the noise +charactersitics of the detector and a noise model. +In this version of APPHOT two noise +functions will be supported a constant sky background noise, +and constant background noise plus Poisson statistics in the object. +.PP +The reason for this capability is that the majority of the APPHOT +algorithm parameters scale with these two image characteristics. +For example all the pixel scale dependent parameters such as the centering +aperture, object apertures, the two sky annuli and the +maximum shift parameter all scale with the full width half +maximum of the point spread function. Similarly most of the pixel intensity +dependent parameters scale with the standard deviation of the sky pixels. + +.NH 3 +Centering +.PP +An APPHOT task shall exist to determine accurate centers for a list of objects, +using the approximate object coordinates as a starting point. +The centering aperture may extend beyond the boundaries of the image but +a warning message will be generated. +.PP +A choice of centering algorithms with a range of efficiency and accuracy will +be available. The center determination must be resistant to the affects of +nearby contaminating objects. +.PP +The user may opt to use the starting center as the actual center in all cases, +to use the starting center as the actual center if the object is very faint, +or tweak up the center if the signal to noise is above a certain threshold. +.PP +The output of the centering algorithm will the set of computed coordinates +and their errors. + +.NH 3 +Fitting the Sky +.PP +An APPHOT task shall exist to compute a constant background value by analysis +of an annular region surrounding the object. +The background is assumed to be flat in the region +of the object, but may contain contaminating objects or defects which +shall be detected and eliminated by the fitting algorithm. +It shall be permissible for the background region to extend beyond the +boundaries of the image; the out of bounds region of the background shall +be excluded from the fit. +.PP +The user may supply a constant background, with zero-valued noise and skew +value or read appropriate values from a file instead of computing the +background. +.PP +The output of the sky fitting algorithm shall be +the mode, standard deviation and skew of the sky as well as the number +of pixels left in the background region after pixel rejection and the number +rejected. + +.NH 3 +Multi-aperture Photometry +.PP +APPHOT routines shall exist to compute the integral of object minus background +within one or more circular apertures centered upon the object. +The integration shall be +performed using partial pixel techniques, to minimize the effects of +sampling. If the aperture contains any indefinite pixels, or if the +aperture extends beyond the boundary of the image, an indefinite result +shall be returned. Both normal and weighted photometry routines shall +be available. +.PP +It shall be possible to normalize the output magnitudes to a user specified +integration time using values stored in the IRAF image header. +.PP +The output shall consist of magnitudes and errors for each of the specified +apertures. +.NH 3 +Polygonal Aperture Photometry +.PP +Determine the integral of the object within a specified +polygon. Aperture integration shall be by fractional pixel summation +of successive image lines. + +.NH +Specifications +.NH 2 +Apphot CL Callable Tasks +.PP +The CL callable part of the APPHOT package consists of the following +routines:\fL + +.nf +.na + mark -- create/verify coordinate lists interactively + polymark -- create/verify polygon lists interactively + daofind -- automatic image finder from DAOPHOT + lintran -- linearly transform a list of coordinates (LISTS package) + + radprof -- compute the radial profile of an object. + fitpsf -- model the PSF + + center -- compute accurate centers for a list of objects + fitsky -- compute accurate sky values for a list of objects + phot -- perform multi-aperture photometry on a set of objects + polyphot -- compute the flux inside a set of irregular polygons\fR + wphot -- perform weighted multi-aperture photometry +.ad +.fi + +.NH 2 +Standard Analysis Procedures +.PP +A standard reduction procedure would be something as follows. +.IP 1. +Estimate the image and data characteristics in the following manner. +.RS +.IP 1. +Use the interactive setup option (i key) in the PHOT task to specify the +fwhm of the psf, +the centering apperture, the sky annuli, the photometry apertures as +well as estimate the sky sigma. +Examine the results (:show command) and optionally store the +new parameters in the parameter files (w key). +.IP 2. +Use the EPAR task to edit the parameter files directly. For example the +detector gain and readout noise must be known before running PHOT in +order to get reliable error estimates. +.RE +.IP 2. +Prepare a coodinate list in one of the following ways. +.RS +.IP 1. +Running MARK or POLYMARK. +.IP 2. +Run DAOFIND or some other automatic image finder. +.IP 3. +Run another APPHOT task such as CENTER . +.IP 4. +Run any other IRAF or user program which generates the appropriate +format. +.IP 5. +Transform an existing list using the LISTS package facilities +.RE +.IP 3. +Run PHOT or WHOT in non-interactive mode to perform the multi-aperture +photometry. The user should be familiar +with the algorithms used to measure the object center, to fit the background, +and compute the aperture integral, magnitude, and errors. The values of +all visible and hidden PHOT parameters should be inspected before doing +any serious processing. Note that CENTER and FITSKY can be run independently +of PHOT and their output used as input to PHOT. +.EQ +delim $$ +.EN + +.NH 2 +The APPHOT Algorithms +.PP +The principal APPHOT algorithms are described below. + +.NH 3 +The RADPROF Algorithm +.PP +The function of the RADPROF task is to compute the radial profile of +selected, isolated, high signal to noise objects in an IRAF image. +.PP +Given the IRAF image, an initial center, an aperture and a step size, +RADPROF computes the radial profile of an object in the following manner. +.IP 1. +The APPHOT centering routines are used to compute an accurate center for the +object. The new center is used to compute the radial coordinate for each +pixel in the subraster. +.IP 2. +The APPHOT sky fitting routines are used to compute an accurate sky value +for the object. The new sky value is used to compute the object intensity +for each pixel in the subraster. +.IP 3. +The CURFIT package routines are used to produce a smooth intensity versus +radius curve by fitting a cubic least squares spline function to the data +using linear least squares techniques. +.IP 4. +The fitted curve is evaluated at equally spaced intervals to produce the +final radial profile. The profile is normalised using the r = 0 value. +.IP 5. +The smoothed curve is integrated using the +1D integration routines IMINTERP to evalute the fraction of the total +integral at each interval. +.IP 6. +The three quantities $I sub r$ the raw intensity, $Inorm sub r$ the +normalized intensity, and $Ifraction sub r$ the fraction of the total +intensity inside radius at r, are plotted on the terminal and +output as a function of r to a text file. +.PP +RADPROF is used principally to compute the stellar image and setup the +parameters for doing photometry. Its default output is a radial profile +plot with the phot parameters marked on it. + +.NH 3 +The FITPSF Algorithm +.PP +The function of the FITPSF task is to fit an analytic model to an object +in order to derive information about the point spread function. Given +an IRAF image, an initial center and an aperture, FITPSF computes the +model parameters in the following manner. +.IP 1. +The fitting function is chosen. +The present version of FITPSF offers two function choices a 2D radial Gaussian +function and an elliptical Gaussian function. +A third option, moment analysis, has been added to the FITPSF package. +The image characteristics are evaluted by using the 0th, 1st and 2nd order +moments of the image. +.IP 2 +Initial guesses for the parameters are made from the subraster data. +.IP 3 +The parameters and their errors are derived using standard non-linear least +squares techniques and the NLFIT package. + +.NH 3 +The DAOFIND Algorithm +.PP +The function of the DAOFIND task is to automatically detect objects +in an IRAF image above a certain intensity threshold. +The user specifies an intensiyt threshold, +the estimated full width half maximum of +the point spread function, +and limits on the sharpness and roundness of the objects to be detected. +DAOFIND produces a list of x and y coordinates and a sharpness +and roundness statistic for each detected object. +.PP +The DAOFIND algorithm works in the following way. +.IP 1. +The user specifies an intensity threshold above local sky and estimates +the full width half maximum of the point spread function. +.IP 2. +DAOFIND computes a convolution kernel which is a linear +function of the brightness values in an approximately circular array of +pixels. The original data is convolved with the computed kernel. +The equivalent mathematical +operation is a convolution of the original data +with truncated, lowered circular Gaussian function with the specified FWHM, +computed in such a way as to be the mathematical +equivalent of fitting a Gaussian stellar profile to the object data by least +squares. The coefficients of the linear function sum to zero so that the +overall bias level (local sky) cancels out exactly. Since the function is +symmetric about a single pixel, a smooth gradient in the sky brightness +also cancels exactly. Therefore the user does not have to specify an +absolute brightness threshold but only a threshold above local sky. +.IP 3 +The convolved data is searched for local maxima. Local maxima which are +less than the specified threshold are rejected. A pixel is defined to be +a local maximum when it is the brightest pixel within +$n ~*~ sigma sub Gauss$. +.IP 4. +Using the original data, DAOFIND computes an object sharpness statistic which +can be used to reject +hot or cold pixels. The sharp parameter is defined below. +Detected objects with a sharpness parameter outside the range specifed +by sharplo and sharphi are rejected. Typical values for sharplo and +sharphi are 0.2 and 1.0 respectively. +.nf + + $I sub delta$ = height of best fitting $delta$ function = pixel value + + $I sub Gauss$ = height of best fitting Gaussian function = convolved value + + sharplo <= sharp = ${I sub delta} over {I sub Gauss}$ <= sharphi + +.fi +If the brightness enhancement detected in the convolved data is due to +a single bright pixel, then the best fitting delta function will have an +amplitude equal to the height of this pixel above the local background, +while the amplitude of the best fitting Gaussian will be pulled down by +the surrounding low valued pixels. Sharp will be a number significantly +greater than one. A single cold pixel will produce +brightness enhancements approximately 0.5 * FWHM away +from the pixel in question in all directions. In this case the height +of the delta +function which best fits these spurious maxima is close to zero, while the +height of the best fitting Gaussian is some small positive number. +In this case sharp will be close to zero. +.IP 5. +The roundess statistic is computed from the original picture data by fitting +1D Gaussians +to the marginal sums in x and y. If the height of either 1D +Gaussian is negative the object is rejected. If both heights are +positive the roundness parameter is computed. +.nf + + $DELTA I ~=~ I sub {x ~ Gauss} ~-~ I sub {y ~ Gauss}$ + + $<I> ~=~ I sub {x ~ Gauss} ~+~ I sub {y ~ Gauss}$ + + $roundlo ~<=~ round ~=~ {DELTA I} over <I> ~<=~ roundhi$ + +.fi +Objects which are elongated in the +x direction have roundness values less than zero and those elongated in +the y direction have roundness greater than zero. +Round discriminates only against objects which are elongated +along either rows or columns. Objects elongated at a 45 degree angle will +not be rejected. +.IP 6. +Finally the approximate x and y centroids of the detected objects, +rough magnitudes relative to threshold are computed, and object is added +to the output file. + + +.NH 3 +The CENTER Task + +.NH 4 +Centering Package Routines +.PP +The following are the principal programmer callable routines routines in the +centering package. +.nf +\fL + + apcinit (ap, cfunction, cbox, fwhmpsf, noise) + ier = apfitcenter (ap, im, xinit, yinit) + ier = aprefitcenter (ap) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apcfree (ap) + +\fR +.fi +.PP +The following quantities can be examined or set by apstat/apset calls +.nf +\fL + data 1. fwhmpsf full width half maximum of psf in pixels +parameters 2. threshold minimum intensity for centering + 3. noise noise model + 4. sigma standard deviation of background + 5. readnoise readout noise of CCD in electrons + 6. epadu electrons per adu + +centering 1. calgorithm centering algorithm +parameters 2. positive emission / absorption features + 3. cbox centering radius in fwhmpsf + 4. cmaxiter maximum number of fitting iterations + 5. maxshift maximum permitted shift in fwhmpsf + 6. minsnratio minimum permitted signal to noise ratio + 7. clean clean subraster before centering + 8. rclean cleaning radius in fwhmpsf + 9. rclip clipping radius in fwhmpsf + 10.kclean k-sigma rejection for cleaning in sigma +\fR +.fi + +.PP +The following computed quantities can be examined by apstat calls. +.nf +\fL + 1. xcenter computed x coordinate + 2. ycenter computed y coordinate + 3. xerr computed x coordinate error + 4. yerr computed y coordinate error +\fR +.fi +.PP +See the manual pages for CENTER and CENTERPARS for a detailed description +of the centering parameters. + +.NH 4 +The Centering Algorithm +.PP +The function of the CENTER task is to compute accurate centers and errors +for objects in an IRAF image given a list of initial positions and a +centering aperture. +.IP 1. +If the centering algorithm is disabled, the computed center is set to the +initial center and the uncertainty estimate is set to zero. +.IP 2. +If the cleaning algorithm is enabled, clean the subraster before centering. +.IP 3. +Estimate is made of the signal to noise of the object. If this quantity is +less than a certain minimum value the computed center is kept +but a warning message is issued. +.IP 4. +The center and errors are computed using one of several algorithms. +.IP 5. +If the computed center is greater than a user specified distance from the +initial center then the computed center is returned with an error +message. + +.NH 4 +Symmetry Clean Algorithm +.PP +The symmetry-clean algorithm attempts to remove defects in the centering +subraster by assuming that the object has radial symmetry and comparing +pixels on the opposite sides of the center of symmetry. The algorithm +works in the following way. +.IP 1. +The center of symmetry is computed. Normally the center of symmetry is assumed +to coincide with the position of the brightest pixel in the subarray. +However if the maximum pixel is more than a user specified distance away +from the intial center, the initial center is used as the center of symmetry. +.IP 2. +Pixels inside a specified cleaning radius are unaltered. +.IP 3. +Pairs of pixels diametrically opposed about the center +in the cleaning region between the cleaning and clipping +radii are tested for equality. If the difference between the pixels is +greater than a specified k-sigma rejection limit, the larger value is replaced +by the smaller. +In this region sigma is computed from Poisson statistics. +.IP 4. +Pairs of pixels in the clippping +region are compared in the same manner as those in the cleaning region +except that sigma is the standard deviation of the sky pixels. +.PP +The effect of the symmetry-clean algorithm is to edit the raster, +removing any contaminating objects in the vicinity of the primary object. +This simplifies the fitting algorithm and increases its reliability, +since it does not have to deal with multipeak marginal distributions. + +.NH 4 +Signal to Noise Estimate + +.PP +The signal to noise of the object is estimated from the data values +in the subraster in the following way. +.nf + + $SNR ~=~ N sub object over {sqrt {n sub pix ~*~sigma sub sky sup 2}}$ + + or + + $SNR ~=~ N sub object over {sqrt {N sub object ~+~ n sub pix~*~sigma sub sky sup 2}}$ + +.fi +where $N sub *$ is the number of counts in the object above threshold, +$sigma sub sky$ +is the standard deviation of the pixels in the sky region and +$n sub pix$ is the number of pixels in the object aperture. +The first approximation corresponds to constant sky noise only, +the second includes Poisson noise in the object. + +.NH 4 +Centroid +.PP +The centroid centering algorithm is similar to that used in MPC and can +be briefly described as follows. For more detailed description +see (Stellar Magnitudes From Digital Pictures, 1980, Adams et al). +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +The intensity weighted centroid positions for the marginals is computed +using only data pixels which are above the threshold intensity. If the +threshold parameter is 0 the mean intensity of the marginal is used +in place of the threshold +.nf + + $I sub i ~=~ I sub i ~-~ threshold ~~~~~ I sub i ~>~ 0.0$ + + $x sub c ~=~ {sum I sub i ~ x sub i} over {sum I sub i}$ + +.fi +.IP 3. +The errors are estimated in the following way +.nf + + $sigma sup 2 ~=~ {sum I sub i ~ x sub i sup 2} over {sum I sub i} ~-~ x sub c sup 2$ + + $err sub xc ~=~ sqrt {{sigma sup 2} ~/~ sum I sub i}$ + +.fi + +.NH 4 +Gaussian Fit to the Marginals +.PP +The fit is performed in the following way. +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +Initial guesses for the parameters of the 1D Gaussians $I sub Gauss$, +$x sub c$ and $I sub sky$ are derived from the marginal distributions +themselves. The width $sigma$ is held constant. +.IP 3. +The best fit parameters and their errors are derived using non-linear +least-squares techniques and the NLFIT package. + +.NH 4 +Optimal Filtering of Marginals +.PP +The fit is performed is the following way. +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +The centroid of the observed distribution is computed by solving the +following equation. +.nf + + $PSI (x sub c ) ~=~ sum omega sub i (x sub c ) ~ PHI sub i ~=~ 0$ + + $omega sub i ~=~ {{partial phi sub i} ~/~ {partial x sub c}} over {phi sub i~+~b}$ + +.fi +The assumptions are that the observed distribution $PHI sub i$ is correctly +modeled by the profile function $phi sub i$. The usual choise of profile +model for centering is a Gaussian. Howver in the interests of speed a triangle +function has been substituted. This causes at most a 7% increase in the +random centering error. +.IP 3. +The startup procedure is based on the following fact. +.nf + + $PSI (x sub n )~>~0~~for~~ x sub n ~<~ x sub c$ + + $PSI (x sub n ) ~<~0~~for~~ x sub n ~>~ x sub c$ + +.fi +The iteration is initialized by assuming that $x sub 1$ = $x sub c$ and +computing $PSI (x sub 1 )$. The initial x +value is incremented by $+- sigma sub Gauss$ depending on the sign of $PSI$. The +search is repeated until $PSI (x sub {n-1})$ and $PSI (x sub n)$ have +opposite signs. At this point the true center is bracketed by the +estimated positions $(x sub n, ~ x sub {n-1})$ and we have a table of at +least 2 values of $PSI (x sub n )$. +.IP 4. +The computation proceeds by interpolating in the table of values for the +estimated position $x sub {n+1}$ where $PSI$ = 0. If the table contains only +two values as may be the case for the inititial interpolation, linear +interpolation is used. In all other cases a quadratic fit to the three +most recent $PSI$ values is used. The computation is complete when +two successive estimates differ by less than some tolerance typically +0.001 pixel. +.IP 5. +The errors are estimated as follows. +.nf + + $sigma sup 2 ~=~ ( {int {( partial phi ~/~ partial x sub c )} sup 2 over { + phi + b}} ) sup -1$ + + $err sub xc ~=~ sqrt {sigma sup 2}$ + +.fi + +.NH 4 +Other Centering Methods +.PP +The code is constructed in such a way that new algorithms may be +easily added at a future date, such as the more sophisticated techniques +required for accurate astrometry. +.EQ +delim $$ +.EN +.NH 3 +The FITSKY Task + +.NH 4 +Sky Fitting Routines + +.PP +The following are the main entry points in the sky fitting package. +.nf +\fL + apsinit (ap, function, annulus, dannulus, fwhmpsf, noise) + ier = apfitsky (ap, im, xpos, ypos, sd, gd) + ier = aprefitsky (ap, sd, gd) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[irs] (ap, param, value) + apsfree (ap) +\fR +.fi +.PP +The following quantities can be examined or set with apset/apstat calls. +.nf +\fL +data 1. fwhmpsf full width half maximum of the psf +parameters 2. sigma standard deviation of sky pixels + +sky fitting 1. annulus inner radius of sky annulus in fwhmpsf +parameters 2. dannulus outer radius of sky annulus in fwhmpsf + 3. sfunction sky fitting algorithm + 4. smaxiter maximum number of fitting iterations + 5. kreject k-sigma rejection limit sigma + 6. nreject maximum number of rejection cycles + 7. rgrow region growing radius in fwhmpsf + + 8. khist half-wdth of histogram in sigma + 9. binsize binsize of histogram in sigma + 10.smooth Lucy smooth the histogram + + 11.skyfile name of text file containing sky values + 12.skyvaluser supplied constant value for sky +\fR +.fi +.PP +The following computed quantities can only be examined with apstat calls. +.nf +\fL + 1. skymode computed sky value + 2. skysig computed sky sigma + 3. skyskew computed sky skew + 4. nsky number of sky pixels + 5. nsky_reject number of rejected sky pixels +\fR +.fi + +.NH 4 +The Sky Fitting Algorithms +.PP +A good background fit is essential to aperture photometry. Fitting +the background is trivial in a sparse field, but difficult in a crowded +field. In general the background region will contain contaminating objects +which must be detected and excluded if a good fit is to be obtained. +.PP +The main algorithm used in APPHOT is the following. +.IP 1. +If the skyfitting switch is disabled either read the sky values from a text +file or accept a user supplied constant for the sky. +.IP 2. +Perform the initial sky fit using one of the specified algorithms. The +sky fitting algorithms fall into three general categories, those that use +the actual sky pixel array itself, those that operate on a histogram of +sky values and those that rely on user interaction. +.IP 3. +If the pixel rejection flags are set perform pixels rejection with optional +region growing. + +.NH 4 +Sky Pixel Array Techniques + +.NH 5 +Median +.IP 1. +Sort the array of sky pixels. This is necessary to avoid quantization effects. +.IP 2. +Compute the median, and the standard deviation and skew with respect to the +mean. +.IP 3. +If the k-sigma rejection limit is greater than zero and the maximum number +of rejection cycles is greater than one, perform pixel rejection. +Pixels greater than k-sigma from the median are rejected. Region growing +is optional. +.IP 4. +Stop the rejection cycle on any given iteration if the maximum number of +rejection cycles ix exceeded, no more sky pixels are left or no more +pixels are rejected. + +.NH 5 +Mode +.IP 1. +Sort the array of sky pixels. This is necessary to avoid quantization effects. +.IP 2. +Compute the mode, and the standard deviation and skew +with respect to the mean. +.nf + + $I sub mode ~=~ 3.0 ~*~ I sub median ~-~ 2.0 ~*~ I sub mean$ + +.fi +.IP 3. +If the k-sigma rejection limit is greater than zero and the maximum number +of rejection cycles is greater than one, perform pixel rejection. +Pixels greater than k-sigma from the mode are rejected. Region growing +is optional. +.IP 4. +Stop the rejection cycle on any given iteration if the maximum number of +rejection cycles ix exceeded, no more sky pixels are left or no more +pixels are rejected. + + +.NH 4 +Histogram Techniques +.PP +The following three techniques all operate on the histogram of the sky pixels. +The routines all construct the histogram in the following identical manner. +.IP 1. +The mean of the sky distribution is computed. +.IP 2. +If the user specified standard deviation of the sky pixels is INDEF the +algorithm computes the standard deviation of the sky pixels with respect +to the mean. +.IP 3. +All pixels within plus or minus sigma standard +deviations are accumulated into a histogram. The user specifies the bin size. +.IP 4. +The histogram may optionally be Lucy smoothed before any operation is performed +on it. + +.NH 5 +Centroid +.PP +The mode, sigma and skew of the sky pixels are computed in the following +manner. +.IP 1. +The histogram is compiled as above. +.IP 2. +The mode, standard deviation and skew of the sky pixels are computed in the +following manner. + +.nf + $I sub 0 ~=~ sum I sub i$ + $I sub 1 ~=~ sum I sub i ~ x sub i$ + $I sub 2 ~=~ sum I sub i ~ x sub i sup 2$ + $I sub 3 ~=~ sum I sub i ~ x sub i sup 3$ + + $I sub mode ~=~ {I sub 1} ~/~ {I sub 0}$ + $sigma ~=~ {( I sub 2 ~/~ I sub 0 ~-~ I sub mode sup 2 )} sup {1/2}$ + $skew ~=~ ( {I sub 3 ~/~ I sub 0 ~-~ I sub mode ~*~ sigma sup 2 ~-~ I sub mode sup 3} ) sup {1/3}$ + +.fi +.IP 3 +If pixel rejection is enabled sky pixels within a user supplied limit of +the mode are rejected with optional region growing. + +.NH 5 +Gaussian Fit +.PP +The mode, standard deviation and skew of the sky pixels are derived from a +model fit in the following way. +.IP 1. +The histogram of the sky pixels is compiled as above. +.IP 2. +Initial guesses to the model parameters, $N sub max$, $I sub mode$, +$sigma$, and $skew$ are made from the histogram itself. +.IP 3. +Final parameters and their errors are derived using non-linear least squares +techniques and the NLFIT package. +.IP 4. +If pixel rejection is enabled sky pixels within a user supplied limit of +the computed mode are rejected with optional region growing. + +.NH 5 +Optimal Filtering +.PP +The method is as follows. +.IP 1. +The histogram is compiled as above. +.IP 2. +Using the mean of the sky pixels as the intital value of the sky mode, +a new mode is computed using the optimal filtering technique +described for centering. +.IP 4 +If pixel rejection is enabled sky pixels within a user supplied limit of +the computed mode are rejected with optional region growing. + +.NH 5 +Cross Correlation +.PP +The method is as follows. +.IP 1. +The histogram is compiled as above. +.IP 2. +The noise function is estimated using the standard deviation of the sky +pixels and the cross-correlation function is computed. +.IP 3. +The mode is computed using quadratic interpolation around the peak of the +distribution. +.IP 4 +If pixel rejection is enabled sky pixels within a user supplied limit of +the mode are rejected with optional region growing. + +.NH 4 +Interactive Techniques + +.NH 5 +Histogram Plot +.PP +The histogram is compiled as described above and the user marks the peak +on the histogram plot with the graphics cursor. The sigma and skew of the +sky distribution with respect to the mean is also computed. + +.NH 5 +Radial Distribution +.PP +A radial profile plot of the sky region is plotted and the user marks the +sky value on the plot with the graphics cursor. The sigma and skew of the sky +distribution with respect to the mean is computed. + +.NH 4 +Pixel Rejection and Region Growing +.PP +All the sky fitting algorithms permit pixel rejection and +optional region growing. +Pixel rejection and region growing are +performed by locating all pixels more than k * sigma from the mode, +and blindly rejecting all pixels within a certain radius of each deviant +pixel. This simple algorithm works well because the sample is large, +and therefore there is little penalty for discarding pixels that might +not be deviant. Region growing also tends to accelerate convergence +significantly. +.PP +Very faint contaminating objects are difficult to detect and reject. +If there are enough such objects, they should not be rejected, because +there are probably a few in the object aperture as well. A higher sky +sigma will be calculated and the computed uncertainty in the magnitude +will increase. The best solution to this problem may be to increase +the size of the annulus to minimize the bias. + +.NH 4 +The Principal PHOT Routines +.PP +The main entries in the photometry routine are the following. +.nf +\fL + apinit (ap, cfunction, cbox, sfunction, annulus, dannulus, + aperts, napert, fwhmpsf, noise) + ier = apfitcenter (ap, im, xinit, yinit) + ier = aprefitcenter (ap) + ier = apfitsky (ap, im, xcenter, ycenter, sd, gd) + ier = aprefitsky (ap, sd, gd) + ier = apmag (ap, im, xcenter, ycenter, skyval, skysig, nsky) + ier = apwmag (ap, im, xcenter, ycenter, positive, skyval, skysig, nsky) + ier = apremag (ap, positive, skyval, skysig, nsky) + ier = apwremag (ap, positive, skyval, skysig, nsky) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apfree (ap) + +\fR +.fi +.PP +The following parameters can be examined or altered by apset/apstat calls. +.nf +\fL + 1. weighting weighting scheme for wphot + 2. aperts list of apertues + 3. naperts number of apertures + 4. zmag zero point of magnitude scale + 5. itime effective integration time +\fR +.fi +.PP +The following quantities can be examined with apstat calls. +.nf +\fL + + 1. sums array of aperture sums + 2. areas array of areas + 3. mags array of magnitudes + 4. magerrs array of magnitude errors + +\fR +.fi + +.NH 4 +The PHOT Aperture Integration Algorithm +.PP +The integral of the flux within a circular aperture is computed by +fractional pixel techniques. Pixels are assumed to be square apertures +arranged in a rectangular grid. The fraction of a pixel which lies within +the circular APPHOT aperture is computed by an approximation, and all +such contributions are summed to produce the total integral. +.PP +The inclusion of a partial pixel inside the aperture is done as follows. +.IP 1. +If the distance of the current pixel from the center of the star, r, is +exactly equal to the radius of the aperture R then one-half the counts in +the pixel are included. +.IP 2. +If r < R - 0.5 the entire pixel is included while if r > R + 0.5 the pixel +is wholly excluded. +.IP 3. +In between the fraction of the counts varies linearly. A circular aperture +is approximated by an irregular polygon. +.PP +The simplicity of aperture photometry limits the amount of information +available for error analysis. The following three sources of error are +considered. +.IP 1. +The error due to sky noise in the aperture. +.nf + + $error sub 1 ~=~ sigma sub sky ~*~ {A sub apert} sup {1/2}$ + +.fi +.IP 2. +The error in the aperture sum. +.nf + + $error sub 2 ~=~ ( {A sub "sum" ~/~ phpadu} ) sup {1/2}$ + +.fi +.IP 3. +The mean error of the sky. +.nf + + $error sub 3 ~=~ sigma sub sky ~*~ A sub apert ~/~ nsky sup {1/2}$ + + +.fi +where $sigma sub sky$ is either computed by the background fitting +algorithm or set by the user, +and $A sub apert$ is the fractional pixel area of the +aperture. + +.NH 4 +The WPHOT Algorithm +.PP +The WPHOT algorithm computes a weighted aperture sum in an attempt to +minimize noise in the sky. The algorithm is the following where w is +the weight for each pixel, p is the noise free profile value and +$sigma$ is the noise per pixel from all sources. (See the paper +by Stover and Allen 1987 for details) +.nf + + $A sub sum ~=~ sum {w sub i ~*~ (I sub i ~-~ sky)}$ + + $w sub i ~=~ C ~*~ p sub i ~/~ sigma sup 2 sub i$ + + $C ~=~ sum {p sub j} / sum {p sub j ~*~ w sub j}$ +.fi + +.NH 4 +The POLYPHOT ROUTINES +.PP +The principal polyphot routines are the following. + +.nf +\fL + apyinit (ap, sfunction, annulus, dannulus, noise) + ier = apfitcenter (ap, im, wx, wy) + ier = aprefitcenter (ap) + ier = apfitsky (ap, im, xcenter, ycenter, sd, gd) + ier = aprefitsky (ap, sd, gd) + ier = polyfit (ap, im, xver, yver, nver) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apfree (ap) + +\fR +.fi + +.PP +.NH 4 +The POLYPHOT Algorithm +.PP +The function of the POLYPHOT task is to compute the flux inside an +irregular polygon given a list of the coordinates of the vertices of a polygon. +The polygon must be entirely inside the image and the vertices of the polygon +must be specified in clockwise or counterclockwise order. +The actual algorithm used is as follows. +.IP 1. +The range of image lines which intersect the polygon are computed. +.IP 2. +For each image line in the specified range the intersection points with the +polygon are computed. +.IP 3. +The flux between pairs of limits is summed using a fractional pixel +approximation for the endpoints. +.IP 4. +The sky is fitted using any of the methods previously discussed and a +user specified annular region. +.IP 5. +The errors are computed as specified in the PHOT specifications. +.PP +.EQ +delim $$ +.EN + +.NH +Example +.PP +A brief example may help illustrate the use of the package. Suppose +we want to process a few hundred stars on image "blue". +.PP +The first step is to prepare a list of objects to be measured. The simplest +way to do this is to interactively mark the objects with the image +cursor using the display (graphics) device and the RIMCURSOR (RGCURSOR) +task. +.nf +\fL + + ... load image on the display ... + + ap> rimcursor > starlist + + ... move cursor and mark stars ... + + + ... load contour plot on graphics terminal ... + + ap> rgcursor > starlist + + ... move cursor and mark stars ... +\fR +.fi + +Alternatively one can run DAOFIND to compute a list of candidate objects +in the frame. +The name of the coordinate file is stored in the PHOT parameter set. + +.nf +\fL + ap> phot.coords=starlist +\fR +.fi + +.PP +The next step is to set up the PHOT parameters interactively. +First we load the image (contour plot) blue on the display (graphics +terminal). Next we call up PHOT in interactive mode. + +.nf +\fL + ap> phot blue + ... cursor appears ... + +\fR +.fi + +.PP +PHOT takes input by reading the image (graphics) +display (terminal) cursor. In order to display the available commands +we tap the ? key and the following text appears on the screen. + +.nf +\fL + Interactive Phot Commands + +? Print options +: Colon command see below +i Setup PHOT parameters interactively +w Write PHOT parameters to the parameter files +l Process the remainder of the coordinate list +r Rewind the coordinate list +c Fit center around the current cursor position +t Fit sky around the current cursor position +s Fit sky around the current center position +p Compute magnitudes around the cursor position +f Fit center, sky and compute magnitudes +sp Fit center, sky, compute magnitudes, and save +q Exit program + +Phot parameters are listed or set with the following commands. + +:m [n] Move cursor to the [nth] object in the coordinate list +:n [n] Measure the [nth] object in the coordinate list + +:show [center/sky/phot/all] List the aphot parameters +:fwhmpsf [value] Full width half maximum of the PSF +:noise [string] Noise model +:threshold [value] Threshold value for centering +:sigma [value] Standard deviation of the background +:ccdread CCD readout noise keyword +:readnoise Readout noise in electrons +:gain Gain keyword +:epadu Electrons per adu + +:calgorithm [string] Centering function +:positive [y/n] Emission or absorption feature +:cbox [value] Width of the centering box in fwhmpsf +:cmaxiter [value] Maximum number of centering iterations +:maxshift [value] Maximum shift in fwhmpf +:minsnratio [value] Minimum signal to noise ratio of pixels +:clean [y/n] Clean subraster before centering +:rclip [value] Clipping radius in fwhmpsf +:rclean [value] Cleaning radius in fwhmpsf +:kclean [value] Sigma for clean algorithm +:mkcenter [y/n] Mark the centers on the display + +:salgorithm [string] Sky fitting algorithm +:annulus [value] Inner radius of sky annulus in fwhmpsf +:dannulus [value] Width of sky annulus in fwhmpsf +:skyvalue [value] User supplied sky +:smaxiter [value] Maximum number of rejection cycles +:skreject [value] +/- Pixel rejection limits in sky sigma +:snreject [value] Maximum number of rejection interations +:khist [value] +/- Sky histogram size in sky sigma +:binsize [value] Resolution of sky histogram in sky sigma +:smooth [y/n] Lucy smooth the sky histogram +:rgrow [value] Region growing radius in fwhmpsf +:marksky [y/n] Mark the sky annuli on the display + +:weighting Weighting for wphot +:aperts [string] Aperture radii in fwhmpsf +:zmag [value] Zero point of magnitude scale +:exposure [string] Exposure time keyword +:itime [value] Integration time +\fR +.fi + +.PP +We select the interactive setup option, move the image +cursor to a high signal-to-noise, isolated star and tap the i key. +PHOT responds by plotting the radial profile of the star on the +screen and requesting the user to mark the fwhm of +the psf, the centering aperture, the inner and outer sky annuli, +the sky background and sigma and the set of circular apertures. +The parameters so set can be examined and/or reset with the : commands as shown +above. Sample measurements can be made of several stars by moving the +cursor and typing the f command. Finally when we are happy with the +parameter set we type w to store the parameters and q to exit the program. +.PP +Now we are ready to do photometry. We enter the PHOT program in batch mode. + +.nf +\fL + ap> phot blue inter- & +\fR +.fi + +The batch job is now running, appending output lines to the file "blue.mag.#". +We can proceed to set up the job for the red image, in much the same way +that we set up the job for the blue image. When both jobs finish, we +can use the list processing tools to filter out the good objects and +calculate colors. + +.NH +The APPHOT Tasks +.PP +Manual pages for the APHOT tasks are attached. Although the working of the +various tasks may change in detail, the help pages attached here should +provide a good description of the function of each task. +.PP +When the package has stabilized a detailed users guide will be written. diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc.lw b/noao/digiphot/apphot/doc/specs/apphot.spc.lw new file mode 100644 index 00000000..71285557 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/apphot.spc.lw @@ -0,0 +1,1296 @@ +.EQ +delim $$ +.EN + +.RP +.TL +Specifications for the Aperture Photometry Package +.AU +Lindsey Davis +.AI +.K2 "" "" "*" +Revised October 1987 + +.AB +The APPHOT package is a set of tasks for performing aperture photometry +on uncrowded or moderately crowded fields, in either interactive or batch mode. +The photometric technique employed is fractional pixel aperture +integration. Point spread function fitting techniques are not used and no +knowledge of the point spread function is required for the computation of +magnitudes. Separate tasks are provided for creating and modifying object lists, +computing accurate centers for a list of objects, computing sky values for +a list of objects and performing aperture photometry inside circular or +polygonal apertures. +.AE + +.NH +Introduction +.PP +The APPHOT package is a set of tasks for performing +aperture photometry on uncrowded or moderately crowded fields. +The photometric technique employed is fractional pixel integration. Point +spread function techniques are not used and no knowledge of the point spread +function is required for the computation of magnitudes. +.PP +The APPHOT package performs multi-aperture photometry on digitized starfields +maintained as IRAF image files. Input to the package consists of an +image file, a list of object coordinates, numerous parameters controlling +the analysis algorithms and, optionally, the graphics terminal and/or +display. APPHOT output consists of successive lines of text where each line +summarizes the results of the analysis for a particular object. +.PP +Given starting coordinates and an IRAF image, the principal APPHOT +task computes accurate centers, sky values and magnitudes +for a list of objects. Separate +IRAF callable tasks in APPHOT exist to create and modify object +lists, to determine image characteristics such as the full width half maximum +of the point spread function or standard deviation of the sky pixels, +to compute accurate centers for a list of objects, to compute accurate local sky +values for a list of objects, and to compute magnitudes inside a polygonal +aperture. + +.NH +APPHOT Package Requirements +.NH 2 +APPHOT Package Input +.NH 3 +The IRAF Image +.PP +APPHOT assumes that images exist on disk in IRAF format. Facilities for reading +and writing images exist elsewhere in IRAF such as in package DATAIO or +MTLOCAL. +.PP +APPHOT assumes that the image data is linear. +The input image is assumed to have been corrected for those instrumental +defects which affect the intensity of a pixel. These include pixel to +pixel variations in the bias values, pixel to pixel gain variations, +cosmic rays, cosmetic defects, geometric distortion, +and detector non-linearities. +.PP +APPHOT assumes that the local sky background is approximately flat in the +vicinity of the object being measured. This assumption is equivalent to +assuming that the local sky region has a unique mode. Therefore any +variations in the sky background which occur at the same scale as the +sky region should be removed prior to entering APPHOT. +.PP +The point spread function of the image is assumed to be constant for all +regions of the image. This is particularly critical in the case of faint objects +for which small apertures which minimize the effects of crowding and +sky noise in the aperture are used. The wings of the object will +almost certainly extend beyond the aperture and good results will only be +obtained if +objects are consistently well centered and the shape and diameter of an object +is constant throughout the image and invariant to magnitude. + +.NH 3 +The Coordinate Lists +.PP +All APPHOT tasks operate on lists of object coordinates or interactive cursor +input. Lists are maintained as text files, +one object per line with the x and y coordinates in +columns one and two respectively. List files may be created interactively +with either the graphics or image cursor, by a previously executed APPHOT +task, by a previously executed IRAF task or by a user task. +.PP +The x and y coordinates contained in the list file can be either the +starting centers for the objects of interest or the true centers. +In either case the aperture centered around the object position must +not extend beyond the boundary of the image. To obtain reliable results +from the centering algorithm the starting centers should not be more than +1 fwhmpsf pixels from the true centers. + +.NH 3 +Algorithm Parameters +.PP +Many tasks in the APPHOT package have an associated set of algorithm parameters +which control the operation of the analysis routines. For example the +centering and sky fitting algorithms each have an associated group of +parameters. +The APPHOT tasks supply reasonable defaults for these parameters. However +the user may alter them at any time in interactive mode or by editing the +appropriate parameter file before running the task in batch. + +.NH 3 +Terminal Graphics and the Image Display +.PP +Most APPHOT programs may be run in either interactive or batch mode. +In interactive mode, the user can mark the positions of objects by +interactively, positioning the image cursor on the display device. +Simple cursor commands can interactively alter the algorithm parameters. +In batch mode the algorithm parameters are +fixed and object coordinates are taken from the user supplied coordinate list. +The display device is not required in batch mode. +.PP +At present there is no high level IRAF display interface. Therefore the present +version of APPHOT replaces the display device with terminal +graphics. For example it is possible to load a contour plot of an image +or image section, and run the APPHOT tasks, interactively marking +positions on the plot. This is a temporary measure to tide thing over until +the display interface is available. Furthermore this option is only +really suitable for those terminal which have both text and graphics +windows displayed at the same time. +.PP +Certain APPHOT tasks such as FITSKY occasionally require an interactive graphics +capability. For example it is sometimes desirable to plot the histogram +of the sky pixels and mark the peak of the histogram interactively rather +than using the automatic sky fitting routines. +Graphics capablity has been added to APPHOT tasks as deemed useful. + +.NH 2 +APPHOT Package Functions +.NH 3 +Creating Coordinate Lists +.PP +APPHOT task(s) shall exist to create coordinate lists interactively within +APPHOT by loading the IRAF image into the image display +and successively marking the objects to be measured with the image cursor. +It shall be possible to mark the positions of objects on the display, and draw +circles of arbitrary size around the objects of interest. +It shall be possible to verify existing coordinate lists by marking the object +coordinates on the image display. +.PP +At present the full image display cababilities do not exist in IRAF. +Therefore as a temporary measure most tasks will run with a contour +plot and the graphics cursor as a substitute for the image display and +image cursor by setting the image cursor to stdgraph and the display +parameter for each task to stdgraph. +The output coordinates will be written to a text file and may be used as +starting coordinates for the APPHOT routines. +.PP +Those sites which have SUN workstations can use the IMTOOL facilites to +create cursor lists. +.PP +APPHOT tasks shall exist to automatically detect objects by specifying the IRAF +image to be searched, plus a few image characteristics such as a detection +threshold and the full width half maximum of the point spread function. +The output coordinates plus a few object statistics will be written to a +text file. + +.NH 3 +Coordinate List Operations +.PP +General list processing tasks are or will be available in the IRAF lists +package. Examples of useful currently existing tasks are list sorting by for +example magnitude and performing a linear transformations +on coordinate lists. +.PP +It may eventually be necessary to add some specialized list processing tasks +to APPHOT. One example is a list matching facility in which objects in +common to two lists are combined and output to a third list. + +.NH 3 +Determining the Image Characteristics +.PP +APPHOT tasks shall exist to estimate certain image +characteristics such as the full width half maximum of the image point spread +function and the standard deviation of the background. In order to obtain +meaningful error estimates it is also necessary to specify the noise +charactersitics of the detector and a noise model. +In this version of APPHOT two noise +functions will be supported a constant sky background noise, +and constant background noise plus Poisson statistics in the object. +.PP +The reason for this capability is that the majority of the APPHOT +algorithm parameters scale with these two image characteristics. +For example all the pixel scale dependent parameters such as the centering +aperture, object apertures, the two sky annuli and the +maximum shift parameter all scale with the full width half +maximum of the point spread function. Similarly most of the pixel intensity +dependent parameters scale with the standard deviation of the sky pixels. + +.NH 3 +Centering +.PP +An APPHOT task shall exist to determine accurate centers for a list of objects, +using the approximate object coordinates as a starting point. +The centering aperture may extend beyond the boundaries of the image but +a warning message will be generated. +.PP +A choice of centering algorithms with a range of efficiency and accuracy will +be available. The center determination must be resistant to the affects of +nearby contaminating objects. +.PP +The user may opt to use the starting center as the actual center in all cases, +to use the starting center as the actual center if the object is very faint, +or tweak up the center if the signal to noise is above a certain threshold. +.PP +The output of the centering algorithm will the set of computed coordinates +and their errors. + +.NH 3 +Fitting the Sky +.PP +An APPHOT task shall exist to compute a constant background value by analysis +of an annular region surrounding the object. +The background is assumed to be flat in the region +of the object, but may contain contaminating objects or defects which +shall be detected and eliminated by the fitting algorithm. +It shall be permissible for the background region to extend beyond the +boundaries of the image; the out of bounds region of the background shall +be excluded from the fit. +.PP +The user may supply a constant background, with zero-valued noise and skew +value or read appropriate values from a file instead of computing the +background. +.PP +The output of the sky fitting algorithm shall be +the mode, standard deviation and skew of the sky as well as the number +of pixels left in the background region after pixel rejection and the number +rejected. + +.NH 3 +Multi-aperture Photometry +.PP +APPHOT routines shall exist to compute the integral of object minus background +within one or more circular apertures centered upon the object. +The integration shall be +performed using partial pixel techniques, to minimize the effects of +sampling. If the aperture contains any indefinite pixels, or if the +aperture extends beyond the boundary of the image, an indefinite result +shall be returned. Both normal and weighted photometry routines shall +be available. +.PP +It shall be possible to normalize the output magnitudes to a user specified +integration time using values stored in the IRAF image header. +.PP +The output shall consist of magnitudes and errors for each of the specified +apertures. +.NH 3 +Polygonal Aperture Photometry +.PP +Determine the integral of the object within a specified +polygon. Aperture integration shall be by fractional pixel summation +of successive image lines. + +.NH +Specifications +.NH 2 +Apphot CL Callable Tasks +.PP +The CL callable part of the APPHOT package consists of the following +routines:\f(CW + +.nf +.na + mark -- create/verify coordinate lists interactively + polymark -- create/verify polygon lists interactively + daofind -- automatic image finder from DAOPHOT + lintran -- linearly transform a list of coordinates (LISTS package) + + radprof -- compute the radial profile of an object. + fitpsf -- model the PSF + + center -- compute accurate centers for a list of objects + fitsky -- compute accurate sky values for a list of objects + phot -- perform multi-aperture photometry on a set of objects + polyphot -- compute the flux inside a set of irregular polygons + wphot -- perform weighted multi-aperture photometry\fR +.ad +.fi + +.NH 2 +Standard Analysis Procedures +.PP +A standard reduction procedure would be something as follows. +.IP 1. +Estimate the image and data characteristics in the following manner. +.RS +.IP 1. +Use the interactive setup option (i key) in the PHOT task to specify the +fwhm of the psf, +the centering apperture, the sky annuli, the photometry apertures as +well as estimate the sky sigma. +Examine the results (:show command) and optionally store the +new parameters in the parameter files (w key). +.IP 2. +Use the EPAR task to edit the parameter files directly. For example the +detector gain and readout noise must be known before running PHOT in +order to get reliable error estimates. +.RE +.IP 2. +Prepare a coodinate list in one of the following ways. +.RS +.IP 1. +Running MARK or POLYMARK. +.IP 2. +Run DAOFIND or some other automatic image finder. +.IP 3. +Run another APPHOT task such as CENTER . +.IP 4. +Run any other IRAF or user program which generates the appropriate +format. +.IP 5. +Transform an existing list using the LISTS package facilities +.RE +.IP 3. +Run PHOT or WHOT in non-interactive mode to perform the multi-aperture +photometry. The user should be familiar +with the algorithms used to measure the object center, to fit the background, +and compute the aperture integral, magnitude, and errors. The values of +all visible and hidden PHOT parameters should be inspected before doing +any serious processing. Note that CENTER and FITSKY can be run independently +of PHOT and their output used as input to PHOT. +.EQ +delim $$ +.EN + +.NH 2 +The APPHOT Algorithms +.PP +The principal APPHOT algorithms are described below. + +.NH 3 +The RADPROF Algorithm +.PP +The function of the RADPROF task is to compute the radial profile of +selected, isolated, high signal to noise objects in an IRAF image. +.PP +Given the IRAF image, an initial center, an aperture and a step size, +RADPROF computes the radial profile of an object in the following manner. +.IP 1. +The APPHOT centering routines are used to compute an accurate center for the +object. The new center is used to compute the radial coordinate for each +pixel in the subraster. +.IP 2. +The APPHOT sky fitting routines are used to compute an accurate sky value +for the object. The new sky value is used to compute the object intensity +for each pixel in the subraster. +.IP 3. +The CURFIT package routines are used to produce a smooth intensity versus +radius curve by fitting a cubic least squares spline function to the data +using linear least squares techniques. +.IP 4. +The fitted curve is evaluated at equally spaced intervals to produce the +final radial profile. The profile is normalised using the r = 0 value. +.IP 5. +The smoothed curve is integrated using the +1D integration routines IMINTERP to evalute the fraction of the total +integral at each interval. +.IP 6. +The three quantities $I sub r$ the raw intensity, $Inorm sub r$ the +normalized intensity, and $Ifraction sub r$ the fraction of the total +intensity inside radius at r, are plotted on the terminal and +output as a function of r to a text file. +.PP +RADPROF is used principally to compute the stellar image and setup the +parameters for doing photometry. Its default output is a radial profile +plot with the phot parameters marked on it. + +.NH 3 +The FITPSF Algorithm +.PP +The function of the FITPSF task is to fit an analytic model to an object +in order to derive information about the point spread function. Given +an IRAF image, an initial center and an aperture, FITPSF computes the +model parameters in the following manner. +.IP 1. +The fitting function is chosen. +The present version of FITPSF offers two function choices a 2D radial Gaussian +function and an elliptical Gaussian function. +A third option, moment analysis, has been added to the FITPSF package. +The image characteristics are evaluted by using the 0th, 1st and 2nd order +moments of the image. +.IP 2 +Initial guesses for the parameters are made from the subraster data. +.IP 3 +The parameters and their errors are derived using standard non-linear least +squares techniques and the NLFIT package. + +.NH 3 +The DAOFIND Algorithm +.PP +The function of the DAOFIND task is to automatically detect objects +in an IRAF image above a certain intensity threshold. +The user specifies an intensiyt threshold, +the estimated full width half maximum of +the point spread function, +and limits on the sharpness and roundness of the objects to be detected. +DAOFIND produces a list of x and y coordinates and a sharpness +and roundness statistic for each detected object. +.PP +The DAOFIND algorithm works in the following way. +.IP 1. +The user specifies an intensity threshold above local sky and estimates +the full width half maximum of the point spread function. +.IP 2. +DAOFIND computes a convolution kernel which is a linear +function of the brightness values in an approximately circular array of +pixels. The original data is convolved with the computed kernel. +The equivalent mathematical +operation is a convolution of the original data +with truncated, lowered circular Gaussian function with the specified FWHM, +computed in such a way as to be the mathematical +equivalent of fitting a Gaussian stellar profile to the object data by least +squares. The coefficients of the linear function sum to zero so that the +overall bias level (local sky) cancels out exactly. Since the function is +symmetric about a single pixel, a smooth gradient in the sky brightness +also cancels exactly. Therefore the user does not have to specify an +absolute brightness threshold but only a threshold above local sky. +.IP 3 +The convolved data is searched for local maxima. Local maxima which are +less than the specified threshold are rejected. A pixel is defined to be +a local maximum when it is the brightest pixel within +$n ~*~ sigma sub Gauss$. +.IP 4. +Using the original data, DAOFIND computes an object sharpness statistic which +can be used to reject +hot or cold pixels. The sharp parameter is defined below. +Detected objects with a sharpness parameter outside the range specifed +by sharplo and sharphi are rejected. Typical values for sharplo and +sharphi are 0.2 and 1.0 respectively. +.nf + + $I sub delta$ = height of best fitting $delta$ function = pixel value + + $I sub Gauss$ = height of best fitting Gaussian function = convolved value + + sharplo <= sharp = ${I sub delta} over {I sub Gauss}$ <= sharphi + +.fi +If the brightness enhancement detected in the convolved data is due to +a single bright pixel, then the best fitting delta function will have an +amplitude equal to the height of this pixel above the local background, +while the amplitude of the best fitting Gaussian will be pulled down by +the surrounding low valued pixels. Sharp will be a number significantly +greater than one. A single cold pixel will produce +brightness enhancements approximately 0.5 * FWHM away +from the pixel in question in all directions. In this case the height +of the delta +function which best fits these spurious maxima is close to zero, while the +height of the best fitting Gaussian is some small positive number. +In this case sharp will be close to zero. +.IP 5. +The roundess statistic is computed from the original picture data by fitting +1D Gaussians +to the marginal sums in x and y. If the height of either 1D +Gaussian is negative the object is rejected. If both heights are +positive the roundness parameter is computed. +.nf + + $DELTA I ~=~ I sub {x ~ Gauss} ~-~ I sub {y ~ Gauss}$ + + $<I> ~=~ I sub {x ~ Gauss} ~+~ I sub {y ~ Gauss}$ + + $roundlo ~<=~ round ~=~ {DELTA I} over <I> ~<=~ roundhi$ + +.fi +Objects which are elongated in the +x direction have roundness values less than zero and those elongated in +the y direction have roundness greater than zero. +Round discriminates only against objects which are elongated +along either rows or columns. Objects elongated at a 45 degree angle will +not be rejected. +.IP 6. +Finally the approximate x and y centroids of the detected objects, +rough magnitudes relative to threshold are computed, and object is added +to the output file. + + +.NH 3 +The CENTER Task + +.NH 4 +Centering Package Routines +.PP +The following are the principal programmer callable routines routines in the +centering package. +.nf +\f(CW + + apcinit (ap, cfunction, cbox, fwhmpsf, noise) + ier = apfitcenter (ap, im, xinit, yinit) + ier = aprefitcenter (ap) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apcfree (ap) + +\fR +.fi +.PP +The following quantities can be examined or set by apstat/apset calls +.nf +\f(CW + data 1. fwhmpsf full width half maximum of psf in pixels +parameters 2. threshold minimum intensity for centering + 3. noise noise model + 4. sigma standard deviation of background + 5. readnoise readout noise of CCD in electrons + 6. epadu electrons per adu + +centering 1. calgorithm centering algorithm +parameters 2. positive emission / absorption features + 3. cbox centering radius in fwhmpsf + 4. cmaxiter maximum number of fitting iterations + 5. maxshift maximum permitted shift in fwhmpsf + 6. minsnratio minimum permitted signal to noise ratio + 7. clean clean subraster before centering + 8. rclean cleaning radius in fwhmpsf + 9. rclip clipping radius in fwhmpsf + 10.kclean k-sigma rejection for cleaning in sigma +\fR +.fi + +.PP +The following computed quantities can be examined by apstat calls. +.nf +\f(CW + 1. xcenter computed x coordinate + 2. ycenter computed y coordinate + 3. xerr computed x coordinate error + 4. yerr computed y coordinate error +\fR +.fi +.PP +See the manual pages for CENTER and CENTERPARS for a detailed description +of the centering parameters. + +.NH 4 +The Centering Algorithm +.PP +The function of the CENTER task is to compute accurate centers and errors +for objects in an IRAF image given a list of initial positions and a +centering aperture. +.IP 1. +If the centering algorithm is disabled, the computed center is set to the +initial center and the uncertainty estimate is set to zero. +.IP 2. +If the cleaning algorithm is enabled, clean the subraster before centering. +.IP 3. +Estimate is made of the signal to noise of the object. If this quantity is +less than a certain minimum value the computed center is kept +but a warning message is issued. +.IP 4. +The center and errors are computed using one of several algorithms. +.IP 5. +If the computed center is greater than a user specified distance from the +initial center then the computed center is returned with an error +message. + +.NH 4 +Symmetry Clean Algorithm +.PP +The symmetry-clean algorithm attempts to remove defects in the centering +subraster by assuming that the object has radial symmetry and comparing +pixels on the opposite sides of the center of symmetry. The algorithm +works in the following way. +.IP 1. +The center of symmetry is computed. Normally the center of symmetry is assumed +to coincide with the position of the brightest pixel in the subarray. +However if the maximum pixel is more than a user specified distance away +from the intial center, the initial center is used as the center of symmetry. +.IP 2. +Pixels inside a specified cleaning radius are unaltered. +.IP 3. +Pairs of pixels diametrically opposed about the center +in the cleaning region between the cleaning and clipping +radii are tested for equality. If the difference between the pixels is +greater than a specified k-sigma rejection limit, the larger value is replaced +by the smaller. +In this region sigma is computed from Poisson statistics. +.IP 4. +Pairs of pixels in the clippping +region are compared in the same manner as those in the cleaning region +except that sigma is the standard deviation of the sky pixels. +.PP +The effect of the symmetry-clean algorithm is to edit the raster, +removing any contaminating objects in the vicinity of the primary object. +This simplifies the fitting algorithm and increases its reliability, +since it does not have to deal with multipeak marginal distributions. + +.NH 4 +Signal to Noise Estimate + +.PP +The signal to noise of the object is estimated from the data values +in the subraster in the following way. +.nf + + $SNR ~=~ N sub object over {sqrt {n sub pix ~*~sigma sub sky sup 2}}$ + + or + + $SNR ~=~ N sub object over {sqrt {N sub object ~+~ n sub pix~*~sigma sub sky sup 2}}$ + +.fi +where $N sub *$ is the number of counts in the object above threshold, +$sigma sub sky$ +is the standard deviation of the pixels in the sky region and +$n sub pix$ is the number of pixels in the object aperture. +The first approximation corresponds to constant sky noise only, +the second includes Poisson noise in the object. + +.NH 4 +Centroid +.PP +The centroid centering algorithm is similar to that used in MPC and can +be briefly described as follows. For more detailed description +see (Stellar Magnitudes From Digital Pictures, 1980, Adams et al). +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +The intensity weighted centroid positions for the marginals is computed +using only data pixels which are above the threshold intensity. If the +threshold parameter is 0 the mean intensity of the marginal is used +in place of the threshold +.nf + + $I sub i ~=~ I sub i ~-~ threshold ~~~~~ I sub i ~>~ 0.0$ + + $x sub c ~=~ {sum I sub i ~ x sub i} over {sum I sub i}$ + +.fi +.IP 3. +The errors are estimated in the following way +.nf + + $sigma sup 2 ~=~ {sum I sub i ~ x sub i sup 2} over {sum I sub i} ~-~ x sub c sup 2$ + + $err sub xc ~=~ sqrt {{sigma sup 2} ~/~ sum I sub i}$ + +.fi + +.NH 4 +Gaussian Fit to the Marginals +.PP +The fit is performed in the following way. +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +Initial guesses for the parameters of the 1D Gaussians $I sub Gauss$, +$x sub c$ and $I sub sky$ are derived from the marginal distributions +themselves. The width $sigma$ is held constant. +.IP 3. +The best fit parameters and their errors are derived using non-linear +least-squares techniques and the NLFIT package. + +.NH 4 +Optimal Filtering of Marginals +.PP +The fit is performed is the following way. +.IP 1. +The marginal distributions in x and y are accumulated. +.IP 2. +The centroid of the observed distribution is computed by solving the +following equation. +.nf + + $PSI (x sub c ) ~=~ sum omega sub i (x sub c ) ~ PHI sub i ~=~ 0$ + + $omega sub i ~=~ {{partial phi sub i} ~/~ {partial x sub c}} over {phi sub i~+~b}$ + +.fi +The assumptions are that the observed distribution $PHI sub i$ is correctly +modeled by the profile function $phi sub i$. The usual choise of profile +model for centering is a Gaussian. Howver in the interests of speed a triangle +function has been substituted. This causes at most a 7% increase in the +random centering error. +.IP 3. +The startup procedure is based on the following fact. +.nf + + $PSI (x sub n )~>~0~~for~~ x sub n ~<~ x sub c$ + + $PSI (x sub n ) ~<~0~~for~~ x sub n ~>~ x sub c$ + +.fi +The iteration is initialized by assuming that $x sub 1$ = $x sub c$ and +computing $PSI (x sub 1 )$. The initial x +value is incremented by $+- sigma sub Gauss$ depending on the sign of $PSI$. The +search is repeated until $PSI (x sub {n-1})$ and $PSI (x sub n)$ have +opposite signs. At this point the true center is bracketed by the +estimated positions $(x sub n, ~ x sub {n-1})$ and we have a table of at +least 2 values of $PSI (x sub n )$. +.IP 4. +The computation proceeds by interpolating in the table of values for the +estimated position $x sub {n+1}$ where $PSI$ = 0. If the table contains only +two values as may be the case for the inititial interpolation, linear +interpolation is used. In all other cases a quadratic fit to the three +most recent $PSI$ values is used. The computation is complete when +two successive estimates differ by less than some tolerance typically +0.001 pixel. +.IP 5. +The errors are estimated as follows. +.nf + + $sigma sup 2 ~=~ ( {int {( partial phi ~/~ partial x sub c )} sup 2 over { + phi + b}} ) sup -1$ + + $err sub xc ~=~ sqrt {sigma sup 2}$ + +.fi + +.NH 4 +Other Centering Methods +.PP +The code is constructed in such a way that new algorithms may be +easily added at a future date, such as the more sophisticated techniques +required for accurate astrometry. +.EQ +delim $$ +.EN +.NH 3 +The FITSKY Task + +.NH 4 +Sky Fitting Routines + +.PP +The following are the main entry points in the sky fitting package. +.nf +\f(CW + apsinit (ap, function, annulus, dannulus, fwhmpsf, noise) + ier = apfitsky (ap, im, xpos, ypos, sd, gd) + ier = aprefitsky (ap, sd, gd) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[irs] (ap, param, value) + apsfree (ap) +\fR +.fi +.PP +The following quantities can be examined or set with apset/apstat calls. +.nf +\f(CW +data 1. fwhmpsf full width half maximum of the psf +parameters 2. sigma standard deviation of sky pixels + +sky fitting 1. annulus inner radius of sky annulus in fwhmpsf +parameters 2. dannulus outer radius of sky annulus in fwhmpsf + 3. sfunction sky fitting algorithm + 4. smaxiter maximum number of fitting iterations + 5. kreject k-sigma rejection limit sigma + 6. nreject maximum number of rejection cycles + 7. rgrow region growing radius in fwhmpsf + + 8. khist half-wdth of histogram in sigma + 9. binsize binsize of histogram in sigma + 10.smooth Lucy smooth the histogram + + 11.skyfile name of text file containing sky values + 12.skyvaluser supplied constant value for sky +\fR +.fi +.PP +The following computed quantities can only be examined with apstat calls. +.nf +\f(CW + 1. skymode computed sky value + 2. skysig computed sky sigma + 3. skyskew computed sky skew + 4. nsky number of sky pixels + 5. nsky_reject number of rejected sky pixels +\fR +.fi + +.NH 4 +The Sky Fitting Algorithms +.PP +A good background fit is essential to aperture photometry. Fitting +the background is trivial in a sparse field, but difficult in a crowded +field. In general the background region will contain contaminating objects +which must be detected and excluded if a good fit is to be obtained. +.PP +The main algorithm used in APPHOT is the following. +.IP 1. +If the skyfitting switch is disabled either read the sky values from a text +file or accept a user supplied constant for the sky. +.IP 2. +Perform the initial sky fit using one of the specified algorithms. The +sky fitting algorithms fall into three general categories, those that use +the actual sky pixel array itself, those that operate on a histogram of +sky values and those that rely on user interaction. +.IP 3. +If the pixel rejection flags are set perform pixels rejection with optional +region growing. + +.NH 4 +Sky Pixel Array Techniques + +.NH 5 +Median +.IP 1. +Sort the array of sky pixels. This is necessary to avoid quantization effects. +.IP 2. +Compute the median, and the standard deviation and skew with respect to the +mean. +.IP 3. +If the k-sigma rejection limit is greater than zero and the maximum number +of rejection cycles is greater than one, perform pixel rejection. +Pixels greater than k-sigma from the median are rejected. Region growing +is optional. +.IP 4. +Stop the rejection cycle on any given iteration if the maximum number of +rejection cycles ix exceeded, no more sky pixels are left or no more +pixels are rejected. + +.NH 5 +Mode +.IP 1. +Sort the array of sky pixels. This is necessary to avoid quantization effects. +.IP 2. +Compute the mode, and the standard deviation and skew +with respect to the mean. +.nf + + $I sub mode ~=~ 3.0 ~*~ I sub median ~-~ 2.0 ~*~ I sub mean$ + +.fi +.IP 3. +If the k-sigma rejection limit is greater than zero and the maximum number +of rejection cycles is greater than one, perform pixel rejection. +Pixels greater than k-sigma from the mode are rejected. Region growing +is optional. +.IP 4. +Stop the rejection cycle on any given iteration if the maximum number of +rejection cycles ix exceeded, no more sky pixels are left or no more +pixels are rejected. + + +.NH 4 +Histogram Techniques +.PP +The following three techniques all operate on the histogram of the sky pixels. +The routines all construct the histogram in the following identical manner. +.IP 1. +The mean of the sky distribution is computed. +.IP 2. +If the user specified standard deviation of the sky pixels is INDEF the +algorithm computes the standard deviation of the sky pixels with respect +to the mean. +.IP 3. +All pixels within plus or minus sigma standard +deviations are accumulated into a histogram. The user specifies the bin size. +.IP 4. +The histogram may optionally be Lucy smoothed before any operation is performed +on it. + +.NH 5 +Centroid +.PP +The mode, sigma and skew of the sky pixels are computed in the following +manner. +.IP 1. +The histogram is compiled as above. +.IP 2. +The mode, standard deviation and skew of the sky pixels are computed in the +following manner. + +.nf + $I sub 0 ~=~ sum I sub i$ + $I sub 1 ~=~ sum I sub i ~ x sub i$ + $I sub 2 ~=~ sum I sub i ~ x sub i sup 2$ + $I sub 3 ~=~ sum I sub i ~ x sub i sup 3$ + + $I sub mode ~=~ {I sub 1} ~/~ {I sub 0}$ + $sigma ~=~ {( I sub 2 ~/~ I sub 0 ~-~ I sub mode sup 2 )} sup {1/2}$ + $skew ~=~ ( {I sub 3 ~/~ I sub 0 ~-~ I sub mode ~*~ sigma sup 2 ~-~ I sub mode sup 3} ) sup {1/3}$ + +.fi +.IP 3 +If pixel rejection is enabled sky pixels within a user supplied limit of +the mode are rejected with optional region growing. + +.NH 5 +Gaussian Fit +.PP +The mode, standard deviation and skew of the sky pixels are derived from a +model fit in the following way. +.IP 1. +The histogram of the sky pixels is compiled as above. +.IP 2. +Initial guesses to the model parameters, $N sub max$, $I sub mode$, +$sigma$, and $skew$ are made from the histogram itself. +.IP 3. +Final parameters and their errors are derived using non-linear least squares +techniques and the NLFIT package. +.IP 4. +If pixel rejection is enabled sky pixels within a user supplied limit of +the computed mode are rejected with optional region growing. + +.NH 5 +Optimal Filtering +.PP +The method is as follows. +.IP 1. +The histogram is compiled as above. +.IP 2. +Using the mean of the sky pixels as the intital value of the sky mode, +a new mode is computed using the optimal filtering technique +described for centering. +.IP 4 +If pixel rejection is enabled sky pixels within a user supplied limit of +the computed mode are rejected with optional region growing. + +.NH 5 +Cross Correlation +.PP +The method is as follows. +.IP 1. +The histogram is compiled as above. +.IP 2. +The noise function is estimated using the standard deviation of the sky +pixels and the cross-correlation function is computed. +.IP 3. +The mode is computed using quadratic interpolation around the peak of the +distribution. +.IP 4 +If pixel rejection is enabled sky pixels within a user supplied limit of +the mode are rejected with optional region growing. + +.NH 4 +Interactive Techniques + +.NH 5 +Histogram Plot +.PP +The histogram is compiled as described above and the user marks the peak +on the histogram plot with the graphics cursor. The sigma and skew of the +sky distribution with respect to the mean is also computed. + +.NH 5 +Radial Distribution +.PP +A radial profile plot of the sky region is plotted and the user marks the +sky value on the plot with the graphics cursor. The sigma and skew of the sky +distribution with respect to the mean is computed. + +.NH 4 +Pixel Rejection and Region Growing +.PP +All the sky fitting algorithms permit pixel rejection and +optional region growing. +Pixel rejection and region growing are +performed by locating all pixels more than k * sigma from the mode, +and blindly rejecting all pixels within a certain radius of each deviant +pixel. This simple algorithm works well because the sample is large, +and therefore there is little penalty for discarding pixels that might +not be deviant. Region growing also tends to accelerate convergence +significantly. +.PP +Very faint contaminating objects are difficult to detect and reject. +If there are enough such objects, they should not be rejected, because +there are probably a few in the object aperture as well. A higher sky +sigma will be calculated and the computed uncertainty in the magnitude +will increase. The best solution to this problem may be to increase +the size of the annulus to minimize the bias. + +.NH 4 +The Principal PHOT Routines +.PP +The main entries in the photometry routine are the following. +.nf +\f(CW + apinit (ap, cfunction, cbox, sfunction, annulus, dannulus, + aperts, napert, fwhmpsf, noise) + ier = apfitcenter (ap, im, xinit, yinit) + ier = aprefitcenter (ap) + ier = apfitsky (ap, im, xcenter, ycenter, sd, gd) + ier = aprefitsky (ap, sd, gd) + ier = apmag (ap, im, xcenter, ycenter, skyval, skysig, nsky) + ier = apwmag (ap, im, xcenter, ycenter, positive, skyval, skysig, + nsky) + ier = apremag (ap, positive, skyval, skysig, nsky) + ier = apwremag (ap, positive, skyval, skysig, nsky) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apfree (ap) + +\fR +.fi +.PP +The following parameters can be examined or altered by apset/apstat calls. +.nf +\f(CW + 1. weighting weighting scheme for wphot + 2. aperts list of apertues + 3. naperts number of apertures + 4. zmag zero point of magnitude scale + 5. itime effective integration time +\fR +.fi +.PP +The following quantities can be examined with apstat calls. +.nf +\f(CW + + 1. sums array of aperture sums + 2. areas array of areas + 3. mags array of magnitudes + 4. magerrs array of magnitude errors + +\fR +.fi + +.NH 4 +The PHOT Aperture Integration Algorithm +.PP +The integral of the flux within a circular aperture is computed by +fractional pixel techniques. Pixels are assumed to be square apertures +arranged in a rectangular grid. The fraction of a pixel which lies within +the circular APPHOT aperture is computed by an approximation, and all +such contributions are summed to produce the total integral. +.PP +The inclusion of a partial pixel inside the aperture is done as follows. +.IP 1. +If the distance of the current pixel from the center of the star, r, is +exactly equal to the radius of the aperture R then one-half the counts in +the pixel are included. +.IP 2. +If r < R - 0.5 the entire pixel is included while if r > R + 0.5 the pixel +is wholly excluded. +.IP 3. +In between the fraction of the counts varies linearly. A circular aperture +is approximated by an irregular polygon. +.PP +The simplicity of aperture photometry limits the amount of information +available for error analysis. The following three sources of error are +considered. +.IP 1. +The error due to sky noise in the aperture. +.nf + + $error sub 1 ~=~ sigma sub sky ~*~ {A sub apert} sup {1/2}$ + +.fi +.IP 2. +The error in the aperture sum. +.nf + + $error sub 2 ~=~ ( {A sub "sum" ~/~ phpadu} ) sup {1/2}$ + +.fi +.IP 3. +The mean error of the sky. +.nf + + $error sub 3 ~=~ sigma sub sky ~*~ A sub apert ~/~ nsky sup {1/2}$ + + +.fi +where $sigma sub sky$ is either computed by the background fitting +algorithm or set by the user, +and $A sub apert$ is the fractional pixel area of the +aperture. + +.NH 4 +The WPHOT Algorithm +.PP +The WPHOT algorithm computes a weighted aperture sum in an attempt to +minimize noise in the sky. The algorithm is the following where w is +the weight for each pixel, p is the noise free profile value and +$sigma$ is the noise per pixel from all sources. (See the paper +by Stover and Allen 1987 for details) +.nf + + $A sub sum ~=~ sum {w sub i ~*~ (I sub i ~-~ sky)}$ + + $w sub i ~=~ C ~*~ p sub i ~/~ sigma sup 2 sub i$ + + $C ~=~ sum {p sub j} / sum {p sub j ~*~ w sub j}$ +.fi + +.NH 4 +The POLYPHOT ROUTINES +.PP +The principal polyphot routines are the following. + +.nf +.na +\f(CW + apyinit (ap, sfunction, annulus, dannulus, noise) + ier = apfitcenter (ap, im, wx, wy) + ier = aprefitcenter (ap) + ier = apfitsky (ap, im, xcenter, ycenter, sd, gd) + ier = aprefitsky (ap, sd, gd) + ier = polyfit (ap, im, xver, yver, nver) + value = apstat[ir] (ap, param) + apstats (ap, param, str, maxch) + apset[sir] (ap, param, value) + apfree (ap) + +\fR +.ad +.fi + +.PP +.NH 4 +The POLYPHOT Algorithm +.PP +The function of the POLYPHOT task is to compute the flux inside an +irregular polygon given a list of the coordinates of the vertices of a polygon. +The polygon must be entirely inside the image and the vertices of the polygon +must be specified in clockwise or counterclockwise order. +The actual algorithm used is as follows. +.IP 1. +The range of image lines which intersect the polygon are computed. +.IP 2. +For each image line in the specified range the intersection points with the +polygon are computed. +.IP 3. +The flux between pairs of limits is summed using a fractional pixel +approximation for the endpoints. +.IP 4. +The sky is fitted using any of the methods previously discussed and a +user specified annular region. +.IP 5. +The errors are computed as specified in the PHOT specifications. +.PP +.EQ +delim $$ +.EN + +.NH +Example +.PP +A brief example may help illustrate the use of the package. Suppose +we want to process a few hundred stars on image "blue". +.PP +The first step is to prepare a list of objects to be measured. The simplest +way to do this is to interactively mark the objects with the image +cursor using the display (graphics) device and the RIMCURSOR (RGCURSOR) +task. +.nf +\f(CW + + ... load image on the display ... + + ap> rimcursor > starlist + + ... move cursor and mark stars ... + + + ... load contour plot on graphics terminal ... + + ap> rgcursor > starlist + + ... move cursor and mark stars ... +\fR +.fi + +Alternatively one can run DAOFIND to compute a list of candidate objects +in the frame. +The name of the coordinate file is stored in the PHOT parameter set. + +.nf +\f(CW + ap> phot.coords=starlist +\fR +.fi + +.PP +The next step is to set up the PHOT parameters interactively. +First we load the image (contour plot) blue on the display (graphics +terminal). Next we call up PHOT in interactive mode. + +.nf +\f(CW + ap> phot blue + ... cursor appears ... + +\fR +.fi + +.PP +PHOT takes input by reading the image (graphics) +display (terminal) cursor. In order to display the available commands +we tap the ? key and the following text appears on the screen. + +.nf +\f(CW + Interactive Phot Commands + +? Print options +: Colon command see below +i Setup PHOT parameters interactively +w Write PHOT parameters to the parameter files +l Process the remainder of the coordinate list +r Rewind the coordinate list +c Fit center around the current cursor position +t Fit sky around the current cursor position +s Fit sky around the current center position +p Compute magnitudes around the cursor position +f Fit center, sky and compute magnitudes +sp Fit center, sky, compute magnitudes, and save +q Exit program + +Phot parameters are listed or set with the following commands. + +:m [n] Move cursor to the [nth] object in the coordinate list +:n [n] Measure the [nth] object in the coordinate list + +:show [center/sky/phot/all] List the aphot parameters +:fwhmpsf [value] Full width half maximum of the PSF +:noise [string] Noise model +:threshold [value] Threshold value for centering +:sigma [value] Standard deviation of the background +:ccdread CCD readout noise keyword +:readnoise Readout noise in electrons +:gain Gain keyword +:epadu Electrons per adu + +:calgorithm [string] Centering function +:positive [y/n] Emission or absorption feature +:cbox [value] Width of the centering box in fwhmpsf +:cmaxiter [value] Maximum number of centering iterations +:maxshift [value] Maximum shift in fwhmpf +:minsnratio [value] Minimum signal to noise ratio of pixels +:clean [y/n] Clean subraster before centering +:rclip [value] Clipping radius in fwhmpsf +:rclean [value] Cleaning radius in fwhmpsf +:kclean [value] Sigma for clean algorithm +:mkcenter [y/n] Mark the centers on the display + +:salgorithm [string] Sky fitting algorithm +:annulus [value] Inner radius of sky annulus in fwhmpsf +:dannulus [value] Width of sky annulus in fwhmpsf +:skyvalue [value] User supplied sky +:smaxiter [value] Maximum number of rejection cycles +:skreject [value] +/- Pixel rejection limits in sky sigma +:snreject [value] Maximum number of rejection interations +:khist [value] +/- Sky histogram size in sky sigma +:binsize [value] Resolution of sky histogram in sky sigma +:smooth [y/n] Lucy smooth the sky histogram +:rgrow [value] Region growing radius in fwhmpsf +:marksky [y/n] Mark the sky annuli on the display + +:weighting Weighting for wphot +:aperts [string] Aperture radii in fwhmpsf +:zmag [value] Zero point of magnitude scale +:exposure [string] Exposure time keyword +:itime [value] Integration time +\fR +.fi + +.PP +We select the interactive setup option, move the image +cursor to a high signal-to-noise, isolated star and tap the i key. +PHOT responds by plotting the radial profile of the star on the +screen and requesting the user to mark the fwhm of +the psf, the centering aperture, the inner and outer sky annuli, +the sky background and sigma and the set of circular apertures. +The parameters so set can be examined and/or reset with the : commands as shown +above. Sample measurements can be made of several stars by moving the +cursor and typing the f command. Finally when we are happy with the +parameter set we type w to store the parameters and q to exit the program. +.PP +Now we are ready to do photometry. We enter the PHOT program in batch mode. + +.nf +\f(CW + ap> phot blue inter- & +\fR +.fi + +The batch job is now running, appending output lines to the file "blue.mag.#". +We can proceed to set up the job for the red image, in much the same way +that we set up the job for the blue image. When both jobs finish, we +can use the list processing tools to filter out the good objects and +calculate colors. + +.NH +The APPHOT Tasks +.PP +Manual pages for the APPHOT tasks are available in the IRAF on line help +database. diff --git a/noao/digiphot/apphot/doc/specs/apphot.spc.toc b/noao/digiphot/apphot/doc/specs/apphot.spc.toc new file mode 100644 index 00000000..757f9a79 --- /dev/null +++ b/noao/digiphot/apphot/doc/specs/apphot.spc.toc @@ -0,0 +1,111 @@ +.LP +.sp +1.\h'|0.4i'\fBIntroduction\fP\l'|5.6i.'\0\01 +.sp +2.\h'|0.4i'\fBAPPHOT Package Requirements\fP\l'|5.6i.'\0\01 +.br +\h'|0.4i'2.1.\h'|0.9i'APPHOT Package Input\l'|5.6i.'\0\01 +.br +\h'|0.9i'2.1.1.\h'|1.5i'The IRAF Image\l'|5.6i.'\0\01 +.br +\h'|0.9i'2.1.2.\h'|1.5i'The Coordinate Lists\l'|5.6i.'\0\02 +.br +\h'|0.9i'2.1.3.\h'|1.5i'Algorithm Parameters\l'|5.6i.'\0\02 +.br +\h'|0.9i'2.1.4.\h'|1.5i'Terminal Graphics and the Image Display\l'|5.6i.'\0\02 +.br +\h'|0.4i'2.2.\h'|0.9i'APPHOT Package Functions\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.1.\h'|1.5i'Creating Coordinate Lists\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.2.\h'|1.5i'Coordinate List Operations\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.3.\h'|1.5i'Determining the Image Characteristics\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.4.\h'|1.5i'Centering\l'|5.6i.'\0\03 +.br +\h'|0.9i'2.2.5.\h'|1.5i'Fitting the Sky\l'|5.6i.'\0\04 +.br +\h'|0.9i'2.2.6.\h'|1.5i'Multi-aperture Photometry\l'|5.6i.'\0\04 +.br +\h'|0.9i'2.2.7.\h'|1.5i'Polygonal Aperture Photometry\l'|5.6i.'\0\04 +.sp +3.\h'|0.4i'\fBAPPHOT Package Specifications\fP\l'|5.6i.'\0\04 +.br +\h'|0.4i'3.1.\h'|0.9i'Apphot CL Callable Tasks\l'|5.6i.'\0\04 +.br +\h'|0.4i'3.2.\h'|0.9i'Standard Analysis Procedures\l'|5.6i.'\0\05 +.br +\h'|0.4i'3.3.\h'|0.9i'The APPHOT Algorithms\l'|5.6i.'\0\05 +.br +\h'|0.9i'3.3.1.\h'|1.5i'The RADPROF Algorithm\l'|5.6i.'\0\05 +.br +\h'|0.9i'3.3.2.\h'|1.5i'The FITPSF Algorithm\l'|5.6i.'\0\06 +.br +\h'|0.9i'3.3.3.\h'|1.5i'The DAOFIND Algorithm\l'|5.6i.'\0\06 +.br +\h'|0.9i'3.3.4.\h'|1.5i'The CENTER Algorithm\l'|5.6i.'\0\08 +.br +\h'|1.5i'3.3.4.1.\h'|2.2i'Centering Package Routines\l'|5.6i.'\0\08 +.br +\h'|1.5i'3.3.4.2.\h'|2.2i'The General Centering Procedure\l'|5.6i.'\0\09 +.br +\h'|1.5i'3.3.4.3.\h'|2.2i'Symmetry Clean Algorithm\l'|5.6i.'\010 +.br +\h'|1.5i'3.3.4.4.\h'|2.2i'Signal to Noise Estimate\l'|5.6i.'\010 +.br +\h'|1.5i'3.3.4.5.\h'|2.2i'Centroid\l'|5.6i.'\010 +.br +\h'|1.5i'3.3.4.6.\h'|2.2i'Gaussian Fit to the Marginals\l'|5.6i.'\011 +.br +\h'|1.5i'3.3.4.7.\h'|2.2i'Radial Gaussian Fit to the Subraster\l'|5.6i.'\011 +.br +\h'|1.5i'3.3.4.8.\h'|2.2i'Optimal Filtering of Marginals\l'|5.6i.'\011 +.br +\h'|1.5i'3.3.4.9.\h'|2.2i'2D Optimal Filtering\l'|5.6i.'\012 +.br +\h'|1.5i'3.3.4.10.\h'|2.2i'Other Centering Methods\l'|5.6i.'\012 +.br +\h'|0.9i'3.3.5.\h'|1.5i'The FITSKY Task\l'|5.6i.'\013 +.br +\h'|1.5i'3.3.5.1.\h'|2.2i'Sky Fitting Package Routines\l'|5.6i.'\013 +.br +\h'|1.5i'3.3.5.2.\h'|2.2i'General Sky Fitting Procedures\l'|5.6i.'\014 +.br +\h'|1.5i'3.3.5.3.\h'|2.2i'Sky Pixel Array Techniques\l'|5.6i.'\014 +.br +\h'|2.2i'3.3.5.3.1.\h'|2.9i'Mean\l'|5.6i.'\014 +.br +\h'|2.2i'3.3.5.3.2.\h'|2.9i'Median\l'|5.6i.'\014 +.br +\h'|2.2i'3.3.5.3.3.\h'|2.9i'Mode\l'|5.6i.'\015 +.br +\h'|1.5i'3.3.5.4.\h'|2.2i'Histogram Techniques\l'|5.6i.'\015 +.br +\h'|2.2i'3.3.5.4.1.\h'|2.9i'Centroid\l'|5.6i.'\015 +.br +\h'|2.2i'3.3.5.4.2.\h'|2.9i'Gaussian Fit\l'|5.6i.'\016 +.br +\h'|2.2i'3.3.5.4.3.\h'|2.9i'Optimal Filtering\l'|5.6i.'\016 +.br +\h'|2.2i'3.3.5.4.4.\h'|2.9i'Cross Correlation\l'|5.6i.'\016 +.br +\h'|1.5i'3.3.5.5.\h'|2.2i'Interactive Techniques\l'|5.6i.'\016 +.br +\h'|2.2i'3.3.5.5.1.\h'|2.9i'Histogram Plot\l'|5.6i.'\016 +.br +\h'|2.2i'3.3.5.5.2.\h'|2.9i'Radial Distribution\l'|5.6i.'\016 +.br +\h'|1.5i'3.3.5.6.\h'|2.2i'Pixel Rejection and Region Growing\l'|5.6i.'\017 +.br +\h'|0.9i'3.3.6.\h'|1.5i'The APPHOT Task\l'|5.6i.'\017 +.br +\h'|1.5i'3.3.6.1.\h'|2.2i'The APPHOT Package Routines\l'|5.6i.'\017 +.br +\h'|1.5i'3.3.6.2.\h'|2.2i'The APPHOT Aperture Integration Algorithm\l'|5.6i.'\018 +.br +\h'|0.9i'3.3.7.\h'|1.5i'The POLYPHOT Algorithm \l'|5.6i.'\018 +.sp +4.\h'|0.4i'\fBExample\fP\l'|5.6i.'\019 +.sp +5.\h'|0.4i'\fBThe APHOT Tasks\fP\l'|5.6i.'\021 diff --git a/noao/digiphot/apphot/doc/ucache.hlp b/noao/digiphot/apphot/doc/ucache.hlp new file mode 100644 index 00000000..34a091dd --- /dev/null +++ b/noao/digiphot/apphot/doc/ucache.hlp @@ -0,0 +1,15 @@ +If \fIcache\fR is yes and the host machine physical memory and working set size +are large enough, the input image pixels are cached in memory. If cacheing +is enabled and the task is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because the task +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. diff --git a/noao/digiphot/apphot/doc/userdocs/apuser.ms b/noao/digiphot/apphot/doc/userdocs/apuser.ms new file mode 100644 index 00000000..24492bcc --- /dev/null +++ b/noao/digiphot/apphot/doc/userdocs/apuser.ms @@ -0,0 +1,1881 @@ +.RP + +.TL +A User's Guide to the IRAF Apphot Package + +.AU +Lindsey Elspeth Davis +.AI + +.K2 "" "" "*" +Revised May 1989 + +.AB +.PP +The APPHOT package is a set of tasks for performing aperture photometry +on uncrowded or moderately crowded stellar fields in either interactive or batch +mode. The photometric technique employed is fractional pixel +integration. Point spread function fitting techniques are not used and no +knowledge of the point spread function is required for the computation of +magnitudes. Separate tasks are provided for creating and modifying object +lists, computing accurate centers and sky values for a list of objects, +and performing photometry inside concentric +circular or polygonal apertures. +.PP +This document describes the data preparation required to run APPHOT, how +to set up the display and graphics devices, how to set the algorithm +parameters, how to run the package tasks in interactive or batch mode +and how to selectively examine the results. Detailed descriptions of the +algorithms can be found in the document \fISpecifications for the +APPHOT Package\fR by the author. +.PP +This document applies to APPHOT under IRAF version 2.8. APPHOT +can be run under IRAF versions 2.5, 2.6 and 2.7 with only minor changes in +the task setup. These differences are documented +where appropriate in the text. +.AE + +.NH +Introduction +.PP +The APPHOT package is a set of tasks for performing +aperture photometry on uncrowded or moderately crowded fields. +The photometric technique employed is fractional pixel integration. Point +spread function techniques are not used and no knowledge of the point spread +function is required for the computation of magnitudes. +.PP +The APPHOT package performs multi-aperture photometry on digitized starfields +maintained as IRAF image files. Input to the package consists of an +image file(s), an optional list(s) of object coordinates, +numerous parameters controlling +the analysis algorithms and, optionally, the graphics terminal and/or +display. APPHOT output consists of successive records, where each record +records the results of the analysis for a single object. Some tasks +also produce graphics output in the form of plot metacode files. +.PP +Given starting coordinates and an IRAF image, the principal APPHOT +task \fBphot\fR computes accurate centers, sky values and magnitudes +for a list of objects. Separate +IRAF callable tasks in APPHOT exist to create and modify object +lists, to determine image characteristics such as the full width half maximum +of the point spread function or standard deviation of the sky pixels, +to compute accurate centers for a list of objects, to compute accurate local sky +values for a list of objects, and to compute magnitudes inside a polygonal +aperture. +.PP +The image data requirements of the APPHOT package are described in section 2. +Section 3 describes various ways to tailor the IRAF environment to run +the APPHOT package. Section 4 describes how to load the APPHOT tasks and how +use the on-help facility. Section 5 describes how to examine and edit the +APPHOT task and algorithm parameters. Several methods of creating and +modifying APPHOT coordinate lists files are described in section 6. +Sections 7 and 8 describe how to run the APPHOT tasks interactively without +and with a coordinate list respectively. Batch mode reductions in APPHOT are +described in section 9. Section 10 describes the format of the APPHOT output +catalogue and plot files. Section 12 lists various APPHOT recipes for reducing +common types of astronomical data with APPHOT. + +.NH +Data Preparation and Requirements +.PP +APPHOT assumes that the images to be analyzed exist on disk in IRAF readable +format. Facilities for reading and writing images exist elsewhere in IRAF +in the DATAIO and MTLOCAL packages. None of the current APPHOT +tasks alter the disk input images in any way. +.PP +APPHOT assumes that the pixel data is linear. The input images should be +corrected for those instrumental defects which affect the intensity +of a pixel prior to entering the APPHOT package. These defects include pixel +to pixel variations in the bias values, +pixel to pixel gain variations, cosmic rays, cosmetic defects, geometric +distortion and detector non-linearities. Users should be aware of the IRAF +CCDRED package for reducing CCD data and the DTOI package for converting +photographic density data to intensity data. +.PP +Extreme valued pixels should be removed from the images prior to entering +the APPHOT package. These include pixel values at or near the data limits of the +host machine as well as any host machine values such as INDEF, +produced by divide by zero, and floating point underflows and overflows. +Floating point operations involving such numbers may crash +with arithmetic exception errors. For efficiency and portability reasons +the APPHOT package and most IRAF routines do not test for these numbers. +The \fBimreplace\fR and \fBimedit\fP tasks in the PROTO package can be used to replace extreme +valued pixels. More general system facilities for handling bad pixels +inside IRAF are planned for the near future. +.PP +In order to normalize the magnitude scales of a list of images to a common +integration time, +APPHOT requires that the image exposure times be stored in the image header. +Similarly the correct computation of magnitude errors requires that +the readout noise and gain parameters also be present in the image +header or be supplied as constants in the APPHOT parameter files. +The readout noise must be supplied in units of electrons and the gain +is assumed to be in electrons per adu. The time units are arbitrary +but must be consistent for a given set of images. +APPHOT tasks access this information using a keyword and value scheme. +The IMAGES package task \fBhedit\fR can be used to insert or edit this +information prior to entering the APPHOT package. For example the following +commands will enter the gain, readout noise and exposure time information +into the headers of a list of images. + +.nf + \f(CWcl> hedit *.imh gain 14.0 add+ ver- + cl> hedit *.imh readout 20.0 add+ ver- + cl> hedit *.imh exptime add+ ver+\fR +.fi + +.PP +The point spread function is assumed to be constant for all regions +of the image. This is critical in the case of faint objects for +which small apertures which minimize the effects of crowding and sky noise in +the aperture are used. The wings of the object will almost certainly extend +beyond the aperture and good results will only be obtained if objects +are consistently well centered and the shape and diameter of an object is +constant throughout the object and invariant to magnitude. +.PP +The centering routines built into the APPHOT package assume that +the images are close to circularly symmetric over the region to be used +in centering although small deviations do not +significantly affect the accuracy of the results. +The user should be aware of the more sophisticated +but less efficient centering routines in the \fBdaofind\fR and \fBfitpsf\fR +routines. Several choices of centering algorithm are available in +APPHOT including no centering. +.PP +APPHOT assumes that the local sky background is approximately flat in the +vicinity of the object being measured. This assumption is equivalent to +assuming that +the local sky region has a unique mode. Therefore any variations in the +sky background which occur at the same scale as the sky region should be +removed prior to entering the APPHOT package. + +.NH +Setting up the IRAF Environment for APPHOT +.NH 2 +Script, Compiled and Pset Tasks +.PP +IRAF supports three types of tasks: scripts, compiled tasks and pset tasks. +In order to distinguish one type of task from another, APPHOT users should +set the cl parameter \fBshowtype\fR to yes as shown below. + +.nf + \f(CWcl> cl.showtype=yes\fR +.fi + +The cl command \fB?\fR or \fB?\fR \fIpackage\fR identifies script +tasks by a terminating period and pset tasks by a terminating @. +No trailing characters are added to the compiled task names. Pset tasks are +important to the APPHOT package and will be discussed further in +section 5. + +.NH 2 +Other IRAF Packages +.PP +Before running APPHOT, users may wish to load the IRAF packages, DATAIO, +IMAGES, +TV and PLOT. Various input and output routines exist in the DATAIO package, +including the fits reader and writer and the cardimage reader and +writer. The IMAGES package contains routines for basic image arithmetic, +for computing image statistics, for listing individual pixel values, +and for examining and +modifying the image headers. TV, a subpackage of IMAGES, contains the +\fBdisplay\fR task for loading images into the display device. +The PLOT package contains tasks for plotting +image data and for extracting and displaying individual plots from the plot +metacode files produced by the APPHOT tasks. +.PP +Various useful tasks for manipulating and displaying the data produced by +APPHOT can be found in the PROTO package under the NOAO package. In +particular the user should be aware of the \fBfields\fR, \fBmkhistogram\fR +and \fBtvmark\fP tasks. + +.NH 2 +The Image Cursor and Display Device +.PP +The APPHOT tasks are designed in interactive mode to read the image cursor +and to perform various actions based on the position of the image cursor +and the keystroke typed. The image cursor is directed to the display +device defined by the environment variable \fBstdimage\fR. To check the +value of the default display device, type the following command. + +.nf + \f(CWcl> show stdimage + imt512\fR +.fi + +In this example the default display device is the 512 pixel square SUN +imtool window. +All tasks which write images to the display access this +device. For example the +TV package \fBdisplay\fR program will load an image onto this device. +.PP +In normal operation IRAF tasks which read the image cursor would read +the hardware cursor from this device. +In response to the user command + +.nf + \f(CWcl> =imcur + or + cl> show imcur\fR +.fi + +the cursor would come up on the image display ready to accept a +keystroke command. At this point the user should check that the display +is reading the correct image coordinates by moving the image cursor to +the lower left hand corner of the display image and tapping any key. +The coordinates should read x,y = (1,1) if the whole image was +displayed. +.PP +Cursor readback is currently implemented under IRAF version 2.7 for the +SUN workstations and the IIS model 70. Users with older versions of IRAF +or other devices cannot run APPHOT tasks directly from the image display +device and must redirect the image cursor. +Two choices are available. +.IP [1] +The image cursor can be directed to accept commands from +the standard input. This is the default setup under IRAF version 2.6. +This setup can be checked by typing the following command. + +.nf + \f(CWcl> show stdimcur + text\fR +.fi + +If the value of \fBstdimcur\fR is not "text" the user can set this value by +typing the following. + +.nf + \f(CWcl> set stdimcur = text\fR +.fi + +Each time the cursor is to be read the user will be prompted for image +cursor mode text input. The form and syntax of this command are +described in detail in section 7.3. +.IP [2] +Alternatively a contour plot of the image can be used in place of the +image display and APPHOT tasks can be directed to read the graphics cursor. +To direct the image cursor to the graphics device the user types + +.nf + \f(CWcl> set stdimcur = stdgraph\fR +.fi + +This usage permits interactive use of the APPHOT package for users with graphics +terminals but no image display. This setup is most suitable for terminals +which permit the text and graphics planes to be displayed simultaneously. +.RS +.LP +It is currently the responsibility of the user to ensure that the image +displayed on the image display is the same as the image operated on by +the APPHOT tasks. +.RE + +.NH +Loading the Apphot Package +.PP +At this point the user has the local environment set up and is ready to +load the APPHOT package. APPHOT resides in the DIGIPHOT package (IRAF +version 2.8 and later) under the NOAO suite of packages. +Assuming +that the NOAO package is already loaded the user types the following. + +.nf + \f(CWcl> digiphot + cl> apphot\fR +.fi + +APPHOT can also be an add-on package (IRAF version 2.7 and earlier) +installed under the +LOCAL package. In this case the user types. + +.nf + \f(CWcl> local + cl> apphot\fR +.fi + +The following menu of tasks is displayed. + +.nf +\f(CW + apselect daofind fitsky photpars@ polyphot wphot + center datapars@ fitskypars@ polymark qphot + centerpars@ fitpsf phot polypars@ radprof +\fR +.fi + +The APPHOT package is now loaded and ready to run. +A quick one line description of each APPHOT task can be obtained by typing +the following command. + +.nf + \f(CWap> help apphot\fR +.fi + +The following text appears. +.KS +.nf +\f(CW +digiphot.apphot: + apselect - Extract select fields from apphot output files + center - Compute accurate centers for a list of objects + centerpars - Edit the centering parameters + daofind - Find stars in an image using the DAO algorithm + datapars - Edit the data dependent parameters + fitpsf - Model the stellar psf with an analytic function + fitsky - Compute sky values in a list of annular or circular + regions + fitskypars - Edit the sky fitting parameters + phot - Measure magnitudes for a list of stars + photpars - Edit the photometry parameters + polymark - Create polygon and coordinate lists for polyphot + polyphot - Measure magnitudes inside a list of polygonal regions + polypars - Edit the polyphot parameters + qphot - Measure quick magnitudes for a list of stars + radprof - Compute the stellar radial profile of a list of stars + wphot - Measure magnitudes with weighting +\fR +.fi +.KE +For the remainder of this document +we will use the principal APPHOT task \fBphot\fR as an example of how to +setup the parameters in both interactive and batch mode. +To get detailed help on the phot task the user types the following. + +.nf + \f(CWcl> help phot | lprint\fR +.fi + +The help page(s) for the \fBphot\fR task will appear on the local default +printer. + +.NH +Setting the APPHOT Photometry Task Parameters +.PP +The principal APPHOT task PHOT is described in sections 5.1 to 5.6. The +quick photometry task QPHOT is described in section 5.7 and the +polygonal aperture photometry task POLYPHOT is described in section +5.8. +.NH 2 +The Task Parameters +.PP +The \fBphot\fR task parameter set specifies the required image, coordinate +and output files, the graphics and display devices, the graphics and image +cursor and the mode of use of the task, interactive or batch. To enter +and edit the parameter set for the \fBphot\fR task the user types the +following. + +.nf + \f(CWcl> epar phot\fR +.fi + +The parameter set for the \fBphot\fR task will appear on the terminal ready +for editing as follows. + +.nf +\f(CW + IRAF + Image Reduction and Analysis Facility + + PACKAGE = apphot + TASK = phot + + image = Input image + (datapar= ) Data dependent parameters + (centerp= ) Centering parameters + (fitskyp= ) Sky fitting parameters + (photpar= ) Photometry parameters + (coords = ) Coordinate list + skyfile = Sky file + (output = default) Results file + (plotfil= ) File of plot metacode + (graphic= stdgraph) Graphics device + (display= stdimage) Display device + (command= ) Image cursor: [x y wcs] key [cmd] + (cursor = ) Graphics cursor: [x y wcs] key [cmd] + (radplot= no) Plot the radial profiles + (interac= yes) Mode of use + (verify = yes) Verify critical parameters in non + interactive mode + (verbose= no) Print messages in non interactive mode + (mode = ql) +\fR +.fi + +The \fBphot\fR parameters can be edited in the usual fashion by successively +moving +the cursor to the line opposite the parameter name, entering the new value, +followed by a carriage return, and finally typing a ^Z to exit the +\fBepar\fR task and update the parameters. +Some general points about the task +parameter sets are summarized below. For more detailed descriptions of each +parameter see the help pages for each task. +.IP [1] +\fBImage\fR specifies the list of input image(s) containing the +stars to be measured. \fBImage\fR may be a list of images, an image +template or a file containing a list of images. +For example if we wish to measure stars in three images: m31U, m31B and +m31V we could specify the \fBimage\fR parameter in the following three ways. + +.nf +\f(CW + image = m31B,m31U,m31V Input image + or + image = m31*.imh Input image + or + image = @imlist Input image +\fR +.fi + +"Imlist" is the name of a text file containing the list of images +one image name per line. The image list file can easily be created with the cl +package \fBfiles\fR task or the editor. +.IP [2] +Four parameter sets, henceforth psets, \fBdatapars\fR, \fBcenterpars\fR, +\fBfitskypars\fR and \fBphotpars\fR specify the algorithm parameters. +They are described in detail in later sections. +.IP [3] +\fBCoords\fR specifies the name of the coordinate file(s) containing the +initial positions of the stars to be measured. If \fBcoords\fR = "", +the current image cursor position is read and used as the initial position. +The number of files specified by +\fBcoords\fR must be either one, in which +case the same coordinate file is used for all the images, or equal in +number to the set of input images. +\fBCoords\fR can be a list of files, a file name template, +or a file +containing the list of x and y coordinates one per line. +For example if we have three coordinate files "m31B.coo", "m31U.coo" and +"m31V.coo" for the three images listed above, we could set the \fBcoords\fR +parameter in the following three ways. + +.nf +\f(CW + (coords = m31B.coo,m31U.coo,m31V.coo) Coordinate list + or + (coords = m31*.coo) Coordinate list + or + (coords = @coordlist) Coordinate list +\fR +.fi + +"Coordlist" is the name of a text file containing the names of the coordinate +files in the desired order one per line. +.IP [4] +\fBOutput\fR specifies the name of the results file(s). If \fBoutput\fR = +"default" then a single output file is created for +each input image and the root of the output file name is the name of the +input image. In the case of the above example \fBphot\fR would create three +output files called "m31B.mag.1", "m31U.mag.1" and "m31V.mag.1" assuming +that this was the initial run of \fBphot\fR on these images. +If the user sets the \fBoutput\fR parameter then the number of output files +must be either one or equal to the number of input images. For example the +user could set \fBoutput\fR to either + +.nf +\f(CW + (output = m31.out) Results + or + (output = m31b.out,m31u.out,m31v.out) Results +\fR +.fi + +If the user sets \fBoutput\fR = "" then no output file is written. +.IP [5] +The parameters \fBgraphics\fR and \fBdisplay\fR specify the graphics and +image display devices. In IRAF version 2.6 and later the APPHOT tasks +which reference these parameters will in interactive mode issue a warning +if they cannot open either of these devices +and continue execution. In IRAF version 2.5 the \fBdisplay\fR parameter must +be set to "stdgraph" as listed below + +.nf +\f(CW + (display= stdgraph) Display device +\fR +.fi + +or the following system error will be generated. + +.nf +\f(CW + "cannot execute connected subprocess x_stdimage.e" +\fR +.fi +Most of the APPHOT tasks use IRAF graphics in interactive mode to allow +users to set up their parameters and /or examine their results using radial +profile plots. The \fBgraphics\fR specifies which graphics device these plots +will be written to. Similarly most IRAF tasks permit the user to optionally +mark the star positions, apertures and sky annuli on the display device. +The parameter \fBdisplay\fR specifies which image display device this +information will be written to. Currently IRAF does not support an image display +kernel so the display marking features of APPHOT are not available unless +the user chooses to run APPHOT interactively from a contour plot. +.IP [6] +If \fBplotfile\fR is not equal to "", then for each star written to +\fBoutput\fR +a radial profile plot is written to the plot metacode file \fBplotfile\fR. +The \fBplotfile\fR is opened in append mode and succeeding executions +of \fBphot\fR write to the end of the same file which may in the process +become very large. +\fIThe user should be aware that writing radial profile plots +to \fBplotfile\fI can significantly slow the execution of \fBphot\fR. +The variable \fBradplots\fR enables radial profile plotting in interactive mode. +For each star measured a radial profile plot displaying the answers is +plotted on the screen. +.IP [7] +The \fBinteractive\fR parameter switches the task between interactive +and batch mode. +In interactive mode plots and text are written to the terminal as well as the +output file and the user can show and set the parameters. In batch mode +\fBphot\fR executes silently. +.IP [8] +The \fBverify\fP parameter allows the user to verify the critical task +parameters in non interactive mode. It is normally set to yes but +should be turned off when submitting jobs to background. +.IP [9] +The \fBverbose\fP switch permits the printing of results to the standard +output in non interactive mode. It is normally turned off. + +.NH 2 +APPHOT Psets +.PP +APPHOT algorithm parameters have been gathered together into logical +groups and stored in parameter files. The use of psets permits the +user to store APPHOT parameters with their relevant datasets rather than +in the uparm directory and allows APPHOT tasks to share common parameter +sets. APPHOT presently supports 5 pset files: 1) \fBdatapars\fR which contains +the data dependent parameter 2) \fBcenterpars\fR which contains the +centering algorithm parameters 3) \fBfitskypars\fR which contains the +sky fitting +algorithm parameters 4) \fBphotpars\fR which contains the multiaperture +photometry parameters and 5) \fBpolypars\fR which contains the polygonal +aperture +photometry parameters. The user should consult the manual page for each +of the named pset files as well as the attached parameter set document, +\fIExternal Parameter Sets in the CL and Related Revisions\fR, by Doug Tody. +.PP +The default mode of running APPHOT is to edit and store the pset parameter +files in the uparm directory. For example to edit the +\fBdatapars\fR parameter set, the user types either + +.nf + \f(CWcl> epar datapars\fR + or + \f(CWcl> datapars\fR +.fi + +and edits the file as usual. All the top level tasks which reference this +pset will pick up the changes from the uparm directory, assuming +datapars = "". +.PP +Alternatively the user can edit the \fBphot\fR +task and its psets all at once as follows using \fBepar\fR. + +.nf + \f(CWcl> epar phot\fR +.fi + +Move the cursor to the \fBdatapars\fR parameter line and type \fB:e\fR. +The menu for the +\fBdatapars\fR pset will appear and is ready for editing. Edit the desired +parameters and type \fB:q\fR. \fBEpar\fR will return to the main +\fBphot\fR parameter set. +Follow the same procedure for the other three psets +\fBcenterpars\fR, \fBfitskypars\fR and \fBphotpars\fR and exit the program +in the usual manner. +.PP +Sometimes it is desirable to store a given pset along with the data. +This provides a facility for keeping many different copies of say the +\fBdatapars\fR pset with the data. +The example below shows how to write a pset out to a file in the same directory +as the data. The user types + +.nf + \f(CWcl> epar phot\fR +.fi + +as before, enters the datapars menu with \f(CW:e\fR and edits the parameters. +The command + +.nf + \f(CW:w data1.par\fR +.fi + +writes the parameter set to a file called "data1.par" and a \fB:q\fR +returns to the main task menu. +A file called "data1.par" containing the new \fBdatapars\fR parameters +will be written in the current directory. At this point the user is in the +\fBphot\fR parameter set at the line opposite \fBdatapars\fR and +enters "data1.par" on the line opposite this parameter. +The next time \fBphot\fR is run the parameters will +be read from "data1.par" not from the pset in the uparm directory. +This procedure can be repeated for each data set which has distinct parameters, +as in for example data taken on separate nights. + +.NH 2 +Datapars +.PP +All the data dependent parameters have been gathered together in one +pset \fBdatapars\fR. The idea behind this organization is to facilitate +setting up the algorithm +psets for data taken under different conditions. For example the +user may have determined the optimal centering box size, sky annulus radius +and width and aperture radii in terms of the current \fBfwhmpsf\fR and the +rejection criteria in terms of the current background standard deviation +\fBsigma\fR. In order to use the same setup on +the next image the user need only reset the \fBscale\fR and background +\fBsigma\fR parameters to the new values. +The only pset which need be edited is \fBdatapars\fR. +.PP +To examine and edit the \fBdatapars\fR pset type + +.nf + \f(CWap> datapars\fR +.fi + +and the following menu will appear on the screen. + +.nf +\f(CW + IRAF + Image Reduction and Analysis Facility + + PACKAGE = apphot + TASK = datapars + + (fwhmpsf= 1.) FWHM of the PSF in scale units + (emissio= yes) Features are positive + (noise = poisson) Noise model + (thresho= 0.) Detection threshold in counts above + background + (cthresh= 0.) Centering threshold in counts above + background + (sigma = INDEF) Standard deviation of background in counts + (scale = 1.) Image scale in units per pixel + (ccdread= ) CCD readout noise image header keyword + (readnoi= INDEF) CCD readout noise in electrons + (gain = ) CCD gain image header keyword + (epadu = 1.) Gain in electrons per count + (exposur= ) Exposure time image header keyword + (itime = INDEF) Integration time + (datamin= INDEF) Minimum good data pixel + (datamax= INDEF) Maximum good data pixel + (mode = ql) + ($nargs = 0) +\fR +.fi + +.PP +The following is a brief description of the parameters and their function +as well as some initial setup recommendations. + +.PP +\fBScale\fP is the image scale parameter in units per pixel, for example +arc-seconds per pixel. All distance dependent parameters in the APPHOT package +including the centering box width \fBcbox\fP in \fBcenterpars\fP, the +inner radius and width of the sky annulus, \fBannulus\fP and +\fBdannulus\fP in \fBfitskypars\fP, and the radii of the concentric +circular apertures \fBapertures\fP in \fBphotpars\fP are defined +in scale units, for example arc seconds. This permits easy comparison +with apertures published in the literature. Some other algorithm +parameters such as \fBmaxshift\fP in \fBcenterpars\fP and the region +growing radius \fBrgrow\fP in +\fBfitskypars\fP are also defined in scale units. By default all +distance parameters are defined in pixels. +.PP +\fBFwhmpsf\fP is used as a first guess for modelling the psf in the +\fBfitpsf\fP task, is important for the optimal use of the \fBdaofind\fP +algorithm, and critical for the centering algorithms "gauss" and +"ofilter" as well as the \fBwphot\fP task. +\fBFwhmpsf\fR as well as the other distance dependent parameters +can be set interactively from inside most of the APPHOT tasks. +.PP +\fBFwhmpsf\fP and \fBscale\fP can be combined in an interesting way. +\fBScale\fP can be defined in units of half width half maximum of the psf per +pixel in which case the value of \fBfwhmpsf\fP should be set to +\fB2.0\fP by definition. By trial and error and use of the interactive +setup menu optimal values of the remaining distance dependent parameters +can be determined in units of \fBscale\fP. Once determined the same +setup can be reused on another image by simply reseting the \fBscale\fP +parameter. +.PP +APPHOT photometry routines permit measurement of both emission and absorption +features. For the majority of applications including photometry of +stars and galaxies +all "objects" are emission "objects" and the \fBemission\fR parameter should +be left at yes. +.PP +APPHOT currently supports two noise models "constant" and "poisson". +If \fBnoise\fR = "constant" the magnitude errors are computed from the +Poisson noise in the sky background plus the readout noise. +If \fBnoise\fR = "poisson" +the magnitude errors are computed on the basis of the Poisson noise in the +constant sky background, Poisson noise in the object and readout noise. +Most users +with CCD data will wish to leave \fBnoise\fR = "poisson". +\fBCthreshold\fR is a parameter required by the centering algorithms. +If \fBcthreshold\fR > 0.0, pixels below the data minimum plus +threshold in the centering subraster are not used by the centering algorithm. +For difficult centering problems the user may wish to adjust +this parameter. +The \fBsigma\fR parameter specifies the standard deviation of the background +in a single pixel. \fBSigma\fR is used +to estimate the signal to noise ratio in the centering subraster and to set +the width and bin size of the histogram of sky pixels, the \fBkhist\fR and +\fBbinsize\fR parameters in the pset \fBfitskypars\fR. Both \fBcthreshold\fR and +\fBsigma\fR can be set interactively from inside the \fBphot\fR task. +.PP +APPHOT currently recognizes three image header keywords \fBccdread\fR, +\fBgain\fR and \fBexposure\fR. Knowledge of the instrument gain and +readout noise is required for the correct computation of the magnitude +errors but not required for the magnitude computation. The units of +the gain and readout noise are assumed to be electrons per adu +and electrons respectively. +Exposure time information is required to normalize the magnitudes computed +for a series of images to a common exposure time. +The time units are arbitrary but must be consistent for a set of images. +If this information is already in the +image header the user can enter the appropriate header keywords. +Otherwise the instrument constants gain and readout noise can be entered +into the parameters \fBepadu\fR and \fBreadnoise\fR. +If the exposure time information is not present in the image header, the +user can either edit it in with the \fBhedit\fR task or change the \fBitime\fR +parameter for each image reduced. If both image header keywords and +default parameter values are defined the image header keywords take +precedence. +.PP +The two parameters \fBdatamin\fP and \fBdatamax\fP which define the upper +and lower good data limits respectively are not currently implemented by +the APPHOT tasks. They will be used in future versions of the package +to, for example, set the limits over which a detector is linear. +.PP +After editing, the new \fBdatapars\fR pset might look like the following. +This user has chosen to wait and set \fBfwhmpsf\fR, \fBthreshold\fR, +\fBcthreshold\fR, and \fBsigma\fR interactively from inside \fBphot\fR but +has decided to set the +image header parameters \fBccdread\fR, \fBgain\fR and \fBexposure\fR. + +.nf +\f(CW + IRAF + Image Reduction and Analysis Facility + + PACKAGE = apphot + TASK = datapars + + (fwhmpsf= 1.) FWHM of the PSF in scale units + (emissio= yes) Features are positive + (noise = poisson) Noise model + (thresho= 0.) Detection threshold in counts above + background + (cthresh= 0.) Centering threshold in counts above + background + (sigma = INDEF) Standard deviation of background in counts + (scale = 1.) Image scale in units per pixel + (ccdread= readout) CCD readout noise image header keyword + (readnoi= INDEF) CCD readout noise in electrons + (gain = gain) CCD gain image header keyword + (epadu = 1.) Gain in electrons per count + (exposur= exptime) Exposure time image header keyword + (itime = INDEF) Integration time + (datamin= INDEF) Minimum good data pixel + (datamax= INDEF) Maximum good data pixel + (mode = ql) + ($nargs = 0) +\fR +.fi + +.NH 2 +The Centering Parameters +.PP +The centering algorithm parameters have been grouped together in a single +parameter set \fBcenterpars\fR. To display and edit these parameters type +the command. + +.nf + \f(CWap> centerpars\fR +.fi + +The following menu will appear on the terminal. + +.nf +\f(CW + IRAF + Image Reduction and Analysis Facility + + PACKAGE = apphot + TASK = centerpars + + (calgori= centroid) Centering algorithm + (cbox = 5.) Centering box width in scale units + (maxshif= 1.) Maximum center shift in scale units + (minsnra= 1.) Minimum SNR ratio for centering + (cmaxite= 10) Maximum iterations for centering algorithm + (clean = no) Symmetry clean before centering + (rclean = 1.) Cleaning radius in scale units + (rclip = 2.) Clipping radius in scale units + (kclean = 3.) K-sigma rejection criterion in skysigma + (mkcente= no) Mark the computed center + (mode = ql) + ($nargs = 0) +\fR +.fi + +.PP +APPHOT offers three choices for the centering algorithm: +the default "centroid", "gauss" and "ofilter". +The default centering algorithm does not depend on \fBfwhmpsf\fR but the +remaining two do. For reasons of simplicity and efficiency the author +recommends the default algorithm. In cases where there is significant +crowding or the data is very noisy users may wish to experiment with +the other algorithms. Centering can be disabled by setting +\fBcalgorithm\fR = "none". This option is useful if accurate centers +have already been computed with the \fBdaofind\fR or \fBfitpsf\fR +tasks. More detailed information on the APPHOT centering algorithms +can be found in the document, \fISpecifications for the Apphot Package\fR +by Lindsey Davis. +.PP +The centering box \fBcbox\fR is defined in units of \fBscale\fR. +Users should try to set \fBcbox\fR as small as possible to avoid +adding noisy pixels to the centering subraster. +\fBCbox\fR can also be set interactively from inside the APPHOT \fBphot\fR +task. +.PP +If the computed centers are more than \fBmaxshift\fR / \fBscale\fR pixels +from the initial centers or the signal-to-noise ratio in the centering +subraster is less than \fBminsnratio\fR the new center will be computed but +flagged with a warning message. +.PP +For stars which are crowded or contaminated by bad pixels the user may +wish to enable the cleaning algorithm by setting \fBclean\fR = yes. +Its use is complicated and not recommended for most data. The algorithm is +described in the APPHOT specifications document. +.PP +If \fBmkcenter\fR=yes, \fBphot\fR tasks will mark the initial +and final centers and draw a line between them on the default display +device. At present this option only works if \fBdisplay\fR="stdgraph". +.PP +In the above example we have elected to leave the \fBcalgorithm\fR parameter +at its default value and set \fBcbox\fR interactively from inside the \fBphot\fR +task. + + +.NH 2 +The Sky Fitting Parameters +.PP +The sky fitting algorithm parameters have been grouped together in a single +parameter set \fBfitskypars\fR. To display and edit these parameters type +the following command. + +.nf + \f(CWap> fitskypars\fR +.fi + +The following menu will appear on the terminal. + +.nf +\f(CW + IRAF + Image Reduction and Analysis Facility + + PACKAGE = apphot + TASK = fitskypars + + (salgori= mode) Sky fitting algorithm + (annulus= 10.) Inner radius of sky annulus in scale units + (dannulu= 10.) Width of sky annulus in scale units + (skyvalu= 0.) User sky value + (smaxite= 10) Maximum number of sky fitting iterations + (snrejec= 50) Maximum number of sky fitting rejection + iterations + (skrejec= 3.) K-sigma rejection limit in sky sigma + (khist = 3.) Half width of histogram in sky sigma + (binsize= 0.1) Binsize of histogram in sky sigma + (smooth = no) Lucy smooth the histogram + (rgrow = 0.) Region growing radius in scale units + (mksky = no) Mark sky annuli on the display + (mode = ql) + ($nargs = 0) +\fR +.fi + +.PP +APPHOT offers ten sky fitting algorithms. The algorithms can be grouped +into 4 categories 1) user supplied sky values including "constant" and "file" +2) sky pixel distribution algorithms including "median" and "mode", +3) sky pixel histogram algorithms including "centroid", "crosscor", +"gauss" and "ofilter" 4) interactive algorithms including "radplot" +and "histplot". +The definitions of the mode used by APPHOT is the following. + +.nf +\f(CW mode = 3.0 * median - 2.0 * mean\fP +.fi + +Detailed descriptions of the algorithms can be found in the document, +\fISpecifications for the Apphot Package\fR by the author. The author recommends +"mode" the default, and one of the two histogram algorithms "centroid" and +"crosscor". +.PP +The inner radius and width of the sky annulus in terms of \fBscale\fR +are set by the parameters \fBannulus\fR and \fBdannulus\fR. These can +easily be set interactively from within the \fBphot\fR task. +Good statistics require several hundred sky pixels. +The user should be aware that a circular sky region can be defined by +setting \fBannulus\fR to 0. +.PP +The user should ensure that the parameter \fBsigma\fR in the +\fBdatapars\fR parameter set is defined if one of the histogram dependent +sky fitting algorithms is selected. +The extent and resolution of the sky pixel histogram is determined +by \fBkhist\fR and \fBbinsize\fR and their relation to \fBsigma\fR. +If \fBsigma\fR is undefined then the standard deviation of the local +sky background is used to parameterise \fBkhist\fR and \fBbinsize\fR +and the histograms of different stars can deviate widely in resolution. +.PP +The sky rejection algorithms are controlled by the parameters \fBskreject\fR, +\fBsnreject\fR and \fBrgrow\fR. It is strongly recommended that the user +leave pixel rejection enabled. The user should experiment with the region +growing radius if the local sky regions are severely crowded. +.PP +If \fBmksky\fR = yes, \fBphot\fR will mark the inner +and outer sky annuli. At present this option +will only work if \fBdisplay\fR = "stdgraph". + +.NH 2 +The Photometry Parameters +.PP +The photometry algorithm parameters have been grouped together in a single +parameter set \fBphotpars\fR. To display and edit these parameters type. + +.nf + \f(CWap> photpars\fR +.fi + +The following menu will appear on the terminal. + +.nf +\f(CW + IRAF + Image Reduction and Analysis Facility + + PACKAGE = apphot + TASK = photpars + + (weighti= constant) Photometric weighting scheme for wphot + (apertur= 3.) List of aperture radii in scale units + (zmag = 26.) Zero point of magnitude scale + (mkapert= no) Draw apertures on the display + (mode = ql) + ($nargs = 0) +\fR +.fi + +.PP +There are three weighting options inside APPHOT. The default is "constant". +Inside the \fBphot\fR, \fBradprof\fR and \fBpolyphot\fR tasks only constant +weighting is used. Two other weighting schemes are available for the +experimental \fBwphot\fR task, "gauss" and "cone". "Gauss" is the more +highly recommended. +.PP +The aperture list is specified by \fBapert\fR in terms of \fBscale\fR. +The apertures can be entered in any order but are sorted on output. +\fBApert\fR can be string or the name of a text file containing the +list of apertures. Apertures can either be listed individually and +separated by whitespace or commas or a ranges notation of the +form apstart:apend:apstep can be used. +These can be set interactively from within the \fBphot\fR task. +.PP +Examples of valid aperture strings are listed below. + +.nf +\f(CW + 1 2 3 + 1.0,2.0,3.0 + 1:10:1 +\fR +.fi + +.PP +An arbitrary zero point is applied to the magnitude scale with \fBzmag\fR. +The user can accept the default or experiment with his/her data until +a suitable value is found. The computation of the magnitude errors +does not depend on the zero point. +.PP +If \fBmkapert\fR = yes, the \fBphot\fR task will draw the concentric +apertures on the display. At present this option +works only if \fBdisplay\fR = "stdgraph". + +.NH 2 +The QPHOT Task +.PP +\fBQphot\fP computes accurate centers, sky values and magnitudes for a list +of objects using a restricted subset of the full \fBphot\fP parameter set. +It is intended to be a quick look photometer suitable for use when +observing on the mountain or in well behaved uncrowded stellar fields. +.PP +The user is automatically queried for the critical parameters \fBcbox\fP, +\fBannulus\fP, \fBdannulus\fP and \fBapertures\fP which are defined in +terms of pixels. The noise characteristics of the detector are assumed +to obey Poisson statistics. \fBQphot\fP computes centers for each +object using the "centroid" centering algorithm. Sky values are +calculated using the "mode" algorithm. The user can set the zero point +of the magnitude scale, \fBzmag\fP, the gain of the detector, \fBepadu\fP, +and exposure time image header keyword, \fBexposure\fP, but all the +remaining parameters are set to their default values. +.PP +\fBQphot\fP can be driven by the image cursor or a coordinate list in +interactive mode or by a coordinate list in batch mode in exactly +the same manner as the \fBphot\fP task. + +.NH 2 +The \fBPOLYPHOT\fP Task +.PP +\fBPolyphot\fP computes accurate centers, sky values and magnitudes for +a list of objects using polygonal shaped apertures. It is most suitable +for measuring the magnitudes of large extended irregularly shaped objects. +.PP +\fBPolyphot\fP uses \fBdatapars\fP, \fBcenterpars\fP, and +\fBfitskypars\fP in exactly the same manner as the \fBphot\fP task. In +general users should set the task parameters in the same way as they +set them in \fBphot\fP. However users who have defined their polygonal +apertures interactively may wish to set the centering algorithm +parameter \fBcalgorithm =\fP "none", to avoid the task trying to center +on the brightest feature in the aperture. +.PP +The apertures are defined either interactively with the image or graphics +cursor or by two files \fBpolygons\fP and \fBcoords\fP. +Polygons defines the shape of the polygonal aperture and coords defines the +initial positions of the apertures. The polygons file may contain +more than one aperture and the flux through each aperture may be measured +at more than one position. A detailed description of the file formats +is given in section 6.4 + +.NH +Creating A Coordinate List +.PP +All APPHOT tasks operate on either lists of object coordinates or +interactive cursor +input. Lists are maintained as text files, one object per line with the x +and y coordinates in columns one and two respectively. The coordinate and +polygon files required by the \fBpolyphot\fR task have a different +format which is described below. List files may be +created interactively with either the graphics or the image cursor, by a +previously executed APPHOT task, by a previously executed IRAF task or by +a user program. Various means of creating coordinate lists within IRAF +are described below. Comments preceded by a # character and blank lines +are ignored. + +.nf +\f(CW + #Sample Coordinate List + 53.6 83.25 + 100.0 35.8 + 2.134 86.89 + .... .... +\fR +.fi + +.NH 2 +Daofind +.PP +\fBDaofind\fR is an APPHOT task which detects stellar objects in an image +automatically. The user sets the \fBfwhmpsf\fR of the psf for which the +detection algorithm is to be +optimized as well as an intensity threshold for detection. \fBDaofind\fR +locates all the qualifying stars and writes their positions, rough magnitudes +and shape characteristics to a file. This file can then be assigned to +the \fBphot\fR task \fBcoords\fR parameter and read directly. +.PP +For example if we have an image containing stars for which the \fBfwhmpsf\fR +is 4.0 pixels and the sigma of the sky background is 10 we might run +\fBdaofind\fR as follows, + +.nf + \f(CWcl> daofind image fwhmpsf=4.0 threshold=30.0\fR +.fi + +where we have set our detection threshold at 3.0 * sigma. + +.NH 2 +Imtool On the SUN Machines +.PP +The SUN IRAF \fBimtool\fR facility supports both image world coordinate +systems and output coordinate files. Coordinate lists can be created +interactively by the users in the following way. +.PP +Display the IRAF image in the imtool window using the \fBdisplay\fR task. +Move the mouse to the top of the \fBimtool\fR window, press the right mouse +button to enter the \fBimtool\fR menu, move the mouse to the setup option and +release the mouse button. Press +the return key until the black triangle is opposite the coordinate list file +name parameter. +Delete the default file name, enter the full host system path name of the +desired coordinate file and press return. This name should now appear at +the top of the imtool window. +Move the mouse to the quit option and press the left mouse button to +quit the setup window. +.PP +To enter the \fBimtool\fR cursor readout mode type the \fBF6\fR key. +The x, y and intensity values at the cursor position +are displayed in the lower right corner of the image. +To mark stars and output their coordinates to the coordinate file, move +the image cursor a star and press the left mouse button. A sequence number +will appear on the display next to the marked position. The numbers can +be changed from black to white and vice versa by toggling the \fBF5\fR key. +The coordinate files are opened in append mode in order that stars may be +added to an already existing list. \fBImtool\fR coordinate files are directly +readable by all APPHOT tasks. + +.NH 2 +Rgcursor and Rimcursor +.PP +The LISTS package tasks \fBrgcursor\fR and \fBrimcursor\fR can be used to +generate coordinate lists interactively. For example a coordinate +list can be created interactively using the display cursor and +the image display. + +.nf +\f(CW + cl> display image + + ... image appears on the display ... + + cl> rimcursor > image.coo + + ... move display cursor to stars of interest and tape space bar ... + + ... type ^Z to terminate the list ... +\fR +.fi + +Similarly a coordinate list +can be created using the graphics cursor and a contour +plot as shown below. + +.nf +\f(CW + cl> contour image + + ... contour plot appears on the terminal ... + + cl> rgcursor > image.coo + + ... move cursor to stars of interest and tap space bar ... + + ... type ^Z to terminate the list ... +\fR +.fi + +The text file "image.coo" contains the x and y coordinates of the marked stars +in image pixel units. The output of \fBrimcursor\fR or \fBrgcursor\fR can +be read directly by the APPHOT \fBphot\fR task. +\fBRimcursor\fR is only available in IRAF versions 2.7 and later and +only for selected devices. + +.NH 2 +The Polygon List +.PP +A utility routine \fBpolymark\fR has been added to the APPHOT package to +generate polygon and initial center lists for the \fBpolyphot\fR task. +The format of the polygon files is 1 vertex per line with the +x and y coordinates of the vertex in columns 1 and 2 respectively. +A line containing the single character ';' terminates the lists of vertices. +There can be more than one polygon in a single polygon file. + +.nf +\f(CW + Sample Polygon File + + 1.0 1.0 + 1.0 51.0 + 51.0 51.0 + 51.0 1.0 + ; + 80.0 80.0 + 80.0 131.0 + 131.0 131.0 + 131.0 80.0 + ; +\fR +.fi + +.PP +The accompanying coordinate file is optional. If no coordinate file is given +the initial center for the polygon is the mean of its vertices in the +polygon file. If a +coordinate file is specified the initial center for the polygon is the +position in the coordinate file. Each polygonal aperture may be moved +to several positions. + +.nf +\f(CW + Sample Polyphot Coords File + + 50. 30. + 80. 100. + 60. 33. + ; + 90. 50. + 55. 90. + 12. 122. + ; +\fR +.fi + +For example all the coordinates in group 1 will be measured using the +aperture defined by polygon 1 and all the coordinates +in group 2 will be measured with the aperture defined by polygon 2. + +.NH 2 +User Program +.PP +Obviously any user program which produces a text file with the coordinates +listed 1 per line with x and y in columns 1 and 2 can be used to produce +APPHOT coordinate files. + +.NH 2 +Modifying an Existing Coordinate List +.PP +The LISTS package routine \fBlintran\fR has been linked into the APPHOT +package. It can be used to perform simple coordinate transformations on +coordinate lists including shifts, magnifications, and rotations. + +.NH +Running Apphot in Interactive Mode Without a Coordinate List +.PP +There are currently three ways to run the \fBphot\fR interactively without +a coordinate list: +1) read image display cursor commands 2) read +graphics cursor commands 3) read commands +from the standard input. The three methods are briefly discussed below. +Detailed examples of all three methods of operation can be found in +the manual pages for each task. + +.NH 2 +Reading Image Cursor Commands +.PP +The default method of running APPHOT. The user loads an image onto +the display, types \fBphot\fR and enters the image name. The image cursor +appears on the display and the program is ready to accept user commands. +This option is not available under IRAF version 2.6 and earlier +because interactive image cursor readback was not available. + +.NH 2 +Redirecting the Image Cursor to the Graphics Cursor +.PP +\fBPhot\fR reads the graphics cursor and executes various keystroke +commands. The environment variable \fBstdimcur\fR must be set to "stdgraph". +For full access +to all the graphics commands the parameter \fBdisplay\fR must also be set +to "stdgraph". +The user creates a contour plot of the image on the graphics terminal +with the \fBcontour\fR task, types \fBphot\fR and answers the image name query. +The graphics cursor appears on the contour plot ready for input. +The user can move around the plot with the cursor successively marking stars. + +.NH 2 +Redirecting the Image Cursor to the Standard Input +.PP +The user can enter cursor commands directly on the standard input. +The environment variable \fBstdimcur\fR must be set to "text". +When the user types the task name \fBphot\fR and enters the image +name, the following prompt appears. + +.nf + \f(CWImage cursor [xcoord ycoord wcs] key [cmd]:\fR +.fi + +\fIXcoord\fR and \fIycoord\fR are the coordinates of the object of +interest, \fIwcs\fR is the current world coordinate system, always 1, +\fIkey\fR is a single +character and \fIcmd\fR is an APPHOT task command. +To perform the default action of +the \fBphot\fR task the user responds as follows. + +.nf + \f(CWImage cursor [xcoord ycoord wcs] key [cmd]: 36. 42. 1\fR +.fi + +\fBPhot\fR measures the magnitude of the star near pixel coordinates +x,y = (36.,42.) and writes the result to the output file. +In IRAF version 2.5 all the cursor command fields must be typed. +The square brackets +indicate those fields which are optional under IRAF version 2.6 and later. +Users with SUN +workstations may wish to combine the IMTOOL coordinate list cursor readback +facilities which generate coordinate lists with this mode of running APPHOT +interactively. + +.NH 2 +The Interactive Keystroke Commands +.PP +A conscious effort has been made to keep the definitions of all the +keystroke commands within the APPHOT package as similar as possible. +The following are the most commonly used keystrokes in the APPHOT package. + +.NH 3 +The ? (Help) Keystroke Command +.PP +The ? key prints the help page describing the cursor keystroke and colon +show commands for the specific APPHOT task. An abbreviated help page +is typed by default when a user enters a task in interactive mode. +The ? key can be typed at any point in the APPHOT task. + +.NH 3 +The :show (Set and Print parameter) Commands +.PP +Any APPHOT parameter can be displayed by typing :\fIparameter\fR command +in interactive mode. +For example to show the current value of the \fBfwhmpsf\fR parameter +type the following command. + +.nf + \f(CW:fwhmpsf\fR +.fi + +To set any APPHOT parameter type :\fIparameter\fR "value". For example +to set the \fBfwhmpsf\fR to 2.0 type. + +.nf + \f(CW:fwhmpsf 2.0\fR +.fi + +To display all the centering parameters type. + +.nf + \f(CW:show center\fR +.fi + +Similarly the sky fitting and photometry parameters can be displayed by +typing. + +.nf + \f(CW:show sky\fR + \f(CW:show phot\fR +.fi + +All the parameters can be displayed with the following command. + +.nf + \f(CW:show\fR +.fi + +.NH 3 +The i (Interactive Setup) Keystroke Command +.PP +This extremely useful key allows one to set up the principal APPHOT +parameters interactively. To use this feature move the image cursor to a star on +the display, or move the graphics cursor to a star on the contour plot +and tap the i key, +or enter the x and y coordinates, and the world coordinate system +of the star and the i key manually. The program will query the user for +the size of the extraction box and plot a radial profile of the star +on the terminal. The user sets the \fBfwhmpsf\fR, the centering +aperture \fBcbox\fR, the inner sky annulus \fBannulus\fR and \fBdannulus\fR, +the list of apertures \fBaperts\fR and the data \fBsigma\fR, +\fBthreshold\fR and \fBcthreshold\fR using the graphics cursor and the +radial profile plot. +The cursor comes up on the plot at the position of the appropriate parameter. +Typing return will preserve the old value. +If the cursor is outside the range of values on the plot the old value +is kept. +.PP +Setting \fBsigma\fP, \fBcthreshold\fP, and \fBthreshold\fP +interactively requires two keystrokes. In each case the measured parameter +is the difference between the two y coordinates of the graphics +cursor. It is recommended in general that the user leave \fBcthreshold\fP +at zero. + +.NH 3 +The v (Verify) Keystroke Command +.PP +The v key verifies that the values of the critical task parameters +currently in memory are the ones that the user wants. To each verify query +the user either types CR to verify the current value or enters a new +value. + +.NH 3 +The w (Write to Psets) Keystroke Command +.PP +The w key writes the current values of the parameters in memory to the +appropriate psets. +This feature is useful for saving values marked with the +i key. On exiting APPHOT a prompt will remind the user that the current +parameters in memory must be stored in the psets or lost. + +.NH 3 +The d (Radial Profile Plot) Keystroke Command +.PP +The d key plots a centered radial profile of a star on the graphics device. + +.NH 3 +The f (Fit) Keystroke Command +.PP +This key performs the default action of each APPHOT task without writing +any results +to the output file. In the \fBphot\fR task the f key will center, fit the +local sky and compute the magnitudes for a star. This key allows the user to +experiment interactively with the data, changing the default parameters, +remeasuring magnitudes and so on before actually writing out any data. + +.NH 3 +The Space Bar (Fit and Write out Results) Keystroke Command +.PP +This key performs the default action of the task and writes the results +to the output catalog. + +.NH +Running Apphot In Interactive Mode From A Coordinate List +.PP +This is currently the best method for running APPHOT interactively for users +without image cursor readback facilities. APPHOT tasks +can pick stars out of the list sequentially or by number, measure stars +sequentially or by number, rewind the coordinate lists and remeasure all +the stars. Stars which are not in the coordinate list can still be +measured and added to the output catalog. + +.IP [1] +The :m (Move) Keystroke Command +.RS +.LP +This command moves the cursor to the next or a specified star in the +coordinate list. If the hardware cursor on the +device being read from is enabled the actual physical cursor will move +to the requested star. For +example a user might decide that star # 10 in the coordinate list is the best +setup star. He/she simply types a :m 10 to move to the star in +question followed by the i key to setup the parameters interactively. +.RE + +.IP [2] +The :n (Next) Keystroke Command +.RS +.LP +This command moves to the next or specified star in the list, performs the +default action of the task and writes the results to the output file. +This key is particularly useful in examining the results of a large batch +run. +For example, a user measures the magnitudes of 500 stars using APPHOT in +batch mode. He/she is suspicious about the results for twenty of the most +crowded stars. By rerunning APPHOT in interactive mode using the original +coordinate list, the user can selectively call up the stars in question, +plot their radial profiles, and examine the results interactively. +.RE + +.IP [3] +The l (List) Keystroke Command +.RS +.LP +This command measures all the stars in the coordinate list sequentially from +the current position in the file. +.RE + +.IP [4] +The r (Rewind) Keystroke Command +.RS +.LP +This command rewinds the coordinate list. +.RE + +.NH +Running Apphot in Batch Mode +.PP +This is the simplest way to run APPHOT. Once the parameters are set and stored +in the pset files the program can be run in batch by setting the parameter +\fBinteractive\fR = no. The program will read the coordinate list +sequentially computing results for each star and writing them to the +output file. + +.NH +Apphot Output +.PP +APPHOT tasks write their output to text and/or plot files as well as to the +standard output and graphics terminals. + +.NH 2 +Text Files +.PP +All APPHOT records are written to text files. +The parameters for the task are listed at the beginning of each APPHOT +output text file and identified with a #K string. +The header record is not written until the record +for the first star is to be written to the database. Parameter changes will +generate a one line entry in the output text file. +The data records follow the header record in the order in which they +were computed. +If the output file parameter \fBoutput\fR = "" no output file is written. +This is the default action for the \fBradprof\fR task. +If \fBoutput\fR = "default", +the output file name is constructed using the image name. + +.NH 2 +Plot Files +.PP +Some APPHOT tasks can optionally produce graphics output. +These files are maintained as plot metacode and may contain many individual +plots. +A directory of plots in each metacode file can be obtained with +\fBgkidir\fR. Individual plots can be extracted with \fBgkiextract\fR and +combined and plotted with \fBgkimosaic\fR. + +.NH 2 +Running Apselect on Apphot Output Files +.PP +Individual fields can be extracted from the APPHOT output files using +the \fBapselect\fR task and a keyword and expression scheme. +For example the user may wish +to extract the x and y center coordinates, the sky value and the +magnitudes from the APPHOT \fBphot\fR catalog. Using apselect they +would type. + +.nf + \f(CWcl> apselect output xc,yc,msky,mag yes > magsfile\fR +.fi + +The selected fields would appear in the textfile "magsfile". + +.NH +Apphot Recipes +.PP +In the following section three APPHOT reduction sessions which illustrate +different methods of using the APPHOT package are described. In the +first example the user wishes to compute magnitudes for a large number +of stars in a single image. In the second example he/she wishes to +measure the magnitude of a single standard star in each of a long list of +images. Finally in the last example the user wishes to measure the +magnitude of an elliptical galaxy through a list of apertures. +Each example assumes that the user has started with the default set of +package parameters. + +.NH 2 +Infrared photometry of a Star Field in Orion +.PP +An observer has an IRAF image on disk of a star forming region in Orion taken +with the +IR CCD camera. The Orion image is a composite formed from 64 separate +IR images using the PROTO \fBirmosaic\fR and \fBiralign\fR tasks. +The Orion image contains about 400 stars but is only moderately crowded. The +observer decides to use the APPHOT package to reduce his data. +.PP +The observer decides to run the \fBdaofind\fR routines to create a coordinate +list of stars, to run \fBphot\fR in interactive mode with the image cursor +directed to the standard input to setup and store the \fBphot\fR task +parameters and finally, to run \fBphot\fR in batch mode to do the photometry. +.PP +To create the coordinate list the user needs to supply the full width half +maximum of the pointspread function and an intensity threshold +above background to the +\fBdaofind\fR program. Using the PLOT package task \fBimplot\fR the user +examines several stars in the image and decides that the \fBfwhmpsf\fR +should be 3.0 +pixels and that the standard deviation of the background should be 10.0 +counts. +The user decides to include all stars with a peak intensity greater +than five standard deviations above local background in the coordinate list. +The user runs \fBdaofind\fR as follows. + +.nf + \f(CWap> daofind orion fwhmpsf=3.0 threshold=50.0\fR +.fi + +The x and y coordinates, a magnitude estimate and some statistics on image +sharpness and roundness are output to the file "orion.coo.1". +The user can obtain a printout of the coordinate +list by typing. + +.nf + \f(CWap> lprint orion.coo.1\fR +.fi + +.PP +Next the user decides to set up the parameters of the \fBphot\fR task. +Using the \fBepar\fR task he enters the phot task parameter menu, +types "orion" opposite the \fBimage\fR parameter and "orion.coo.1" +opposite the \fBcoords\fR parameter. Next he moves the cursor opposite +the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR +menu. He sets the gain parameter \fBepadu\fR to 5.0 electrons per adu +and the readout noise \fBreadnoise\fR to 5.0 electrons. He types \fB:q\fR to +quit and save the \fBdatapars\fR parameters and \fB^Z\fR to quit and save the +\fBphot\fR parameters. +.PP +Now the user is ready to enter the \fBphot\fR task in interactive mode to set +up the remaining data dependent parameters. The user types the following +sequence of commands in response to the cursor prompt. Note that the +example below assumes that the image cursor has been directed to the +standard input. The image cursor comes up on the screen in the form of +a prompt. This example could equally well be run from the image hardware +cursor in which case the cursor would appear on the displayed image. The +keystroke commands are identical in the two cases. + +.br + +.nf +\f(CW + ap> phot orion + + ... \fIload the phot task\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: ? + + ... \fIprint help page for phot task\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: :radplots yes + + ... \fIenable radial profile plotting\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: :m 10 + + ... \fImove to star 10 in the coordinate list\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: i + + ... \fIenter interactive setup mode using star 10\fR ... + + ... \fImark fwhmpsf, cbox, sky annulus, apertures on the plot\fR ... + + ... \fIleave sigma and cthreshold at their default values\fR ... + + ... \fIcheck answers on radial profile plot of the results\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: v + + ... \fIverify the critical parameters\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: :radplots no + + ... \fIdisable radial profile plotting\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: w + + ... \fIstore new parameters in the psets\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: q + + ... \fIquit interactive cursor loop\fR ... + + q + + ... \fIquit the phot task\fR ... + +\fR +.fi +.PP +The user decides he is happy with the current parameter set and decides +to run the \fBphot\fR task in batch and submit it as a background task. + +.nf + \f(CWap> phot orion inter- verify- &\fR +.fi + +The results will appear in the text file "orion.mag.1". + +.NH 2 +Landolt Standards +.PP +The user has 100 UBVRI images of 20 Landolt Standards +taken on a single night. These frames have been taken at various short +exposures. +The user wishes to process all this data +in batch mode with the output records going to a single file. +.PP +The observer decides to run the \fBdaofind\fR task to create a coordinate +list for each image, to run \fBphot\fR on a representative image +in interactive mode with the image cursor +directed to the standard input to set up and store the \fBphot\fR task +parameters, and finally to run \fBphot\fR in batch mode on all the images +to do the photometry. +.PP +Note that the example below assumes that the image cursor has been redirected +to the standard input. The image cursor comes up on the screen in the +form of a prompt. This example could equally well be run from the image +hardware cursor in which case the cursor would appear on the displayed +image. The keystroke commands are identical in the two cases. +.PP +To create the coordinate list the user needs to supply the full width half +maximum of the point spread function and an intensity threshold above +local background to the +\fBdaofind\fR task. Using the PLOT package task \fBimplot\fR the user +examines the Landolt standards in several images and decides that the +average \fBfwhmpsf\fR is 4.3 +pixels and that the standard deviation of the background is 15.0 counts. +Note that if the user has access to an image display \fBfwhmpsf\fP and +\fBthreshold\fP can be determined interactively from inside the +daofind task itself. +The user decides to include all stars with a peak intensity greater +than five standard deviations above local background in the coordinate list, +which should include weak and spurious objects. +The user runs \fBdaofind\fR as follows. + +.nf + \f(CWap> daofind lan*.imh fwhmpsf=4.3 threshold=75.0 verify- &\fP +.fi + +The x and y coordinates, an initial guess at the magnitude and some +sharpness and roundness characteristics are output to the files "lan*.coo.1". +For example the image lan100350.imh will now have a corresponding +coordinate file lan100350.coo;1. The user may wish at this point +to quickly check the coordinate files for spurious objects. +.PP +Next the user decides to set up the parameters of the phot task. +Using the \fBepar\fR task he enters the phot task parameter set, +enters "lan100350b" opposite the \fBimage\fR parameter and "lan100350b.coo.1" +opposite the \fBcoords\fR parameter. Next he moves the cursor opposite +the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR +menu. He sets the gain parameter \fBepadu\fR to 10 electrons per adu +and the readout noise \fBreadnoise\fR to 50.0 electrons. +Finally in order to normalize all the magnitudes the user enters +the image header exposure time keyword "itime" opposite the +\fBexposure\fP parameter. He types \fB:q\fR to +quit and save the \fBdatapars\fR parameters and \fB^Z\fR to quit and save the +\fBphot\fR parameters. +.PP +Now the user is ready to enter the \fBphot\fR task in interactive mode to set +up the remaining data dependent parameters. The user types the following +sequence of commands in response to the cursor prompt. + +.nf +\f(CW + ap> phot lan100350.imh + + ... \fIload the phot task\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: ? + + ... \fIprint help page for phot task\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: :radplots yes + + ... \fIenable radial profile plotting\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: :m #n + + ... \fImove to star n in the coordinate list\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: i + + ... \fIenter interactive setup mode using star n\fR ... + + ... \fImark fwhmpsf, cbox, sky annulus, apertures on the plot\fR ... + + ... \fIleave sigma and cthreshold at their default values\fR ... + + ... \fIcheck answers on radial profile plot of the results\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: v + + ... \fIverify the critical parameters\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: :radplots no + + ... \fIdisable radial profile plotting\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: w + + ... \fIstore new parameters in the psets\fR ... + + Image cursor [xcoord ycoord wcs] key [cmd]: q + + ... \fIquit interactive cursor loop\fR ... + + q + + ... \fIquit the phot task\fR ... + +\fR +.fi +.PP +Finally the user runs the \fBphot\fR task on the full list of images, +with their corresponding parameter sets and dumps the output to a single +text file named "output". + +.nf + \f(CWap> phot lan*.imh coords="lan*.coo.*" output=output veri- inter- &\fR +.fi + +The results will appear in the text file "output". + +.NH 2 +Aperture Photometry of an Elliptical Galaxy +.PP +The user has a single image of the elliptical galaxy N315. She +wishes to measure the magnitude of this galaxy through a list of apertures +equal to those published in a well known catalogue of photoelectric photometry. +Her data has been sky subtracted to give an average background value of 0.0 +and the standard deviation of the sky background is 20.0 counts. +From the published aperture photometry +and the scale of her telescope she knows that she wishes to measure +the galaxy through aperture radii of 10.5, 15.2, 20.8, and 25.6 arc seconds. +.PP +The user wishes to work in interactive mode using a contour plot +of the image and the graphics cursor to enter commands to the \fBphot\fR +task. She therefore sets the image cursor to "stdgraph" as follows. + +.nf + \f(CWap> set stdimcur = stdgraph\fR +.fi + +.PP +Next she makes a contour plot of the image and writes it to +a plot metacode file as follows. + +.nf +\f(CW + ap> contour N315 + + ... \fIcontour plot appears on the terminal\fR ... + + ap> =gcur + + ... \fIenter cursor mode\fR ... + + :.write n315.plot + + ... \fIwrite the plot to a file\fR ... + + q + + ... \fIexit cursor mode\fR ... + +\fR +.fi +.PP +Now the user is ready to set up the parameters of the \fBphot\fR task. +Since she already knows the values of the parameters she wishes to use +she types + +.nf + \f(CWap> epar phot\fR +.fi + +to enter the phot task menu. She positions the cursor opposite +\fBimage\fR parameter and types "N315", opposite \fBdispay\fR and +types "stdgraph". +Next she moves the cursor opposite +the \fBdatapars\fR parameter and types \fB:e\fR to enter the \fBdatapars\fR +menu. She makes sure that \fBscale =\fP 0.75 arc-seconds per pixel the scale +of the telescope, sets the standard deviation +of the sky background \fBsigma\fR to 20.0, sets the gain +parameter \fBepadu\fR to 5 electrons per adu +and the readout noise \fBreadnoise\fR to 5.0 electrons. She types \fB:q\fR to +quit and save the \fBdatapars\fR parameters. She decides to leave the +centering parameters in \fBcenterpars\fR at their default values. +\fBCbox\fP in particular will be 5.0 arcseconds wide. The user +has already removed a low order polynomial sky background from this image. +She wishes to fix the sky value at 0.0. She moves the cursor opposite +the \fBfitskypars\fR parameter and types \fB:e\fR to enter the sky fitting menu. +She types "constant" opposite the \fBsalgorithm\fR parameter, "0.0" +opposite the \fBskyvalue\fR parameter and \fB:e\fR to exit +the sky fitting parameter menu. Finally she enters the \fBphotpars\fR +menu and enters the aperture string "10.5,15.2,20.8,25.6" opposite +the \fBapert\fR parameter. +.PP +To measure the galaxy she types + +.nf + \f(CWap> phot N315\fR +.fi + +to enter the phot task, positions the cursor on the center of the +galaxy in the contour plot and taps the space bar to make the measurement. +The results are written to the file "N315.mag.1". diff --git a/noao/digiphot/apphot/doc/wphot.hlp b/noao/digiphot/apphot/doc/wphot.hlp new file mode 100644 index 00000000..69bfd7c7 --- /dev/null +++ b/noao/digiphot/apphot/doc/wphot.hlp @@ -0,0 +1,780 @@ +.help wphot May00 noao.digiphot.apphot +.ih +NAME +wphot -- perform weighted aperture photometry on a list of stars +.ih +USAGE +wphot image +.ih +PARAMETERS +.ls image +The list of images containing the objects to be measured. +.le +.ls skyfile = "" +The list of text files containing the sky values, of the measured objects, +one object per line with x, y, the sky value, sky sigma, sky skew, number of sky +pixels and number of rejected sky pixels in columns one to seven respectively. +The number of sky files must be zero, one, or equal to the number of input +images. A skyfile value is only requested if \fIfitskypars.salgorithm\fR = +"file" and if WPHOT is run non-interactively. +.le +.ls coords = "" +The list of text files containing initial coordinates for the objects to +be centered. Objects are listed in coords one object per line with the +initial coordinate values in columns one and two. The number of coordinate +files must be zero, one, or equal to the number of images. If coords is +"default", "dir$default", or a directory specification then a coords file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "coo" and version is +the next available version number for the file. +.le +.ls output = "default" +The name of the results file or results directory. If output is +"default", "dir$default", or a directory specification then an output file name +of the form dir$root.extension.version is constructed, where dir is the +directory, root is the root image name, extension is "omag" and version is +the next available version number for the file. The number of output files +must be zero, one, or equal to the number of image files. In both interactive +and batch mode full output is written to output. In interactive mode +an output summary is also written to the standard output. +.le +.ls plotfile = "" +The name of the file containing radial profile plots of the stars written +to the output file. If plotfile is defined then a radial profile plot +is written to plotfile every time a record is written to \fIoutput\fR. +The user should be aware that this can be a time consuming operation. +.le +.ls datapars = "" +The name of the file containing the data dependent parameters. The critical +parameters \fIfwhmpsf\fR and \fIsigma\fR are located here. If \fIdatapars\fR +is undefined then the default parameter set in uparm directory is used. +.le +.ls centerpars = "" +The name of the file containing the centering parameters. The critical +parameters \fIcalgorithm\fR and \fIcbox\fR are located here. +If \fIcenterpars\fR is undefined then the default parameter set in +uparm directory is used. +.le +.ls fitskypars = "" +The name of the text file containing the sky fitting parameters. The critical +parameters \fIsalgorithm\fR, \fIannulus\fR, and \fIdannulus\fR are located here. +If \fIfitskypars\fR is undefined then the default parameter set in uparm +directory is used. +.le +.ls photpars = "" +The name of the file containing the photometry parameters. The critical +parameter \fIapertures\fR is located here. If \fIphotpars\fR is undefined +then the default parameter set in uparm directory is used. +.le +.ls interactive = yes +Run the task interactively ? +.le +.ls radplots = no +If \fIradplots\fR is "yes" and PHOT is run in interactive mode, a radial +profile of each star is plotted on the screen after the star is measured. +.le +.ls icommands = "" +The image display cursor or image cursor command file. +.le +.ls gcommands = "" +The graphics cursor or graphics cursor command file. +.le +.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" +The coordinate system of the input coordinates read from \fIcoords\fR and +of the output coordinates written to \fIoutput\fR respectively. The image +header coordinate system is used to transform from the input coordinate +system to the "logical" pixel coordinate system used internally, +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 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 and wcsout parameters default to the values of the package +parameters of the same name. The default values of the package parameters +wcsin and wcsout are "logical" and "logical" respectively. +.le +.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 cacheing is +disabled. +.le +.ls verify = ")_.verify" +Verify the critical parameters in non-interactive mode. Verify may be set to +the apphot package parameter value (the default), "yes", or "no". +.le +.ls update = ")_.update" +Update the critical parameters in non-interactive mode if verify is yes. +Update may be set to the apphot package parameter value (the default), "yes", +or "no". + +.le +.ls verbose = ")_.verbose" +Print messages on the terminal about actions taken in non-interactive mode. +Verbose may be set to the apphot package parameter value (the default), "yes", +or "no". +.le +.ls graphics = ")_.graphics" +The default graphics device. Graphics may be set to the apphot package +parameter value (the default), "yes", or "no". + +.le +.ls display = ")_.display" +The default display device. Graphics may be set to the apphot package +parameter value (the default), "yes", or "no. By default graphics overlay +is disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" +enables graphics overlay with the IMD graphics kernel. Setting display to +"stdgraph" enables WPHOT to work interactively from a contour plot. +.le + +.ih +DESCRIPTION +WPHOT computes accurate centers, sky values, and weighted magnitudes for a +list of objects in the IRAF image \fIimage\fR whose initial coordinates are read +from the text file \fIcoords\fR or image display cursor, and writes the +computed x and y coordinates, sky values and magnitudes to the text file +\fIoutput\fR. + +The coordinates read from \fIcoords\fR are assumed to be in coordinate +system defined by \fIwcsin\fR. 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. +Users importing coordinate lists in world coordinates, e.g. ra and dec, +must use the "world" coordinate system and may need to convert their +equatorial coordinate units from hours and degrees to degrees and degrees first. + +The coordinates written to \fIoutput\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 input image pixels are cached in memory. If cacheing +is enabled and WPHOT is run interactively the first measurement will appear +to take a long time as the entire image must be read in before the measurement +is actually made. All subsequent measurements will be very fast because WPHOT +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. + +In interactive mode the user may either define the list of objects to be +measured interactively with the image cursor or create an object list prior +to entering WPHOT. In either case the user may adjust the centering, sky +fitting and photometry parameters until a satisfactory fit is achieved and +only then store the final results in \fIoutput\fR. In batch +mode the initial positions are read from the text file \fIcoords\fR +or the image cursor parameter \fIicommands\fR is redirected to a text +file containing a list of cursor commands. + +.ih +CURSOR COMMANDS + +The following list of cursor commands are currently available. + +.nf + Interactive Photometry Commands + +? Print help +: Colon commands +v Verify the critical parameters +w Store the current parameters +d Plot radial profile of current star +i Interactively set parameters using current star +c Fit center of current star +t Fit sky around the cursor +a Average sky values fit around several cursor positions +s Fit sky around the current star +p Do photometry for current star, using current sky +o Do photometry for current star, using current sky, output results +f Do photometry for current star +spbar Do photometry for current star, output results +m Move to next star in coordinate list +n Do photometry for next star in coordinate list, output results +l Do photometry for remaining stars in coordinate list, output results +r Rewind the coordinate list +e Print error messages +q Exit task + + + Colon Commands + +:show [data/center/sky/fit] Show parameters +:m [n] Move to next [nth] star in the coordinate list +:n [n] Do photometry for next [nth] star in coordinate list, output results + + + Colon Parameter Editing Commands + +# Image and file parameters + +:image [string] Image name +:coords [string] Coordinate file name +:output [string] Output file name + +# Data dependent parameters + +:scale [value] Image scale (units per pixel) +:fwhmpsf [value] Full-width half-maximum of PSF (scale units) +:emission [y/n] Emission features (y), absorption (n) +:sigma [value] Standard deviation of sky (counts) +:datamin [value] Minimum good pixel value (counts) +:datamax [value] Maximum good pixel value (counts) + +# Noise parameters + +:noise [string] Noise model (constant|poisson) +:gain [string] Gain image header keyword +:ccdread [string] Readout noise image header keyword +:epadu [value] Gain (electrons per adu) +:readnoise [value] Readout noise (electrons) + +# Observations parameters + +:exposure [string] Exposure time image header keyword +:airmass [string] Airmass image header keyword +:filter [string] Filter image header keyword +:obstime [string] Time of observation image header keyword +:itime [value] Integration time (time units) +:xairmass [value] Airmass value (number) +:ifilter [string] Filter id string +:otime [string] Time of observations (time units) + +# Centering algorithm parameters + +:calgorithm [string] Centering algorithm +:cbox [value] Width of the centering box (scale units) +:cthreshold [value] Centering intensity threshold (sigma) +:cmaxiter [value] Maximum number of iterations +:maxshift [value] Maximum center shift (scale units) +:minsnratio [value] Minimum S/N ratio for centering +:clean [y/n] Clean subraster before centering +:rclean [value] Cleaning radius (scale units) +:rclip [value] Clipping radius (scale units) +:kclean [value] Clean K-sigma rejection limit (sigma) + +# Sky fitting algorithm parameters + +:salgorithm [string] Sky fitting algorithm +:skyvalue [value] User supplied sky value (counts) +:annulus [value] Inner radius of sky annulus (scale units) +:dannulus [value] Width of sky annulus (scale units) +:khist [value] Sky histogram extent (+/- sigma) +:binsize [value] Resolution of sky histogram (sigma) +:smooth [y/n] Lucy smooth the sky histogram +:sloclip [value] Low-side clipping factor in percent +:shiclip [value] High-side clipping factor in percent +:smaxiter [value] Maximum number of iterations +:snreject [value] Maximum number of rejection cycles +:sloreject [value] Low-side pixel rejection limits (sky sigma) +:shireject [value] High-side pixel rejection limits (sky sigma) +:rgrow [value] Region growing radius (scale units) + +# Photometry parameters + +:weighting [string] Weighting function (constant|cone|gauss) +:apertures [string] List of aperture radii (scale units) +:zmag [value] Zero point of magnitude scale + +# Plotting and marking parameters + +:mkcenter [y/n] Mark computed centers on display +:mksky [y/n] Mark the sky annuli on the display +:mkapert [y/n] Mark apertures on the display +:radplot [y/n] Plot radial profile of object + + + +The following commands are available from inside the interactive setup menu. + + + Interactive Phot/Wphot Setup Menu + + v Mark and verify the critical parameters (f,s,c,a,d,r) + + f Mark and verify the full-width half-maximum of psf + s Mark and verify the standard deviation of the background + l Mark and verify the minimum good data value + u Mark and verify the maximum good data value + + c Mark and verify the centering box width + n Mark and verify the cleaning radius + p Mark and verify the clipping radius + + a Mark and verify the inner radius of the sky annulus + d Mark and verify the width of the sky annulus + g Mark and verify the region growing radius + + r Mark and verify the aperture radii +.fi + +.ih +ALGORITHMS + +WPHOT computes accurate centers for each object using the centering +parameters defined in the CENTERPARS task, computes an accurate sky value +for each object using the sky fitting parameters defined in FITSKYPARS task, +and computes magnitudes using the photometry parameters defined in the +PHOTPARS task. The data dependent parameter are defined in the DATAPARS task. + +Three weighting functions are currently supported: constant, cone and gauss. +Constant weighting, the default gives identical results to the PHOT task. +Pixels are weighted by the fraction of their area inside the circular +aperture. For cone and gauss weighting an additional triangular or gaussian +weighting function of full width half maximum equal to \fIfwhmpsf\fR is +applied to the pixels before aperture summing. + +This task is currently experimental. Further algorithm work is required. + +.ih +OUTPUT + +In interactive mode the following quantities are printed on the standard +output as each object is measured. Error is a simple string which +indicates whether the task encountered any errors in the +the centering algorithm, the sky fitting algorithm or the photometry +algorithm. Mag and merr are the magnitudes and errors in +apertures 1 through N respectively and xcenter, ycenter and msky are the +x and y centers and the sky value respectively. + +.nf + image xcenter ycenter msky mag[1 ... N] error +.fi + +In both interactive and batch mode full output is written to the text file +\fIoutput\fR. At the beginning of each file is a header listing the +current values of the parameters when the first stellar record was written. +These parameters can be subsequently altered. For each star measured the +following record is written + +.nf + image xinit yinit id coords lid + xcenter ycenter xshift yshift xerr yerr cier error + msky stdev sskew nsky nsrej sier serror + itime xairmass ifilter otime + rapert sum area flux mag merr pier perr +.fi + +Image and coords are the name of the image and coordinate file respectively. +Id and lid are the sequence numbers of stars in the output and coordinate +files respectively. Cier and cerror are the error code and accompanying +error message respectively. Xinit, yinit, xcenter, ycenter, xshift, yshift, +and xerr, yerr are self explanatory and output in pixel units. The sense of +the xshift and yshift definitions is the following. + +.nf + xshift = xcenter - xinit + yshift = ycenter - yinit +.fi + +Sier and serror are the error code and accompanying error message respectively. +Msky, stdev and sskew are the best estimate of the sky value (per pixel), +standard deviation and skew respectively. Nsky and nsrej are the number of +sky pixels and the number of sky pixels rejected respectively. + +Itime is the exposure time, xairmass is self-evident, ifilter is an id +string identifying the filter used during the observation, and otime is +a string specifying the time of the observation in whatever units the +user has defined. + +Rapert, sum, area, and flux are the radius of the aperture in pixels, the total +number of counts including sky in the aperture, the area of the aperture +in square pixels, and the total number of counts in the aperture excluding +sky. Mag and merr are the magnitude and error in the magnitude +in the aperture (see below). + +.nf + flux = sum - area * msky + mag = zmag - 2.5 * log10 (flux) + 2.5 * log10 (itime) + merr = 1.0857 * error / flux + error = sqrt (flux / epadu + area * stdev**2 + + area**2 * stdev**2 / nsky) +.fi + +Pier and perror are photometry error code and accompanying error message. + +In interactive mode a radial profile of each measured object is plotted +in the graphics window if \fIradplots\fR is "yes". + +In interactive and batchmode a radial profile plot is written to +\fIplotfile\fR if it is defined each time the result of an object +measurement is written to \fIoutput\fR . + +.ih +ERRORS +If the object centering was error free then the field cier will be zero. +Non-zero values of cier flag the following error conditions. + +.nf + 0 # No error + 101 # The centering box is off image + 102 # The centering box is partially off the image + 103 # The S/N ratio is low in the centering box + 104 # There are two few points for a good fit + 105 # The x or y center fit is singular + 106 # The x or y center fit did not converge + 107 # The x or y center shift is greater than maxshift + 108 # There is bad data in the centering box +.fi + +If all goes well during the sky fitting process then the error code sier +will be 0. Non-zero values of sier flag the following error conditions. + +.nf + 0 # No error + 201 # There are no sky pixels in the sky annulus + 202 # Sky annulus is partially off the image + 203 # The histogram of sky pixels has no width + 204 # The histogram of sky pixels is flat or concave + 205 # There are too few points for a good sky fit + 206 # The sky fit is singular + 207 # The sky fit did not converge + 208 # The graphics stream is undefined + 209 # The file of sky values does not exist + 210 # The sky file is at EOF + 211 # Cannot read the sky value correctly + 212 # The best fit parameter are non-physical +.fi + +If no error occurs during the measurement of the magnitudes then pier is +0. Non-zero values of pier flag the following error conditions. + +.nf + 0 # No error + 301 # The aperture is off the image + 302 # The aperture is partially off the image + 303 # The sky value is undefined + 305 # There is bad data in the aperture +.fi + +.ih +EXAMPLES + +1. Compute the magnitudes for a few stars in dev$ypix using the display +and the image cursor. Setup the task parameters using the interactive +setup menu defined by the i key command and a radial profile plot. + +.nf + ap> display dev$ypix 1 fi+ + + ... display the image + + ap> wphot dev$ypix + + ... type ? to print an optional help page + + ... move the image cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or hit + CR to accept the default + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + photometry apertures, and sigma using the graphics cursor and the + stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the parameters + + ... type the w key to save the parameters in the parameter files + + ... move the image cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.omag.1 +.fi + +2. Compute the magnitudes for a few stars in dev$ypix using a contour plot +and the graphics cursor. This option is only useful for those (now very few) +users who have access to a graphics terminal but not to an image display +server. Setup the task parameters using the interactive setup menu defined by +the i key command as in example 1. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = stdgraph + + ... define the image cursor to be the graphics cursor + + ap> contour dev$ypix + + ... make a contour plot of dev$ypix + + ap> contour dev$ypix >G ypix.plot1 + + ... store the contour plot of dev$ypix in the file ypix.plot1 + + ap> wphot dev$ypix display=stdgraph + + ... type ? to get an optional help page + + ... move graphics cursor to a star + ... type i to enter the interactive setup menu + ... enter maximum radius in pixels of the radial profile or CR + to accept the default value + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + apertures, and sigma using the graphics cursor and the + stellar radial profile plot + ... typing <CR> leaves everything at the default value + ... type q to quit the setup menu + + ... type the v key to verify the critical parameters + + ... type the w key to save the parameters in the parameter files + + ... retype :.read ypix.plot1 to reload the contour plot + + ... move the graphics cursor to the stars of interest and tap + the space bar + + ... a one line summary of the fitted parameters will appear on the + standard output for each star measured + + ... type q to quit and q again to verify + + ... full output will appear in the text file ypix.omag.2 + + ap> set stdimcur = <default> + + ... reset stdimcur to its previous value +.fi + + +3. Setup and run PHOT interactively on a list of objects temporarily +overriding the fwhmpsf, sigma, cbox, annulus, dannulus, and apertures +parameters determined in examples 1 or 2. + +.nf + ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify- + + ... make a coordinate list + + ... the output will appear in the text file ypix.coo.1 + + ap> wphot dev$ypix cbox=7.0 annulus=12.0 dannulus=5.0 \ + apertures="3.0,5.0" coords=ypix.coo.1 + + ... type ? for optional help + + + ... move the graphics cursor to the stars and tap space bar + + or + + ... select stars from the input coordinate list with m / :m # + and measure with spbar + + ... measure stars selected from the input coordinate list + with n / n # + + ... a one line summary of results will appear on the standard output + for each star measured + + ... type q to quit and q again to confirm the quit + + ... the output will appear in ypix.omag.3 ... +.fi + + +4. Display and measure some stars in an image section and write the output +coordinates in the coordinate system of the parent image. + +.nf + ap> display dev$ypix[150:450,150:450] 1 + + ... display the image section + + ap> wphot dev$ypix[150:450,150:450] wcsout=tv + + ... move cursor to stars and type spbar + + ... type q to quit and q again to confirm quit + + ... output will appear in ypix.omag.4 + + ap> pdump ypix.omag.4 xc,yc yes | tvmark 1 STDIN col=204 +.fi + + +5. Run PHOT in batch mode using the coordinate file and the previously +saved parameters. Verify the critical parameters. + +.nf + ap> wphot dev$ypix coords=ypix.coo.1 verify+ inter- + + ... output will appear in ypix.omag.5 ... +.fi + + +6. Repeat example 5 but assume that the input coordinate are ra and dec +in degrees and degrees, turn off verification, and submit the task to to +the background. + +.nf + ap> display dev$ypix 1 + + ap> rimcursor wcs=world > radec.coo + + ... move to selected stars and type any key + + ... type ^Z to quit + + ap> wphot dev$ypix coords=radec.coo wcsin=world verify- inter- & + + ... output will appear in ypix.omag.6 + + ap> pdump ypix.omag.6 xc,yc yes | tvmark 1 STDIN col=204 + + ... mark the stars on the display +.fi + + +7. Run PHOT interactively without using the image display. + +.nf + ap> show stdimcur + + ... record the default value of stdimcur + + ap> set stdimcur = text + + ... set the image cursor to the standard input + + ap> wphot dev$ypix coords=ypix.coo.1 + + ... type ? for optional help + + ... type :m 3 to set the initial coordinates to those of the + third star in the list + + ... type i to enter the interactive setup menu + ... enter the maximum radius in pixels for the radial profile or + accept the default with a CR + ... type v to enter the default menu + ... set the fwhmpsf, centering radius, inner and outer sky annuli, + apertures, and sigma using the graphics cursor and the + stellar radial profile plot + ... typing <CR> after the prompt leaves the parameter at its default + value + ... type q to quit the setup menu + + ... type r to rewind the coordinate list + + ... type l to measure all the stars in the coordinate list + + ... a one line summary of the answers will appear on the standard + output for each star measured + + ... type q to quit followed by q to confirm the quit + + ... full output will appear in the text file ypix.omag.7 + + ap> set stdimcur = <default> + + ... reset the value of stdimcur +.fi + + +8. Use a image cursor command file to drive the PHOT task. The cursor command +file shown below sets the cbox, annulus, dannulus, and apertures parameters +computes the centers, sky values, and magnitudes for 3 stars, updates the +parameter files, and quits the task. + +.nf + ap> type cmdfile + : cbox 9.0 + : annulus 12.0 + : dannulus 5.0 + : apertures 5.0 + 442 410 101 \040 + 349 188 101 \040 + 225 131 101 \040 + w + q + + ap> wphot dev$ypix icommands=cmdfile verify- + + ... full output will appear in ypix.omag.8 +.fi + + + + +.ih +BUGS +This task is experimental and requires more work. + +It is currently the responsibility of the user to make sure that the +image displayed in the frame is the same as that specified by the image +parameter. + +Commands which draw to the image display are disabled by default. +To enable graphics overlay on the image display, set the display +parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, +blue or yellow overlays and set the centerpars mkcenter switch to +"yes", the fitskypars mksky switch to"yes", or the photpars mkapert +witch to "yes". It may be necessary to run gflush and to redisplay the image +to get the overlays position correctly. + + +.ih +SEE ALSO +datapars, centerpars, fitskypars, photpars, qphot, phot, polyphot +.endhelp |