diff options
Diffstat (limited to 'noao/obsutil/src/doc/starfocus.hlp')
| -rw-r--r-- | noao/obsutil/src/doc/starfocus.hlp | 820 |
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 |