From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 noao/digiphot/apphot/doc/qphot.hlp | 647 +++++++++++++++++++++++++++++++++++++
 1 file changed, 647 insertions(+)
 create mode 100644 noao/digiphot/apphot/doc/qphot.hlp

(limited to 'noao/digiphot/apphot/doc/qphot.hlp')

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
-- 
cgit 

