imexamine -- examine images using image display, plots, and text
imexamine [input [frame]]
In addition to these three reserved WCS names, the name of any user WCS defined for the reference image may be given. A user world coordinate system may be any linear or nonlinear world system.
The various graphs and the aperture sum command have parameters defined in additional parameter sets. The parameter sets are hidden tasks with the first character being the cursor command graph key that uses the parameters followed by "imexam". The parameter sets are:
cimexam Parameters for column plots eimexam Parameters for contour plots himexam Parameters for histogram plots jimexam Parameters for line 1D gaussian fit plots kimexam Parameters for column 1D gaussian fit plots limexam Parameters for line plots rimexam Parameters for radial profile plots and aperture sums simexam Parameters for surface plots vimexam Parameters for vector plots (centered and endpoint)
The same parameters dealing with graph formats occur in many of the parameter sets while some are specific only to one parameter set. In the summary below those common to more than one parameter set are shown only once. The characters in parenthesis are the graph key prefixes for the paraemter sets in which the parameter occurs.
Images are examined using an image display, various types of plots, and text output. Commands are given using the image display cursor and/or graphics cursor. This task brings together many of the features of the IRAF image display and graphics facilities with some simple image analysis capabilities.
If use_display is yes the image display is used to examine images. When no input list is specified images may be loaded with the d key, frames selected with n, p, and ":select", and the scaled contents of the display frame buffer examined if the image itself is not available.
When an input list is specified the n, p, and ":select" allow moving about the list and new images may be added to the end of the list with d. Images are automatically loaded as they are selected if not currently loaded. Two parameters control how the frames are loaded. The nframes parameter determines which frames are available. Within the available frames images may be loaded by cycling through them if allframes is yes or in the last loaded frame (initially frame 1) if it is no.
When reading the image cursor the frame and the name of the image in the frame are determined. Therefore images may also be selected by changing the frame externally or if the image cursor input is changed from the standard image display to text or file input.
The d command displays an image using the template CL command given by parameter display . Usually this is the standard IRAF tv.display command though in some cirmcumstances other commands like plot.contour may be used. This command may be used to display an image even if use_display is no.
This task is generally intended for interactive use with an image display. However it is possible to disable use of the image display and change the image cursor input to a graphics cursor, a file, or typed in by the user. In this case an input image list is most appropriate but if one is missing, a query will be issued each time a command requiring an image is given.
Commands are given using cursor input. Generally the image cursor is used to select points in the images to be examined and the key typed selects a particular operation. In addition to the image cursor the graphics cursor is sometimes useful. First, it gives access to the graphics cursor mode commands (see cursors ) such as annotating, saving or printing a graph, expanding and roaming, and printing cursor positions. Second, it can give a better perspective on the data for cursor positions than the image cursor. And lastly, it may be needed when an image display is not available. The commands g and i select between the graphics and image cursors. Initially the image cursor is read.
Interpretation of the graph coordinate in terms of an image coordinate depends on the type of graph as described below.
There are some special features associated with cursor input in IRAF which might be useful in some circumstances. The image display cursor can be reset to be a text cursor, graphics cursor, or image cursor by setting the environment variable "stdimcur" to "text", "stdgraph", or "stdimage" respectively. Text cursor input consists of the x and y coordinates, a frame number, and the key or colon command. Another form of text input is to set the value of the cursor input parameter to a file containing cursor commands. There are two special features dealing with text cursor input. If only x and y are entered the default key parameter defkey determines the command. This is particularly useful if one has a list of pixel positions prepared by some other program. The second feature is that for commands not requiring coordinates they may be left out and the command key or colon command entered.
The following commands produce text output which may also be appended to a logfile.
The radius of the photometry and fitting aperture is specified by the radius parameter and the iteration parameter. Iteration of the fitting radius and printing of the final radius is only done for the a key. If the number of iterations is one then the radius is not adjusted. If it is greater than one then the direct FWHM (described) below is used to adjust the radius. At each iteration the new radius is set to three times the direct FWHM (which is six times the radius at half-maximum). The radius is printed as part of the output.
If the background subtraction option is selected a concentric circular annulus is defined. The inner edge is separated from the object aperture by a specified buffer distance and the outer edge is defined by a width for the annulus. The type of background used is determined by the parameters xorder and yorder . If either parameter is zero then a median of the background annulus is determined. If 1 or greater a polynomial surface of the specified number of terms is fit. Typically the orders are 1 for a constant or 2 for a plane. The median or fitted surface values within the object aperture are then subtracted.
The flux within the circular aperture is computed by simply summing the pixel values with centers within the specified radius of the center position. No partial pixel adjustments are made. If the flux is positive a magnitude is computed as
magnitude = magzero - 2.5 * log10 (flux)
where the magnitude zero point is a user defined parameter.
In addition to the flux, the second intensity momemnts are used to compute an ellipticity and position angle. The equations defining the moments and related parameters are:
Mxx = sum (x * x * I) / sum (I) Myy = sum (y * y * I) / sum (I) Mxy = sum (x * y * I) / sum (I) e = sqrt ((Mxx - Myy) ** 2 + (2 * Mxy) ** 2) / (Mxx + Myy) pa = 0.5 * atan (2 * Mxy / (Mxx - Myy))
A nonlinear least squares profile of fixed center and zero background is fit to the radius and flux values of the background subtracted pixels to determine a peak intensity and FWHM. The profile type is set by the fittype parameter. The choices are "gaussian" and "moffat". If the profile type is "moffat" there is an additional parameter "beta". This value may be specifed to fix it or given as INDEF to also be determined. The profile equations are:
I = Ic exp (-0.5 * (r / sigma)**2) (fittype = "gaussian") I = Ic (1 + (r / alpha)**2)**(-beta) (fittype = "moffat")
where Ic is the peak value, r is the radius, and the parameters are sigma, alpha, and beta. The sigma and alpha values are converted to FWHM in the reported results.
Weights which are the inverse square of the pixel radius are used. This has the effect of giving equal weight to all parts of the profile instead of being overwhelmed by the larger number of pixels are larger radii. An additional weighting factor is used for pixels outside the half-maximum radius (as determined using the algorithm described below). The weights are
wt = exp (-(r/rhalf - 1)**2) for r/rhalf > 1
where rhalf is the radius at half-maximum. This has the effect of reducing the contribution of the profile wings.
The above fit is done to the individual pixel values with a radius measured to the center of the pixel. For the a key two additional measurements are made on a azimuthally averaged radial profile with a finer sampling of the radial bins. This uses the same algorithms for centering, background estimation, and FWHM measurement as in the task psfmeasure . The centering is essentially the same as described above but the background estimation is a mode of the sky annulus pixels. Note that the centering and background subtraction are done for these measurements regardless of the the center and background parameters which apply only to the photometry and profile fitting to the individual pixel values.
To form the radially smoothed profile an image interpolator function is fit to the region containing the object. The enclosed flux profile (total flux within a particular radius) is computed. The sampling is done at a much finer resolution than individual pixels. The subsampling scheme is that described in psfmeasure and is such that the center of the profile is more finely sampled than the edges of the profile.
Because the image interpolator function may not be very good for narrow profiles a second iteration is done if the radius enclosing half the flux is less than two pixels. In this second iteration an analytic, radially symmetric Gaussian profile is subtracted from the image raster and the interpolation function is fit to the residuals. Subpixel values are then computed by evaluating the analytic function plus the interpolated residual value.
There are two FWHM measurements computed using the enclosed flux radial profile. One is to fit a Gaussian or Moffat profile to the enclosed flux profile. The type is selected by the same fittype parameter used to select the profile to fit to the individual pixel values. As with the direct fit the Moffat beta value may be fixed or included in the fit. The FWHM of the fit is then printed on the status line, terminal output, and log file.
The other FWHM measurement directly measure the FWHM independent of a profile model. The derivative of the enclosed flux profile is computed. This derivative is the azimuthally averaged radial profile with the radial bin sampling mentioned above. The peak of this profile is found and the FWHM is twice the radius of the profile at half the peak value. This "direct FWHM" is part of the output and is also used for the iterative adjustment of the fitting radius as noted above.
This aperture photometry and FWHM tool is intended only for general image analysis and quick look measurements. The background fitting, photometry, and FWHM techniques used are not intended for serious astronomical photometry; other packages, e.g., noao.digiphot.apphot , should be used if precise results are are desired.
The following commands produce graphics output to the specified graphics device (normally the graphics terminal).
The following commands control useful features of the task.
Sometimes one wants to explicitly enter the coordinates for a command. This may be done with a colon command having the following syntax:
:<column> <line> <key>
where column and line are the coordinates and key is the command. If the line is not given then <column> = <line>. For the frequently used line and column plots there is also the simple syntax:
:c<column> or :l<line>
with no space, e.g., ":l64".
Every parameter except the input image list and the display command may be queried or set by a colon command. In addition the parameter sets for the various graphs and aperture sum algorithm may be edited using the eparam editor and reinitialized to default values using the unlearn command. There are a large number of parameters as well as many graph types / parameter sets. To achieve some consistency and order as well as simplify the colon commands several things have been done.
Many parameters occur in more than one graph type. This includes things like graph labeling, tickmarks, and so forth. When issuing a colon command for one of these parameters the current graph type is assumed to be the one affected. If the graph type is wrong or no graph has been made then a warning is given.
If the parameter only occurs in one parameter set then the colon command may be used with any current graph. However, if the parameter affects the current graph and the automatic redraw option is set then the graph will be redrawn.
The eparam and unlearn commands also apply by default to the parameters for the current graph. However, they may take the keystroke character for the graph as an argument to override this. If the current graph parameters are changed and the automatic redraw option is set then the graph will be redrawn.
The important colon commands x and y affect the x1, y1, x2, y2 parameters in most of the graphs. They are frequently used to override the automatic graph scaling. If no arguments are given the window limits are set to INDEF resulting in plotting the full range of the data plus a buffer. If two values are given then only that range of the data will be plotted.
? Print help a Aperture sum, moment parameters, and profile fit b Box coordinates for two cursor positions - c1 c2 l1 l2 c Column plot d Load the image display e Contour plot f Redraw the last graph g Graphics cursor h Histogram plot i Image cursor j Fit 1D gaussian to image lines k Fit 1D gaussian to image columns l Line plot m Statistics image[section] npixels mean median stddev min max n Next frame or image o Overplot p Previous frame or image q Quit r Radial profile plot with fit and aperture sum values s Surface plot t Output image centered on cursor (parameters output, ncoutput, nloutput) u Centered vector plot from two cursor positions v Vector plot between two cursor positions w Toggle write to logfile x Print coordinates col line pixval [xorign yorigin dx dy r theta] y Set origin for relative positions z Print grid of pixel values - 10 x 10 grid , Quick Gaussian/Moffat photometry . Quick Gaussian/Moffat radial profile plot and fit
Explicit image coordinates may be entered using the colon command syntax:
:<column> <line> <key>
where column and line are the image coordinates and the key is one of the cursor keys. A special syntax for line or column plots is also available as :c# or :l# where # is a column or line and no space is allowed.
Other colon commands set or show parameters governing the plots and other features of the task. Each graph type has it's own set of parameters. When a parameter applies to more than one graph the current graph is assumed. If the current graph is not applicable then a warning is given. The "eparam" and "unlearn" commands may be used to change many parameters and without an argument the current graph parameters are modified while with the graph key as an argument the appropriate parameter set is modified. In the list below the graph key(s) to which a parameter applies are shown.
allframes Cycle through all display frames to display images angh s Horizontal angle for surface plot angv s Vertical angle for surface plot autoredraw cehlrsuv Automatically redraw graph after colon command? autoscale h Adjust number of histogram bins to avoid aliasing axes s Draw axes in surface plot? background jkr Subtract background for radial plot and photometry? banner cehjklrsuv Include standard banner on plots? beta ar Moffat beta parameter (INDEF to fit or value to fix) boundary uv Boundary extension type for vector plots box cehjklruv Draw box around graph? buffer r Buffer distance for background subtraction ceiling es Data ceiling for contour and surface plots center jkr Find center for radial plot and photometry? constant uv Constant value for boundry extension in vector plots dashpat e Dash pattern for contour plot eparam cehjklrsuv Edit parameters fill e Fill viewport vs enforce unity aspect ratio? fitplot r Overplot profile fit on data? fittype ar Profile fitting type (gaussian|moffat) floor es Data floor for contour and surface plots interval e Contour interval (0 for default) iterations ar Iterations on fitting radius label e Draw axis labels for contour plot? logfile Log file name logx chjklruv Plot x axis logrithmically? logy chjklruv Plot y axis logrithmically? magzero r Magnitude zero for photometry majrx cehjklruv Number of major tick marks on x axis majry cehjklruv Number of major tick marks on y axis marker chjklruv Marker type for graph minrx cehjklruv Number of minor tick marks on x axis minry cehjklruv Number of minor tick marks on y axis naverage cjkluv Number of columns, lines, vectors to average nbins h Number of histogram bins ncolumns ehs Number of columns in contour, histogram, or surface plot ncontours e Number of contours (0 for default) ncoutput Number of columns in output image ncstat Number of columns in statistics box nhi e hi/low marking option for contours nlines ehs Number of lines in contour, histogram, or surface plot nloutput Number of lines in output image nlstat Number of lines in statistics box output Output image root name pointmode chjkluv Plot points instead of lines? radius r Radius of object aperture for radial plot and photmetry round cehjklruv Round axes to nice values? rplot jkr Radius to plot in 1D and radial profile plots select Select image or display frame sigma jk Initial sigma for 1D gaussian fits szmarker chjklruv Size of marks for point mode ticklabels cehjklruv Label ticks? title cehjklrsuv Optional title for graph top_closed h Close last bin of histogram unlearn cehjklrsuv Unlearn parameters to default values wcs World coordinate system for axis labels and readback width jkr Width of background region x [min max] chjklruv Range of x to be plotted (no values for autoscaling) xformat Coordinate format for column world coordinates xlabel cehjklrsuv Optional label for x axis xorder jkr X order of surface for background subtraction y [min max] chjklruv Range of y to be plotted (no values for autoscaling) yformat Coordinate format for line world coordinates ylabel cehjklrsuv Optional label for y axis yorder r Y order of surface for background subtraction z1 h Lower intensity value limit of histogram z2 h Upper intensity value limit of histogram zero e Zero level for contour plot
The following example illustrates many of the features in a descriptive way using the standard image dev$pix.
cl> imexam dev$pix nframes=2 [The image is loaded in the display if not already loaded] <Image cursor> l # Make a line plot <Image cursor> e # Make a contour plot <image cursor> d # Load a new image image name: saga display frame (1:) (1): 2 <Image cursor> e # Make a contour plot <Image cursor> g # Switch to graphics cursor <Graph cursor> u # Mark the center of a vector <Graph cursor> u # Mark endpoint make a vector plot <Graph cursor> i # Go back to display <Image cursor> r # Select star and make radial plot <Image cursor> :rplot 10 # Set radius of plot <Image cursor> :epar # Set radius plot parameters <Image cursor> c # Make column plot <Image cursor> :100 l # Line 100 of image 1 <Image cursor> :20 30 e # Contour plot at (20,30) <Image cursor> p # Go to previous image <Image cursor> n # Go to next image <Image cursor> :sel 1 # Select image 1 <Image cursor> :log log # Set log file <Image cursor> w # Begin logging Log file log is open <Image cursor> a # Do aperture sum on star 1 <Image cursor> a # Do aperture sum on star 2 <Image cursor> a # Do aperture sum on star 3 <Image cursor> a # Do aperture sum on star 4 <Image cursor> w # Close log file Log file log is closed <Image cursor> y # Mark position of galaxy center <Image cursor> x # Print position relative to center <Image cursor> x # Print position relative to center <Image cursor> s # Make surface plot <Image cursor> q # Quit
If an operation is interrupted, e.g., an image display or surface plot, imexamine is terminated rather than the operation in progress.
When used on a workstation imexamine attempts to always position the cursor to the window (text, image, or graphics) from which input is being taken. Moving the mouse manually while the program is also trying to move it can cause the mouse to be positioned to the wrong window, requiring that it be manually moved to the window from which input is currently being taken.
When entering a colon command in image cursor mode, if one types too fast the characters typed before the mouse is moved to the input window will be lost. To avoid this, pause a moment after typing the colon, before entering the command, and verify that the mouse has been moved to the correct window. In the future colon command input will be entered without moving the mouse out of the image window, which will avoid the problem.
(a and r): New estimates fo the FWHM were added to the a and r keys. These include the Moffat profile fit noted above, a direct measurement of the FWHM from the radially binned profile, and a Gaussian or Moffat fit to the radial enclosed flux profile. The output from these keys was modified to include the new information.
(a and r): The direct FWHM may be used to iteratively adjust the fitting radius to lessen the dependence on the initial fitting radius value.
(, and .): New keys to do the Gaussian or Moffat fitting without iteration or the enclosed flux and direct measurements. The output format is the same as the previous version.
(k): Added a kimexam parameter set.
cursors, eparam, unlearn, plot.*, tvmark, digiphot.*, apphot.*, implot, splot, imedit, radplt, imcntr, imhistogram, imstatistics, display psfmeasure.