CLIENT RESOURCES¶

Description of ximtool client resources:

defConfig

Default frame buffer configuration number on startup. See below for more information on frame buffers.

defNFrames

Default number of frames on startup. Set to zero to use the value from the frame buffer configuration (imtoolrc) file.

tileBorderWidth

tileBorderColor

Used by the tile frames option. Specifies how far apart to space the frames in tile frames mode. Color "9" refers to the Gterm widget resource color9, which is assigned a color with its own resource.

autoscale

Enable/disable the autoscale option.

antialias

Enable/disable the antialias option.

antialiasType

Type of antialiasing. Options include boxcar (default), bilinear, nearest, area, blkavg, lowpass, and gaussian.

tileFrames

Enable/disable the tile frames option.

highlightFrames

Determines whether the current frame is highlighted when in tile frames mode.

gui

The GUI to be executed. "default" refers to the default, builtin ximtool GUI. You can replace this with your own GUI file if you are bold enough, and completely change the look and functionality of the GUI if desired.

imtoolrc

Where to find the imtoolrc file. This defines the recognized frame buffer configurations.

invert

Start Ximtool using an inverted colormap. When set, a "normalized" display will always be the inverse of the selected colormap.

memModel

Determines how ximtool uses memory in the ximtool client and the X server. The options are fast, beNiceToServer, and small. The default is fast, which uses server pixmaps to make frame blink fast. This is recommended unless server memory is very limited. Note that even in fast mode, the server pixmap is only the size of the display window, so memory usage is reasonable even if the frame buffer is very large.

basePixel

maxColors

These two resources determine the region of colormap space used to render image pixels.

cmapInitialize

Initialize the ximtool colormap at startup. This is a required resource to clear a previous ximtool colormap allowing a new basePixel and maxColors to take effect.

cmap1

cmap2

User colormap files. The intent here is to allow individual colormaps to be conveniently specified as a resource.

cmapDir1

cmapDir2

User or system colormap directories. By default cmapDir2 points to the system directory /usr/local/lib/imtoolcmap, allowing a set of site default colormaps to be defined here. This leaves cmapDir1 available to a user colormap directory.

input_fifo

output_fifo

The input and output fifos for fifo i/o. "Input" and "output" are from the client's point of view. Note that only one display server can use a fifo-pair at one time.

unixaddr

Template address for unix domain socket. The user must have write permission on this directory, or the file must already exist. %d, if given, is replaced by the user's UID.

port

TCP/IP port for the server. Note that only one server can listen on a port at one time, so if multiple ximtool servers are desired on the same machine, they should be given different ports.

ism_addr

Template address for ISM unix domain socket. The user must have write permission on this directory, or the file must already exist. %d, if given, is replaced by the user's UID.

ism_task

Command string to execute for the real-time pixel and WCS readout ISM (Image Support Module) task.

GUI RESOURCES¶

The following are some of the more useful resources used by the default ximtool GUI. The imagewin resources are Gterm widget resources.

Description of selected resources:

*cmapName

Name used for private colormap. The default for all IRAF imaging applications is "image". Gterm widget based imaging applications which have the same value of cmapName will share the same colormap, minimizing colormap flashing and allowing multiple applications to be run at the same time.

*basePixel

The base colormap cell used by the display colormap.

*imagewin.warpCursor

Warp pointer into image window when initiating a cursor read.

*imagewin.raiseWindow

Raise image window when initiating a cursor read.

*imagewin.deiconifyWindow

Deiconify image window if necessary when initiating a cursor read.

*imagewin.ginmodeCursor

Type of cursor when a cursor read is in progress. The default is a circle. Any selection from the X cursor font can be used. A special case is "full_crosshair" which is the full crosshair cursor of the Gterm widget.

*imagewin.ginmodeBlinkInterval

Determines whether the cursor blinks when a cursor read is in progress. The value is given in milliseconds.

*imagewin.color0

Background color.

*imagewin.color1

Foreground color.

*imagewin.color8

Color assigned the panner window.

*imagewin.color9

Color used for the tileFrames highlight.

*imagewin.width

Width of the main image window.

*imagewin.height

Height of the main image window.

*pannerArea

Area in pixels of the panner window.

*pannerGeom

Where to place the panner window.

*wcsboxGeom

Where to place the coords box.

*maxContrast

Maximum contrast value.

MOUSE OPERATIONS¶

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.

KEYSTROKE ACCELERATORS¶

NOTE: These keystrokes only work with the cursor in the main image window, only a few of the commands are implemented to work within subwindows or markers to avoid conflicts with translations for those objects. If a command does not work, check the cursor location and try it again in the main display window.

SUPPORT FOR 16 DISPLAY FRAMES¶

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.

PANNER MARKER¶

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 hitting 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.

MAGNIFIER MARKER¶

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 and MB2 buttons 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 magnifierArea and magnifierGeom GUI resources respectively.

COORDS BOX MARKER¶

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 text marker, it can be moved and resized with the pointer like any other marker. The coords box marker can be disabled by defining the displayCoords GUI resource, its location can be controlled by the wcsboxGeom GUI resource.

MARKER MENU OPTIONS¶

o

Zoom does an equal aspect zoom of the region outlined by the marker. In this way you can mark a region of the image and zoom it up.

o

Fill exactly zooms the area outlined by the marker, making it fill the display window. Since the marker is not likely to be exactly square, the aspect ratio of the resultant image will not be unitary.

o

Print prints the region outlined by the marker to the printer or file currently configured by the Print Panel.

o

Save saves the region outlined by the marker to the file currently configured by the Save Panel.

o

Info prints a description of the marked region. The text is printed in the Info Panel.

o

Unrotate unrotates a rotated marker.

o

Color is a menu of possible marker colors.

o

Type is a menu of possible marker types. This is still a little buggy and it isn't very useful, but you can use it to play with different types of markers.

o

Destroy destroys the marker. You can also hit the delete or backspace key in a marker to destroy the marker.

RULER MARKERS¶

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:

Sticky

By default rulers are destroyed whenever the display changes due to a pan, zoom, flip, or frame change. This option will make the ruler "sticky" so it will not be erased, subsequent use of the menu to shows this option to be "UnSticky" to remove this feature.

Units

Sub-menu to select the units of the display. If the ISM is enabled and a WCS is present in the image and selected as one of the readout options, distances may also be read out in units of arcseconds, arcminutes, or degrees instead of the default logical pixels. All markers created after the unit change will readout in the new units as their default.

Color

Select the color of the marker.

Draw into Frame

(Not Yet Implemented) Draw the marker as overlay graphics in the frame. Doing so will retain the marker when printing a hardcopy of the display.

Destroy

Destroy the marker.

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.

Command Summary¶

Ctrl-0 (zero)

Reposition to centroid/max-pixel

Alt-Ctrl-0 (zero)

Reposition to min-pixel

Ctrl-[

Decrease centering box size (min of 5)

Ctrl-]

Increase centering box size

Resource Summary¶

peakCentroid = True

Compute the box centroid position, a 'False' value force the max value to be used

centerBoxSize = 5

Size of the centroid box, used as cursor position +/- this value

Command Summary¶

Ctrl-o

Set the registration offset from center

Ctrl-a

Toggle the Auto-Register feature

VIEW CONTROLS¶

The text display window gives the field X,Y center, X,Y scale factors, the X,Y zoom factors, and the frame offset used in Auto-Registration. 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 too large to fit on the screen.

ENHANCEMENT CONTROLS¶

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. The Initialize button does a reset of the server.

BLINK CONTROLS¶

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.

OPTIONS:¶

Panner

Toggles whether to display the Panner marker.

Magnifier

Toggles whether to display the Magnifier marker.

Coords Box

Toggles whether to display the coordinate box marker.

Autoscale

If autoscale is enabled then at zoom=1, the frame buffer will be automatically scaled to fit within the display window. With autoscale disabled (the default), the image scale is more predictable, but the image may be clipped by the display window, or may not fill the display window.

Antialias

When dezooming an image, i.e., displaying a large image in a smaller display window, antialiasing causes all the data to be used to compute the displayed image. If antialiasing is disabled then image is subsampled to compute the displayed image. Antialiasing can prevent subsampling from omitting image features that don't fall in the sample grid, but it is significantly slower than dezooming via subsampling. The default is no antialising.

Tile Frames

The default display mode is to view one frame at a time. In tile frames mode, 2 or 4 frames may be viewed simultaneously in the display window. All the usual operations (zoom and pan, colortable enhancement, cursor readback, etc.) still work for each frame even when in tile frames mode.

Warnings

The warnings options toggles whether you see warning dialog boxes in situations like overwriting an existing file, clearing the frame buffer, etc.

Centroid Peaks

If enabled, the Ctrl-0 keystroke will reposition the cursor to the computed centroid of the centroiding box, otherwise the cursor is repositioned to the local maximum value within the box.

COLOR OPTIONS¶

POSTSCRIPT OPTIONS¶

Orientation

Set the page orientation.

Paper Size

Select the paper size to be used.

Image Scale

Set the scale factor used to compute the final image size. No checking is done to make sure the image will fit correctly on the page.

PROCESSING OPTIONS¶

Auto Scale

Toggles whether or not the image is automatically scaled to fit the page. If not enabled, the image scale will be used to determine the output image size, otherwise the image will be scaled down (if necessary) to fit on the page.

Auto Rotate

Determines whether or not the image will be rotated to fit on the page. When set, an image larger than the current orientation will be rotated and possibly scaled to fit the page, otherwise the image may be scaled so that it fits in the current orientation.

Max Aspect

Automatically increases the scale so the image fills the page in the current orientation.

Annotate

The annotate option toggles whether or not the final file includes annotation such as the image title, a colorbar, and axis labels. There is currently no option for partial annotation.

ANNOTATION OPTIONS¶

Annotate

Selects whether Postscript image is to be annotated. Title Annotate with a title on the top of the image. Borders Annotate with borders surrounding the image giving image coordinates. Colorbar Annotate with colorbar at the bottom of the image Title String Title string to use when title is selected. The special value imtitle will force the title to be the currently displayed image title, otherwise it will be this user-selected field.

PRINTER SELECTION¶

name\tcommand

The 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.

BUILTIN COLORMAPS¶

USER-DEFINED COLORMAPS¶

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 and comment lines (lines beginning with a '#') 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 found will be used.

MINIMIZING COLORMAP CONFLICTS¶

XImtool logically defines 200 colors which the client image display program can use to render pixels. However, ximtool may or may not actually allocate all of those colors. By default it currently allocates only about 192 colors, to reserve 64 colors for the other windows on the screen. You don't normally notice this as 1) usually the default screen colormap has enough free cells to allow ximtool to match the colors, and 2) the extra unallocated cells correspond to the brightest pixels in the rendered image, and these colors may not be used or usually only correspond to a few small regions near the saturated cores of bright objects.

You can eliminate this problem by setting the basePixel resource to e.g. 48 instead of 64, which will let the gterm widget allocate all 200 colors. However, this isn't recommended for normal use as it will increase the likelihood of colormap flashing. If you change basePixel, either restart the X server or set the resource cmapInitialize=True to force the gterm widget to update its global colormap resource in the X server. The colormap resource may also be deleted by using the command

xprop -root -remove GT_image

These options may also be set on the command line when first starting up.

In general one can set the Gterm widget resources basePixel and maxColors to specify the region of colormap space to be used for image display. If you set maxColors to a small value, the 200 logical colors defined by the widget will be mapped by the imtool color model into whatever number of colors are actually available to the widget. For example, in the default setup, 200 color values are really being mapped into 192 color cells used for display, the remaining colors are used for buttons, menus etc and are allocated from the default colormap by the X toolkit when the application starts up.

Even though the Gterm widget uses a private colormap, it is a private global colormap meaning that all Gterm widgets share the same colormap. An example of colormap sharing in ximtool is the main image window and the colorbar window. These are two separate gterm widgets that share the same colormap. They have to share the same colormap, as otherwise when you windowed the main image window the colorbar window would not accurately reflect the modified colormap. By default two separate ximtools would also share the same colormap meaning contrast enhancements in one window would affect the other. By resetting the cmapName command line option or resource you can change the name of the private colormap used causing separate ximtools to use different colormaps, but note this also creates colormap flashing between the two windows that cannot easily be avoided. By setting the cmapName to "default" the widget will allocate colors from the default colormap, but this is of little use at the moment.

There are a number of other resources that can be used to modify the behavior of the Gterm widget color management scheme, but these are the most useful ones. For question and further information feel free to contact iraf@noao.edu.

COMMUNICATIONS PROTOCOL¶

Beginning with XImtool V1.3 the protocol was modified even more to allow extra text at the end of the WCS string to define image mappings and to better support multiple world coordinate systems within a frame. For backwards compatibility none of the existing IIS protocols were modified completely, however we take advantage of unused registers to flag the new features in existing functions (like read/write WCS). The WCS mapping changes required only that the unused 'x' register be set to indicate the new behavior was desired, e.g. the wcs text containing the extra mapping data.

We also added two new WCS calls that allow us to query the WCS version, or query a WCS by a specific number corresponding to a mapping. The WCS version query will return a string such as "version=10" which can be parsed by the client to get a version number '10' (corresponding to version 1.0).

Because of the added mapping text the WCS string length was increased from 320 to 1024 bytes, the string length used internally depends on whether the 'x' register has been set.

Support for the full 16 frames allowed by the bit-flag 'z' register in the IIS header packet required the masking values be changed at various places in the code. This was more a limitation of the initial implementation than a required change to the protocol.

A complete summary of the XImtool IIS protocol implementation follows.

IIS PROTOCOL SUMMARY¶

		struct  iism70 {
        		short   tid;
        		short   thingct;
        		short   subunit;
        		short   checksum;
        		short   x, y, z;
        		short   t;
		};   

The thing count field contains the negative number of bytes of data that will be sent following the header packet. The IIS header checksum is computed as

    checksum = 0177777 - (tid + subunit + thingct + x + y + z + t);

IIS Header Packet Summary

TID fields can be logically OR'd with the PACKED flag indicating the number of data bytes is exactly thingct bytes long, otherwise thingct must be specified as half the number of data bytes. In a cursor read, if the IIS_READ flag is OR'd with IMC_SAMPLE the logical cursor position (i.e. the last value read or set) is returned immediately, otherwise the server will wait for a keystroke to be hit before returning a string containing the (x,y) position, wcs of the read, and the keystroke. When setting the frame you must send a short integer in the data containing the frame selected.

ISM SOCKET CONNECTION¶

Once a connection request is received, XImtool replies with a message telling the ISM to reconnect on a different socket, it then frees the initial connection allowing multiple other ISMs to request their own connection. The communications between XImtool and the ISM are carried out entirely over this second negotiated socket. Once connected, the ISM appears as just another named object which can receive OBM messages.

COMMUNICATIONS PROTOCOL¶

Where messages are of the form:

All messages must be null-terminated. XImtool will buffer the text until a complete message is received. Once an ISM client has delivered a QUIT message no further messages will be sent the that ISM.

In OBM terminology the ISM is a named Client class object, where the name is set in the connection request. Messages sent to the ISM should use this name, messages sent to "client" are still interpreted to mean the XImtool client.

The content of messages delivered to the ISM are totally free-form and may contain any text the ISM is expected to understand.

GUI OBJECTS¶

In all cases the message is expected to be of the form

<cmd> <ism_name> [ <arg1> <arg2> <...> ]

where <cmd> is one of the above keywords, <ism_name> is the name of the ISM sending the message. The remainder of the message is passed as an 'argv' list to the processing callback uploaded for the ISM. The ISM is responsible for formatting these messages.