Initial commit

1 files changed, 820 insertions, 0 deletions

diff --git a/noao/obsutil/src/doc/starfocus.hlp b/noao/obsutil/src/doc/starfocus.hlp
new file mode 100644
index 00000000..351bf14c
--- /dev/null
+++ b/noao/obsutil/src/doc/starfocus.hlp
@@ -0,0 +1,820 @@
+.help starfocus Nov01 noao.obsutil
+.ih
+NAME
+starfocus -- Measure focus variations using stellar images
+.ih
+USAGE
+starfocus images
+.ih
+PARAMETERS
+.ls images
+List of images.  The images may be either taken at a sequence
+of focus values or be multiple shifted exposures at a sequence of
+focus settings.
+.le
+.ls focus = "1x1"
+If the parameter \fIfstep\fR is not set (a "" null string) then this
+parameter is interpreted as either a list of focus values or an
+image header keyword to one focus value per image.  A list may be an explicit
+list of values, a range specification, or an @ file containing the values.
+If there is only a single exposure per image then the focus list gives one
+value per image while if there are multiple exposures per image the list
+applies to the multiple exposures with the same values reused for other
+images.  If the parameter \fIfstep\fR is given then this parameter is
+interpreted as a single starting focus value and the focus step
+defines the increment between subsequent single exposure images or
+for the various exposures in a multiple exposure image.
+.le
+.ls fstep = ""
+A focus increment value or an image header keyword to the focus increment.
+.le
+
+.ls nexposures = "1"
+The number of exposures per image specified either as a value or as
+an image header keyword.  A double step gap in a multiple
+exposure sequence does not count as an exposure.
+.le
+.ls step = "30."
+The step in pixels between exposures specified either as a value or
+as an image header keyword.
+.le
+.ls direction = "-line" (-line|+line|-column|+column)
+The direction of the exposure sequence in the image.  The values are
+"-line" for successive object images appearing at smaller line numbers,
+"+line" for objects appearing at larger line numbers, "-column" for
+objects appearing at smaller column numbers, and "+column" for objects
+appearing at larger column numbers.
+.le
+.ls gap = "end" (none|beginning|end)
+Location of a double step gap in a sequence with the specified direction.
+The available cases are "none" for an even sequence with no gap,
+"beginning" where a double step is taken between the first and
+the second exposure, and "end" where a double step is taken before
+the last exposure.  Note that "beginning" and "end" are defined in
+terms of the \fIdirection\fR parameter.
+.le
+
+.ls coords = "mark1" (center|mark1|markall)
+Method by which the coordinates of objects to be measured are specified.
+If "center" then a single object at the center of each image is measured.
+If "mark1" then the \fIimagecur\fR parameter, typically the interactive
+image display cursor, defines the coordinates of one or more objects in the
+first image ending with a 'q' key value and then the same coordinates are
+automatically used in subsequent images.  If "markall" then the
+\fIimagecur\fR parameter defines the coordinates for objects in each image
+ending with a 'q' key value.
+.le
+.ls wcs = "logical" (logical|physical|world)
+Coordinate system for input coordinates.  When using image cursor input
+this will always be "logical".  When using cursor input from a file this
+could be "physical" or "world".
+.le
+.ls display = yes, frame = 1
+Display the image or images as needed?  If yes the image display is checked
+to see if the image is already in one of the display frames.  If it is not
+the \fBdisplay\fR task is called to display the image in the frame
+specified by the \fBframe\fR parameter.  All other display parameters are
+taken from the current settings of the task.  This option requires that the
+image display be active.  A value of no is typically used when an input
+cursor file is used instead of the image display cursor.  An image display
+need not be active in that case.
+.le
+
+.ls level = 0.5
+The parameter used to quantify an object image size is the radius from the
+image center enclosing the fraction of the total flux given by this
+parameter.  If the value is greater than 1 it is treated as a percentage.
+.le
+.ls size = "FWHM" (Radius|FWHM|GFWHM|MFWHM)
+There are four ways the PSF size may be shown in graphs and given in
+the output.  These are:
+
+.nf
+    Radius - the radius enclosing the specified fraction of the flux
+    FWHM   - a direct FWHM from the measured radial profile
+    GFWHM  - the FWHM of the best fit Gaussian profile
+    MFWHM  - the FWHM of the best fit Moffat profile
+.fi
+
+The labels in the graphs and output will be the value of this parameter
+to distinguish the different types of size measurements.
+.le
+.ls beta = INDEF
+For the Moffat profile fit (size = MFWHM) the exponent parameter may
+be fixed at a specified value or left free to be determined from the
+fit.  The exponent parameter is determined by the fit if \fIbeta\fR
+task parameter is INDEF.
+.le
+.ls scale = 1.
+Pixel scale in user units per pixel.  Usually the value is 1 to measure
+sizes in pixels or the image pixel scale in arc seconds per pixel.
+.le
+.ls radius = 5., iterations = 2
+Measurement radius in pixels and number of iterations on the radius.  The
+enclosed flux profile is measured out to this radius.  This radius may be
+adjusted if the \fIiteration\fR parameter is greater than 1.  In that case
+after each iteration a new radius is computed from the previous FWHM
+estimate to be the radius the equivalent gaussian enclosing 99.5% of the
+light.  The purpose of this is so that if the initial PSF size of the image
+need not be known.  However, the radius should then be larger than true
+image size since the iterations best converge to smaller values.
+.le
+.ls sbuffer = 5, swidth = 5.
+Sky buffer and sky width in pixels.  The buffer is added to the specified
+measurement \fIradius\fR to define the inner radius for a circular sky
+aperture.  The sky width is the width of the circular sky aperture.
+.le
+.ls saturation=INDEF, ignore_sat=no
+Data values (prior to sky subtraction) to be considered saturated within
+measurement radius.  A value of INDEF treats all pixels as unsaturated.  If
+a measurement has saturated pixels there are two actions.  If
+\fIignore_sat\fR=no then a warning is given but the measurement is saved
+for use.  The object will also be indicated as saturated in the output
+log.  If \fIignore_sat\fR=yes then a warning is given and the object is
+discarded as if it was not measured.  In a focus sequence only the
+saturated objects are discarded and not the whole sequence.
+.le
+.ls xcenter = INDEF, ycenter = INDEF
+The optical field center of the image given in image pixel coordinates.
+These values need not lie in the image.  If INDEF the center of the image
+is used.  These values are used to make plots of size verse distance from
+the field center for studies of radial variations.
+.le
+.ls logfile = "logfile"
+File in which to record the final results.  If no log file is desired a
+null string may be specified.
+.le
+
+.ls imagecur = ""
+Image cursor input for the "mark1" and "markall" options.  If null then the
+image dispaly cursor is used interactively.  If a file name is specified
+then the coordinates come from this file.  The format of the file are lines
+of x, y, id, and key.  Values of x an y alone may be used to select objects
+and the single character 'q' (or the end of the file) may be used to end
+the list.
+.le
+.ls graphcur = ""
+Graphics cursor input.  If null then the standard graphics cursor
+is used otherwise a standard cursor format file may be specified.
+.le
+.ih
+CURSOR COMMANDS
+When selecting objects with the image cursor the following commands are
+available.
+
+.nf
+?  Page cursor command summary
+g  Measure object and graph the results.
+m  Measure object.
+q  Quit object marking and go to next image.
+   At the end of all images go to analysis of all measurements.
+
+:show  Show current results.
+.fi
+
+When in the interactive graphics the following cursor commands are available.
+All plots may not be available depending on the number of focus values and
+the number of stars.
+
+.nf
+?  Page cursor command summary
+a  Spatial plot at a single focus
+b  Spatial plot of best focus values
+d  Delete star nearest to cursor
+e  Enclosed flux for stars at one focus and one star at all focus
+f  Size and ellipticity vs focus for all data
+i  Information about point nearest the cursor
+m  Size and ellipticity vs relative magnitude at one focus
+n  Normalize enclosed flux at x cursor position
+o  Offset enclosed flux to by adjusting background
+p  Radial profiles for stars at one focus and one star at all focus
+q  Quit
+r  Redraw
+s  Toggle magnitude symbols in spatial plots
+t  Size and ellipticity vs radius from field center at one focus
+u  Undelete all deleted points
+x  Delete nearest point, star, or focus (selected by query)
+z  Zoom to a single measurement
+<space> Step through different focus or stars in current plot type
+
+
+:beta <val>     Beta parameter for Moffat fit
+:level <val>	Level at which the size parameter is evaluated
+:overplot <y|n> Overplot the profiles from the narrowest profile?
+:radius <val>   Change profile radius
+:show <file>	Page all information for the current set of objects
+:size <type>	Size type (Radius|FWHM)
+:scale <val>	Pixel scale for size values
+:xcenter <val>	X field center for radius from field center plots
+:ycenter <val>	Y field center for radius from field center plots
+
+The profile radius may not exceed the initial value set by the task
+parameter.
+.fi
+.ih
+DESCRIPTION
+This task measures the point-spread function (PSF) width of stars or other
+unresolved objects in digital images.  The width is measured based on the
+circular radius which encloses a specified fraction of the background
+subtracted flux.  The details of this are described in the ALGORITHMS
+section.  When a sequence of images or multiple exposures in a single image
+are made with the focus varied the program provides an estimate of the best
+focus and various views of how the PSF width varies with focus and position
+in the image.  A single star may be measured at each focus or measurements
+of multiple stars may be made and combined.  The task has three stages;
+selecting objects and measuring the PSF width and other parameters, an
+interactive graphical analysis, and a final output of the results to the
+terminal and to a logfile.
+
+If a saturation value is specified then all pixels within the specified
+measurement radius are checked for saturation.  If any saturated pixels are
+found a warning is given and \fIignore_sat\fR parameter may be used ot
+ignore the measurement.  If not ignored the object will still be indicated
+as saturated in the output log.  In a focus sequence only the saturated
+objects are discarded and not the whole sequence.
+
+The input images are specified by an image template list.  The list may
+consist of explicit image names, wildcard templates, and @ files.  A
+"focus" value or values is associated with each image; though this may be
+any numeric quantity (integer or floating point) and not just a focus.  The
+focus values may be specified in several ways.  If each image has a focus
+value recorded in the image header, the keyword name may be specified.  If
+the images consists of multiple exposures the \fIfstep\fR parameter would
+specify a second image header keyword (or constant value) giving the
+focus increment per exposure.  
+
+The focus values may also be specified as a range list
+as described in the help topic \fBranges\fR.  This consists of
+individual values, ranges of values, a starting value and a step, and a
+range with a step.  The elements of the list are separated by commas,
+ranges are separated by hyphens, and a step is indicated by the character
+'x'.  Long range lists, such as a list of individual focus values, may be
+placed in a file and specified with the @<filename> convention.  The
+assignment of a focus value from a list depends on whether the images
+are single or multiple exposure as specified by the \fInexposure\fR
+parameter.  Single exposure images are assigned focus values from the
+list in the order in which the images and focus values are given.  If
+the images are multiple exposure focus frames in which each offset exposure
+has a different focus, the focus values from the list are assigned in
+order to the multiple exposures and if there are multiple images the
+assignments are repeated.
+
+For a simple sequence of a starting focus value and focus increment,
+either for multiple single exposure images or multiple exposure
+images the \fIfocus\fR and \fIfstep\fR parameters by be used
+togther as single values or image header keywords.  Note that if
+\fIfstep\fR is specified then the focus parameter is NOT interpreted
+as a list.
+
+There are two common ways of doing focus sequences.  One is to take an
+exposure at each focus value.  In this case the parameter \fInexposure\fR
+is given the value 1.  The second is to take an image with multiple
+exposures where the objects in the image are shifted between exposures and
+the focus is changed.  In this case \fInexposure\fR is greater than 1 and
+other parameters are used to specify the shift size and direction.  The
+\fInexposure\fR parameter may be a number of an image header keyword.
+
+Currently the task allows only multiple exposure shifts along either the
+column or line dimension and the shifts must be the same between each
+exposure except that there may be a double shift at either end of the
+sequence.  The shift magnitude, in pixels, is specified as either a number
+or image header keyword.  The shift direction is given by the
+\fIdirection\fR parameter.  It is specified relative to the image; i.e. it
+need not be the same as the physical shifts of the telescope or detector
+but depends on how the image was created.  Steps in which the object
+positions decrease in column or line are specified with a leading minus and
+those which increase with a leading plus.  The step is specified as a
+positive number of pixels between exposures.  Often a double shift is made
+at the beginning or end of the sequence.  If this is done the \fIgap\fR
+parameter is used to identify which end the gap is on.  Note that one may
+change the sense of the exposure sequence from that used to make the focus
+frame by properly adjust the direction, the gap, the focus list, and which
+object is marked as the start of the sequence.
+
+Identifying the object or objects to be measured may be accomplished in
+several ways.  If a single object near the center of the image is to be
+measured then the \fIcoords\fR parameter takes the value "center".  This
+may be used with multiple exposure focus frames if the first exposure of
+the object sequence is at the center.  When the "center" option is used
+the \fIdisplay\fR and \fIimagecur\fR parameters are ignored.
+
+If there are multiple objects or the desired object is not at the center of
+the frame the object coordinates are entered with the \fIimagecur\fR
+parameter.  This type of coordinate input is selected by specifying either
+"mark1" or "markall" for the \fIcoords\fR parameter.  If the value is
+"mark1" then the coordinates are entered for the first image and the same
+values are automatically used for subsequent images.  If "markall" is
+specified then the objects in each image are marked.
+
+Normally the \fIimagecur\fR parameter would select the interactive image
+display cursor though a standard cursor file could be used to make this
+part noninteractive.  When the image display cursor is used either the
+image must be displayed previously by the user, or the task may be allowed
+to load the image display using the \fBdisplay\fR task by setting the
+parameter \fIdisplay\fR to yes and \fIframe\fR to a display frame.  If yes
+the image display must be active.  The task will look at the image names as
+stored in the image display and only load the display if needed.
+
+If one wants to enter a coordinate list rather than use the interactive
+image cursor the list can consist of just the column and line coordinates
+since the key will default to 'm'.  To finish the list either the end
+of file may be encountered or a single 'q' may be given since the
+coordinates are irrelevant.  For the "markall" option with multiple
+images there would need to be a 'q' at the end of each object except
+possibly the last.
+
+When objects are marked interactively with the image cursor there
+are a four keys which may be used as shown in the CURSOR COMMAND section.
+The important distinction is between 'm' to mark and measure an
+object and 'g' to mark, measure, and graph the results.  The former
+accumulates the results until the end while the latter can give an
+immediate result to be examined.  Unless only one object is marked
+the 'g' key also accumulates the results for later graphical analysis.
+It is important to note that the measurements are done as each
+object is marked so there can be a significant delay before the
+next object may be marked.
+
+The quantities measured and the algorithms used are described in the
+ALGORITHMS section.  Once all the objects have been measured an
+interactive (unless only one object is measured) graphical presentation
+of the measurements is entered.
+
+When the task exits it prints the results to the terminal (STDOUT)
+and also to the \fIlogfile\fR if one is specified.  The results may
+also be previewed during the execution of the task with the
+":show" command.  The results begin with a banner and the overall
+estimate of the best focus and PSF size.  If there are multiple
+stars measured at multiple focus values the best focus estimate
+for each star is printed.  The star is identified by it's position
+(the starting position for multiple exposure images).  The average
+size, relative magnitude, and best focus estimate are then given.
+If there are multiple focus values the average of the
+PSF size over all objects at each focus are listed next.
+Finally, the individual measurements are given.  The columns
+give the image name, the column and line position, the relative
+magnitude, the focus value, the PSF size as either the enclosed
+flux radius or the FWHM, the ellipticity, the position angle, and
+an indication of saturation.
+.ih
+ALGORITHMS
+The PSF of an object is characterized using a radially symmetric
+enclosed flux profile.  First the center of the object is determined from
+an initial rough coordinate.  The center is computed from marginal profiles
+which are sums of lines or columns centered at the initial coordinate and
+with a width given by the sum of the \fIradius\fR, \fIsbuffer\fR, and
+\fIswidth\fR parameters.  The mean of the marginal profile is determined
+and then the centroid of the profile above this is computed.  The centroids
+from the two marginal profiles define a new object center.  These steps of
+forming the marginal profiles centered at the estimated object position and
+then computing the centroids are repeated until the centroids converge or
+three iterations have been completed.
+
+Next a background is determined from the mode of the pixel values in the
+sky annulus defined by the object center and \fIradius\fR, \fIsbuffer\fR,
+and \fIswidth\fR parameters.  The pixel values in the annulus are sorted
+and the mode is estimated as the point of minimum slope in this sorted
+array using a width of 5% of the number of points.  If there are multiple
+regions with the same minimum slope the lowest pixel value is used.
+
+The background subtracted enclosed flux profile is determined next.
+To obtain subpixel precision and to give accurate estimates for small
+widths relative to the pixel sampling, several things are done.
+First interpolation between pixels is done using a cubic spline surface.
+The radii measured are in subpixel steps.  To accommodate small and
+large PSF widths (and \fIradius\fR parameters) the steps are nonuniform
+with very fine steps at small radii (steps of 0.05 pixels in the
+central pixel) and coarser steps at larger radii (beyond 9 pixels
+the steps are one pixel) out to the specified \fIradius\fR.  Similarly each
+pixel is subsampled finely near the center and more coarsely at larger
+distances from the object center.  Each subpixel value, as obtained by
+interpolation, is background subtracted and added into the enclosed flux
+profile.  Even with subpixel sampling there is still a point where a
+subpixel straddles a particular radius.  At those points the fraction of
+the subpixel dimension in radius falling within the radius being measured
+is used as the fraction of the pixel value accumulated.
+
+Because of errors in the background determination due to noise and
+contaminating objects it is sometimes the case that the enclosed flux
+is not completely monotonic with radius.  The enclosed flux
+normalization, and the magnitude used in plots and reported in
+results, is the maximum of the enclosed flux profile even if it
+occurs at a radius less than the maximum radius.  It is possible
+to change the normalization and subtract or add a background correction
+interactively.
+
+Because a very narrow PSF will produce significant errors in the cubic
+spline interpolation due to the steepness and rapid variation in the pixel
+values near the peak, the Gaussian profile with FWHM that encloses the same
+80% of the flux is computed as:
+
+    FWHM(80%) = 2 * r(80%) * sqrt (ln(2) / (ln (1/.2)))
+
+If this is less than five pixels the Gaussian model is subtracted from the
+data.  The Gaussian normalization is chosed to perfectly subtract the
+central pixel.  The resulting subtraction will not be perfect but the
+residual data will have much lower amplitudes and variations.  A spline
+interpolation is fit to this residual data and the enclosed flux profile is
+recomputed in exactly the same manner as previously except the subpixel
+intensity is evaluated as the sum of the analytic Gaussian and the
+interpolation to the residual data.
+
+The Gaussian normalization is chosed to perfectly subtract the central
+pixel.  The resulting subtraction will not be perfect but the residual data
+will have much lower amplitudes and variations.  A spline interpolation is
+fit to this residual data and the enclosed flux profile is recomputed in
+exactly the same manner as previously except the subpixel intensity is
+evaluated as the sum of the analytic Gaussian and the interpolation to the
+residual data.  This technique yields accurate FWHM for simulated Gaussian
+PSFs down to at least a FWHM of 1 pixel.
+
+In addition to the enclosed flux profile, an estimate of the radially
+symmetric intensity profile is computed from the enclosed flux profile.
+This is based on the equation
+
+.nf
+    F(R) = integral from 0 to R { P(r) r dr }
+.fi
+
+where F(R) is the enclosed flux at radius R and P(r) is the intensity per
+unit area profile.  Thus the derivative of F(R) divided by R gives an
+estimate of P(R).
+
+Cubic spline interpolation functions are fit to the normalized enclosed
+flux profile and the intensity profile.  These are used to find the radius
+enclosing any specified fraction of the flux and to find the direct FWHM of
+the intensity profile.  These are output when \fIsize\fR is "Radius" or
+"FWHM" respectively.
+
+In addition to enclosed flux radius and direct FWHM size measurements
+there are also two size measurements based on fitting analytic profiles.
+A Gaussian profile and a Moffat profile are fit to the final enclosed flux
+profile to the points with enclosed flux less than 80%.  The limit is
+included to minimize the effects of poor background values and to make the
+profile fit be representative of the core of the PSF profile.  These profiles
+are fit whether or not the selected \fIsize\fR requires it.  This is done
+for simplicity and to allow quickly changing the size estimate with the
+":size" command.
+
+The intensity profile functions (with unit peak) are:
+
+.nf
+    I(r) = exp (-0.5 * (r/sigma)**2)			Gaussian
+    I(r) = (1 + (r/alpha)**2)) ** (-beta)		Moffat
+.fi
+
+with parameters sigma, alpha, and beta.  The normalized enclosed flux
+profiles, which is what is actually fit, are then:
+
+.nf
+    F(r) = 1 - exp (-0.5 * (r/sigma)**2)		Gaussian
+    F(r) = 1 - (1 + (r/alpha)**2)) ** (1-beta)		Moffat
+.fi
+
+The fits determine the parameters sigma or alpha and beta (if a
+beta value is not specified by the users).  The reported FWHM values
+are given by:
+
+.nf
+    GFWHM = 2 * sigma * sqrt (2 * ln (2))		Gaussian
+    MFWHM = 2 * alpha * sqrt (2 ** (1/beta) - 1)	Moffat
+.fi
+
+were the units are adjusted by the pixel scale factor.
+
+In addition to the four size measurements there are several additional
+quantities which are determined.  
+Other quantities which are computed are the relative magnitude,
+ellipticity, and position angle.  The magnitude of an individual
+measurement is obtained from the maximum flux attained in the enclosed
+flux profile computation.  Though the normalization and background may be
+adjusted interactively later, the magnitude is not changed from the
+initial determination.  The relative magnitude of an object is then
+computed as
+
+.nf
+    rel. mag. = -2.5 * log (object flux / maximum star flux)
+.fi
+
+The maximum star magnitude over all stars is used as the zero point for the
+relative magnitudes (hence it is possible for an individual object relative
+magnitude to be less than zero).
+
+The ellipticity and positional angle of an object are derived from the
+second central intensity weighted moments.  The moments are:
+
+.nf
+	Mxx = sum { (I - B) * x * x } / sum { I - B }
+	Myy = sum { (I - B) * y * y } / sum { I - B }
+	Mxy = sum { (I - B) * x * y } / sum { I - B }
+.fi
+
+where x and y are the distances from the object center, I is
+the pixel intensity and B is the background intensity.  The sum is
+over the same subpixels used in the enclosed flux evaluation with
+intensities above an isophote which is slightly above the background.
+The ellipticity and position angles are derived from the moments
+by the equations:
+
+.nf
+	M1 = (Mxx - Myy) / (Mxx + Myy)
+	M2 = 2 * Mxy / (Mxx + Myy)
+	ellip = (M1**2 + M2**2) ** 1/2
+	pa = atan (M2 / M1) / 2
+.fi
+
+where ** is the exponentiation operator and atan is the arc tangent
+operator.  The ellipticity is essentially (a - b) / (a + b) where a
+is a major axis scale length and b is a minor axis scale length.  A
+value of zero corresponds to a circular image.  The position angle is
+given in degrees counterclockwise from the x or column axis.
+
+The overall size when there are multiple stars is estimated by averaging
+the individual sizes weighted by the flux of the star as described above.
+Thus, when there are multiple stars, the brighter stars are given greater
+weight in the average size.  This average size is what is given in the
+banner for the graphs and in the printed output.
+
+One of the quantities computed for the graphical analysis is the
+FWHM of a Gaussian or Moffat profile that encloses the same flux
+as the measured object as a function of the level.  The equation are:
+
+.nf
+   FWHM = 2 * r(level) * sqrt (ln(2.) / ln (1/(1-level)))  Gaussian
+
+   FWHM = 2 * r(level) * sqrt (2**(1/beta)-1) /
+	  sqrt ((1-level)**(1/(1-beta))-1)		   Moffat
+.fi
+
+where r(level) is the radius that encloses "level" fraction of the total
+flux.  ln is the natural logarithm and sqrt is the square root.  The beta
+value is either the user specified value or the value determined by fitting
+the enclosed flux profile.
+
+This function of level will be a constant if the object profile matches
+the Gaussian or Moffat profile.  Deviations from a constant show
+the departures from the profile model.  The Moffat profile used in making
+the graphs except for the case where the \fIsize\fR is GFWHM.
+
+The task estimates a value for the best focus and PSF size at that focus
+for each star.  This is done by finding the minimum size at each focus
+value (in case there are multiple measurements of the same star at the same
+focus), sorting them by focus value, finding the focus value with the
+minimum size, and parabolically interpolating using the nearest focus
+values on each side.  When the minimum size occurs at either extreme of the
+focus range the best focus is at that extreme focus; in other words there
+is no extrapolation outside the range of focus values.
+
+The overall best focus and size when there are multiple stars are estimated
+by averaging the best focus values for each star weighted by the
+average flux of the star as described above.  Thus, when there are
+multiple stars, the brighter stars are given greater weight in the
+overall best average focus and size.  This best average focus and
+size are what are given in the banner for the graphs and in the
+printed output.
+
+The log output also includes an average PSF size for all measurements
+at a single focus value.  This average is also weighted by the
+average flux of each star at that focus.
+.ih
+INTERACTIVE GRAPHICS MODE
+The graphics part of \fBstarfocus\fR consists of a number of different
+plots selected by cursor keys.  The available plots depend on the
+number of stars and the number of focus values.  The various plots
+and the keys which select them are summarized below.
+
+.nf
+a  Spatial plot at a single focus
+b  Spatial plot of best focus values
+e  Enclosed flux for stars at one focus and one star at all focus
+f  Size and ellipticity vs focus for all data
+m  Size and ellipticity vs relative magnitude at one focus
+p  Radial profiles for stars at one focus and one star at all focus
+t  Size and ellipticity vs radius from field center at one focus
+z  Zoom to a single measurement
+.fi
+
+If there is only one object at a single focus the only available plot is
+the 'z' or zoom plot.  This has three graphs; a graph of the normalized
+enclosed flux verses scaled radius, a graph of the intensity profile verses
+scaled radius, and equivalent Moffat/Gaussian full width at half maximum verses
+enclosed flux fraction.  The latter two graphs are derived from the
+normalized enclosed flux profile as described in the ALGORITHMS section.
+In the graphs the measured points are shown with symbols, a smooth curve is
+drawn through the symbols and dashed lines indicate the measurement level
+and enclosed flux radius at that level.
+
+Overplotted on these graphs are the Moffat profile fit or the
+Gaussian profile fit when \fIsize\fR is GFWHM.
+
+The zoom plot is always available from any other plot.  The cursor position
+when the 'z' key is typed selects a particular object measurement.
+This plot is also the one presented with the 'g' key when marking objects for
+single exposure images.  In that case the graphs are drawn followed by
+a return to image cursor mode.
+
+There are three types of symbol plots showing the measured PSF size (either
+enclosed flux radius or FWHM) and ellipticity.  These plot the measurements
+verses focus ('f' key), relative magnitude ('m' key), and radius from the
+field center ('t' key).  The focus plot includes all measurements and shows
+dashed lines at the estimated best focus and size.  This plot is only
+available when there are multiple focus values.  It is the initial plot in
+this case for both the 'g' key when there are multiple exposures and when
+the graphical analysis stage is entered after defining the objects.
+
+The magnitude and field radius plots are only available when there are
+multiple objects measured.  The relative magnitude used for a particular
+measurement is the average magnitude of the star over all focus values and
+not the individual object magnitude.  The data shown is for a single focus
+value.  The focus value is selected when typing 'm' or 't' by the focus of
+the nearest object to the cursor in the preceding plot.  When in one of
+these plots, other focus values may be shown by typing <space>, the space
+bar.  This scrolls through the focus values.  The field center for the
+field radius graph may be changed interactively using the ":xcenter" and
+":ycenter" commands.
+
+Grids of enclosed flux vs. radius, intensity profile vs. radius, and
+FWHM vs. enclosed flux fraction are shown with the 'e', 'p', and
+'g' keys respectively.  If there are multiple objects at multiple focus
+values there are two grids. One grid is all objects at one focus and the
+other is one object at all focuses.  The titles identify the object (by
+location) and focus.  The profiles in the grids have no axis labels or
+ticks.  Within each box are the coordinates of the object or the focus
+value, and the PSF size are given.  When there is only one object at
+multiple focus values or multiple objects at only one focus value then
+there is only one grid and a graph of a one object.  The single object
+graph does have axis labels and  ticks.
+
+In the grids there is one profile which is highlighted (by a second
+box or by a color border).  The highlighted profile is the current
+object.  To change the current object, and thus change either
+the contents of the other grid or the single object graphed, one
+can type the space bar to advance to the next object or
+use the cursor and the 'e', 'p', or 'g' key again.  Other keys
+will select another plot using the object nearest the cursor to select
+a focus or object.
+
+Any of the graphs with enclosed flux or intensity profiles vs radius may
+have the profiles of the object with the smallest size overplotted.  The
+overplot has a dashed line, a different color on color graphics devices,
+and no symbols marking the measurement points.  The overplots may be
+enabled or disabled with the ":overplot" command.  Initially it is
+disabled.
+
+The final plots give a spatial representation.  These require more than one
+object.  The 'a' key gives a spatial plot at a single focus.  The space bar
+can be used to advance to another focus.  This plot has a central graph of
+column and line coordinates with symbols indicating the position of an
+object.  The objects are marked with a circle (when plotted at unit aspect
+ratio) whose size is proportional to the measured PSF size.  In addition an
+optional asterisk symbol with size proportional to the relative
+brightness of the object may be plotted.  This symbol is toggled with the
+'s' key.  On color displays the circles may have two colors, one if object
+size is above the average best size and the other if the size is below the
+best size.  The purpose of this is to look for a spatial pattern in the
+smallest PSF sizes.
+
+Adjacent to the central graph are graphs with column or line as one
+coordinate and radius or ellipticity as the other.  The symbols
+are the same as described previously.  These plots can show spatial
+gradients in the PSF size and shape across the image.
+
+The 'b' key gives a spatial plot of the best focus estimates for each
+object.  This requires multiple objects and multiple focus values.
+As discussed previously, given more than one focus a best focus
+value and size at the best focus is computed by parabolic interpolation.
+This plot type shows the object positions in the same way as the 'a'
+plot except that the radius is the estimated best radius.  Instead
+of adjacent ellipticity plots there are plots of best focus verses
+columns and lines.  Also the two colors in the symbol plots are
+selected depending on whether the object's best focus estimate is
+above or below the overall best focus estimate.  This allows seeing
+spatial trends in the best focus.
+
+In addition to the keys which select plots there are other keys which
+do various things.  These are summarized below.
+
+.nf
+?  Page cursor command summary
+d  Delete star nearest to cursor
+i  Information about point nearest the cursor
+n  Normalize enclosed flux at x cursor position
+o  Offset enclosed flux by adjusting background
+q  Quit
+r  Redraw
+s  Toggle magnitude symbols in spatial plots
+u  Undelete all deleted points
+x  Delete nearest point, star, or focus (selected by query)
+<space> Step through different focus or stars in current plot type
+.fi
+
+The help, redraw, and quit keys are provide the standard functions.
+The 's' and space keys were described previously.  The 'i' key
+locates the nearest object to the cursor in whatever plot is shown and
+prints one line of information about the object on the graphics device
+status area.
+
+The 'd' key deletes the star nearest the cursor in whatever plot is
+currently displayed.  Deleting a star deletes all measurements of an object
+at different focus values.  To delete all objects from an image, all focus
+values for one star (the same as 'd'), all objects at one focus, or a
+single measurement, the 'x' key is used.  Typing this key produces a query
+for which type of deletion and the user responds with 'i', 's', 'f', or
+'p'.  The most common use of this is to delete all objects at the extreme
+focus values.  Deleted measurements do not appear in any subsequent
+graphics, are excluded from all computations, and are not output in the
+results.  The 'u' key allows one to recover deleted measurements.  This
+undeletes all previously deleted data.
+
+Due to various sources of error the sky value may be wrong causing
+the enclosed flux profile to not converge properly but instead
+decreases beyond some point (overestimated sky) or linearly
+increases with radius (underestimated sky).  This affects the size
+measurement by raising or lowering the normalization and altering
+the shape of the enclosed flux profile.  The 'n' and 'o' keys allow
+fudging the enclosed flux profiles.  These keys apply only in
+the zoom plot of the enclosed flux profile or the case where
+a single enclosed flux profile is shown with the 'e' key; in other
+words plots of the enclosed flux which have axes labels.
+
+The 'n' key normalizes the enclosed flux profile at the point
+set by the x position of the cursor.  The 'o' key increases or
+decreases the background estimate to bring curve up or down to
+the point specified by the cursor.  The effect of this is to
+add or subtract a quadratic function since the number of pixels
+at a particular radius varies as the square of the radius.
+To restore the original profile, type 'n' or 'o' at a radius
+less than zero.
+
+The colon commands, shown below, allow checking or changing parameters
+initially set by the task parameters, toggling the overplotting of the
+smallest PSF profiles, and showing the current results.  The overplotting
+option and the contents of the results displayed by :show were described
+previously.
+
+.nf
+:beta <val>     Beta parameter for Moffat fits
+:level <val>	Level at which the size parameter is evaluated
+:overplot <y|n> Overplot the profiles from the narrowest profile?
+:radius <val>   Change profile radius
+:show <file>	Page all information for the current set of objects
+:size <type>	Size type (Radius|FWHM)
+:scale <val>	Pixel scale for size values
+:xcenter <val>	X field center for radius from field center plots
+:ycenter <val>	Y field center for radius from field center plots
+.fi
+
+The important values which one might want to change interactively are
+the measurement level and the profile radius.  The measurement level
+directly affects the results reported.  When it is changed the sizes
+of all object PSFs are recomputed and the displayed plots and title
+information are updated.  The profile radius is the
+maximum radius shown in plots and used to set the enclosed flux normalization.
+It does not affect the object centering or sky region definition and
+evaluation which are done when the image data is accessed.  Because
+the objects are not remeasured from the image data the radius may
+not be made larger than the radius defined by the task parameter though
+it may be decreased and then increased again.
+.ih
+EXAMPLES
+1.  A multiple exposure frame is taken with 7 exposures of a bright
+star, each exposure shifted by 50 pixels to lower line positions, with a
+double gap at the end.  The exposure pattern is typical of Kitt Peak and
+the default values for the direction and gap position are applicable.  The
+default focus value numbering and measurements in pixels are also used.
+
+.nf
+cl> starfocus focus1 nexp=7 step=50
+<The image is displayed and the image cursor activated>
+<The bright star is marked with 'm'>
+<Marking is finished with 'q'>
+<A graph of FWHM vs focus index is shown>
+<Exit with 'q'>
+NOAO/IRAF IRAFV2.10.3 valdes@puppis Wed 16:09:39 30-Jun-93
+  Best focus of 4.12073 with FWHM (at 50% level) of 3.04
+
+   Image  Column    Line     Mag   Focus    FWHM   Ellip      PA SAT
+  focus1  536.63  804.03    0.07      1.  13.878    0.06     -11
+	  535.94  753.28   -0.11      2.   8.579    0.09      89
+	  535.38  703.96   -0.08      3.   5.184    0.11     -87
+	  537.12  655.36   -0.02      4.   3.066    0.07     -77
+	  534.20  604.59    0.00      5.   4.360    0.10      74
+	  534.41  554.99   -0.00      6.   9.799    0.09     -35
+	  534.83  456.08    0.16      7.  12.579    0.13     -10
+.fi
+
+The estimated best focus is between the 4th and 5th focus setting
+and the best focus FWHM is 3.04 pixels.
+
+Note that in more recent Kitt Peak multiple exposure focus images the
+starting focus value, the focus step, the number of exposures, and
+the shift are recorded in the image header with the keywords
+FOCSTART, FOCSTEP, FOCNEXPO, and FOCSHIFT.  Thus the task parameters
+\fIfocus\fR, \fIfstep\fR, \fInexposures\fR, and \fIstep\fR may be
+set to those names.  However, rather than use \fBstarfocus\fR
+one would use the more convenient \fBkpnofocus\fR.
+.ih
+SEE ALSO
+.nf
+imexamine, implot, kpnofocus, pprofile, pradprof, psfmeasure, radlist,
+radplt, radprof, ranges, specfocus, splot
+.endhelp