More detailed help is available on the following topics:
Please contact iraf@noao.edu with comments, bugs, or suggestions. More detailed documentation is also available in the man page for this task.
Getting Started GUI Overview Mouse Operations Keystroke Accelerators Command-line Options Client Connections Frame Buffers Support for 16 Frames Markers Panner Marker Magnifier Marker Coords Box Marker Ruler Markers General Markers Menu Options Real-Time WCS/Pixel Readout Freezing Cursor Readout Auto-Registration of Images Image Cut Graphics Peak-Up Cursor Centroid Positioning Integrated Control Panel Display Panel View Controls Enhancement Controls Blink Controls Options: Panner Magnifier Coords Box Autoscale Antialias Tile Frames Warnings Centroid Peaks Colormap Selection Builtin Colormaps User-defined Colormaps Load Panel Directory browsing File Patterns Direct File Load Frame Selections Save Panel File Name Format Color Print Panel Postscript Options Color Options Processing Options Printer selection Info Panel Tile Panel Coords Panel Tcl Interactie Shell
When run in standalone mode, images may be loaded on the command line or by using the Load Panel. This allows you to browse images and perform the same manipulations as if they had been displayed by a client.
The GUI consists of a large image display window and a number of smaller pannels that control various specific functions such as image Load, Save and Print as well as a general purpose Control Panel. The main window menubar has several menu buttons to the left: the Files menu is used to load/save/print an image as well as quit the task. The View menu let's you select the image orientation, zoom, colormap or frame. The Options menu allows you to call up control panels, toggle markers or blinking etc. Some of this functionality is duplicated elsewhere in the GUI. The right side of the menubar contains command buttons to flip the image as well as buttons for frame selection and the help button.
For more detailed information on the operation of the control panels please see the on-line help (i.e. use the '?' button or Alt-h keystroke in the main image window).
Clicking on MB2 in the main image window pans (one click) or zooms (two clicks) the image. Further clicks cycle through the builtin zoom factors. Moving the pointer to a new location and clicking moves the feature under the pointer to the center of the display window. Holding down the Shift key while clicking MB2 will cause a full-screen crosshair cursor to appear until the button is released, this can be useful for fine positioning of the cursor.
MB3 is used to adjust the contrast and brightness of the displayed image. The position of the pointer within the display window determines the contrast and brightness values. Click once to set the values corresponding to the pointer location, or click and drag to continuously adjust the display.
Misc Functions Ctrl-b Previous (back) frame Ctrl-c Center frame Ctrl-f Forward frame Ctrl-i Invert colormap Ctrl-m Toggle magnifier Ctrl-n Normalize Ctrl-p Toggle panner Ctrl-r Register Ctrl-s Match LUT scaling Ctrl-t Tile frames toggle Ctrl-u Unzoom (zoom=1) Ctrl-x Flip X Ctrl-y Flip Y Ctrl-= Print using current setup Ctrl-< Decrease blink rate (blink faster) Ctrl-> Increase blink rate (blink slower) Ctrl-+ Zoom in Ctrl-- Zoom out Alt-1 thru Alt-4 Set frame to be displayed Ctrl-1 thru Ctrl9 Set integer zoom factor Ctrl-Alt-q Quit Ctrl-Alt-f Fitframe Panel Toggles Alt-b Blink frames Alt-c Control panel Alt-h Help popup Alt-i Info box popup Alt-l Load file popup Alt-p Print popup Alt-s Save popup Alt-t TclShell popup Cursor Positioning Ctrl-h / Ctrl-Left Move cursor one pixel left Ctrl-j / Ctrl-Down Move cursor one pixel down Ctrl-k / Ctrl-Up Move cursor one pixel up Ctrl-l / Ctrl-Right Move cursor one pixel right Shift-Ctrl-h Move cursor ten pixels left Shift-Ctrl-Left Move cursor ten pixels left Shift-Ctrl-j Move cursor ten pixels down Shift-Ctrl-Down Move cursor ten pixels down Shift-Ctrl-k Move cursor ten pixels up Shift-Ctrl-Up Move cursor ten pixels up Shift-Ctrl-l Move cursor ten pixels right Shift-Ctrl-Right Move cursor ten pixels right Auto-Registration Ctrl-a Toggle auto-registration Ctrl-o Set frame offset Frame Positioning Ctrl-Left Shift one full frame left Ctrl-Down Shift one full frame down Ctrl-Up Shift one full frame up Ctrl-Right Shift one full frame right Ctrl-Alt-Left Shift one half frame left Ctrl-Alt-Down Shift one half frame down Ctrl-Alt-Up Shift one half frame up Ctrl-Alt-Right Shift one half frame right Peak Up Centroiding Ctrl-[ Decrease centroiding box size Ctrl-] Increase centroiding box size Ctrl-0 (zero) Centroid/find local maximum Alt-Ctrl-0 (zero) Find local minimum Mouse Button Events Shift-Btn1Down Turn on magnifier Shift-Btn1Up Turn off magnifier Shift-Btn2Down Turn on crosshair cursor Shift-Btn2Up Turn off crosshair cursor Btn1Down Create a Marker Btn1Motion Resize marker being created Btn2Down Zoom/center on cursor position Btn3Down/Motion Brightness/contrast scale the image Ctrl-Btn1Down Create Ruler Marker Ctrl-Btn1Motion Resize Ruler Marker being created Ctrl-Btn1Up Destroy Ruler Marker Alt-Motion Freeze cursor readout
The format of the frame buffer configuration file is
configno nframes width height [extra fields] e.g. 1 2 512 512 2 2 800 800 3 1 1024 1024 # commentAt most 128 frame buffer sizes may be defined, each configuration may define up to 16 frames, configuration numbers need not be sequential.
As part of the extensive GUI changes with the V1.3 release, support for the full 16 frames allowed by the IIS protocol is now available. IRAF V2.11.4 or later client tasks (and CDL library) are required to take advantage of this frames. All changes are backwards compatible, older versions of IRAF will continue to work but cannot access more than the original four frames. The new DISPLAY task will automatically sense whether the display server being used supports 16 frames or the original 4 and adjust the 'frame' parameter maximum accordingly. The changes are fully backwards compatible for other servers.
More frames are possible if needed but will require further changes to the client IRAF code to be effective. Allowing creation of more than 16 frames by the Load panel can be done independently but would also require numerous code change to XImtool. Please contact site support if there is a need for this, or for workaround suggestions depending on your application.
-basePixel <num> Base colormap pixel number -cmap1 <file> User cmap 1 -cmap2 <file> User cmap 2 -cmapDir1 <dir> User cmapDir 1 -cmapDir1 <dir> User cmapDir 2 -cmapInitialize <bool> Initialize colormap at startup -cmapName <name> Private colormap name -config <num> Initial config number -defgui Print default GUI to stdout -displayPanner <bool> Display panner box -displayCoords <bool> Display wcs coords box -fifo <pipe> Fifo pipe to use -fifo_only Use fifo pipes only -gui <file> GUI file to use -help Print command-line summary -imtoolrc <file> Frame buffer configuration file -inet_only Use inet sockets only -invert Invert colormap on startup? -ismdev ISM socket template -maxColors <num> Number of colors -memModel <type> Memory model (fast,small,beNiceToServer) -nframes <num> Number of frames at startup -port <num> Inet port to use -printConfig <file> Printer configuration file -port_only Use inet sockets only -tile Tile frames on startup? -unix <name> Unix socket to use -unix_only Use unix sockets only <file> File to load on startup
The panner window always displays the full frame buffer. Try setting the frame buffer configuration to a nonsquare frame buffer (e.g. imtcryo) and then displaying a square image (e.g. dev$pix) and the panner will show you exactly where the image has been loaded into the frame.
The panner window uses two markers, one for the window border and one to mark the displayed region of the frame. Most of the usual marker keystrokes mentioned below apply to these markers as well, e.g. you can use MB1 to reposition on the panner window within the main image display window, or to drag the region marker within the panner (pan the image). Resizing the region marker zooms the image; this is a non-aspect constrained zoom. The panner window itself can be resized by dragging a corner with MB1. Typing delete or backspace anywhere in the panner window deletes the panner.
A special case is MB2. Hitting MB2 anywhere in the panner window pans the image to that point. This is analogous to typing MB2 in the main display window to pan the image.
The panner marker can be disabled by defining the displayPanner GUI resource, its size and location can be controlled using the pannerArea and pannerGeom GUI resources respectively.
By default the magnifier marker is not visible, to toggle it select the Magnifier option from the Options menubar button. Alternatively, for just a quick look holding down the Shift Key and MB2 Button will display the marker until the button is released.
The magnifier marker can be disabled by defining the displayMagnifier GUI resource, its size and location can be controlled using the magnifierAreaand magnifierGeom GUI resources respectively.
Ximtool provides a limited notion of world coordinates, allowing frame buffer pixel coordinates and pixel values to be converted to some arbitrary client defined coordinate system. The coords box feature is used to display these world coordinates as the pointer is moved about in the image window.
The quantities displayed in the coords box are X, Y, and Z: the X,Y world coordinates of the pointer, and Z, the world equivalent of the pixel value under the pointer. All coordinate systems are linear. The precision of a displayed quantity is limited by the range of values of the associated raw frame buffer value. For example, if the display window is 512x512 only 512 coordinate values are possible in either axis (the positional precision can be increased however by zooming the image). More seriously, at most about 200 pixel values can be displayed since this is the limit on the range of pixel values loaded into the frame buffer. If a display pixel is saturated a "+" will be displayed after the intensity value.
The coords box is a marker (text marker) and it can be moved and resized with the pointer like any other marker.
Holding down the Ctrl key and the Left-Mouse-Button while moving the mouse will drag out a "ruler marker" measuring the distance from the initial point to the current mouse position. Releasing the Ctrl key before lifting the mouse button will leave the marker on the display, otherwise it will be erased automatically once the mouse button is released. Any number of ruler markers can be created in the frame.
Distances are measured by default in image logical pixels however the Right-Mouse-Button can be used inside the marker to popup a menu of options:
The marker can also be destroyed by hitting the Delete or Backspace key while the cursor is in the marker. There is presently no way to move the marker to a new position in the frame.
WCS readout is enabled by default but can be toggled or reset using the WCS/Pix button on the Coords tab in the control panel or the ISM toggle on the alt-gui menubar. When enabled, images currently in the server or subsequently displayed will be passed to the external process where they are cached for access. Cursor movements generate an event that maps the current frame buffer position to a position in the cached image. The ISM (ISM is Image Support Module) task then reads the image to determine the pixel value (or a small table of values around the current position), and computes one or more coordinates from the image position. The ISM task also has access to the associated BPM images and can optionally return bad pixel information during the cursor readout.
By default, the logical and world image coordinates are displayed to both the Coords panel readout as well as the main display window wcsbox text marker. Alternate coordinate systems (e.g. transformation of equatorial to galactic coordinates or some other sky system, physical coords, amplifier coords, etc) can be selected for display by hitting the Options toggle on the Coords panel. Available coordinate systems are chosen using the Type menu on the panel, the readout format (sexigesimal, degrees, etc) using the Format menu, and the display to the current panel or main image window using the remaining toggles for each WCS. Up to four systems may be displayed at one time, the coordinate panel and wcsbox marker will adjust size automatically depending on the display.
By selecting the BPM Data toggle from the Coords.Options panel ximtool is able to flag pixels in images with an associated bad pixel mask. This bad pixel mask is currently assumed to be named in the image header "BPM" keyword by convention. If the cursor passes over a bad pixel in the mask, the Coords bpm display as well as the main window wcsbox will change to a red background color. Only the Coords display will show the value, any non-zero value will be flagged with the color change.
With the ISM enabled the Compass indicator will display a set of arrows showing North-East if a WCS is available, otherwise just the current X-Y axes are shown. The pixel table will display actual pixel values from the image, with the ISM off the pixel table displays the scaled image values from the frame buffer.
Holding down the Alt key will now freeze the cursor display readout and draw crosshairs on the screen at the last position. This can be used for example to position the cursor but then allow the cursor to be moved to another window (to enter text, start a program, whatever) without losing the position information displayed on the screen.
The auto-register feature allows you specify a registration of two or more display frames with an offset. When enabled, this registration is maintained for all frames in the list if any one of them is panned or zoomed to a new location in the frame buffer.
For example, to use this feature do the following:
The register display list is shared with the blink list and can be set using the Display control panel. By default all frames are included in the list. For accessing more than four frames, use the box icon in the Blink/Register box of the Display control panel to bring up a new window with access to all 16 available frames.
XImtool now has the ability to display horizontal and vertical cut-graphs of the display, these appear as "flip-out" panels that appear on the bottom and right side of the main display window and are controlled by the small H and V buttons in the lower right corner of the window. When both panels are enabled the corner area of the display also shows an options panel for the graphs. Current options are:
Several new keystroke commands are available to reposition the cursor to a centroid or min/max pixel value within a bounding box of the cursor position, allowing you to approximate the position with the mouse and fine tune it quickly before typing the application keystroke command. The initial box size is controlled with a centerBoxSize GUI resource (defaults to 5 pixels) but can be adjusted interactively using the Ctrl-[ and Ctrl-] commands to descrease/increase the box size respectively. A marker will flash briefly to indicate the box size.
The Ctrl-0 (zero) key finds either a centroid or the local maximum pixel value within this box region, Alt-Ctrl-0 (zero) will find the local minimum value. In either case the cursor is reposition to the computed value. The default peak-up action is to find the centroid position in the box however this can be changed to find the max pixel by selection the "Centroid Peaks" option from the main Display control panel or by resetting the peakCentroid GUI resource (defaults to True).
Centroiding is done using only the scaled screen pixel values and only pixels above the mean value within the box are used. It works best if the box size is set appropriately, the centroid position may appear to drift if the box is too large and includes too many background pixels.
The separate windows previously used for Control/Print/Load/Save/etc have now been integrated into a single window with the appropriate control panel selectable with a Tab widget. There are also new Tab panels for setting the frame tile configuration (see below), more detailed information on the server status, and selecting the WCS readout options (see below).
The Frame box will list only the frame buffers you currently have defined. Currently, the only way to destroy a frame buffer is to change the frame buffer configuration, new frame buffers (up to 4) will be created automatically if requested by the client.
The text display window gives the field X,Y center, X,Y scale factors, and the X,Y zoom factors. The scale factor and the zoom factor will be the same unless autoscale is enabled. The scale is in units of display pixels per frame buffer pixel, and is an absolute measure (it doesn't matter whether or not autoscale is enabled). Zoom is relative to the autoscale factor, which is 1.0 if autoscaling is disabled. This information is also presented in the Info panel.
The numbers in the Zoom box are zoom factors. Blue numbers zoom, red numbers dezoom. Zoom In and Zoom Out may be used to go to larger or smaller zoom factors, e.g. "Ctrl-5" followed by "Zoom In" will get you to zoom factor 10. Specific zoom factors may also be accessed directly as Control keystrokes, e.g. Ctrl-5 will set zoom factor 5. Center centers the field. Toggle Zoom toggles between the current zoom/center values, and the unzoomed image.
Aspect recomputes the view so that the aspect ratio is 1.0. Aspect also integerizes the zoom factor (use the version in the View menu if you don't want integerization).
Fit Frame makes the display window the same size as the frame buffer. Note that autoscale has much the same effect, and allows you to resize the display window to any size you want, or view images to large to fit on the screen.
At the top is a scrolled list of all the available colormaps. Click on the one you want to load it. You can add your own colormaps to this list.
The two sliders adjust the contrast (upper slider) and brightness (lower slider) of the display. The Invert button inverts the colormap (multiples the contrast by -1.0). Note that due to the use of the private colormap the sliders are a bit sluggish when dragged to window the display. If this is annoying, using MB3 in the display window is faster.
The Normalize button (on the bottom of the control panel) will normalize the enhancement, i.e. set the contrast and brightness to the default one-to-one values (1.0, 0.5). This is the preferred setting for many of the pseudocolor colortables and for private colormaps loaded from disk images.
Blink frames is the list of frames to be blinked. When blink mode is in effect ximtool just cycles through these frames endlessly, pausing "blink rate" seconds between each frame. The same frame can be entered in the list more than once. To program an arbitrary list of blink frames, hit the Reset button and click on each blink frame button until it is set to the desired frame number. The main control panel allows only the original four frames to be specified in the blink list, however access to the full list of 16 frames now supported is gained using the box icon button next the the Reset button to bring up a new control panel.
The Blink Rate can be adjusted as slow or as fast as you want using the arrow buttons. If you set the blink rate small enough it will go to zero, enabling single step mode (see below).
The Register button registers all the blink frames with the current display frame. Frames not in the blink list are not affected.
The Match LUTs button sets the enhancement of all blink frames to the same values as the display frame. Frames not in the blink list are not affected.
The Blink button turns blink on and off. When the blink rate is set to zero the Blink button will single step through the blink frames, one frame per button press.
NOTE: You can blink no matter what ximtool options are in effect, but many of these will slow blink down. To get the fastest blink you may want to turn off the panner and coords box, and match the LUTs of all the blink frames. All the ximtool controls are fully active during blink mode, plus you can load frames etc.
The format of a user lookup table is very simple: each row defines one colortable entry, and consists of three columns defining the red, green, and blue values scaled to the range 0.0 (off) to 1.0 (full intensity).
R G B R G B (etc.)Blank lines and comment lines (# ...) are ignored.
Usually 256 rows are provided, but the number may actually be anything in the range 1 to 256. Ximtool will interpolate the table as necessary to compute the colortable values used in Ximtool. Ximtool uses at most 201 colors to render pixel data, so it is usually necessary to interpolate the table when it is loaded.
The name of the colortable as it will appear in the Ximtool control panel is the root name of the file, e.g., if the file is "rainbow.lut" the colortable name will be "rainbow". Lower case names are suggested to avoid name collisions with the builtin colortables. Private colormaps for disk images will be have the same name as the image loaded. If the same colortable file appears in multiple user colortable directories, the first one will be used.
The directory "luts" in the ximtool source directory contains a sample set of colortable files. This can be installed as /usr/local/lib/imtoolcmap when ximtool is installed.
When loading new images the frame buffer configuration table will be searched for a frame buffer that is the same size or larger than the new image size, if no frame buffer can be found a custom buffer exactly the size of the image will be created. This means that the image may not fill the display window when loaded, or you may see a subsection of the image in the main display window. Setting the autoscale option on the main Display panel will scale the entire image to fit the main display window, the full frame buffer will always be visible in the Panner marker window.
Images with more colors than can be displayed will automatically be quantized to the number of available colors before display. If the Auto Grayscale button is enabled any image colormap will be converted to grayscale and loaded as the standard grayscale colormap.
Formats which permit pixels larger than 8-bits/pixel will be sampled on a grid to determine an optimal range in the data to be used to compute a linear transformation to the number of display colors. This is the same z-scale sampling and transformation used by the IRAF DISPLAY task when computing the z1/z2 values and provides a much better initial display than simple truncation to 8-bits. This scaling will be done automatically using a grid of Nsample points if the Zscale option is enabled. Otherwise, if the Zrange option is set the full data range will be used to scale the image. Lastly, is neither Zscale nor Zrange are enabled, the z1/z2 values may be set explicitly using the options box.
The Root button will reset the current directory to the system root directory. The Home button will reset the current directory to the user's login directory, the Up button moves up one directory level, and Rescan reloads the file list by rescanning the directory. The current working directory is given below the file selection window.
Selecting the List Image Headers option will change the display text to list all images in the current directory which match the filename filter. Directory browsing is disabled while this option is in effect.
name < tab > commandThe name value is what appears in the selection list and may be more than a single word, the command can be any command that accepts EPS input from a pipe, the two fields must be separated by a tab character. Normally the command will be a simple 'lpr -Pfoo' or some such, but can also include converters or previewers. At most 128 printer commands may be used.
Tile configuration will make use of all frames currently selected in the Tile Frame group in the following manner:
Other options below this group control whether or not to display the WCS labels, the image name/title, and frame buffer information in the main Coords Panel display. The BPM Data option controls whether or not the ISM will try to map any bad-pixel mask associated with the image. If enabled, a bad-pixel mask specified by the image header BPM keyword (currently fixed by convention but this may be selectable later) will be mapped along with the image. Aside from wcs/pixel readouts at each cursor position, any BPM data values found will also be displayed. A non-zero value will cause the BPM field of the Coords Panel readout as well as the main image window marker to switch to a red background color to flag the value.
The last box allows the user to specify a different ISM task to be executed or to reinitialize the current one. In most cases this won't need to be changed, however a custom ISM could be started when using special data formats. This command string can also be controlled by the application ism_task resource.
send helpButton set background redCool, huh.