diff options
Diffstat (limited to 'pkg/images/tv/doc')
| -rw-r--r-- | pkg/images/tv/doc/Tv.hlp | 357 | ||||
| -rw-r--r-- | pkg/images/tv/doc/bpmedit.hlp | 155 | ||||
| -rw-r--r-- | pkg/images/tv/doc/display.hlp | 555 | ||||
| -rw-r--r-- | pkg/images/tv/doc/imedit.hlp | 493 | ||||
| -rw-r--r-- | pkg/images/tv/doc/imexamine.hlp | 1043 | ||||
| -rw-r--r-- | pkg/images/tv/doc/tvmark.hlp | 405 | ||||
| -rw-r--r-- | pkg/images/tv/doc/wcslab.hlp | 698 |
7 files changed, 3706 insertions, 0 deletions
diff --git a/pkg/images/tv/doc/Tv.hlp b/pkg/images/tv/doc/Tv.hlp new file mode 100644 index 00000000..c48bbe2e --- /dev/null +++ b/pkg/images/tv/doc/Tv.hlp @@ -0,0 +1,357 @@ +.helpsys dcontrol Feb84 "Image Display Control" +.ce +\fBImage Display Control Software\fR +.ce +Technical Specifications +.ce +February 17, 1984 + + +.nh +Virtual Display Characteristics + + The display device is assumed to have N image memories or frames, +where N is at least one. All frames are assumed to be the same size and depth. +The frame size and depth (number of bits per pixel) are constant for a device. +There should be at least one graphics frame. The virtual interface associates +one graphics frame with each image frame, but at the device level the graphics +may be or-ed together and displayed on a single plane, if necessary. +A lookup table is associated with each image frame buffer and with each +color gun. The input of a color gun is the sum of the outputs of zero +or more frame buffers. There must be at least one cursor. + +.nh 2 +Basic Functions + + The virtual display device is assumed to provide the following +minimal set of basic functions. +.ls 4 +.ls [1] +Read or write an image frame buffer. Random addressability of pixels +is not assumed; writes may be aligned on image lines if necessary. +The ability to write more than one image line in a single transfer is assumed. +.le +.ls [2] +Erase an entire image frame buffer. +.le +.ls [3] +Read or write an image frame lookup table. +.le +.ls [4] +Read or write the pseudocolor lookup table. +.le +.ls [5] +Connect the output of one or more image frame lookup tables to a +color gun (used to select the frame to be displayed, etc.). +.le +.ls [6] +Read or write the position of a cursor. +.le +.ls [7] +Read, write, or "or into" a graphics overlay bit plane. A one bit +graphics plane is associated with each image frame. Graphics planes +may be erased and turned on and off independently of each other and +the image planes. A read or write operation may reference any combination +of graphics planes simultaneously, permitting multicolor vector graphics. +A single lookup table is used to assign a color to each graphics plane. +.le +.le + + +The following functions are supported but are not required. +.ls +.ls [8] +Zoom and pan. +.le +.ls [9] +Split screen: simultaneous display of any two frames, horizontal or vertical +split through the center of the display. +.le +.le + + +Blinking of two or more image frames is provided in software. Character and +vector generation in the graphics overlays is only provided in software in the +current interface. + +.nh 2 +Lookup Tables + + A monochrome lookup table is associated with each image frame and with +each of the three color guns (red, green, and blue). A lookup table may be +read and written independently of any other lookup table or image frame. +The image frame lookup tables are used principally for window stretch +enhancement (contrast and dc offset), and the color lookup tables are used +for pseudocolor. + +Our model assumes that the input of each color gun may be connected to the +sum of the lookup table outputs of zero or more image frames. Furthermore, +each color gun assignment may be specified independently of that for any +other color gun. The more common display modes are shown below. The table +illustrates the assignment of image frames to color guns. If only one image +frame combination appears in the list, that one combination is taken to be +assigned to each gun. Thus, "RGB = 123" indicates that the \fIsum\fR of the +outputs of frames 1, 2, and 3 is assigned to \fIeach\fR of the three color guns. + +.nf + RGB = 1 single frame monochrome, pseudocolor, etc. + RGB = 1,2,3 true color (R=1, G=2, B=3) + RGB = 123 multi frame monochrome, pseudocolor, etc. +.fi + +On many displays, there will be restrictions on the ways in which frames +may be assigned to guns. For example, many displays will not permit a gun +to be assigned to more than one frame. + +Our model also associates a single monochrome lookup table with each of +the three color guns. By feeding the same input into each of the guns, +but loading a different lookup table into each gun, many types of +pseudocolor enhancement are possible. If monochrome enhancement or +true color is desired, the color lookup tables are normally all set to +provide a one to one mapping, effectively taking them out of the circuit. + +.nh 2 +Cursors + + Each image display device is assumed to have at least one cursor, +with the following associated control functions: +.ls 4 +.ls [1] +Read cursor position. The one-indexed coordinates of the center of the +visible cursor are returned. The origin is assumed to be consistent +with that used for reading and writing image data, but is otherwise +undefined. A read should return immediately (sample mode), rather than +wait for some external event to occur (event mode). +.le +.ls [2] +Write cursor position. A read followed by a write does not move the +cursor. Cursor motions do not affect image data in any way. +.le +.ls [3] +Disable cursor (invisible cursor). +.le +.ls [4] +Enable cursor. +.le +.ls [5] +Blink cursor. +.le +.le + +.nh +Display Control Software + + A single executable process contains all display control functions. +A separate process (executable image) is provided for each display device. +All display control processes behave identically at the CL level. The STDIMAGE +environment variable is used to select the particular display control process +to be run. + + +.ks +.nf + user interface + display control process + virtual device interface + physical device +.fi + +.ce +Structure of the Display Control Software +.ke + + +The display control process consists of a device independent part and a +device dependent part. The device dependent part provides the virtual +device control and data functions identified in section 1. +The specifications of the virtual device interface have not yet been written, +though a prototype interface has been implemented for the IIS model 70. +In the long run, the virtual device interface may be provided by an +extension to GKS (the Graphical Kernel System). + +.nh 2 +User Interfaces + + At least two user interfaces are planned for display control. The first, +and most transportable, interface will be a conventional CL level command +interface. Separate commands will be provided for frame selection, +enhancement selection, frame erase, windowing, blinking, etc. The second +interface will be a menu driven interface run on a dedicated terminal +with touch screen overlay for input. This latter interface will run +asynchronously with the user terminal, and will therefore provide access +to the display at all times, as well as increased functionality and +interactiveness. Both user interfaces will use the same virtual device +interface. + +.nh 3 +The Display Control Package + + The command oriented image display control interface will be implemented +as a set of CL callable tasks in the package \fBimages.dcontrol\fR. +The new \fBdcontrol\fR package will include the \fBdisplay\fR program, +used to load images into the image display device, and any other programs +specifically concerned with the image display device. +The specifications for the package are given below (excluding the \fBdisplay\fR +program, which is documented elsewhere). All control functions operate +independently of each other, i.e., without side effects, unless otherwise noted. + + +.ks +.nf + blink dsave initdisplay rgb + contour frame lumatch splitscreen + display grclear monochrome window + drestore imclear pseudocolor zoom +.fi + +.ce +The \fBDcontrol\fR Package +.ke + + +The basic \fBdcontrol\fR package is shown above, and further documentation +is given below. Additional routines will be added in the future. +These will include: +.ls +.ls [1] +An display routine wherein the image histogram is computed and plotted, +then the user interactively marks the intensity region to be mapped into +the display, using the graphics cursor. +.le +.ls [2] +A routine for reading out a monochrome display into an imagefile, +which is then plotted on a hardcopy device (i.e., the Dicomed). +.le +.ls [3] +A routine for drawing vectors, marks, and text strings into a graphics +overlay. +.le +.le + +The display status should not be modified upon entry to the package, i.e., +the display should not change except under control of the user. +For example, if a new user logs on and a previous user's image is still +loaded and being displayed in pseudocolor, the control software should not +suddenly change the display mode to RGB, merely because the new user left +the display in RGB mode when they last logged off. The physical display +device is the important reference frame. +[N.B.: See also \fBdsave\fR and \fBdrestore\fR]. + +.ls +.ls \fBblink\fR (frame1, frame2 [, ... frameN] [, rate=1]) +The indicated frames are blinked at a rate given by the hidden parameter +\fIrate\fR. The positional arguments are the frame numbers; +a variable number of arguments are permitted. The order of the arguments +determines the order in which the frames are displayed. The same frame +may appear any number of times in the list, permitting different frames +to be displayed for various lengths of time. +.le +.ls \fBcontour\fR ([frame]) +The operation of this routine is very similar to that of \fBwindow\fR. +A cursor device is interactively used to control the spacing and width +of black contour lines, written with equal spacing into the image +lookup table. The window transfer function is not changed, other than +to black out the regions where the contour bands fall. Since only the +image frame lookup table is affected, this routine may be used with any +form of enhancement (i.e., pseudocolor). +.le +.ls \fBdsave\fR (save_file [, image=1234, graphics=1234]) +The full control status of the display, and optionally the image and +graphics memories, are saved in the named savefile for later restoration by +\fBdrestore\fR. By default all image and graphics memories are saved; +the hidden parameters \fBimage\fR and \fBgraphics\fR may be used to +indicate the specific image frames or graphics planes to be saved, +if desired. +.le +.ls \fBdrestore\fR (savefile) +The display device is restored to a previously saved state from the named +savefile. +.le +.ls \fBframe\fR (frame_number) +Select single frame mode and display the indicated frame. Frame enhancement +is not affected. This command will clear any multiple frame modes +(rgb, blink, split screen, etc.) previously in effect. +.le +.ls \fBgrclear\fR (frame) +The specified graphics frame is cleared. If the frame number is zero, +all graphics frames are cleared. +.le +.ls \fBimclear\fR (frame) +The specified image frame is cleared. If the frame number is zero, +all image frames are cleared. +.le +.ls \fBinitdisplay\fR +Initializes the image display to a default (device dependent) state. +All image and graphics memories are cleared, all lookup tables are +set to a default mapping (usually one-to-one), the cursor is centered +and enabled, single frame monochrome enhancement is selected, zoom, +blink, etc. are disabled, and frame one is selected for display. +.le +.ls \fBmonochrome\fR +Select monochrome enhancement (black and white). +.le +.ls \fBlumatch\fR (frame, reference_frame) +The image frame lookup table of the first frame is matched to that of +the reference frame. +.le +.ls \fBpseudocolor\fR (type_of_pseudocolor [, ncolors=64]) +Select one of the many possible pseudocolor enhancement modes. A single +string type argument selects the type of enhancement to be displayed. +The hidden parameter \fBncolors\fR controls the maximum number of +colors to be displayed; permissible values are limited to powers of +two. Pseudocolor is a contrast enhancement technique, and is most useful for +smooth images. The types of pseudocolor enhancement currently implemented +are the following: +.ls +.ls linear +The full range of greylevels are uniformly mapped into a spectrum of colors +ranging from blue through red. +.le +.ls random +A randomly selected color is assigned to each output greylevel. +This mode provides maximum discrimination between successive greylevels. +.le +.le +.sp +Selecting a pseudocolor or monochrome enhancement mode does not change the +windowing. After selecting an enhancement mode, \fBwindow\fR may be used +to control the number and range of color or grey levels in the image. +The number of greylevels or colors actually displayed will depend on the +smoothness of the input frames, and on how the input frames are windowed. +.le +.ls \fBrgb\fR [red=1, green=2, blue=3] +True color mode is selected, i.e., the specified red frames are mapped +to the red gun, the green frames are mapped to the green gun, and so on. +The hidden parameters \fIred\fR, \fIgreen\fR, and \fIblue\fR define +the mapping of image frames to guns. On some displays, it may be possible +to additively assign more than one frame to a single gun, i.e., "red=123" +would assign the sum of frames 1 through 3 to the red gun. +If pseudocolor enhancement was previously in effect it may or may not +be cleared, depending on the display characteristics. +.le +.ls \fBsplitscreen\fR (frame, frame [, vertical=yes]) +Two images are displayed simultaneously, one on either half of the image. +The two images may be split either horizontally or vertically. +.le +.ls \fBwindow\fR [frame] [, ...frame] +This command causes a linear mapping function to be repetitively loaded +into the lookup table for one or more image frames. If no frame +arguments are given, the frame or frames currently displayed are windowed. +In RGB mode, for example, all frames are simultaneously windowed by +default. The \fBhjklHJKL\fR keys on the terminal, the trackball, +or some other analog input device associated with the display, may be used +to interactively adjust the mapping. As the mapping is changed, the cursor +will be seen to move on the display. Vertical motions control the contrast +and whether or not a positive or negative image is displayed; the highest +contrast lies furthest from the center. Horizontal motions adjust the dc +offset. [N.B.: Initialize the cursor position to reflect the current mapping +before entering the loop, to avoid any abrupt changes in the windowing.] +.le +.ls \fBzoom\fR (scale_factor) +The current display is magnified by the indicated scale factor, which +is normally limited to small powers of two (i.e., 1, 2, 4, and 8). +While in zoom mode, the cursor controls the position of the viewport window +on the full image. +.le +.le +.endhelp diff --git a/pkg/images/tv/doc/bpmedit.hlp b/pkg/images/tv/doc/bpmedit.hlp new file mode 100644 index 00000000..2350b846 --- /dev/null +++ b/pkg/images/tv/doc/bpmedit.hlp @@ -0,0 +1,155 @@ +.help bpmedit Aug07 images.tv +.ih +NAME +bpmedit -- examine and edit bad pixel masks associated with images +.ih +USAGE +bpmedit images +.ih +PARAMETERS +.ls images +List of images whose bad pixel masks are to be edit. The images must +contain the keyword BPM whose value is an existing bad pixel mask to +be edit. If the keyword is missing or the mask does not exit a warning +is issued and the task proceeds to the next image. +.le +.ls bpmkey = "BPM" +The mask to be edited is defined by the value of this keyword. +.le +.ls frame = 1 +The display frame where the image with the mask overlay is shown. +.le +.ls refframe = 2 +The display frame with the image without the mask is shown. +.le +.ls command = "display ..." +Command for displaying and updating the mask overlay. This is the +command used with \fBimedit\fR. This should be changed with care. +In the string the following changes are made: + +.nf + $image -- substitute the image + $mask -- substitute the mask being edited + $frame -- substitute the value of the frame parameter + $erase -- substituted by imedit +.fi +.le + +.ls display = yes +Use the task interactively with the display? This sets the behavior +of \fBimedit\fR as described for the parameter of the same name. +.le +.ls cursor = "" +Image cursor input. This is normally either a null string for interactive +display editing or the value of a file with cursor commands to edit +non-interactively. See the help for \fBimedit\fR for more information. +.le + +.ih +ADDITIONAL PARAMETERS + +This task calls \fBdisplay\fR to load the image display and \fBimedit\fR +to do the editing. The current default parameters are used from those +tasks except the image names, frames, and the display command are set by +this task. Also the search radius is set to zero (i.e. no centering). +Also the \fIdisplay\fR and \fIcursor\fR parameters override the +values of the parameters of the same name in \fBimedit\fR. Of particular +note is the default value for imedit.value which defines the mask value to +be set initially. This value may be changed interactively in \fBimedit\fR. +.ih +DESCRIPTION +\fBBpmedit\fR is a variant of \fBimedit\fR. It displays the input images +with the masks overlaid. The mask is defined +by the value of the keyword keywords specified by the \fIbpmkey\fR +parameter. The editing commands apply to the mask overlay and not the +image pixels. In this application the edited values should be integer mask +values. In the usual case where zero indicates good pixels and non-zero +indicates bad pixels one can set and unset values by changing current +replacement value with ":value". Two useful parameters, ":minvalue" +and ":maxvalue", are useful in this context to allow editing only +specific ranges of mask values. Note that many of the imedit options are +not useful for mask editing. The '?' keystroke prints a list of the +useful cursor and colon commands. This list is also shown below. + +Because it is common to want to see the image pixels to which the +mask values apply this task loads two image display frames. In one the +mask is overlaid and changes to the mask are updated with the +redisplay options of imedit (note the options to turn on and off +automatic redisplay). In the second the image without the mask is +displayed. The editing commands may be given in either frame but the +mask updates will appear only in the mask overlay frame. + +This task also provides the parameters \fIdisplay\fR and \fIcursor\fR +to use \fBimedit\fR in a non-interactive manner as described for that +task. Because only the setting and clearing of rectangles, circles, +or vectors makes sense with this task this may not be of great use. +Also there are many other tasks that can be used to edit masks +non-interactively. + +Please read the help for \fBimedit\fR for details of the editing +process. + +.nf + BPMEDIT CURSOR KEYSTROKE COMMANDS + + The following are the useful commands for BPMEDIT. Note all + the commands for IMEDIT are available but only those shown + here should be used for editing pixel masks. + + ? Print help + : Colon commands (see below) + i Initialize (start over without saving changes) + q Quit and save changes + r Redraw image display + + Increase radius by one + - Decrease radius by one + I Interrupt task immediately + Q Quit without saving changes + + The following editing options are available. Rectangular + and vector regions are specified with two positions and + aperture regions are specified by one position. The current + aperture type (circular or square) is used in the latter + case. All the following substitute the new value set for + the "value" parameter (see :value). Some replace all pixels + within the mask that have the same pixel value as the value + at the cursor position. + + d Set rectangle to "value" + e Set aperture to "value" + u Undo last change (see also 'i', 'j', and 'k') + v Set vector to "value" + = Replace pixels = to "cursor value" to "value" + < Replace pixels < or = to "cursor value" to "value" + > Replace pixels > than or = to "cursor value" to "value" + + + BPMEDIT COLON COMMANDS + + The colon either print the current value of a parameter when + there is no value or set the parameter to the specified + value. + + aperture [type] Aperture type (circular|square) + autodisplay [yes|no] Automatic image display? + command [string] Display command + display [yes|no] Display image? + eparam Edit parameters + radius [value] Aperture radius + value [value] Constant substitution value + minvalue [value] Minimum value for modification (INDEF=minimum) + maxvalue [value] Maximum value for modification (INDEF=maximum) + write [name] Write changes to name +.fi +.ih +EXAMPLES +1. Interactively edit a mask. + +.nf + cl> bpmedit wpix +.fi + +.ih +SEE ALSO +imedit, display, badpiximage, text2mask, mskexpr, mskregions, imexpr +.endhelp diff --git a/pkg/images/tv/doc/display.hlp b/pkg/images/tv/doc/display.hlp new file mode 100644 index 00000000..9e8670c4 --- /dev/null +++ b/pkg/images/tv/doc/display.hlp @@ -0,0 +1,555 @@ +.help display Mar97 images.tv +.ih +NAME +display -- Load and display images in an image display +.ih +USAGE +display image frame +.ih +PARAMETERS +.ls image +Image to be loaded. +.le +.ls frame +Display frame to be loaded. +.le + +.ls bpmask = "BPM" +Bad pixel mask. The bad pixel mask is used to exclude bad pixels from the +automatic intensity mapping algorithm. It may also be displayed as an +overlay or to interpolate the input image as selected by the \fIbpdisplay\fR +parameter. The bad pixel mask is specified by a pixel list image +(.pl extension) or an regular image. Values greater than zero define the +bad pixels. The special value "BPM" may be specified to select a pixel list +image defined in the image header under the keyword "BPM". If the +bad pixel mask cannot be found a warning is given and the bad pixel mask +is not used in the display. +.le +.ls bpdisplay = "none" (none|overlay|interpolate) +Type of display for the bad pixel mask. The options are "none" to not +display the mask, "overlay" to display as an overlay with the colors given +by the \fIbpcolors\fR parameter, or "interpolate" to linearly interpolate +across the bad pixels in the displayed image. Note that the bad is still +used in the automatic intensity scaling regardless of the type of display +for the bad pixel mask. +.le +.ls bpcolors = "red" +The mapping between bad pixel values and display colors or intensity values +when the bad pixels are displayed as an overlay. There are two forms, +explicit color assignments for values or ranges of values, and expressions. +These is described in the OVERLAY COLOR section. +.le + +.ls overlay = "" +Overlay mask to be displayed. The overlay mask may be a pixel list image +(.pl extension) or a regular image. Overlay pixels are identified by +values greater than zero. The overlay values are displayed with a mapping +given by the \fIocolors\fR parameter. If the overlay cannot be found a +warning is given and the overlay is not displayed. +.le +.ls ocolors = "green" +The mapping between bad pixel values and display colors or intensity values +when the bad pixels are displayed as an overlay. There are two forms, +explicit color assignments for values or ranges of values, and expressions. +These is described in the OVERLAY COLOR section. +.le + +.ls erase = yes +Erase frame before loading image? +.le +.ls border_erase = no +Erase unfilled area of window in display frame if the whole frame is not +erased? +.le +.ls select_frame = yes +Select the display frame to be the same as the frame being loaded? +.le +.ls repeat = no +Repeat the previous spatial and intensity transformations? +.le +.ls fill = no +Interpolate the image to fit the display window? +.le +.ls zscale = yes +Apply an automatic intensity mapping algorithm when loading the image? +.le +.ls contrast = 0.25 +Contrast factor for the automatic intensity mapping algorithm. +If a value of zero is given then the minimum and maximum of the +intensity sample is used. +.le +.ls zrange = yes +If not using the automatic mapping algorithm (\fIzscale = no\fR) map the +full range of the image intensity to the full range of the display? If the +displayed image has current min/max values defined these will be used to +determine the mapping, otherwise the min/max of the intensity sample will +be used. The \fIMINMAX\fR task can be used to update the min/max values in +the image header. +.le +.ls zmask = "" +Pixel mask selecting the sample pixels for the automatic or range intensity +mapping algorithm. The pixel mask may be a pixel list image (.pl +extension), a regular image, or an image section. The sample pixels are +identified by values greater than zero in the masks and by the region specified +in an image section. If no mask specification is given then a uniform sample +of approximately \fInsample\fR good pixels will be used. The \fInsample\fR +parameter also limits the number of sample pixels used from a mask. Note that +pixels identified by the bad pixel mask will be excluded from the sample. +.le +.ls nsample = 1000 (minimum of 100) +The number of pixels from the image sampled for computing the automatic +intensity scaling. This number will be uniformly sampled from the image +if the default \fIzmask\fR is used otherwise the first \fInsample\fR +pixels from the specified mask will be used. +.le +.ls xcenter = 0.5, ycenter = 0.5 +Horizontal and vertical centers of the display window in normalized +coordinates measured from the left and bottom respectively. +.le +.ls xsize = 1, ysize = 1 +Horizontal and vertical sizes of the display window in normalized coordinates. +.le +.ls xmag = 1., ymag = 1. +Horizontal and vertical image magnifications when not filling the display +window. Magnifications greater than 1 map image pixels into more than 1 +display pixel and magnifications less than 1 map more than 1 image pixel +into a display pixel. +.le +.ls order = 0 +Order of the interpolator to be used for spatially interpolating the image. +The current choices are 0 for pixel replication, and 1 for bilinear +interpolation. +.le +.ls z1, z2 +Minimum and maximum image intensity to be mapped to the minimum and maximum +display levels. These values apply when not using the automatic or range +intensity mapping methods. +.le +.ls ztrans = "linear" +Transformation of the image intensity levels to the display levels. The +choices are: +.ls "linear" +Map the minimum and maximum image intensities linearly to the minimum and +maximum display levels. +.le +.ls "log" +Map the minimum and maximum image intensities linearly to the range 1 to 1000, +take the logarithm (base 10), and then map the logarithms to the display +range. +.le +.ls "none" +Apply no mapping of the image intensities (regardless of the values of +\fIzcale, zrange, z1, and z2\fR). For most image displays, values exceeding +the maximum display value are truncated by masking the highest bits. +This corresponds to applying a modulus operation to the intensity values +and produces "wrap-around" in the display levels. +.le +.ls "user" +User supplies a look up table of intensities and their corresponding +greyscale values. +.le +.le +.ls lutfile = "" +Name of text file containing the look up table when \fIztrans\fR = user. +The table should contain two columns per line; column 1 contains the +intensity, column 2 the desired greyscale output. +.le +.ih +DESCRIPTION +The specified image and overlay mask are loaded into the specified frame of +the standard image display device ("stdimage"). For devices with more than +one frame it is possible to load an image in a frame different than that +displayed on the monitor. An option allows the loaded frame to become the +displayed frame. The previous contents of the frame may be erased (which +can be done very quickly on most display devices) before the image is +loaded. Without erasing, the image replaces only those pixels in the frame +defined by the display window and spatial mapping described below. This +allows displaying more than one image in a frame. An alternate erase +option erases only those pixels in the defined display window which are not +occupied by the image being loaded. This is generally slower than erasing +the entire frame and should be used only if a display window is smaller +than the entire frame. + +The image is mapped both in intensity and in space. The intensity is +mapped from the image pixel values to the range of display values in the +device. Spatial interpolation maps the image pixel coordinates into a part +of the display frame called the display window. Many of the parameters of +this task are related to these two transformations. + +A bad pixel mask may be specified to be displayed as an overlay or to +interpolate the displayed image. It is also used to exclude bad pixels +from the automatic intensity scaling. The bad pixel mask is specified by +the parameter \fIbpmask\fR and the display mode by the \fIbpdisplay\fR +parameter. The overlay display option uses the \fIbpcolors\fR parameters +to specify a color mapping as described in the OVERLAY COLOR section. +Interpolation consists of linear interpolation across columns if the mask +value is one, across lines if the mask value is two, or across the shortest +direction for other values. This interpolation is done on the input data +before any spatial interpolation and filling is done. It does not modify +the input data. The task \fBfixpix\fR provides the same algorithm to fix +the data in the image. + +An overlay mask may be specified by the \fIoverlay\fR parameter. Any +value greater than zero in the overlay mask will be displayed in the color or +intensity specified by the \fIocolor\fR parameter (see the OVERLAY COLOR +section). + +Note that bad pixel masks in "pixel list" format are constrained to +non-negative values. When an image is used instead of a pixel list the +image is internally converted to a pixel list. Negative values are +set to zero or good pixels and positive real values are truncated to +the nearest integer. + +A display window is defined in terms of the full frame. The lower left +corner of the frame is (0, 0) and the upper right corner is (1, 1) as +viewed on the monitor. The display window is specified by a center +(defaulted to the center of the frame (0.5, 0.5)) and a size (defaulted to +the full size of the frame, 1 by 1). The image is loaded only within the +display window and does not affect data outside the window; though, of +course, an initial frame erase erases the entire frame. By using different +windows one may load several images in various parts of the display frame. + +If the option \fIfill\fR is selected the image and overlay mask are +spatially interpolated to fill the display window in its largest dimension +(with an aspect ratio of 1:1). When the display window is not +automatically filled the image is scaled by the magnification factors +(which need not be the same) and centered in the display window. If the +number of image pixels exceeds the number of display pixels in the window +only the central portion of the image which fills the window is loaded. By +default the display window is the full frame, the image is not interpolated +(no filling and magnification factors of 1), and is centered in the frame. +The spatial interpolation algorithm is described in the section MAGNIFY AND +FILL ALGORITHM. + +There are several options for mapping the pixel values to the display values. +There are two steps; mapping a range of image intensities to +the full display range and selecting the mapping function or +transformation. The mapping transformation is set by the parameter +\fIztrans\fR. The most direct mapping is "none" which loads the +image pixel values directly without any transformation or range +mapping. Most displays only use the lowest bits resulting in a +wrap-around effect for images with a range exceeding the display range. +This is sometimes desirable because it produces a contoured image which +is not saturated at the brightest or weakest points. +This is the fastest method of loading the display. Another +transformation, "linear", maps the selected image range linearly to the full +display range. The logarithmic transformation, "log", maps the image range +linearly between 1 and 1000 and then maps the logarithm (base 10) linearly +to the full display range. In the latter transformations pixel values +greater than selected maximum display intensity are set to the maximum +display value and pixel values less than the minimum intensity +are set to the minimum display value. + +Methods for setting of the range of image pixel values, \fIz1\fR and +\fIz2\fR, to be mapped to the full display range are arranged in a +hierarchy from an automatic mapping which gives generally good result for +typical astronomical images to those requiring the user to specify the +mapping in detail. The automatic mapping is selected with the parameter +\fIzscale\fR. The automatic mapping algorithm is described in the section +ZSCALE ALGORITHM and has three parameters, \fIzmask\fR, \fInsample\fR and +\fIcontrast\fR. + +When \fIztrans\fR = user, a look up table of intensity values and their +corresponding greyscale levels is read from the file specified by the +\fIlutfile\fR parameter. From this information, a piecewise linear +look up table containing 4096 discrete values is composed. The text +format table contains two columns per line; column 1 contains the +intensity, column 2 the desired greyscale output. The greyscale values +specified by the user must match those available on the output device. +Task \fIshowcap\fR can be used to determine the range of acceptable +greyscale levels. When \fIztrans\fR = user, parameters \fIzscale\fR, +\fIzrange\fR and \fIzmap\fR are ignored. + +If the zscale algorithm is not selected the \fIzrange\fR parameter is +examined. If \fIzrange\fR is yes then the minimum and maximum pixel values +in the image are taken from the image header or estimated from the +intensity sample and \fIz1\fR and \fIz1\fR are set to those values, +respectively. This insures that the full range of the image is displayed +but is generally slower than the zscale algorithm (because all the image +pixels must be examined) and, for images with a large dynamic range, will +generally show only the brightest parts of the image. + +Finally, if the zrange algorithm is not selected the user specifies the +values of \fIz1\fR and \fIz2\fR directly. + +Often several images are to be loaded with the same intensity and spatial +transformations. The option \fIrepeat\fR repeats the transformations from +the previous image loaded. +.ih +ZSCALE ALGORITHM +The zscale algorithm is designed to display the image values near the median +image value without the time consuming process of computing a full image +histogram. This is particularly useful for astronomical images which +generally have a very peaked histogram corresponding to the background +sky in direct imaging or the continuum in a two dimensional spectrum. + +The sample of pixels, specified by values greater than zero in the sample mask +\fIzmask\fR or by an image section, is selected up to a maximum of +\fInsample\fR pixels. If a bad pixel mask is specified by the \fIbpmask\fR +parameter then any pixels with mask values which are greater than zero are not +counted in the sample. Only the first pixels up to the limit are selected +where the order is by line beginning from the first line. If no mask is +specified then a grid of pixels with even spacing along lines and columns +that make up a number less than or equal to the maximum sample size is +used. + +If a \fIcontrast\fR of zero is specified (or the \fIzrange\fR flag is +used and the image does not have a valid minimum/maximum value) then +the minimum and maximum of the sample is used for the intensity mapping +range. + +If the contrast is not zero the sample pixels are ranked in brightness to +form the function I(i) where i is the rank of the pixel and I is its +value. Generally the midpoint of this function (the median) is very near +the peak of the image histogram and there is a well defined slope about the +midpoint which is related to the width of the histogram. At the ends of +the I(i) function there are a few very bright and dark pixels due to +objects and defects in the field. To determine the slope a linear function +is fit with iterative rejection; + + I(i) = intercept + slope * (i - midpoint) + +If more than half of the points are rejected then there is no well defined +slope and the full range of the sample defines \fIz1\fR and \fIz2\fR. +Otherwise the endpoints of the linear function are used (provided they are +within the original range of the sample): + +.nf + z1 = I(midpoint) + (slope / contrast) * (1 - midpoint) + z2 = I(midpoint) + (slope / contrast) * (npoints - midpoint) +.fi + +As can be seen, the parameter \fIcontrast\fR may be used to adjust the contrast +produced by this algorithm. +.ih +MAGNIFY AND FILL ALGORITHM +The spatial interpolation algorithm magnifies (or demagnifies) the image +(and the bad pixel and overlay masks) along each axis by the desired +amount. The fill option is a special case of magnification in that the +magnification factors are set by the requirement that the image just fit +the display window in its maximum dimension with an aspect ratio (ratio of +magnifications) of 1. There are two requirements on the interpolation +algorithm; all the image pixels must contribute to the interpolated image +and the interpolation must be time efficient. The second requirement means +that simple linear interpolation is used. If more complex interpolation is +desired then tasks in the IMAGES package must be used to first interpolate +the image to the desired size before loading the display frame. + +If the magnification factors are greater than 0.5 (sampling step size +less than 2) then the image is simply interpolated. However, if the +magnification factors are less than 0.5 (sampling step size greater +than 2) the image is first block averaged by the smallest amount such +that magnification in the reduced image is again greater than 0.5. +Then the reduced image is interpolated to achieve the desired +magnifications. The reason for block averaging rather than simply +interpolating with a step size greater than 2 is the requirement that +all of the image pixels contribute to the displayed image. If this is +not desired then the user can explicitly subsample using image +sections. The effective difference is that with subsampling the +pixel-to-pixel noise is unchanged and small features may be lost due to +the subsampling. With block averaging pixel-to-pixel noise is reduced +and small scale features still contribute to the displayed image. +.ih +OVERLAY COLORS +The masks specified by the \fIbpmask\fR and \fIoverlay\fR parameters may be +displayed as color overlays on the image data. The non-zero pixels in the +mask are assigned integer display values. The values may fall in the same +range, 1 to 200, as the mapped image pixel data values and will behave the +same way as the pixel values when the display map is interactively adjusted. +Values of 0 and 201 to 255 may be used and depend on the display server and +display resource definitions. The expected or standard server behavior is +that 0 is the background color and 201 to 255 are various colors with the +lower numbers being the more standard primary colors. The expected colors +are: + +.nf + Value Color Value Color + 201 white (cursor) 210 coral + 202 black (background) 211 maroon + 203 white 212 orange + 204 red 213 khaki + 205 green 214 orchid + 206 blue 215 turquoise + 207 yellow 216 violet + 208 cyan 217 wheat + 209 magenta +.fi + +The values 201 and 202 are tied to the cursor and background resource +colors. These are generally white and black respectively. Values above 217 +are not defined and depend on the current state of the color table for the +window system. + +The mapping between mask values and overlay colors are specified +by the \fIbpcolors\fR and \fIocolors\fR parameters. There are two mapping +syntax, a list and an expression. + +The list syntax consists of +a comma delimited set of values and assignments with one of the following +forms. + +.nf + color + maskvalue=color + maskvalue-maskvalue=color +.fi + +where color may be a color name, a color value, or value to be added or +subtracted to the mask value to yield a color value. Color names may be +black, white, red, green, blue, yellow, cyan, magenta, or transparent with +case ignored and abbreviations allowed. Transparent does the obvious of +being invisible. These values are based on the default resource colors for +the display servers (as shown above) and any custom definitions may result +in incorrect colors. + +The color values are unsigned integers (no '+' or '-') or values to be added +or subtracted are given as signed integers. The first form provides the +default intensity or color for all mask values. Note that if no default +color is specified the default will be white. The other forms map a mask +value or range of mask values to a color. In a list the last color defined +for the default or mask value will be used. + +The addition or subtraction from mask values provides a mechanism to have +the bad pixel or overlay masks encode a variety of overlay colors. Note +that to display the mask values directly as colors one would use the color +value "+0". Subtraction may produce values less than zero which then +are not visible; i.e. equivalent to "transparent". + +The following examples illustrate the features of the syntax. + +.nf + ocolors="" Display in default white + ocolors="red" Display in red + ocolors="+0" Display mask values as color values + ocolors="+200" Display mask values offset by 200 + + ocolors="205,1=red,2=yellow,10-20=cyan,30-40=+100,50-100=transparent" +.fi + +The last example has a default color of 205, mask values of 1 are +red, mask values of 2 are yellow, mask values of 10 to 20 are cyan, +and mask values of 30 to 40 are displayed as intensities 130 to 140. + +Expressions are identified by being enclosed in parentheses. +This uses the general IRAF expression syntax (see \fBexpressions\fR). +The mask values are referenced by the character $. The same named +colors (black, white, red, green, blue, yellow, cyan, magenta, +and transparent) may be used in place of color values. Expressions +must evaluate to integer values. To avoid needing special handling of +input mask values of zero, all pixels with input mask values of zero +are not shown regardless of the expression value. + +There are currently two function extensions, "colors" and "acenum". +In both functions the first and only required argument, arg1, is an integer +value. Typically this will '$' or a function based on '$'. + +The "colors" function maps input values with a modulus type behavior. The +optional second argument, arg2, is a color value for mapping zero. As noted +above, if the input mask value is zero it will not be displayed. However, +functions applied to non-zero input mask values may return a value of zero +which may then be displayed with the specified color. The default is +transparent. The next two optional arguments (arg3 and arg4) define a color +range with defaults of 204 to 217. If only arg3 is specified then +arg4 takes the value of arg3, thus having the effect of a constant +output color. Positive values of the first argument are mapped to a color +value by + +.nf + if arg1 is 0: result = arg2 + if arg1 greater 0: result = arg3 + mod ($-1, arg4-arg3+1) + otherwise: result = arg1 +.fi + +This function is primarily used to make colorful displays of regions +defined with different mask values. + +The "acenum" function handles \fBace\fR package object detection masks +which include bit flags. Each object in the mask has an object number +with value greater than 10. Values less than 10 are passed along during +detection and generally identify detector or saturated bad pixels. +Along with the object number there may be zero or more bit flags +set. This function removes the bit flags and returns the mask number. +The optional second argument, arg2, is a string of letters which selects +pixels with certain sets of bit flags. The bit flags are: + +.nf + B -- a bad pixel treated as a good for detection + D -- original detection (i.e. without G or S flag) + E -- edge pixel used for displaying detection isophotes + F -- object contains a bad pixel + G -- grown pixel + S -- pixel not assigned to an object during splitting +.fi + +The default of arg2 is "BDEG" which essentially returns all pixels +in an object. + +The acenum function also returns 0 for the pixels with values between +one and ten and -1 for the pixels not selected by the flags. The value +of zero may be made visible using the colors function. The two functions +are often used in concert: + +.nf + (colors(acenum($))) + (colors(acenum($),black)) + (colors(acenum($,'E'),red,green) +.fi + +Note that when filling and anti-aliasing the behavior of the overlay +colors may be different than intended. +.ih +EXAMPLES +For the purpose of these examples we assume a display with four frames, +512 x 512 in size, and a display range of 0 to 255. Also consider two +images, image1 is 100 x 200 with a range 200 to 2000 and image2 is +2000 x 1000 with a range -1000 to 1000. To load the images with the +default parameters: + +.nf + cl> display image1 1 + cl> display image2 2 +.fi + +The image frames are first erased and image1 is loaded in the center of +display frame 1 without spatial interpolation and with the automatic intensity +mapping. Only the central 512x512 area of image2 is loaded in display frame 2 + +To load the display without any intensity transformation: + + cl> cvl image1 1 ztrans=none + +The next example interpolates image2 to fill the full 512 horizontal range +of the frame and maps the full image range into the display range. Note +that the spatial interpolation first block averages by a factor of 2 and then +magnifies by 0.512. + + cl> display image2 3 fill+ zscale- + +The next example makes image1 square and sets the intensity range explicitly. + + cl> display image1 4 zscale- zrange- z1=800 z2=1200 xmag=2 + +The next example loads the two images in the same frame side-by-side. + +.nf + cl> display.xsize=0.5 + cl> display image1 fill+ xcen=0.25 + cl> display image2 erase- fill+ xcen=0.75 +.fi +.ih +REVISIONS +.ls DISPLAY V2.11 +The bad pixel mask, overlay mask, sample mask, and overlay colors +parameters and functionality have been added. The "nsample_lines" +parameter is now an "nsample" parameter. + +Bugs in the coordinate system sent to the image display for cursor +readback were fixed. +.le +.ih +BUGS +The "repeat" option is not implemented. +.ih +SEE ALSO +cvl, magnify, implot, minmax, fixpix +.endhelp diff --git a/pkg/images/tv/doc/imedit.hlp b/pkg/images/tv/doc/imedit.hlp new file mode 100644 index 00000000..66b113af --- /dev/null +++ b/pkg/images/tv/doc/imedit.hlp @@ -0,0 +1,493 @@ +.help imedit Aug07 images.tv +.ih +NAME +imedit -- examine and edit pixels in images +.ih +USAGE +imedit input output +.ih +PARAMETERS +.ls input +List of images to be edited. Images must be two dimensional. +.le +.ls output +List of output images. The list must match the input list or be empty. +In the latter case the output image is the same as the input image; i.e. +the edited image replaces the input image. +.le +.ls cursor = "" +The editing commands are entered via a cursor list. When the task is +run interactively this will normally be the standard image cursor +(stdimcur) specified by a null string. Commands may be read from +a file. The file format may be cursor values including the command +keys, a simple list of positions with the default command given +by the \fIdefault\fR parameter, and a regions file, as used in +the task \fBfixpix\fR and the \fBccdred\fR package, selected by +the \fIfixpix\fR parameter. +.le +.ls logfile = "" +File in which to record the editing commands which modify the images. +The display and statistics commands which don't modify the images are +not recorded. This file may be used for keeping a record of the +modifications. It may also be used as cursor input for other images +to replicate the same editing operations. +.le +.ls display = yes +Display the image during editing? If yes then the display command, +given by the parameter \fIcommand\fR, is used to display the image. +Normally the display is used when editing interactively and turned +off when using file input. +.le +.ls autodisplay = yes +Automatically redisplay the image after each change? If the display +of the image is rapid enough then each change can be displayed as +it is made by setting this parameter to yes. However, it is faster +to accumulate changes and then explicitly redisplay the image. +When the parameter is no then the image is only redisplayed by +explicit command. +.le +.ls autosurface = no +Automatically display surface plots after each change? In addition +to the image display command, the task can display a before and after +surface plot of the modified region. This can be done by explicit +command or automatically after each change. +.le +.ls aperture = "circular" +Aperture for aperture editing. Some commands specify the region to +be edited by a center and radius. The shape of the aperture is selected +by this parameter. The choices are "circular" and "square". Note that +this does not apply to commands in which a rectangle is specified by +selecting the corners. +.le +.ls radius = 2. +Radius of the aperture for commands selecting an aperture. For circular +apertures this is the radius while for square apertures it is half of the +side of the square. Note that partial pixels are not used so that a +circular aperture is not perfectly circular; i.e. if the center of a +pixel is within this distance of the center pixel it is modified and +otherwise it is not. A radius of zero may be used to select a single +pixel (with either aperture type). +.le +.ls search = 2. +Search radius for adjusting the position of the region to be edited. +This applies to both aperture regions and rectangular regions. The +center pixel of the region is searched within this radius for the +maximum or minimum pixel value. If the value is zero then no searching +is done and the specified region is used directly. If the value is +positive then the specified region is adjusted to be centered on a +relative maximum. A relative minimum may be found if the value is +negative with the absolute value used as the search radius. +.le +.ls buffer = 1. +Background buffer width. A buffer annulus separates the region to be +edited from a background annulus used for determining the background. +It has the same shape as the region to be edited; i.e. circular, square, +rectangular, or line. +.le +.ls width = 2. +Width of background annulus. The pixels used for background determinations +is taken from an annulus of the same shape as the region to be edited and +with the specified width in pixels. +.le +.ls xorder = 2, yorder = 2 +Orders (number of terms) of surface polynomial fit to background pixels +for statistics and background subtraction. The orders should generally +be low with orders of 2 for a plane background. If either order is +zero then a median background is used. +.le +.ls value = 0. +Value for constant substitution. One editing command is replacement of +a region by this value. +.le +.ls minvalue = INDEF, maxvalue = INDEF +Range of values which may be modified. Value of INDEF map to the minimum +and maximum possible values. +.le +.ls sigma = INDEF +Sigma of noise to be added to substitution values. If less than or +equal to zero then no noise is added. If INDEF then pixel values from +the background region are randomly selected after subtracting the +fitted background surface or median. Finally if a positive value is given than +a gaussian noise distribution is added. +.le +.ls angh = -33., angv = 25. +Horizontal and vertical viewing angles (in degrees) for surface plots. +.le +.ls command = "display $image 1 erase=$erase fill=yes order=0 >& dev$null" +Command for displaying images. This task displays images by executing a +standard IRAF command. Two arguments may be substituted by the appropriate +values; the image name specified by "$image" and the boolean erase +flag specified by "$erase". Except for unusual cases the \fBtv.display\fR +command is used with the fill option. The fill option is required to +provide a zoom feature. See the examples for another possible command. +.le +.ls graphics = "stdgraph" +Graphics device used for surface plots. Normally this is the standard +graphics device "stdgraph" though other possibilities are "stdplot" +and "stdvdm". Note the standard graphics output may also be +redirected to a file with ">G file" where "file" is any file name. +.le +.ls default = "b" +Default command option for simple position list input. If the input +is a list of column and line positions (x,y) then the command executed +at each position is given by this parameter. This should be one of +the aperture type editing commands, the statistics command, or the +surface plotting command. Two keystroke commands would obviously +be incorrect. \fIThis parameter is ignored in "fixpix" mode\fR. +.le +.ls fixpix = no +Fixpix style input? This type of input consists of rectangular regions +specified by lines giving the starting and ending column and starting +and ending line. This is the same input used by \fBfixpix\fR and in +the \fBccdred\fR package. The feature to refer to "untrimmed" images +in the latter package is not available in this task. When selected +the editing consists of interpolation across the narrowest dimension +of the region and the default key is ignored. +.le +.ih +DESCRIPTION +Regions of images are examined and edited. This may be done interactively +using an image display and cursor or non-interactively using a list of +positions and commands. There are a variety of display and editing +options. A list of input images and a matching list of output images +are specified. The output images are only created if the input image +is modified (except by an explicit "write" command). If no output +list is specified (an empty list given by "") then the modified images +are written back to the input images. The images are edited in +a temporary buffer image beginning with "imedit". + +Commands are given via a cursor list. When the task is run +interactively this will normally be the standard image cursor +(stdimcur). Commands may be read from a file. The file format may be +cursor values including the command keys, a simple list of positions +with the default command given by the \fIdefault\fR parameter, and a +regions file, as used in the task \fBfixpix\fR and the \fBccdred\fR +package, selected by the \fIfixpix\fR parameter. + +The commands which modify the image may be written to a log file specified +by parameter \fIlogfile\fR. This file can be used as a record of the +pixels modified. The format of this file is also suitable for input +as a cursor list. This allows the same commands to be applied to other +images. \fIBe careful not to have the cursor input and logfile have the +same name!\fR + +When the \fIdisplay\fR parameter is set the command given by the parameter +\fIcommand\fR is executed. Normally this command loads the image display +though it could also create a contour map or other graph whose x and y +coordinates are the same as the image coordinates. The image is displayed +when editing interactively and the standard image cursor (which can +be redefined to be the standard graphics cursor) is used to select +regions to be edited. When not editing interactively the display +flag should be turned off. + +It is nice to see changes to the image displayed immediately. This is +possible using the \fIautodisplay\fR option. Note that this requires +the display parameter to also be set. If the autodisplay flag is set +the display command is repeated after each change to the image. The +drawback to this is that the full image (or image section) is reloaded +and so can be slow. If not set it is still possible to explicitly give +a redisplay command, 'r', after a number of changes have been made. + +Another display option is to make surface graphs to the specified +graphics device (normally the standard graphics terminal). This may +be done by the commands 'g' and 's' and automatically after each +change if the \fIautosurface\fR parameter is set. The two types of +surface plots are a single surface of the image at the marked position +and before and after plots for a change. + +Regions of the image to be examined or edited are selected by one +or two cursor commands. The single cursor commands define the center +of an aperture. The shape of the aperture, circular or square, is +specified by the \fIaperture\fR parameter and the radius (or half +the edge of a square) is specified by the \fIradius\fR parameter. +The radius may be zero to select a single pixel. The keys '+' and +'-' may be used to quickly increment or decrement the current radius. +The two keystroke commands either define the corners of a rectangular +region or the endpoints of a line. + +Because it is sometimes difficult to mark cursor position precisely +the defined region may be shifted so that the center is either +a local maximum or minimum. This is usually desired for editing +cosmicrays, bad pixels, and stars. The center pixel of the aperture +is moved within a specified search radius given by parameter +\fIsearch\fR. If the search radius is zero then the region defined +by the cursor is not adjusted. The sign of the search radius +selects whether a maximum (positive value) or a minimum (negative value) +is sought. The special key 't' toggles between the two modes +in order to quickly edit both low sensitivity bad pixels and +cosmicrays and stars. + +Once a region has been defined a background region may be required +to estimate the background for replacement. The background +region is an annulus of the same shape separated by a buffer width, +given by the parameter \fIbuffer\fR, and having a width given by +the parameter \fIwidth\fR. + +The replacement options are described below as is a summary of all the +commands. Two commands requiring a little more description are the +space and 'p' commands. These print the statistics at the cursor +position for the current aperture and background parameters. The +printout gives the x and y position of the aperture center (after the +search if any), the pixel value (z) at that pixel, the mean background +subtracted flux in the aperture, the number of pixels in the aperture, +the mean background "sky", the sigma of the background residuals from +the background fit, and the number of pixels in the background region. +The 'p' key additionally prints the pixel values in the aperture. +Beware of apertures with radii greater than 5 since they will wrap +around in an 80 column terminal. + +When done editing or examining an image exit with 'q' or 'Q'. The +former saves the modified image in the output image (which might be +the same as the input image) while the latter does not save the +modified image. Note that if the image has not been modified then +no output occurs. After exiting the next image in the input +list is edited. One may also change input images using the +":input" command. Note that this command sets the output to be the +same as the input and a subsequent ":output" command should be +used to define a different output image name. A final useful +colon command is ":write" which forces the current editor buffer +to be written. This can be used to save partial changes. +.ih +REPLACEMENT ALGORITHMS +The parameters "minvalue" and "maxvalue" are may be used to limit the +range of values modified. The default is to modify all pixels which +are selected as described below. + +.ls a, b +Replace rectangular or aperture regions by background values. A background +surface is fit the pixels in the background annulus if the x and y orders +are greater than zero otherwise a median is computed. The x and y orders +of the surface function are given by the \fIxorder\fR and \fIyorder\fR +parameters. The median is used or the surface is evaluated for the pixels +in the replacement region. If a positive sigma is specified then gaussian +noise is added. If a sigma of INDEF is specified then the residuals of the +background pixels are sorted, the upper and lower 10% are excluded, and the +remainder are randomly selected as additive noise. +.le +.ls c, f, l +Replace rectangular or line regions by interpolation from the nearest +background column or line. The 'f' line option interpolates across the +narrowest dimension; i.e. for lines nearer to the line axis interpolation +is by lines while for those nearer to the column axis interpolation is +by columns. The buffer region applies but only the nearest background +pixel at each line or column on either side of the replacement region +is used for interpolation. Gaussian noise may be added but background +sampling is not available. This method is similar to the method used +in \fBfixpix\fR or \fBccdred\fR with no buffer. For "fixpix" type +input the type of interpolation is automatically selected for the +narrower dimension with column interpolation for square regions. +.le +.ls d, e, v +Replace rectangular, aperture, or vector regions by the specified +constant value. This may be used to flag pixels or make masks. +The vector option makes a line between two points with a width +set by the radius value. +.le +.ls j, k +Replace rectangular or aperture regions in the editor buffer by the data +from the input image. This may be used to undo any change. Note that +the 'i' command can be used to completely reinitialize the editor +buffer from the input image. +.le +.ls m, n +Replace an aperture region by another aperture region. There is no +centering applied in this option. The aperture region to copy is +background subtracted using the background annulus for median or surface +fitting. This data may then be added to the destination aperture or +replace the data in the destination aperture. In the latter case the +destination background surface is also computed and added. +.le +.ls u +Undo the last change. When a change is made the before and after data +are saved. An undo exchanges the two sets of data. Note that it is +possible to undo an undo to restore a change. If any other command is +used which causes data to be read (including the statistics and surface +plotting) then the undo is lost. +.le +.ls =, <, > +The all pixels with a value equal to that of the pixel at the cursor +position are replaced by the specified constant value. This is intended +for editing detection masks where detected objects have specific mask +values. +.le +.ih +COMMANDS +.ce + IMEDIT CURSOR KEYSTROKE COMMANDS + +.nf + ? Print help + : Colon commands (see below) + <space> Statistics + g Surface graph + i Initialize (start over without saving changes) + q Quit and save changes + p Print box of pixel values and statistics + r Redraw image display + s Surface plot at cursor + t Toggle between minimum and maximum search + + Increase radius by one + - Decrease radius by one + I Interrupt task immediately + Q Quit without saving changes +.fi + +The following editing options are available. Rectangular, line, and +vector regions are specified with two positions and aperture regions +are specified by one position. The current aperture type (circular or +square) is used in the latter case. The move option takes two positions, +the position to move from and the position to move to. + +.nf + a Background replacement (rectangle) + b Background replacement (aperture) + c Column interpolation (rectangle) + d Constant value substitution (rectangle) + e Constant value substitution (aperture) + f Interpolation across line (line) + j Replace with input data (rectangle) + k Replace with input data (aperture) + l Line interpolation (rectangle) + m Copy by replacement (aperture) + n Copy by addition (aperture) + u Undo last change (see also 'i', 'j', and 'k') + v Constant value substitution (vector) + = Constant value substitution of pixels equal + to pixel at the cursor position + < Constant value substitution of pixels less than or equal + to pixel at the cursor position + > Constant value substitution of pixels greater than or equal + to pixel at the cursor position +.fi + +When the image display provides a fill option then the effect of zoom +and roam is provided by loading image sections. This is a temporary +mechanism which will eventually be replaced by a more sophisticated +image display interface. + +.nf + E Expand image display + P Pan image display + R Redraw image display + Z Zoom image display + 0 Redraw image display with no zoom + 1-9 Shift display +.fi + + +.ce +IMEDIT COLON COMMANDS + +The colon either print the current value of a parameter when there is +no value or set the parameter to the specified value. + +.nf +angh [value] Horizontal viewing angle (degrees) +angv [value] Vertical viewing angle (degrees) +aperture [type] Aperture type (circular|square) +autodisplay [yes|no] Automatic image display? +autosurface [yes|no] Automatic surface plots? +buffer [value] Background buffer width +command [string] Display command +display [yes|no] Display image? +eparam Edit parameters +graphics [device] Graphics device +input [image] New input image to edit (output name = input) +output [image] New output image name +radius [value] Aperture radius +search [value] Search radius +sigma [value] Noise sigma (INDEF for histogram replacement) +value [value] Constant substitution value +minvalue [value] Minimum value for modification (INDEF=minimum) +maxvalue [value] Maximum value for modification (INDEF=maximum) +width [value] Background annulus width +write [name] Write changes to name (default current output) +xorder [value] X order for background fitting +yorder [value] Y order for background fitting +.fi +.ih +KEYWORDS +None +.ih +EXAMPLES +1. Interactively edit an image. + + cl> imedit raw002 ed002 + +2. Edit pixels non-interactively from an x-y list. Replace the original images + by the edited images. + +.nf + cl> head bad + 20 32 + 40 91 + <etc> + cl> imedit raw* "" cursor=bad display- +.fi + +3. It is possible to use a contour plot for image display. This is really + not very satisfactory but can be used in desperation. + +.nf + cl> reset stdimcur=stdgraph + cl> display.command="contour $image >& dev$null" + cl> imedit raw002 ed002 +.fi + +4. Use a "fixpix" file (without trim option). + +.nf + cl> head fixpix + 20 22 30 80 + 99 99 1 500 + <etc> + cl> imedit raw* %raw%ed%* cursor=fixpix fixpix+ display- +.fi +.ih +REVISIONS +.ls IMEDIT V2.13 +The 'v' option was added to allow vector replacement. +The '=', '<', '>' options were added to replace values matching the pixel +at the cursor. +.le +.ls IMEDIT V2.11.2 +The temporary editor image was changed to use a unique temporary image +name beginning with "imedit" rather than the fixed name of "epixbuf". +.le +.ls IMEDIT V2.11 +If xorder or yorder are zero then a median background is computed +for the 'a' and 'b' keys. +.le +.ls IMEDIT V2.10.4 +The 'u', 'j', 'k', and 'n' keys were added to those recorded in the +log file. +.le +.ls IMEDIT V2.8 +This task is a first version of what will be an evolving task. +Additional features and options will be added as they are suggested. +It is also a prototype using a very limited display interface; execution +of a separate display command. Much better interaction with a variety +of image displays will be provided after a planned "image display +interface" is implemented. Therefore any deficiencies in this area +should be excused. + +The zoom and roam features provided here are quite useful. However, +they depend on a feature of the tv.display program which fills the +current image display window by pixel replication or interpolation. +If this is left out of the display command these features will not +work. The trick is that this task displays sections of the editor +buffer whose size and position is based on an internal zoom and +center and the display program expands the section to fill the +display. + +The surface plotting is done using an imported package. The limitations +of this package (actually limitations in the complexity of interfacing +the application to this sophisticated package) mean that the +surface plots are always scaled to the range of the data and that +it is not possible to label the graph or use the graphics cursor to +point at features for the task. +.le +.ih +SEE ALSO +ccdred.instruments proto.fixpix +.endhelp diff --git a/pkg/images/tv/doc/imexamine.hlp b/pkg/images/tv/doc/imexamine.hlp new file mode 100644 index 00000000..14dbb59d --- /dev/null +++ b/pkg/images/tv/doc/imexamine.hlp @@ -0,0 +1,1043 @@ +.help imexamine Mar96 images.tv +.ih +NAME +imexamine -- examine images using image display, plots, and text +.ih +USAGE +imexamine [input [frame]] +.ih +PARAMETERS +.ls input +Optional list of images to be examined. If specified, images are examined +in turn, displaying them automatically. If no images are specified the +images currently loaded into the image display are examined. +.le +.ls output = "" +Rootname for output images created with the 't' key. If no name is specified +then the name of the input image is used. A three digit number is appended +to the rootname, such as ".001", starting with 1 until no image is found with +that name. Thus, successive output images with the same rootname will be +numbered sequentially. +.le +.ls ncoutput = 101, nloutput = 101 +Size of the output image created with the 't' key which is centered on the +position of the cursor. +.le +.ls frame = 1 +During program execution, a query parameter specifying the frame to be loaded. +May also be specified on the command line when \fIimexamine\fR is used as a +task to display a new image, to specify the frame to be loaded. +.le +.ls image +Query parameter for selecting images to be loaded. +.le +.ls logfile = "" +Logfile filename in which to record output of the commands producing text. +If no filename is given then no logfile will be kept. +.le +.ls keeplog = no +Log output results initially? Logging can be toggled interactively during +program execution. +.le +.ls defkey = "a" +Default key for cursor x-y input list. This key is applied to input +cursor lists which do not have a cursor key specified. It is used +to repetitively apply a cursor command to a list of positions typically +obtained from another task. +.le +.ls autoredraw = yes +Automatically redraw graphs after a parameter change? If no then graphs +are only drawn when a graph or redraw command is given. +If yes then colon commands which modify a parameter of the last graph +will automatically redraw the graph. A common example of this would +be changing the graph limits. +.le +.ls allframes = yes +Use all frames for displaying images? If set, images from the input list +are loaded cycling through the available frames. If not set the last frame +loaded is reused. +.le +.ls nframes = 0 +Number of display frames. When automatically loading images from the input +list only this number of frames will be used. This should, of course, +not exceed the number of frames provided by the display device. +If the number of frames is set to 0 then the task will query the display +device to determine how many frames are currently allocated. New frames may +be allocated during program execution by displaying images with the 'd' key. +.le +.ls ncstat = 5, nlstat = 5 +The statistics command computes values from a box centered on the +specified cursor position with the number of columns and lines +given by these parameters. +.le +.ls graphcur = "" +Graphics cursor input. If null the standard graphics cursor is used whenever +graphics cursor input is requested. A cursor file in the appropriate +format may be substituted by specifying the name of the file. +.le +.ls imagecur = "" +Image display cursor input. If null the standard image display cursor is +used whenever image cursor input is requested. A cursor file in the +appropriate format may be substituted by specifying the name of the file. +Also the image cursor may be changed to query the graphics device or +the terminal by setting the environment parameter "stdimcur" +to "stdgraph" or "text" respectively. +.le +.ls wcs = "logical" +The world coordinate system (\fIwcs\fR) to be used for axis labeling when +input is from images. +The following standard world systems are predefined. +.ls logical +Logical coordinates are image pixel coordinates relative to the image currently +being displayed. +.le +.ls physical +The physical coordinate system is invariant with respect to linear +transformations of the physical image matrix. For example, if the reference +image was created by extracting a section of another image, the physical +coordinates of an object in the reference image will be the pixel coordinates +of the same object in the original image. The physical coordinate system +thus provides a consistent coordinate system (a given object always has the +same coordinates) for all images, regardless of whether any user world +coordinate systems have been defined. +.le +.ls world +The "world" coordinate system is the \fIcurrent default WCS\fR. +The default world system is the system named by the environment variable +\fIdefwcs\fR if defined in the user environment and present in the reference +image WCS description, else it is the first user WCS defined for the image +(if any), else physical coordinates are returned. +.le +.ls xformat = "", yformat = "" +The numerical format for the world coordinate labels in the line and column +plots and the format for printing world coordinates. The values may be "" +(an empty string), %f for decimal format, %h and %H for xx:xx:xx format, and +%m and %M for xx:xx.x format. The upper case %H and %M convert degrees +to hours. Images sometimes include recommended coordinate formats as +WCS attributes. These are used if the format specified by these parameters +is "". Any other value will override the image attribute. +.le + +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. +.le +.ls graphics = "stdgraph" +Graphics output device. Normally this is the standard graphics device +specified by the environment variable "stdgraph". +.le +.ls display = "display(image='$1',frame=$2)" +Command template used to display an image. The image to be displayed is +substituted for argument $1 and the frame for argument $2. Any display task +may be used for image display by modifying this template. +.le +.ls use_display = yes +Use the image display? Set to no to disable all interaction with the +display device, e.g., when working at a terminal that does not provide image +display capabilities. +.le +.ih +ADDITIONAL PARAMETERS +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: + +.nf + 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) +.fi + +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 parameter sets in which the parameter occurs. + +.ls angh = -33., angv = 25. (s) +Horizontal and vertical viewing angles (degrees) for surface plots. +.le +.ls autoscale = yes (h) +In the case of integer data, automatically adjust \fInbins\fR and +\fIz2\fR to avoid aliasing effects. +.le +.ls axes = yes (s) +Draw axes along edge of surface plots? +.le +.ls background = yes (jkr.) +Fit and subtract a background for aperture sums, 1D gaussian fits, and +radial profile plots? +.le +.ls banner = yes (cehjklrsv.) +Add a standard banner to a graph? The standard banner includes the +IRAF user and host identification and time, the image name and title, +and graph specific parameters. +.le +.ls beta = INDEF (ar.) +Beta value to use for Moffat profile fits. If the value is INDEF +the value will be determine as part of the fit otherwise the parameter +will be fixed at the specified value. +.le +.ls boundary = "constant" (v) +Boundary extension for vector plots in which the averaging width might +go outside of the image. +.le +.ls box = yes (cehjklrv.) +Draw graph box and axes? +.le +.ls buffer = 5. (r.) +Buffer distance from object aperture of background annulus for aperture sums +and radial profile plots. +.le +.ls ceiling = INDEF (es) +Ceiling data value for contour and surface plots. A value of INDEF does +not apply a ceiling. (In contour plots a value of 0. also does not +apply a ceiling.) +.le +.ls center = yes (jkr.) +Apply a centering algorithm for doing aperture sums, 1D gaussian fits, +and radial profile plots? +.le +.ls constant = 0. (v) +Boundary extension constant for vector plots in which the averaging width +might go outside of the image. +.le +.ls dashpat = 528 (e) +Dash pattern for negative contours. +.le +.ls fill = no (e) +Fill the output viewport regardless of the device aspect ratio? +.le +.ls fitplot = yes (r.) +Overplot the profile fit on the radial profile data? +.le +.ls fittype = "moffat" (ar.) +Profile type to fit the radial profile data? The choices are "gaussian" +and "moffat". +.le +.ls floor = INDEF (es) +Floor data value for contour and surface plots. A value of INDEF does +not apply a floor. (In contour plots a value of 0. also does not +apply a floor.) +.le +.ls interval = 0 (e) +Contour interval. If 0, a contour interval is chosen which places 20 to 30 +contours spanning the intensity range of the image. +.le +.ls iterations = 3 (ar) +Number of iterations to adjust the fitting radius. +.le +.ls label= no (e) +Label the major contours in the contour plot? +.le +.ls logx = no, logy = no (chjklrv.) +Plot the x or y axis logarithmically? The default for histogram plots is +to plot the y axis logarithmically. +.le +.ls magzero = 25. (r.) +Magnitude zero point for aperture sums. +.le +.ls majrx=5, minrx=5, majry=5, minry=5 (cehjklrv.) +Maximum number of major tick marks on each axis and number of minor tick marks +between major tick marks. +.le +.ls marker = "box" (chjklrv.) +Marker to be drawn if \fBpointmode\fR = yes. Markers are "point", "box", +"cross", "plus", "circle", "hebar", "vebar", "hline", "vline" or "diamond". +.le +.ls naverage = 1 (cjklv) +Number of lines, columns, or width perpendicular to a vector to be averaged. +.le +.ls nbins = 512 (h) +The number of bins in, or resolution of, histogram plots. +.le +.ls ncolumns = 21, nlines = 21 (ehs) +Number of columns and lines used in contour, histogram, and surface plots. +.le +.ls ncontours = 5 (e) +Number of contours to be drawn. If 0, the contour interval may be specified, +otherwise 20-30 nicely spaced contours are drawn. A maximum of 40 contours +can be drawn. +.le +.ls nhi = -1 (e) +If -1, highs and lows are not marked. If 0, highs and lows are marked +on the plot. If 1, the intensity of each pixel is marked on the plot. +.le +.ls pointmode = no (chlv) +Plot points or marks instead of lines? +.le +.ls pointmode = yes (jkr.) +Plot points or marks instead of lines? For radial profile plots point +mode should always be yes. +.le +.ls radius = 5. (r.) +Radius of aperture for aperture sums and centering. +.le +.ls round = no (cehjklrv.) +Extend the axes up to "nice" values? +.le +.ls rplot = 8. (jkr.) +Radius to which the radial profile or 1D profile fits are plotted. +.le +.ls sigma = 2. (jk) +Initial guess for 1D gaussian fits. The value is in pixels even if the fitting +is done in world coordinates. This must be close to the true value +for convergence. Also the four times the initial sigma is used to define +the distance to the background region for the initial background estimate. +.le +.ls szmarker = 1 (chjklrv.) +Size of mark (except for points). A positive size less than 1 specifies +a fraction of the device size. Values of 1, 2, 3, and 4 signify +default sizes of increasing size. +.le +.ls ticklabels = yes (cehjklrv.) +Label the tick marks? +.le +.ls title = "" (cehjklrsv.) +User title. This is independent of the standard banner title. +.le +.ls top_closed = no (h) +Include z2 in the top histogram bin? Each bin of the histogram is a +subinterval that is half open at the top. \fITop_closed\fR decides whether +those pixels with values equal to z2 are to be counted in the histogram. If +\fBtop_closed\fR is yes, the top bin will be larger than the other bins. +.le +.ls width = 5. (jkr.) +Width of background region for background subtraction in aperture sums, +1D profile fits, and radial profile plots. +.le +.ls wcs = "physical" +World coordinate system for axis labeling and coordinate readback. +.le +.ls x1 = INDEF, x2 = INDEF, y1 = INDEF, y2 = INDEF (chjklrv.) +Range of graph along each axis. If INDEF the range is determined from +the data range plus a buffer. The default y1 for histogram plots is 0. +.le +.ls xformat, yformat +Set world image coordinate formats. Any format changes take effect on the next +usage; i.e. there is no automatic redrawing. +.le +.ls xlabel, ylabel (cehjklrv.) +Axis labels. Each graph type has an appropriate default. If the label +value is "wcslabel" then the coordinate label from the image WCS +will be used if defined. +.le +.ls xorder = 0 (jk) +Order for 1D gaussian background. If 0 then a median is computed. If +1 then a constant background is fit simultaneously with the other gaussian +parameters. If 2 then a linear background is fit simultaneously with the +other gaussian parameters. +.le +.ls xorder = 0, yorder = 0 (r.) +If either parameter is zero then the median value of the +background annulus is used for background subtraction in aperture sums and +radial profile plots. Values greater than zero define polynomial +surface orders for background subtraction. The orders are actually the +number of polynomial terms. An order of 1 is a constant an order of 2 +is a plane. +.le +.ls zero = 0. (e) +Greyscale value of the zero contour, i.e., the value of a zero point shift +to be applied to the image data before plotting. Does not affect the values +of the floor and ceiling parameters. +.le +.ls z1 = INDEF, z2 = INDEF (h) +Range of pixel values to be used in histogram. INDEF values default to +the range in the region being histogramed. +.le +.ih +DESCRIPTION +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. + +IMAGE DISPLAY + +If \fIuse_display\fR 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 \fInframes\fR parameter determines which frames are +available. Within the available frames images may be loaded by cycling +through them if \fIallframes\fR 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 \fIdisplay\fR. Usually this is the standard +IRAF \fBtv.display\fR command though in some circumstances other commands +like \fBplot.contour\fR may be used. This command may be used to +display an image even if \fIuse_display\fR 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. + +CURSOR INPUT + +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 \fBcursors\fR) 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. + +.ls contour plot +This gives image coordinates directly and both the x and y cursor values +are used. +.le +.ls column plot +The x cursor position gives the line coordinate and the column coordinate +used for the plot (that specified before averaging) gives the column +coordinate. +.le +.ls line plot +The x cursor position gives the column coordinate and the line coordinate +used for the plot (that specified before averaging) gives the line +coordinate. +.le +.ls vector plot +The x cursor position defines a column and line coordinate along the vector +plotted. +.le +.ls surface plot +No cursor information is available in this plot and the cursor position +used to make the surface plot (the center of the surface) is used again. +.le +.ls histogram plot +No cursor information is available in this plot and the cursor position +used to make the histogram (the center of the box) is used again. +.le +.ls radial profile plot +No cursor information is available in this plot and the cursor position +used to define the center is used again. +.le + +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 \fIdefkey\fR 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. + +TEXT OUTPUT + +The following commands produce text output which may also be appended to +a logfile. + +.ls a, ',' +Circular aperture photometry is performed at the position of the cursor. +If the centering option is selected the cursor position is used as the +initial point for computing the central moments of the marginal +distributions in x and y. The marginal distributions are obtained from a +square aperture with edge dimensions of twice the aperture radius +parameter. Only the pixels above the mean are used in computing the +central moments. If the central moments are in a different pixel than that +used for extracting the marginal distributions the computation is repeated +using the new center. + +The radius of the photometry and fitting aperture is specified by the +\fIradius\fR parameter and the \fIiteration\fR 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 \fIxorder\fR and \fIyorder\fR. 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 moments are used to compute +an ellipticity and position angle. The equations defining the moments and +related parameters are: + +.nf + 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)) +.fi + +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 +\fIfittype\fR parameter. The choices are "gaussian" and "moffat". If the +profile type is "moffat" there is an additional parameter "beta". This +value may be specified to fix it or given as INDEF to also be determined. +The profile equations are: + +.nf + I = Ic exp (-0.5 * (r / sigma)**2) (fittype = "gaussian") + I = Ic (1 + (r / alpha)**2)**(-beta) (fittype = "moffat") +.fi + +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 + +.nf + wt = exp (-(r/rhalf - 1)**2) for r/rhalf > 1 +.fi + +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 \fBpsfmeasure\fR. 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 \fIcenter\fR and \fIbackground\fR 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 \fBpsfmeasure\fR 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 \fIfittype\fR +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. + +.ls a +The output consists of the image line and column, the coordinates, the +final radius used for the photometry and fitting, magnitude, flux, mean +background, peak value of the profile fit, e, pa (in degrees between -90 +and +90 with 0 along the x axis), the Moffat beta value if a Moffat profile +is fit, and three measures of the FWHM. The coordinates are those +specified by the \fIwcs\fR and formatted by the format parameters. For the +logical wcs the coordinates will be the same as the column and line +values. If a value is numerically undefined then INDEF is printed. The +FWHM values are, in order, the profile fit to the enclosed flux, the +profile fit to the individual pixels, and the direct measurement from the +derivative of the enclosed flux profile. Note that except for the direct +method, the other estimates are not really measurements of the FWHM but are +quantities which give the correct FWHM for the specified profile type. +.le +.ls ',' +The output consists of the image line and column, magnitude, flux, number +of pixels within the aperture, mean background, r (moment FWHM), e, pa (in +degrees between -90 and +90 with 0 along the x axis), and the peak value +and FWHM of the profile fit. The label GFWHM indicates a Gaussian fit +while the label MFWHM indicates a Moffat profile fit. If a quantity is +numerically undefined then INDEF is printed. +.le + +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., \fInoao.digiphot.apphot\fR, should be +used if precise results are desired. +.le +.ls b +The integer pixel coordinates defining a region of the image are printed. +Two cursor positions are used to select the range of columns and lines. +The output format consists of the starting and ending column +coordinates and the starting and ending line coordinates. This format is +used as input by some tasks and can be used to generate image sections if +desired. +.le +.ls j, k +The fitted gaussian center, peak, sigma, full width at half maximum, and +background at the center is computed and printed. +.le +.ls m +Statistics of a rectangular region centered on the cursor position are +computed and printed. The size of the statistics box is set by the +parameters \fIncstat\fR and \fInlstat\fR. The output format consists +of the image section, the number of pixels, the mean, the median, the +standard deviation, the minimum, and the maximum. +.le +.ls x, y +The cursor x and y coordinates and the pixel value nearest this position +are printed. The 'y' key may be used define a relative origin. If +an origin is defined (is not 0,0) then additional quantities are printed. +These quantities are origin coordinates, the delta x and delta y distances, +the radial distance, and the position angle (in degrees counterclockwise from +the x axis). +.le +.ls z +A 10x10 grid of pixel values is printed. The integer coordinates are +also printed around the grid. +.le + +GRAPHICS OUTPUT + +The following commands produce graphics output to the specified graphics +device (normally the graphics terminal). + +.ls c +A plot of a column or average of columns is made with the line number as +the ordinate and the pixel value as the abscissa. The averaging number +and various graph options are specified by the parameters from the +\fBcimexam\fR parameter set. +.le +.ls e +A contour plot of a region centered on the cursor is made. The +size of the region and various contouring and labeling options are +specified by the parameters from the \fBeimexam\fR parameter set. +.le +.ls h +A histogram of a region centered on the cursor is made. The size +of the region and various binning parameters are specified by +the parameters from the \fBhimexam\fR parameter set. +.le +.ls l +A plot of a line or average of lines is made with the column number as +the ordinate and the pixel value as the abscissa. The averaging number +and various graph options are specified by the parameters from the +\fBlimexam\fR parameter set. +.le +.ls r, '.' +A radial profile plot is made. As with 'a'/',' there are options for centering +and background subtraction. There are also graphics option to set the +radius to be plotted (\fIrplot\fR) and to overplot the profile fit +(\fIfitplot\fR). The measurement algorithms are those described for the +'a'/',' key and the output is the same except that there is no header line and +the object center is given in the graph title rather than on the graphics +status line. The aperture sum and graph options are specified by the +parameters from the \fBrimexam\fR parameter set. +.le +.ls s +A surface plot of a region centered on the cursor is made. The size +of the region and various surface and labeling options are +specified by the parameters from the \fBsimexam\fR parameter set. +.le +.ls u, v +A plot of a vector defined by two cursor positions is made. The 'u' +plot uses the first cursor position to define the center of the vector +and the second position to define the endpoint. The vector is extended +an equal distance in the opposite direction and the graph x coordinates +are the radial distance from the center position. The 'v' plot +uses the two cursor positions as endpoints and the coordinates are +the radial distance from the first cursor position. The vector may +be averaged over a specified number of parallel vectors. The +averaging number and various graph options are specified by the parameters +from the \fBvimexam\fR parameter set. +.le + + +MISCELLANEOUS COMMANDS + +The following commands control useful features of the task. + +.ls d +The display command given by the parameter \fIdisplay\fR is given +with appropriate image name. By default this loads the image +display using the \fBtv.display\fR task. When using an input image +list this operation also appends new images to the list for subsequent +'n' and 'p' commands. +.le +.ls f +Redraw the last graph. If the \fIautoredraw\fR parameter is no then +this is used to redraw a graph after making parameter changes with +colon commands. If the parameter is yes then any colon command which +affects the current plot will execute a redraw automatically. +.le +.ls g, i +Cursor input may be selected to be from the graphics cursor (g) or +image display cursor (i). +.le +.ls n, p +Go to the next or previous image in the image list or display frames. +.le +.ls o +Overplot the next graph. This generally only makes sense with the +line, column, and histogram plots. +.le +.ls q +Quit the task. +.le +.ls t +Output an image centered on the cursor position with name and size set +by the \fIoutput\fR, \fIncoutput\fR and \fInloutput\fR parameters. +Note that the cursor input might be from a contour, surface, or other +plot as well as from the image display. +.le +.ls w +Toggle output to the logfile. If no logfile is specified this has no +effect except to print a message. If the logfile is specified a message +is printed indicating that the logfile has been opened or closed. +Every time the logfile is opened the current image name and title is +entered as well as when the image is changed. The logfile name may +be set or changed by a colon command. +.le +.ls :select +Select an image. If an input image list is used the specified index +number selects an image from the list. If an input image list is not +used and the image display is used then the specified display frame +is selected. If the new image is different from the previous image +an identification line is inserted in the logfile if it is open. +.le +.ls :eparam, :unlearn +These colon commands manipulate the various parameter sets as +described below. +.le +.ls :c<#>, :l<#> +Special colon commands to plot specific columns or lines, symbolically +shown as <#>, rather than use a cursor position. +.le +.ls :<column> <line> <key> +Special colon command syntax to explicitly give image coordinates for +a cursor command key. +.le + +COLON COMMANDS + +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: + +.nf + :c<column> or :l<line> +.fi + +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 \fBeparam\fR editor +and reinitialized to default values using the \fBunlearn\fR 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. + +.ih +COMMANDS + +.ce +Cursor Keys + +.nf +? 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 +.fi + +.ce +Colon Commands + +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. + +.nf +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 boundary 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 logarithmically? +logy chjklruv Plot y axis logarithmically? +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 photometry +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 +.fi +.ih +EXAMPLES +The following example illustrates many of the features in a descriptive +way using the standard image dev$pix. + +.nf + 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 +.fi +.ih +BUGS +If an operation is interrupted, e.g., an image display or surface plot, +\fIimexamine\fR is terminated rather than the operation in progress. + +When used on a workstation \fIimexamine\fR 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. +.ih +REVISIONS +.ls IMEXAMINE V2.11.4 +('t'): A new cursor key to create an output image. +.le +.ls IMEXAMINE V2.11 +('a' and 'r'): The fit to the radial profile points now includes both a +Gaussian and a Moffat profile. The Moffat profile exponent parameter, +beta, may be fixed or left free to be fit. + +('a' and 'r'): New estimates of 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. +.le +.ih +SEE ALSO +cursors, eparam, unlearn, plot.*, tvmark, digiphot.*, apphot.*, +implot, splot, imedit, radplt, imcntr, imhistogram, imstatistics, display +psfmeasure. +.endhelp diff --git a/pkg/images/tv/doc/tvmark.hlp b/pkg/images/tv/doc/tvmark.hlp new file mode 100644 index 00000000..b6611b22 --- /dev/null +++ b/pkg/images/tv/doc/tvmark.hlp @@ -0,0 +1,405 @@ +.help tvmark Dec89 images.tv +.ih +NAME +tvmark -- mark objects on the image display +.ih +USAGE +tvmark frame coords +.ih +PARAMETERS +.ls frame +The frame or image plane number of the display to be marked. +.le +.ls coords +The text file containing the coordinates of objects to be +marked, one object per line with x and y in columns 1 and 2 respectively. +An optional label may be read out of the third column. +If \fIcoords\fR = "", the coordinate file is undefined. +.le +.ls logfile = "" +The text file in which image cursor commands typed in interactive mode +are logged. If \fIlogfile\fR = "" no commands are logged. +If automatic logging is enabled, all cursor commands +are logged, otherwise the user must use the interactive keep keystroke +command to select specific cursor commands for logging. +Commands are not logged in non-interactive mode. +.le +.ls autolog = no +Automatically log all cursor commands in interactive mode. +.le +.ls outimage = "" +The name of the output snapshot image. +If tvmark is run in non-interactive mode and no command file is specified, +a copy of the frame buffer +is automatically written to the IRAF image \fIoutimage\fR after tvmark +terminates execution. +If \fIoutimage\fR = "" no output image is written. +In interactive mode or in non-interactive mode if a command file +is specified, the user can make snapshots of the frame buffer +with the interactive colon write command. In this case the name of the output +snapped image will be in order of priority, the name specified +by the user in the colon write ommand, "outimage.snap.version", or, +"imagename.snap.version". +.le +.ls deletions = "" +The extension of the output file containing objects which were deleted +from the coordinate file in interactive or command file mode. +By default no output deletions file is written. +If \fIdeletions\fR is not equal to the null string (""), then deleted +objects are written to a file called \fIcoords.deletions\fR. For +example if \fIcoords\fR = "nite1" and \fIdeletions\fR = "del", then the +deletions file will be called "nite1.del". +.le +.ls commands = "" +The text file containing the marking commands. +In interactive mode if \fIcommands\fR = "", +\fIcommands\fR is the image cursor. In non-interactive mode +cursor commands may be read from a text file, by setting \fIcommands\fR = +"textfile". This file may be a user +created command file, or the \fIlogfile\fR from a previous run of tvmark. +If \fIcommands\fR = "" in non-interactive mode, the default mark is drawn +on the display at the positions of all the objects in \fIcoords\fR. +.le +.ls mark = "point" +The default mark type. The options are: +.ls point +A point. To ensure legibility \fIpoint\fR is actually a square dot whose +size is specified by \fIpointsize\fR. +.le +.ls plus +A plus sign. The shape of the plus sign is determined by the raster font +and its size is specified by \fItxsize\fR. +.le +.ls cross +An x. The shape of the x is determined by the raster font and its size is +is specified by \fItxsize\fR. +.le +.ls circle +A set of concentric circles whose radii are specified by the \fIradii\fR +parameter. The radii are in image pixel units. If the magnifications +used by display are not equal in x and y circles will become ellipses +when drawn. +.le +.ls rectangle +A set of concentric rectangles whose lengths and width/length ratio are +specified by the \fIlengths\fR parameter. The lengths are specified in +image pixel units. If the magnifications used by the display are not +equal in x and y then squares will become rectangles when drawn. +.le +.le +.ls radii = "0" +If the default mark type is "circle" than concentric circles of radii +"r1,r2,...rN" are drawn around each selected point. +.le +.ls lengths = "0" +if the default mark type is "rectangle" then concentric rectangles of +length and width / length ratio "l1,l2,...lN ratio" are drawn around +each selected point. If ratio is not supplied, it defaults to 1.0 +and squares are drawn. +.le +.ls font = "raster" +The name of the font. At present only a simple raster font is supported. +.le +.ls color = 255 +The numerical value or color of the marks drawn. +Any number between 0 and 255 may be specified. +The meaning of the color is device dependent. +In the current version of the Sun/IRAF IMTOOL numbers between 202 +and 217 may be used to display graphics colors. The current color +assignments for IMTOOL are summarized later in this help page. +.le +.ls label = no +Label the marked coordinates with the string in the third column of +the text file \fIcoords\fR. \fIlabel\fR overrides \fInumber\fR. +.le +.ls number = no +Label the marked objects with their sequence number in the coordinate +list \fIcoords\fR. +.le +.ls nxoffset = 0, nyoffset = 0 +The x and y offset in display pixels of the numbers to be drawn. +Numbers are drawn by default with the lower left corner of the first +digit at the coordinate list position. +.le +.ls pointsize = 3 +The size of the default mark type "point". Point size will be rounded up +to the nearest odd number. +.le +.ls txsize = 1 +The size of text, numbers and the plus and cross marks to be written. +The size is in font units which are 6 display pixels wide and 7 display +pixels high. +.le +.ls tolerance = 1.5 +Objects marked by the cursor for deletion from the coordinate list +\fIcoords\fR must be less than or equal to \fItolerance\fR pixels +from the cursor position to be deleted. If 1 or more objects +is closer than \fItolerance\fR, the closest object is deleted. +.le +.ls interactive = no +Interactive mode. +.le +.ih +DESCRIPTION +TVMARK marks objects on the display by writing directly into +the frame buffer specified by \fIframe\fR. TVMARK can draw on +any devices supported by the IRAF \fIdisplay\fR program. +After marking, the +contents of the frame buffer may be written out to the IRAF image +\fIoutimage\fR. The output image is equal in size and intensity +to the contents of the frame buffer displayed at the time of writing. + +In interactive mode objects to be marked may be selected interactively +using the image cursor or read from the text file \fIcoords\fR. +Objects in the coordinate list +may be selected individually by number, +in groups by specifying a range of numbers, or the entire list may +be read. New objects may be added to the list interactively +using the append keystroke command. In batch mode cursor commands +may be read from a text file by setting \fIcommands\fR to the name +of the text file. This may be a user created file of cursor +commands or a log file from a previous interactive run of TVMARK. +If no command file is specified then all the objects in the coordinate +list are marked with the default mark type /fImark/fR. + +The mark commands entered in interactive mode can be saved in the text +file \fIlogfile\fR. If \fIautolog\fR +is enabled and \fIlogfile\fR is defined all cursor commands +are automatically logged. If \fIautolog\fR is turned off then the user +can select which commands are to be logged interactively using the +interactive keep keystroke. + +The default mark type are currently "none", "point", "plus", "cross", +"circle", a +list of concentric circles, and "rectangles", a list of concentric rectangles. +The size of the "point" mark is set using the parameter \fIpointsize\fR +while the sizes of the "plus" and "cross" mark types are set by the +\fItxsize\fR parameter. Txsize is in font units which for the simple raster +font currently implemented is six display pixels in x and seven display +pixels in y. +The \fIradii\fR and \fIlengths\fR parameters +describe the concentric circles and concentric rectangles to be drawn +respectively. +If \fInumber=yes\fR then objects in the coordinate list will be automatically +numbered as well as marked. The position of the number can be altered +with the \fInxoffset\fR and \fInyoffset\fR parameters. + +In interactive mode tvmark maintains a scratch buffer. The user opens +the scratch buffer by issuing a save command which saves the current +contents of the frame buffer in a temporary IRAF image. +The user can continue marking and if unsatisfied with the results +restore the last saved copy of the frame buffer with the restore +command. Subsections of the saved frame buffer can be restored to the +current frame buffer with the erase keystroke command. +Finally a snapshot of the frame buffer can be saved permanently by +using the write command. These snapped images can be redisplayed +by setting the display task parameter \fIztrans\fR = "none". +.ih +CURSOR COMMANDS + +.nf + Interactive TVMARK Keystroke/Colon Commands + +The following keystroke commands are available. + + ? Print help + + Mark the cursor position with + + x Mark the cursor position with x + . Mark the cursor position with a dot + c Draw defined concentric circles around the cursor position + r Draw defined concentric rectangles around the cursor position + s Draw line segments, 2 keystrokes + v Draw a circle, 2 keystrokes + b Draw a rectangle, 2 keystrokes + f Draw filled rectangle, 2 keystrokes + e Mark region to be erased and restored, 2 keystrokes + + - Move to previous object in the coordinate list + m Move to next object in the coordinate list + p Mark the previous object in the coordinate list + n Mark next object in the coordinate list + l Mark all the objects in the coordinate list + o Rewind the coordinate list + a Append object at cursor position to coordinate list and mark + d Delete object nearest the cursor position in the coordinate list + and mark + + k Keep last cursor command + q Exit tvmark + +The following colon commands are available. + + :show List the tvmark parameters + :move N Move to Nth object in coordinate list + :next N M Mark objects N to M in coordinate list + :text [string] Write text at the cursor position + :save Save the current contents of frame buffer + :restore Restore last saved frame buffer + :write [imagename] Write the contents of frame buffer to an image + +The following parameters can be shown or set with colon commands. + + :frame [number] + :outimage [imagename] + :coords [filename] + :logfile [filename] + :autolog [yes/no] + :mark [point|line|circle|rectangle|cross|plus] + :radii [r1,...,rN] + :lengths [l1,...,lN] [width] + :font [raster] + :color [number] + :number [yes/no] + :label [yes/no] + :txsize [1,2,..] + :pointsize [1,3,5...] +.fi + +.ih +CURRENT IMTOOL COLORS + +.nf + 0 = sunview background color (normally white) + 1-200 = frame buffer data values, windowed + 201 = cursor color (white) + + 202 = black + 203 = white + 204 = red + 205 = green + 206 = blue + 207 = yellow + 208 = cyan + 209 = magenta + 210 = coral + 211 = maroon + 212 = orange + 213 = khaki + 214 = orchid + 215 = turquoise + 216 = violet + 217 = wheat + + 218-254 = reserved for use by other windows + 255 = black (sunview foreground color) +.fi + +.ih +EXAMPLES +1. Display an image, mark all the objects in the coordinate file +m92.coo.1 with red dots, and save the contents of the frame buffer +in the iraf image m92r.snap. Redisplay the marked image. + +.nf + cl> display m92r 1 + cl> tvmark 1 m92.coo.1 outimage=m92r.snap col=204 + cl> display m92r.snap 2 ztrans="none" +.fi + +2. Execute the same command only number the objects in the coordinate +list instead of marking them. + +.nf + cl> display m92r 1 + cl> tvmark 1 m92.coo.1 outimage=m92r.snap mark=none\ + >>> number+ col=204 + cl> display m92r.snap 2 ztrans="none" +.fi + +3. Display an image and draw concentric circles with radii of 5, 10 and +20 pixels corresponding to an aperture radius and inner and outer +sky annulus around the objects in the coordinate list. + +.nf + cl> display m92r 1 + cl> tvmark 1 m92.coo.1 mark=circle radii="5,10,20" col=204 +.fi + +4. Display an image, mark objects in a coordinate list with dots +and append new objects to the coordinate file. + +.nf + cl> display m92r 1 + + cl> tvmark 1 m92.coo.1 interactive+ + ... type q to quit the help menu ... + ... type :number yes to turn on numbering ... + ... type l to mark all objects in the coordinate file + ... move cursor to desired unmarked objects and type a + ... type :write to take a snap shot of the frame buffer + ... type q to quit +.fi + +5. Make a finder chart of a region containing 10 stars by drawing +a box around the field, marking each of the 10 stars with a dot, +labeling each with an id and finally labeling the whole field. +Save all the keystroke commands in a log file. + +.nf + cl> display m92r 1 log=m92r.log auto+ + + cl> tvmark 1 "" interactive+ + + ... type q to quit the help menu ... + + ... to draw a box around the finder field move the cursor to the + lower left corner of the finder field and type b, move the + cursor the upper right corner of the field and type b again + + ... to mark and label each object move to the position of the + object and type ., next move slightly away from the object + and type :text id + + ... to label the chart with a title first type :txsize 2 for + bigger text then move the cursor to the position where + the title should begin and type :text title + + ... save the marked image with :write + + ... type q to quit the program +.fi + +6. Edit the log file created above to remove any undesired commands +and rerun tvmark redirecting cursor input to the log file. + +.nf + cl> display m92r 1 + cl> tvmark 1 "" commands=logfile inter- +.fi + +7. Draw a box on the display with a lower left corner of 101,101 and an +upper right corner of 200,200 using a simple cursor command file. +Note than in interactive mode the b key is the one that draws a box. + +.nf +The command file contains the following 3 lines + + 101.0 101.0 101 b + 200.0 200.0 101 b + 200.0 200.0 101 q + + cl> display m92r 1 + cl> tvmark 1 "" commands=commandfile inter- +.fi +.ih +BUGS +Tvmark is a prototype task which can be expected to undergo considerable +modification and enhancement in the future. The current version of this +task does not produce publication quality graphics. +In particular aliasing is easily visible in the code which draws circles +and lines. + +Input from the coordinate list is sequential. No attempt has been made +to arrange the objects to be marked in order for efficiency of input and +output. + +Note that the move command does not currently physically move the image +cursor. However the next mark drawn will be at the current coordinate +list position. + +Users may wish to disable the markcur option in the imtool setup window +before running tvmark. +.ih +SEE ALSO +display, imedit, imexamine +.endhelp diff --git a/pkg/images/tv/doc/wcslab.hlp b/pkg/images/tv/doc/wcslab.hlp new file mode 100644 index 00000000..0095c68c --- /dev/null +++ b/pkg/images/tv/doc/wcslab.hlp @@ -0,0 +1,698 @@ +.help wcslab Dec91 images.tv + +.ih +NAME +wcslab -- overlay a labeled world coordinate grid on an image + +.ih +USAGE +wcslab image + +.ih +PARAMETERS + +.ls image +The name of the image to be labeled. If image is "", the parameters +in wcspars will be used to draw a labeled coordinate grid. +.le +.ls frame +The display frame buffer displaying the image to be labeled. +.le +.ls usewcs = no +Use the world coordinate system specified by the parameters in the wcspars +parameter set in place of the image world coordinate system or if +image is "" ? +.le +.ls wcspars = "" +The name of the parameter set defining the world coordinate system +to be used if image is "" or if usewcs = "yes". The wcspars parameters +are described in more detail below. +.le +.ls wlpars = "" +The name of the parameter set which controls the +detailed appearance of the plot. The wlpars parameters are described +in more detail below. +.le +.ls fill = yes +If fill is no, wcslab tries to +create a square viewport with a maximum size dictated by the viewport +parameters. If fill is yes, then wcslab +uses the viewport exactly as specified. +.le +.ls vl = INDEF, vr = INDEF, vb = INDEF, vt = INDEF +The left, right, bottom, and top edges of the viewport in NDC (0-1) +coordinates. If any of vl, vr, vb, or vt are INDEF, +wcslab computes a default value. To overlay the plot +with a displayed image, vl, vr, vb, and vt must use the same viewport used +by the display task to load the image into the frame buffer. +.le +.ls overplot = no +Overplot to an existing plot? If yes, wcslab will not erase the +current plot. This differs from append in that a new viewport +may be defined. Append has priority if both +append and overwrite are yes. +.le +.ls append = no +Append to an existing plot? If no, wcslab resets the +graphics to a new viewport/wcs for each new plot. Otherwise, it uses +the scaling from a previous plot. If append=yes but no plot was drawn, it +will behave as if append=no. This differs from overplot in that +the same viewport is used. Append has priority if both +append and overwrite are yes. +.le +.ls device = "imd" +The graphics device. To create an overlay plot, device must be set +to one of the imdkern devices listed in dev$graphcap. To create a +plot of the coordinate grid in the +graphics window, device should be set to "stdgraph". +.le + +.ih +WCSPARS PARAMETERS + +.ls ctype1 = "linear", ctype2 = "linear" +The coordinate system type of the first and second axes. +Valid coordinate system types are: +"linear", and "xxx--tan", "xxx-sin", and "xxx-arc", where "xxx" can be either +"ra-" or "dec". +.le +.ls crpix1 = 0.0, crpix2 = 0.0 +The X and Y coordinates of the reference point in pixel space that +correspond to the reference point in world space. +.le +.ls crval1 = 0.0, crval2 = 0.0 +The X and Y coordinate of the reference point in world space that +corresponds to the reference point in pixel space. +.le +.ls cd1_1 = 1.0, cd1_2 = 0.0 +The FITS CD matrix elements [1,1] and [1,2] which describe the x-axis +coordinate transformation. These elements usually have the values +<xscale * cos (angle)> and, <-yscale * sin (angle)>, or, for ra/dec systems +<-xscale * cos (angle)> and <yscale * sin (angle)>. +.le +.ls cd2_1 = 0.0, cd2_2 = 1.0 +The FITS CD matrix elements [2,1] and [2,2] which describe the y-axis +coordinate transformation. These elements usually have the values +<xscale * sin (angle)> and <yscale * cos (angle)>. +.le +.ls log_x1 = 0.0, log_x2 = 1.0, log_y1 = 0.0, log_y2 = 1.0 +The extent in pixel space over which the transformation is valid. +.le + + +.ih +WLPARS PARAMETERS + +.ls major_grid = yes +Draw a grid instead of tick marks at the position of the major +axes intervals? If yes, lines of constant axis 1 and axis 2 values +are drawn. If no, tick marks are drawn instead. Major grid +lines / tick marks are labeled with the appropriate axis values. +.le +.ls minor_grid = no +Draw a grid instead of tick marks at the position of the +minor axes intervals? If yes, lines of constant axis 1 and axis 2 values +are drawn between the major grid lines / tick +marks. If no, tick marks are drawn instead. Minor grid lines / tick +marks are not labeled. +.le +.ls dolabel = yes +Label the major grid lines or tick marks? +.le +.ls remember = no +Modify the wlpars parameter file when done? If yes, parameters that have +been calculated by the task are written back to the parameter file. +If no, the default, the parameter file is left untouched by the task. +This option is useful for fine-tuning the appearance of the graph. +.le +.ls axis1_beg = "" +The lowest value of axis 1 in world coordinates units +at which a major grid line / tick mark will be drawn. +If axis1_beg = "", wcslab will compute this quantity. +Axis1_beg will be ignored if axis1_end and axis1_int are undefined. +.le +.ls axis1_end = "" +The highest value of axis 1 in world coordinate +units at which a major grid line / tick mark will be drawn. +If axis1_end = "", wcslab will compute this quantity. +Axis1_end will be ignored if axis1_beg and axis1_int are undefined. +.le +.ls axis1_int = "" +The interval in world coordinate units at which +major grid lines / tick marks will be drawn along axis 1. +If axis1_int = "", wcslab will compute this quantity. +Axis1_int will be ignored if axis1_beg and axis1_end are undefined. +.le +.ls axis2_beg = "" +The lowest value of axis 2 in world coordinates units +at which a major grid line / tick mark will be drawn. +If axis2_beg = "", wcslab will compute this quantity. +Axis2_beg will be ignored if axis2_end and axis2_int are undefined. +.le +.ls axis2_end = "" +The highest value of axis 2 in world coordinate +units at which a major grid line / tick mark will be drawn. +If axis2_end = "", wcslab will compute this quantity. +Axis2_end will be ignored if axis2_beg and axis2_int are undefined. +.le +.ls axis2_int = "" +The interval in world coordinate units at which +major grid lines / tick marks will be drawn along axis 2. +If axis2_int = "", wcslab will compute this quantity. +Axis2_int will be ignored if axis1_beg and axis1_end are undefined. +.le +.ls major_line = "solid" +The type of major grid lines to be plotted. +The permitted values are "solid", "dotted", "dashed", and "dotdash". +.le +.ls major_tick = .03 +Size of major tick marks relative to the size of the viewport. +By default the major tick marks are .03 times the size of the +viewport. +.le +.ls axis1_minor = 5 +The number of minor grid lines / tick marks that will appear between major +grid lines / tick marks for axis 1. +.le +.ls axis2_minor = 5 +The number of minor grid lines / tick marks that will appear between major +grid lines / tick marks for axis 2. +.le +.ls minor_line = "dotted" +The type of minor grid lines to be plotted. +The permitted values are "solid", "dotted", "dashed", and "dotdash". +.le +.ls minor_tick = .01 +Size of minor tick marks relative to the size of the viewport. +BY default the minor tick marks are .01 times the size of the +viewport. +.le +.ls tick_in = yes +Do tick marks point into instead of away from the graph ? +.le +.ls axis1_side = "default" +The list of viewport edges, separated by commas, on which to place the axis +1 labels. If axis1_side is "default", wcslab will choose a side. +Axis1_side may contain any combination of "left", "right", +"bottom", "top", or "default". +.le +.ls axis2_side = "default" +The list of viewport edges, separated by commas, on which to place the axis +2 labels. If axis2_side is "default", wcslab will choose a side. +Axis2_side may contain any combination of "left", "right", +"bottom", "top", or "default". +.le +.ls axis2_dir = "" +The axis 1 value at which the axis 2 labels will be written for polar graphs. +If axis2_dir is "", wcslab will compute this number. +.le +.ls justify = "default" +The direction with respect to axis 2 along which the axis 2 +labels will be drawn from the point they are labeling on polar graphs. +If justify = "", then wcslab will calculate this quantity. The permitted +values are "default", "left", "right", "top", and "bottom". +.le +.ls labout = yes +Draw the labels outside the axes ? If yes, the labels will be drawn +outside the image viewport. Otherwise, the axes labels will be drawn inside +the image border. The latter option is useful if the image fills the +display frame buffer. +.le +.ls full_label = no +Always draw all the labels in full format (h:m:s or d:m:s) if the world +coordinate system of the image is in RA and DEC ? If full_label = no, then +only certain axes will be labeled in full format. The remainder will +be labeled in minutes or seconds as appropriate. +.le +.ls rotate = yes +Permit the labels to rotate ? +If rotate = yes, then labels will be written +at an angle to match that of the major grid lines that are being +labeled. If rotate = no, then labels are always written +"normally", that is horizontally. If labout = no, then rotate is +set to "no" by default. +.le +.ls label_size = 1.0 +The size of the characters used to draw the major grid line labels. +.le +.ls title = "imtitle" +The graph title. If title = "imtitle", then a default title containing +the image name and title is created. +.le +.ls axis1_title = "" +The title for axis 1. By default no axis title is drawn. +.le +.ls axis2_title = "" +The title for axis 2. By default no axis title is drawn. +.le +.ls title_side = "top" +The side of the plot on which to place the title. +The options are "left", "right", "bottom", and "top". +.le +.ls axis1_title_side = "default" +The side of the plot on which to place the axis 1 title. +If axis1_title_side = "default", wcslab will choose a side for the title. +The permitted values are "default", "right", "left", "top", and +"bottom". +.le +.ls axis2_title_side = "default" +The side of the plot on which to place the axis 2 title. +If axis2_title_side = "default", wcslab will choose a side for the title. +The permitted values are "default", "right", "left", "top", and +"bottom". +.le +.ls title_size = 1.0 +The size of characters used to draw the title. +.le +.ls axis_title_size = 1.0 +The size of the characters used to draw the axis titles. +.le +.ls graph_type = "default" +The type of graph to be drawn. If graph_type = "default", wcslab will +choose an appropriate graph type. The permitted values are "normal", "polar", +and "near_polar". +.le + +.ih +DESCRIPTION + +WCSLAB draws a labeled world coordinate grid on the graphics device +\fIdevice\fR using world coordinate system (WCS) +information stored in the header of the IRAF image \fIimage\fR if +\fIusewcs\fR is "no", or +in \fIwcspars\fR if \fIusewcs\fR is "yes" or \fIimage\fR is "". +WCSLAB currently supports the following coordinate system types 1) +the tangent plane, sin, and arc sky projections in right ascension +and declination and 2) any linear coordinate system. + +By default WCSLAB draws on the image display device, displacing +the currently loaded image pixels with graphics pixels. Therefore in order +to register the coordinate grid plot with the image, the image must +loaded into the image display with the DISPLAY task, prior to +running WCSLAB. + +If the viewport parameters \fIvl\fR, \fIvr\fR, \fIvb\fR, and +\fIvt\fR are left undefined, WCSLAB will try to match the viewport +of the coordinate grid plot with the viewport of the currently +displayed image in the selected frame \fIframe\fR. +This scheme works well in the case where \fIimage\fR is smaller +than the display frame buffer, and in the case where \fIimage\fR is +actually a subsection of the image currently loaded into the display frame +buffer. In the case where \fIimage\fR +fills or overflows the image display frame buffer, WCSLAB +draws the appropriate coordinate grid but is not able to draw the +titles and labels which would normally appear outside the plot. +In this case the user must, either adjust the DISPLAY parameters +\fIxmag\fR, and \fIymag\fR so that the image will fit in the frame +buffer, or change the DISPLAY viewport parameters \fIxsize\fR and +\fIysize\fR so as to display only a fraction of the image. + +WCSLAB can create a new plot each time it is run, \fIappend\fR = no +and \fIoverplot\fR = no, add a new graph to an existing plot +if \fIoverplot\fR = yes and \fIappend\fR=no, +or append to an existing plot if \fIappend\fR = yes. +For new or overplots WCSLAB computes the viewport and window, otherwise it +uses the viewport and window of a previously existing plot. If \fIdevice\fR +is "stdgraph", then WCSLAB will clear the screen between each new plot. +This is not possible if \fIdevice\fR is one of the "imd" devices +since the image display graphics kernel writes directly into the display +frame buffer. In this case the user must redisplay the image and rerun +WCSLAB for each new plot. + +The parameters controlling the detailed appearance of the plot +are contained in the parameter set specified by \fIwlpars\fR. + +.ih +THE USER-DEFINED WCS + +The parameters in WCSPARS are used to define the world +coordinate system only if, 1) the parameter \fIusewcs\fR is "yes" +or, 2) the input image is undefined. +This user-defined WCS specifies the transformation from the logical coordinate +system, e.g. pixel units, to a world system, e.g. ra and dec. + +Currently IRAF supports two types of world coordinate systems: +1) linear, which provides a linear mapping from pixel units to +the world coordinate system 2) and the sky projections which provide +a mapping from pixel units to ra and dec. The parameters +\fIctype1\fR and \fIctype2\fR define which coordinate system will be in +effect. If a linear system is +desired, both \fIctype1\fR and \fIctype2\fR must be "linear". +If the tangent plane sky projection is desired, +and the first axis is ra and the +second axis is dec, then \fIcypte1\fR and \fIctype2\fR +must be "ra---tan" and "dec--tan" respectively. +To obtain the sin or arc projections "tan" is replaced with "sin" or +"arc" respectively. + +The scale factor and rotation between the logical and world coordinate +system is described by the CD matrix. Using matrix +multiplication, the logical coordinates are multiplied by the CD +matrix to produce the world coordinates. The CD matrix is represented in +the parameters as follows: + +.nf + + |---------------| + | cd1_1 cd1_2 | + | | + | cd2_1 cd2_2 | + |---------------| + +.fi + +To construct a typical CD matrix, the following definitions of the +individual matrix elements may be used: + +.nf + + cd1_1 = xscale * cos (ROT) + cd1_2 = -yscale * sin (ROT) + cd2_1 = xscale * sin (ROT) + cd2_2 = yscale * cos (ROT) + +.fi + +where xscale and yscale are the scale factors from the logical to world +systems, e.g. degrees per pixel, and ROT is the angle of rotation between +the two systems, where positive rotations are counter-clockwise. + +The ra/dec transformation is a special case. Since by convention ra +increases "to the left", opposite of standard convention, the first axis +transformation needs to be multiplied by -1. This results in the +following formulas: + +.nf + + cd1_1 = -xscale * cos (ROT) + cd1_2 = yscale * sin (ROT) + cd2_1 = xscale * sin (ROT) + cd2_2 = yscale * cos (ROT) + +.fi + +Finally, the origins of the logical and world systems must be defined. +The parameters \fIcrpix1\fR and \fIcrpix2\fR define the coordinate in +the logical space that corresponds to the coordinate in world space +defined by the parameters \fIcrval1\fR and \fIcrval2\fR. The coordinates +(crpix1, crpix2) in logical space, when transformed to world space, +become (crval1, crval2). + +The last set of parameters, log_x1, log_x2, log_y1, log_y2, define the +region in the logical space, e.g. in pixels, over which the transformation +is valid. + +.ih +AXIS SPECIFICATION + +For all \fIlinear\fR transformations axis 1 and axis 2 specify which axis in +the image is being referred to. +For example in a 2-dimensional image, the FITS image header keywords +CTYPE1, CRPIX1, CRVAL1, CDELT1, +CD1_1, and CD1_2 define the world coordinate transformation for axis 1. +Similarly the FITS image header keywords +CTYPE2, CRPIX2, CRVAL2, CDELT2, +CD2_1, CD2_2, define the world coordinate transformation for axis 2. + +THIS RULE DOES NOT APPLY TO THE TANGENT PLANE, SIN, and ARC SKY +PROJECTION WCS'S. +For this type of WCS axis 1 and axis 2 +always refer to right ascension and declination respectively, +and WCSLAB assumes that all axis 1 parameters refer to right +ascension and all axis 2 parameters refer to declination, regardless of +which axis in the image WCS actually specifies right ascension and declination. + +.ih +GRID DRAWING + +There are two types of grid lines / tick marks, "major" and +"minor". The major grid lines / tick marks are the lines / ticks +that will be labeled. The minor grid lines / tick marks are plotted +between the major marks. Whether lines or tick marks are drawn is +determined by the boolean parameters \fImajor_grid\fR and \fIminor_grid\fR. +If yes, lines are drawn; if no, tick marks are drawn. How the lines +appear is controlled by the parameters \fImajor_line\fR and \fIminor_line\fR. + +The spacing of minor marks is controlled by the parameters \fIaxis1_minor\fR +and \fIaxis2_minor\fR. These parameters specify the number of minor marks +that will appear between the major marks along the axis 1 +and axis 2 axes. + +Spacing of major marks is more complicated. WCSLAB tries to +present major marks only along "significant values" in the +coordinate system. For example, if the graph spans several hours of +right ascension, the interval between major marks will in general be an +hour and the major marks will appear at whole hours within the graph. +If what WCSLAB chooses is unacceptable, the interval and range can +be modified by the parameters \fIaxis1_int\fR, \fIaxis1_beg\fR, +\fIaxis1_end\fR for the axis 1, and \fIaxis2_int\fR, \fIaxis2_beg\fR, +and \fIaxis2_end\fR for axis 2. All three parameters must be specified for +each axis in order for the new values to take affect + +.ih +GRAPH APPEARANCE + +WCSLAB supports three types of graph: normal, polar, and near_polar. + +A normal graph is the usual Cartesian graph where lines of constant +axis 1 or 2 values cross at least two different sides of the graph. +WCSLAB will by default plot a normal type graph for any image 1) +which has no defined WCS 2) which has a linear WCS 3) where the sky +projection WCS approximates a Cartesian system. + +A polar graph is one in which the north or south pole of the +coordinate system actually appears on the graph. +Lines of constant declination are no longer approximately +straight lines, but are circles which may not intersect any +of the edges of the graph. In this type of graph, axis 1 values +are labeled all the way around the graph. +Axis 2 values are labeled within the graph +next to each circle. An attempt is made to label as many circles as +possible. However, if the WCSLAB's defaults are not agreeable, +the parameters, \fIaxis2_dir\fR and \fIjustify\fR, can be modified +to control how this labeling is done. +\fIAxis2_dir\fR specifies along which axis 1 value the +axis 2 labels should be written. \fIJustify\fR specifies on which side of +this value the label should appear. + +The near_polar graph is a cross between the normal graph and the polar +graph. In this case the pole is not on the graph, but is close enough +to significantly affect the appearance of the plot. The near_polar graph +is handled like a polar graph. + +The parameter \fIgraph_type\fR can be used to force WCSLAB +to plot a graph of the type specified, although in this case it +may be necessary to modify the values of other WLPARS parameters to +obtain pleasing results. For example trying to plot a polar graph as +Cartesian may producing a strange appearing graph. + +.ih +GRAPH LABELING + +Due to the variety of graph types that can be plotted (see above), and +the arbitrary rotation that any WCS can have, the task of labeling +the major grid lines in a coherent and pleasing manner is not trivial. + +The basic model used is the Cartesian or normal graph. Labels +normally appear on the left and bottom edges of the graph with a side +devoted solely to one of the WCS coordinate axis. For example, right +ascension might be labeled only along the bottom edge of the graph +and declination only along the left edge, or vice versa. + +If the defaults chosen by WCSLAB are unacceptable, the +parameters \fIaxis1_side\fR and \fIaxis2_side\fR, can be used to specify which +side (or sides) the labels for axis 1 and axis 2 will appear. +Either a single side or a list of sides can be specified for either +axis. If a list is specified, labels will appear on each side listed, +even if the same side appears in both of the parameters. In this way, +labels can be made to appear on the same side of the graph. + +.ih +LABEL APPEARANCE + +Due to coordinate rotations, lines of constant axis 1 or axis 2 value +may not intersect the edges +of the graph perpendicularly. To help clarify which line belongs to +which label, the labels will be drawn at an angle equal to that of the +line which is being labeled. If this is not desired, +the parameter \fIrotate\fR may be set to no, and labels will always appear +"normal", i.e. the text will not be rotated in any way. + +By default, all labels will be shortened to the smallest unit +needed to indicate the value of the labeled line. For example, if the +graph spans about 30 seconds of declination, the interval between the +labels will be approximately 5 or 10 seconds. The first label will contain the +full specification, i.e. -22:32:20. But the rest of the labels will +only be the seconds, i.e. 30, 40, 50. However, at the change in +minutes, the full format would be used again, -22:33:00, but then +again afterwards only seconds will be displayed, i.e. 10, 20, etc. +If this shortening of labels is undesirable, it +can be turned off by setting the parameter \fIfull_label\fR to yes. This +forces every label to use the full specification. + +Finally, the parameter \fIlabel_size\fR can be used to adjust the size of the +characters used in the axis labels. + +.ih +TITLES + +A graph title may specified using the parameter \fItitle\fR. If \fItitle\fR += "imtitle" a default title constructed from the image name and title +is used. The location and size of the graph title are controlled by +the parameters \fItitle_side\fR and \fItitle_size\fR. +Similarly the content, placement and size of the axis titles are +controlled by the parameters \fIaxis1_title\fR, \fIaxis2_title\fR, +\fIaxis1_title_side\fR, \fIaxis2_title_side\fR, and +\fIaxis_title_size\fR. + +.ih +OUTPUT FORMATS + +If \fIremember\fR = yes, the coordinates are output to the parameter set +WLPARS in a form suitable for the type of system the coordinates +represent. For example right +ascensions are output in HH:MM:SS (hours:minutes:seconds) and +declinations are output in DD:MM:SS (degrees:minutes:seconds). +If the input parameters are changed, for example axis1_int, their values +must be input in the same format. +If the WCS is linear, then the parameters will not be formatted in any special +way; i.e. no assumptions are made about units, etc. + +.ih +EXAMPLES + +1. Display the 512 pixel square IRAF test image dev$pix in an 800 square +display window and overlay it with a labeled coordinate grid. Since +dev$pix does not have a defined WCS a pixel coordinate grid will appear. + +.nf + cl> display dev$pix 1 + + ... display the image in frame 1 + + cl> wcslab dev$pix 1 + + ... the coordinate grid in green will be plotted on the display +.fi + +2. Redisplay the previous image and by overlay the labeled +coordinate grid on the inner 100 by 400 pixels in x and y. + +.nf + cl> display dev$pix 1 + + ... erase the graphics by redisplaying the image + + cl> wcslab dev$pix[100:400,100:400] 1 +.fi + +3. Display an 800 square image which has a defined linear WCS in an 800 square +display window and overlay it with the coordinate grid. Reduce +the display viewport in order to leave space around the edge of the +displayed image for the labels and titles. + +.nf + cl> display image 1 xsize=0.8 ysize=0.8 fill+ + cl> wcslab image 1 vl=.1 vr=.9 vb=.1 vt=.9 +.fi + +4. Repeat the previous example using a different combination of display +and wcslab parameters to achieve the same goal. + +.nf + cl> display image 1 xmag=0.8 ymag=0.8 + cl> wcslab image 1 +.fi + +5. Display a section of the previous image and overlay it with a +coordinate grid. Note that the same section should be specified in +both cases. + +.nf + cl> display image[101:700,101:700] 1 + cl> wcslab image[101:700,101:700] 1 +.fi + +6. Display a 512 square image with a defined tangent plane sky projection +in an 800 square frame buffer and overlay the labeled coordinate grid. The +standard FITS keywords shown below define the WCS. This WCS is +approximately correct for the IRAF test image dev$pix. + +.nf + # IRAF image header keywords which define the WCS + + CRPIX1 = 257.75 + CRPIX2 = 258.93 + CRVAL1 = 201.94541667302 # RA is stored in degrees ! + CRVAL2 = 47.45444 + CTYPE1 = 'RA---TAN' + CTYPE2 = 'DEC--TAN' + CDELT1 = -2.1277777E-4 + CDELT2 = 2.1277777E-4 + + + cl> display dev$pix 1 + + cl> wcslab dev$pix 1 +.fi + +7. Display a 512 square image with a defined tangent plane sky projection +approximately centered on the north celestial pole in an 800 square frame +buffer. The FITS keywords shown below define the WCS. + + +.nf + # IRAF image header keywords which define the WCS + + CRPIX1 = 257.75 + CRPIX2 = 258.93 + CRVAL1 = 201.94541667302 # RA is stored in degrees ! + CRVAL2 = 90.00000 + CTYPE1 = 'RA---TAN' + CTYPE2 = 'DEC--TAN' + CDELT1 = -2.1277777E-4 + CDELT2 = 2.1277777E-4 + + cl> display northpole 1 + + cl> wcslab northpole 1 +.fi + +8. Display and label a 512 square image which has no WCS information +using the values of the parameters in wcspars. The center pixel (256.0, 256.0) +is located at (9h 22m 30.5s, -15o 05m 42s), the pixels are .10 +arcseconds in size, and are rotated 30.0 degrees counter-clockwise. + +.nf + + cl> lpar wcspars + + ctype1 = 'ra---tan' + ctype2 = 'dec--tan' + crpix1 = 256.0 + crpix2 = 256.0 + crval1 = 140.62708 + crval2 = -15.09500 + cd1_1 = -2.405626e-5 + cd1_2 = 1.388889e-5 + cd2_1 = 1.388889e-5 + cd2_2 = 2.405626e-5 + log_x1 = 1. + log_x2 = 512. + log_y1 = 1. + log_y2 = 512. + + cl> display image 1 + + cl> wcslab image usewcs+ + +.fi +.ih +AUTHORS +The WCSLAB task was written by members of the STScI SDAS programming group +and integrated into the IRAF DISPLAY package by members of the IRAF +programming group for version 2.10 IRAF. +.ih +SEE ALSO +display, gcur, imdkern +.endhelp |