diff options
Diffstat (limited to 'noao/digiphot/apphot/doc/qphot.hlp')
| -rw-r--r-- | noao/digiphot/apphot/doc/qphot.hlp | 647 |
1 files changed, 647 insertions, 0 deletions
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 |