path: root/vendor/x11iraf/man/ximtool.1

." @(#)ximtool.1 1.1 12-Aug-2001 MJF
.TH XIMTOOL 1 "12 Aug 2001" "X11IRAF Project"
.SH NAME
ximtool \- interactive image display program for the X Window System
.sp 0.5
.SH SYNOPSIS
.B "ximtool" [\-\fItoolkitoption\fP ...] [ \fIoptions\fP ...] [\fIimagename\fP]
.sp 0.5
.SH OPTIONS
.TP 5
.B "-basePixel \fIN\fP"       
The base colormap cell used by the colormap.  This essentially allows you
to reserve \fIbasePixel\fP colors in the global colormap for other applications.
The default is 64, if changed you'll need to also specify the
\fI-cmapInitialize\fP option or resource.
.TP 5
.B "-cmap1 \fIfile\fP"          
User colormap 1.  This flag allows you to specify a colormap to be made
available at task startup.
.TP 5
.B "-cmap2 \fIfile\fP"          
User colormap 2.  This flag allows you to specify a second colormap to be
made available at task startup.
.TP 5
.B "-cmapDir1 \fIdir\fP"        
User colormap directory 1.  Specifies a directory to be searched for colormaps.
.TP 5
.B "-cmapDir2 \fIdir\fP"        
User colormap directory 2.  Specifies a directory to be searched for colormaps.
By default this points to the system directory /usr/local/lib/imtoolcmap, 
allowing a set of site default colormaps to be defined here.
.TP 5
.B "-cmapInitialize \fIbool\fP"       
Initialize the ximtool colormap at startup.  When setting the \fIbasePixel\fP
option or resource this is required in order to force the Gterm widget to 
update its global colormap resource in the X server.  The default is
\fIfalse\fP.
.TP 5
.B "-cmapName \fIname\fP"       
Name used for private colormap.  The default for all IRAF imaging
applications is \fIimage\fP.  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.
.TP 5
.B "-config \fIN\fP"          
Initial frame buffer configuration number.  The default value is 1, indicating
a 512x512 frame buffer with 2 frames.  See below for information on the frame
buffers.
.TP 5
.B "-defgui"                
Print the default GUI to the stdout.  The GUI is a Tcl program that may be
customized by the user and reloaded using the \fI-gui\fP option or
the \fIgui\fP resource parameter.
.TP 5
.B "-displayPanner \fIbool\fP"
Display panner marker window at startup.  If set, a panner window showing
the full frame buffer will appear in the upper-right side of the main display
window.
.TP 5
.B "-displayCoords \fIbool\fP"
Display WCS coordinate marker window at startup.  If set, a coordinate
readout text marker showing will appear in the lower-right side of the main
display window.
.TP 5
.B "-fifo \fIpipe\fP"           
Specifies the name of the fifo pipe to be used, the \fIi\fP 
and \fIo\fP suffixes will be added automatically.  The default pipe names
will be /dev/imt1i (input pipe) and /dev/imt1o (output pipe).  
.TP 5
.B "-fifo_only"             
If set, only fifo pipes will be used for communication with a client program,
sockets will be disabled.
.TP 5
.B "-gui \fIfile\fP"            
Specifies the GUI file to be used.
.TP 5
.B "-help"                  
Print a summary of command line options to the screen.
.TP 5
.B "-imtoolrc \fIfile\fP"       
Specifies the frame buffer configuration file to be used.  See below for 
information on frame buffers.
.TP 5
.B "-inet_only"
If set, only inet sockets will be used for communication with a client program,
fifo pipes and unix sockets will be disabled.
.TP 5
.B "-invert"                
Start XImtool using inverted colormaps.  When set, a "normalized" display
will always be the inverse of the selected colormap.
.TP 5
.B "-ismdev \fIdev\fP"                
Specifies the plug-in ISM connection socket.  This should be a unix domain
socket of the form "\fI/tmp/.ISM%d\fP", where the \fI%d\fP will be replaced
by the user id.  Once an ISM has connected this port is freed to accept
other connections.
.TP 5
.B "-maxColors \fIN\fP"       
Specify the max number of colors to be used for the display.
.TP 5
.B "-memModel \fItype\fP"       
Determines how ximtool uses memory in the ximtool client and the X server.  
The options are \fIfast\fP, \fIbeNiceToServer\fP, and \fIsmall\fP.  The 
default is \fIfast\fP, 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.
.TP 5
.B "-nframes \fIN\fP"         
Specifies the number of frame buffers to configure at startup.  By default
there will be 2 frames available, a maximum of 4 frames are allowed.
.TP 5
.B "-port \fIN\fP"            
Specifies the port number to use when connecting through an inet socket.
.TP 5
.B "-port_only"
Same as \fI-inet_only\fP option.  If set, only inet sockets will be used for
communication with a client program.
.TP 5
.B "-printConfig \fIname\fP"    
Specifies the printer configuration file to use.  By default this will be
/usr/local/lib/ximprint.cfg.  See below for more information on configuring
output devices.
.TP 5
.B "-tile"                  
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.
.TP 5
.B "-unix \fIname\fP"           
Specifies the unix domain socket name to use.  A "%d" in the filename will
be replaced with the user id.
.TP 5
.B "-unix_only"             
If set, only unix domain sockets will be used for communication with a client
program, inet sockets and fifos will be disabled.

.SH "APPLICATION RESOURCES"
XImtool is implemented as a client program which is responsible for loading
the frame buffers/colormaps, communicating with clients, etc, and a
user-modifiable GUI file written as a Tcl script which handles all the user
interface details.  The \fIclient resources\fP described below will be common
to any user-defined GUI, the \fIgui resources\fP may change depending on how
extensively the GUI has been modified by the user.  Each of these components
has its own set of resources, but to the user setting them is the same as
with any other application.  

\fIGterm\fP widget resources (i.e. those for the main image window or 
colorbar) may be set as either client or GUI resources.  See the
\fIxgterm(1)\fP man page for a complete description of \fIGterm\fP widget
resources.

.SS "CLIENT RESOURCES"
The client resources generally define the initial state of the application
or set configuration parameters.  
.RS
.TP 25
.B "Resource Name"
\fBDefault Value\fP
.sp -0.5
.TP 25
defConfig
1
.sp -0.5
.TP 25
defNFrames
0
.sp -0.5
.TP 25
tileBorderWidth
3
.sp -0.5
.TP 25
tileBorderColor
9
.sp -0.5
.TP 25
autoscale
false
.sp -0.5
.TP 25
antialias
false
.sp -0.5
.TP 25
antialiasType
boxcar
.sp -0.5
.TP 25
tileFrames
false
.sp -0.5
.TP 25
highlightFrames
true
.sp -0.5
.TP 25
gui
default
.sp -0.5
.TP 25
imtoolrc
/usr/local/lib/imtoolrc
.sp -0.5
.TP 25
invert
false
.sp -0.5
.TP 25
memModel
fast
.sp -0.5
.TP 25
basePixel:
64
.sp -0.5
.TP 25
maxColors:
216
.sp -0.5
.TP 25
cmapInitialize:
false
.sp -0.5
.TP 25
cmap1
none
.sp -0.5
.TP 25
cmap2
none
.sp -0.5
.TP 25
cmapDir1
none
.sp -0.5
.TP 25
cmapDir2
/usr/local/lib/imtoolcmap
.sp -0.5
.TP 25
input_fifo
/dev/imt1i
.sp -0.5
.TP 25
output_fifo
/dev/imt1o
.sp -0.5
.TP 25
unixaddr
/tmp/.IMT%d
.sp -0.5
.TP 25
port
5137
.sp -0.5
.TP 25
ism_addr
/tmp/.ISM%d
.sp -0.5
.TP 25
ism_task
"ism_wcspix.e wcspix &"
.RE

Description of ximtool client resources:

.TP 18
.B "defConfig"
Default frame buffer configuration number on startup.  See below for more
information on frame buffers.
.TP 18
.B "defNFrames"
Default number of frames on startup.  Set to zero to use the value from 
the frame buffer configuration (\fIimtoolrc\fP) file.  
.TP 18
.B "tileBorderWidth"
.sp -0.5
.TP 18
.B "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.
.TP 18
.B "autoscale"
Enable/disable the autoscale option.
.TP 18
.B "antialias"
Enable/disable the antialias option.
.TP 18
.B "antialiasType"
Type of antialiasing.  Options include \fIboxcar\fP (default), \fIbilinear\fP,
\fInearest\fP, \fIarea\fP, \fIblkavg\fP, \fIlowpass\fP, and \fIgaussian\fP.
.TP 18
.B "tileFrames"
Enable/disable the tile frames option.
.TP 18
.B "highlightFrames"
Determines whether the current frame is highlighted when in tile frames mode.
.TP 18
.B "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.
.TP 18
.B "imtoolrc"
Where to find the imtoolrc file.  This defines the
recognized frame buffer configurations.
.TP 18
.B "invert"
Start Ximtool using an inverted colormap.  When set, a "normalized" display
will always be the inverse of the selected colormap.
.TP 18
.B "memModel"
Determines how ximtool uses memory in the ximtool client and the X server.  
The options are \fIfast\fP, \fIbeNiceToServer\fP, and \fIsmall\fP.
The default is \fIfast\fP, 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.
.sp -0.5
.TP 18
.B "basePixel"
.sp -0.5
.TP 18
.B "maxColors"
These two resources determine the region of colormap space used to
render image pixels.
.TP 18
.B "cmapInitialize"
Initialize the ximtool colormap at startup.  This is a required resource to
clear a previous ximtool colormap allowing a new \fBbasePixel\fP and
\fBmaxColors\fP to take effect.
.TP 18
.B "cmap1"
.sp -0.5
.TP 18
.B "cmap2"
User colormap files.  The intent here is to allow individual colormaps to be
conveniently specified as a resource.
.TP 18
.B "cmapDir1"
.sp -0.5
.TP 18
.B "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.
.TP 18
.B "input_fifo"
.sp -0.5
.TP 18
.B "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.
.TP 18
.B "unixaddr"
Template address for unix domain socket.  The user must have write permission
on this directory, or the file must already exist.  \fI%d\fP, if given,
is replaced by the user's UID.
.TP 18
.B "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.
.TP 18
.B "ism_addr"
Template address for ISM unix domain socket. The user must have write
permission on this directory, or the file must already exist.  \fI%d\fP,
if given, is replaced by the user's UID.
.TP 18
.B "ism_task"
Command string to execute for the real-time pixel and WCS readout ISM
(Image Support Module) task. 

.SS "GUI RESOURCES"

In principle ximtool can have any number of different GUIs, each of which
defines its own set of resources.  GUIs typically define a great many
resources, but most of these are not really intended for modification by
the user (although one can modify them if desired).

The following are some of the more useful resources used by the default
ximtool GUI.  The \fIimagewin\fR resources are Gterm widget resources.
.RS

.TP -10
.B Main Display Gterm Widget Resources
.TP 35
.B " Resource Name"
\fBDefault Value\fP
.sp -0.5
.TP 35
 *imagewin.cmapName:
image
.sp -0.5
.TP 35
 *imagewin.basePixel:
64
.sp -0.5
.TP 35
 *imagewin.warpCursor:
True
.sp -0.5
.TP 35
 *imagewin.raiseWindow:
True
.sp -0.5
.TP 35
 *imagewin.deiconifyWindow:
True
.sp -0.5
.TP 35
 *imagewin.ginmodeCursor:
circle
.sp -0.5
.TP 35
 *imagewin.ginmodeBlinkInterval:
500
.sp -0.5
.TP 35
 *imagewin.color0 (background):
black
.sp -0.5
.TP 35
 *imagewin.color1 (foreground):
white
.sp -0.5
.TP 35
 *imagewin.color8 (panner highlight):
#7c8498
.sp -0.5
.TP 35
 *imagewin.color9 (tileFrame color):
SteelBlue
.sp -0.5
.TP 35
 *imagewin.width:
512
.sp -0.5
.TP 35
 *imagewin.height:
512

.TP -10
.B GUI Resources

.TP 35
.B " Resource Name"
\fBDefault Value\fP
.sp -0.5
.TP 35
 *autoscale:
True
.sp -0.5
.TP 35
 *zoomfactors:
1 2 4 8
.sp -0.5
.TP 35
 *displayCoords:
True
.sp -0.5
.TP 35
 *displayPanner:
True
.sp -0.5
.TP 35
 *displayMagnifier:
True
.sp -0.5
.TP 35
 *blinkRate:
1.0
.sp -0.5
.TP 35
 *pannerArea:
150*150
.sp -0.5
.TP 35
 *pannerGeom:
-5+5
.sp -0.5
.TP 35
 *magnifierArea:
100*100
.sp -0.5
.TP 35
 *magnifierGeom:
+5+5
.sp -0.5
.TP 35
 *wcsboxGeom:
-5-5
.sp -0.5
.TP 35
 *maxContrast:
5.0
.sp -0.5
.TP 35
 *warnings:
True
.sp -0.5
.TP 35
 *centerBoxSize:
5
.sp -0.5
.TP 35
 *peakCentroid:
True

.TP -10
.B Alternate GUI Resources
.TP 35
.B " Resource Name"
\fBDefault Value\fP
.sp -0.5
.TP 35
 *showToolBar:
False
.sp -0.5
.TP 35
 *showPanelBar:
False
.RE

Description of selected resources:

.TP 22
.B "*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.
.TP 22
.B "*basePixel"
The base colormap cell used by the display colormap.
.TP 22
.B "*imagewin.warpCursor"
Warp pointer into image window when initiating a cursor read.
.TP 22
.B "*imagewin.raiseWindow"
Raise image window when initiating a cursor read.
.TP 22
.B "*imagewin.deiconifyWindow"
Deiconify image window if necessary when initiating a cursor read.
.TP 22
.B "*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.
.TP 22
.B "*imagewin.ginmodeBlinkInterval"
Determines whether the cursor blinks when a cursor read is in progress.
The value is given in milliseconds.
.TP 22
.B "*imagewin.color0"
Background color.
.TP 22
.B "*imagewin.color1"
Foreground color.
.TP 22
.B "*imagewin.color8"
Color assigned the panner window.
.TP 22
.B "*imagewin.color9"
Color used for the tileFrames highlight.
.TP 22
.B "*imagewin.width"
Width of the main image window.
.TP 22
.B "*imagewin.height"
Height of the main image window.
.TP 22
.B "*pannerArea"
Area in pixels of the panner window.
.TP 22
.B "*pannerGeom"
Where to place the panner window.
.TP 22
.B "*wcsboxGeom"
Where to place the coords box.
.TP 22
.B "*maxContrast"
Maximum contrast value.


.SH DESCRIPTION

As a display server, XImtool is started as a separate process from client
software such as IRAF. Once it is running it will accept client connections
simultaneously on fifo pipes, unix domain sockets, or inet sockets. A
display client like the IRAF \fIDISPLAY\fP task makes a connection and sends
the image across using a modified IIS Model 70 protocol.  Once the image is
loaded in the display buffer it may be enhanced, saved to a disk file in a
number of different formats, or printed as Encapsulated Postscript to a
printer or disk file.  Up to sixteen frame buffers are allowed, these may be
displayed simultaneously in a tiled mode, or blinked frame-to-frame.
Each frame may have its own colormap or brightness/contrast enhancement.
Pan/Zoom and cursor readout are permitted using \fImarkers\fP, on-line help
is also available.

When run in standalone mode, images (currently IRAF OIF, GIF, Sun Rasterfiles
or simple FITS (i.e. excluding MEF files) formats are permitted) 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.

.SS "MOUSE OPERATIONS"

Clicking and dragging MB1 (mouse button 1) in the main image window creates
a rectangular region marker, used to select a region of the image. If you do
this accidentally and don't want the marker, put the pointer in the marker
and type DELETE or BACKSPACE to delete the marker. With the pointer in the
marker, MB3 will call up a marker menu listing some things you can do with
the marker, like zoom the outlined region. MB1 can be used to drag or resize
the marker. See below for more information on markers.

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.

.SS "KEYSTROKE ACCELERATORS"

The following keystrokes are currently defined in the GUI:

.RS
-------------------- \fBMisc Functions\fP ---------------------
.sp -0.2
.TP 20
.B "Ctrl-b"
Previous (back) frame
.sp -0.5
.TP 20
.B "Ctrl-c"
Center frame
.sp -0.5
.TP 20
.B "Ctrl-f"
Forward frame
.sp -0.5
.TP 20
.B "Ctrl-i"
Invert colormap
.sp -0.5
.TP 20
.B "Ctrl-m"
Toggle magnifier
.sp -0.5
.TP 20
.B "Ctrl-n"
Normalize
.sp -0.5
.TP 20
.B "Ctrl-p"
Toggle panner
.sp -0.5
.TP 20
.B "Ctrl-r"
Register
.sp -0.5
.TP 20
.B "Ctrl-s"
Match LUT scaling
.sp -0.5
.TP 20
.B "Ctrl-t"
Tile frames toggle
.sp -0.5
.TP 20
.B "Ctrl-u"
Unzoom (zoom=1)
.sp -0.5
.TP 20
.B "Ctrl-x"
Flip X
.sp -0.5
.TP 20
.B "Ctrl-y"
Flip Y
.TP 20
.B "Ctrl-="
Print using current setup
.sp -0.5
.TP 20
.B "Ctrl-<"
Decrease blink rate (blink faster)
.sp -0.5
.TP 20
.B "Ctrl->"
Increase blink rate (blink slower)
.sp -0.5
.TP 20
.B "Ctrl-+"
Zoom in
.sp -0.5
.TP 20
.B "Ctrl--"
Zoom out
.TP 20
.B "Alt-1 thru Alt-4"
Set frame to be displayed
.sp -0.5
.TP 20
.B "Ctrl-1 thru Ctrl9"
Set integer zoom factor
.TP 20
.B "Ctrl-Alt-q"
Quit
.sp -0.5
.TP 20
.B "Ctrl-Alt-f"
Fitframe
.TP -12
--------------------- \fBPanel Toggles\fP ---------------------
.sp -0.2
.TP 20
.B "Alt-b"
Blink frames
.sp -0.5
.TP 20
.B "Alt-c"
Control panel
.sp -0.5
.TP 20
.B "Alt-h"
Help popup
.sp -0.5
.TP 20
.B "Alt-i"
Info box popup
.sp -0.5
.TP 20
.B "Alt-l"
Load file popup
.sp -0.5
.TP 20
.B "Alt-p"
Print popup
.sp -0.5
.TP 20
.B "Alt-s"
Save popup
.sp -0.5
.TP 20
.B "Alt-t"
TclShell popup
.sp 0.5
.TP -12
------------------- \fBCursor Positioning\fP ------------------
.sp -0.2
.TP 28
.B "Ctrl-h / Ctrl-Left"
Move cursor one pixel left
.sp -0.5
.TP 28
.B "Ctrl-j / Ctrl-Down"
Move cursor one pixel down
.sp -0.5
.TP 28
.B "Ctrl-k / Ctrl-Up"
Move cursor one pixel up
.sp -0.5
.TP 28
.B "Ctrl-l / Ctrl-Right"
Move cursor one pixel right
.TP 28
.B "Shift-Ctrl-h / Shift-Ctrl-Left"
Move cursor ten pixels left
.sp -0.5
.TP 28
.B "Shift-Ctrl-j / Shift-Ctrl-Down"
Move cursor ten pixels down
.sp -0.5
.TP 28
.B "Shift-Ctrl-k / Shift-Ctrl-Up"
Move cursor ten pixels up
.sp -0.5
.TP 28
.B "Shift-Ctrl-l / Shift-Ctrl-Right"
Move cursor ten pixels right
.sp 0.5
.TP -12
------------------- \fBAuto-Registration\fP -------------------
.sp -0.2
.TP 20
.B "Ctrl-a"
Toggle auto-registration
.sp -0.5
.TP 20
.B "Ctrl-o"
Set frame offset
.sp 0.5
.TP -12
-------------------- \fBFrame Positioning\fP ------------------
.sp -0.2
.TP 20
.B "Ctrl-Left"
Shift one full frame left
.sp -0.5
.TP 20
.B "Ctrl-Down"
Shift one full frame down
.sp -0.5
.TP 20
.B "Ctrl-Up"
Shift one full frame up
.sp -0.5
.TP 20
.B "Ctrl-Right"
Shift one full frame right
.TP 20
.B "Ctrl-Alt-Left"
Shift one half frame left
.sp -0.5
.TP 20
.B "Ctrl-Alt-Down"
Shift one half frame down
.sp -0.5
.TP 20
.B "Ctrl-Alt-Up"
Shift one half frame up
.sp -0.5
.TP 20
.B "Ctrl-Alt-Right"
Shift one half frame right
.sp 0.5
.TP -12
------------------- \fBPeak-Up Centroiding\fP -----------------
.sp -0.2
.TP 20
.B "Ctrl-["
Decrease centroiding box size
.sp -0.5
.TP 20
.B "Ctrl-]"
Increase centroiding box size
.sp -0.5
.TP 20
.B "Ctrl-0 (zero)"
Centroid/find local maximum
.sp -0.5
.TP 20
.B "Alt-Ctrl-0 (zero)"
Find local minimum
.sp 0.5
.TP -12
------------------ \fBMouse Button Events\fP ------------------
.sp -0.2
.TP 20
.B "Shift-Btn1Down"
Turn on magnifier
.sp -0.5
.TP 20
.B "Shift-Btn1Up"
Turn off magnifier
.sp -0.5
.TP 20
.B "Shift-Btn2Down"
Turn on crosshair cursor
.sp -0.5
.TP 20
.B "Shift-Btn2Up"
Turn off crosshair cursor
.TP 20
.B "Btn1Down"
Create a Marker
.sp -0.5
.TP 20
.B "Btn1Motion"
Resize marker being created
.sp -0.5
.TP 20
.B "Btn2Down"
Zoom/center on cursor position
.sp -0.5
.TP 20
.B "Btn3Down/Motion"
Brightness/contrast scale the image
.TP 20
.B "Ctrl-Btn1Down"
Create Ruler Marker
.sp -0.5
.TP 20
.B "Ctrl-Btn1Motion"
Resize Ruler Marker being created
.sp -0.5
.TP 20
.B "Ctrl-Btn1Up"
Destroy Ruler Marker
.TP 20
.B "Alt-Motion"
Freeze cursor readout
.RE

.LP
\fBNOTE:\fP 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.

.SH "FRAME BUFFER CONFIGURATIONS"

XImtool starts up using default frame buffer size of 512x512 pixels, two
(of 16 possible) frames will be created. When loading disk images (i.e.
run in standalone mode) the frame buffer configuration file will be
searched for a defined frame buffer that is the same size or larger than
the current image, if no suitable buffer can be found a custom frame
buffer the same size as the image will be created in an unused portion of
the configuration table.  When used as a display server the frame buffer
configuration number is passed in by the client and loaded explicitly even
if it means clipping the image.  If a new frame buffer is a different size
than previously defined frames, all available frames will be initialized
and cleared prior to the display.  The default frame buffer configuration
file is /usr/local/lib/imtoolrc, this can be overridden by defining a
IMTOOLRC environment variable naming the file to be used, by creating a
.imtoolrc file in your home directory, or a new file may be specified
using the \fI-imtoolrc\fR command line flag or \fIimtoolrc\fR application
resource.

The format of the frame buffer configuration file is

     \fIconfigno nframes width height [extra fields]\fP
 e.g.
          1  2  512  512
          2  2  800  800
          3  1 1024 1024          # comment
          :  :   :    :

At most 128 frame buffer sizes may be defined, each configuration may define
up to 16 frames, configuration numbers need not be sequential.

.LP
\fBNOTE:\fR  When defining a new frame buffer for use with client software
such as IRAF the user must also remember to define those frame buffers in
the IRAF \fIdev$graphcap\fR file.

.SS "SUPPORT FOR 16 DISPLAY FRAMES"

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.

.SH "MARKERS"

Although ximtool doesn't do much with markers currently, they are a general
feature of the \fIGterm\fP widget and are used more extensively in other
programs (e.g. the prototype IRAF science GUI applications). XImtool uses 
markers for the marker zoom feature discussed above, and also for the panner
and the coords box. All markers share some of the same characteristics, so it
is worthwhile learning basic marker manipulation keystrokes.
.TP 3
\fBo\fP
MB1 anywhere inside a marker may be used to drag the marker.
.TP 3
\fBo\fP
MB1 near a marker corner or edge, depending on the type of marker, 
resizes the marker.
.TP 3
\fBo\fP
Shift-MB1 on the corner of most markers will rotate the marker.
.TP 3
\fBo\fP
Markers stack, if you have several markers and you put one on top of
the other. The active marker is highlighted to tell you which of the
stacked markers is active. If the markers overlap, this will be marker
"on top" in the stacking order.
.TP 3
\fBo\fP
MB2 in the body of a marker "lowers" the marker, i.e. moves it to the
bottom of the stacking order.
.TP 3
\fBo\fP
Delete or backspace in a marker deletes it.
.TP 3
\fBo\fP
Markers have their own translation resources and so the default 
keystroke commands will not be recognized when the cursor is in a marker.

For example, try placing the pointer anywhere in the coords box, then press
MB1 and hold it down, and drag the coords box marker somewhere else on the
screen. You can also resize the coords box by dragging a corner, or delete
it with the delete or backspace key. (The Initialize button will get the
original coords box back if you delete it, or you can reset the toggle in
the control panel).

.SS "PANNER MARKER"

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 hitting MB2 in the main display
window to pan the image. 

The panner marker can be disabled by defining the \fIdisplayPanner\fP
GUI resource, its size and location can be controlled using the
\fIpannerArea\fP and \fIpannerGeom\fP GUI resources respectively.

.SS "MAGNIFIER MARKER"

The magnifier marker can be used to zoom in on a small area around the
cursor.
It will be updated as the cursor moves but only for small motions (either
mouse movement or with the cursor movement keystrokes) to minimize the
impact on the system.  The zoom factor is expressed as some fraction of the
size of the magnifier marker itself.  The default zoom is 4, i.e. the area
in the marker represents and area in the image that's one-fourth the size
of the marker.  Other zoom factors may be selected using the popup menu 
created by hitting MB1 in the marker.

By default the magnifier marker is not visible, to toggle it select the
\fIMagnifier\fR option from the \fIOptions\fR 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 \fIdisplayMagnifier\fP
GUI resource, its size and location can be controlled using the
\fImagnifierArea\fP and \fImagnifierGeom\fP GUI resources respectively.

.SS "COORDS BOX MARKER"

XImtool provides a limited notion of world coordinates, allowing frame
buffer pixel coordinates and pixel values to be converted to some arbitrary
linear 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 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 \fIdisplayCoords\fP GUI resource, its location
can be controlled by the \fIwcsboxGeom\fP GUI resource.

.SS "MARKER MENU OPTIONS"

Except for the panner and WCS markers, MB3 (mouse button 3) calls up the
marker menu providing a limited set of functions common to all markers:
.TP 3 
\fBo
Zoom\fP 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.
.TP 3 
\fBo
Fill\fP 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.
.TP 3 
\fBo
Print\fP prints the region outlined by the marker to the printer or file
currently configured by the Print Panel.
.TP 3 
\fBo
Save\fP saves the region outlined by the marker to the file currently
configured by the Save Panel.
.TP 3 
\fBo
Info\fP prints a description of the marked region. The text is printed in
the Info Panel.
.TP 3 
\fBo
Unrotate\fP unrotates a rotated marker.
.TP 3 
\fBo
Color\fP is a menu of possible marker colors.
.TP 3 
\fBo
Type\fP 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.
.TP 3 
\fBo
Destroy\fP destroys the marker. You can also hit the delete or backspace
key in a marker to destroy the marker.

.SS "RULER MARKERS"

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:

.TP 20
.B 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.
.TP 20
.B 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.  
.TP 20                        
.B Color
Select the color of the marker.
.TP 20
.B Draw into Frame
(\fINot Yet Implemented\fP)  Draw the marker as overlay
graphics in the frame.  Doing so will retain the
marker when printing a hardcopy of the display.
.TP 20
.B 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.

.SH "REAL-TIME WCS/PIXEL-VALUE READOUT"

XImtool now has the ability to display the actual pixel value of an image
(as well as the scaled value previously shown) and the cursor position in
image WCS values (e.g. RA/DEC, GLAT/GLONG, etc).  This is done using an
external task (the 'ism_wcspix.e' binary in the new distribution) to
access the image and pass the coordinate/pixel information to the GUI.

WCS readout is enabled by default but can be toggled or reset using the
\fIWCS/Pix\fP button on the Coords tab in the control panel or the \fIISM\fP
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
\fIOptions\fP toggle on the Coords panel.  Available coordinate systems are
chosen using the \fIType\fP menu on the panel, the readout format
(sexigesimal, degrees, etc) using the \fIFormat\fP 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 \fIBPM Data\fP 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.

.SH "FREEZING CURSOR READOUT"

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.

.SH "CUT-GRAPHS"

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:

.TP 20
.B Better Speed
Draw the graphics so they update at the fastest possible rate.  This is
done by subsampling pixels to produce a smoother graph but without sacrificing
too much accuracy.
.TP 20
.B Better Accuracy
Draw the graphics using all screen pixels to produce the most accurate
display.  On fast modern machines this can be enabled with no apparent
loss of speed, however older machines may wish to use this only
occassionally to limit any lag in the cursor tracking.
.TP 20
.B Image Pixels
(\fINot Yet Implemented\fP)
.TP 20
.B Jump Cursor
If enabled, large jumps of the cursor do not update the graphics display,
small movements around an object of interest will update the display
continuously.
.TP 20
.B Smooth Cursor
If enabled, all cursor movements cause the display to be updated.  This
is another option that can be set safely on faster machines but will
cause a delay on slower ones.
.TP 20
.B Graphics Cursors
If enabled, the graphics cursors in either of the plots are active and
can be used to update the cursor readout on the main image window and the
complementary cut-graph.  This can be used for example to freeze
the cursor in the main display using the Alt key (see above), then moving
to one of the graphics windows to perform cut graphs in only one axis.

Graphs are (currently) drawn using only the scaled display values 
to avoid complications of accessing multiple images in a mosaic display. Both
plots are labeled using the frame z1/z2 values and contain cursor indicators
which update contuously.

.SH "PEAK-UP CURSOR CENTROID POSITIONING"

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 \fIcenterBoxSize\fP GUI resource
(defaults to 5 pixels) but can be adjusted interactively using the \fBCtrl-[\fP
and \fBCtrl-]\fP commands to descrease/increase the box size respectively.  A
marker will flash briefly to indicate the box size.

The \fBCtrl-0\fP (zero) key finds either a centroid or the local maximum
pixel value within this box region, \fBAlt-Ctrl-0\fP (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
"\fICentroid Peaks\fP" option from the main Display control panel or by
resetting the \fIpeakCentroid\fP 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.

.SS "Command Summary"
.TP 20
.B Ctrl-0 (zero)
Reposition to centroid/max-pixel
.sp -0.5
.TP 20
.B Alt-Ctrl-0 (zero)
Reposition to min-pixel
.sp -0.5
.TP 20
.B Ctrl-[
Decrease centering box size (min of 5)
.sp -0.5
.TP 20
.B Ctrl-]
Increase centering box size

.SS "Resource Summary"
.TP 20
.B "peakCentroid = True"
Compute the box centroid position, a 'False' value force the max value
to be used
.sp -0.5
.TP 20
.B "centerBoxSize = 5"
Size of the centroid box, used as cursor position +/- this value

.SH "AUTO-REGISTRATION OF IMAGES"

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:
.RS
.TP 5
.B 1)
Enable Auto-Register (either on the Control Panel or the toolbar on the
alt-gui) and pan/zoom to some star of interest.
.TP 5
.B 2)
Use Mouse-Button-2 to center the star in the frame.
.TP 5
.B 3)
Cycle through the frames and you may see a small shift of the star.  For
each frame,  position the cursor on the star and type \fBCtrl-o\fP to
offset it to the center.  Repeat as necessary.  Small corrections will be
cumulatively added so you can use the \fBCtrl-0\fP (Ctrl-zero) peak-up
command to centroid each object in the frame before the \fBCtrl-o\fP offset.
.TP 5
.B 4)
Pan around the image in one display frame, then switch frames and the new
frame should also be panned to the new image with the proper offset.
.TP 5
.B 5)
A \fBCtrl-a\fP command will toggle the feature, offsets are only allowed
when autoreg is enabled.
.RE
.LP
Hitting \fBRegister\fP will zero the offsets, as will toggling the
auto-register function.  What you should see is the object centered in
the frame and as you blink through it remains registered but the panner
box marker is moving around.  Drag the panner around and all frames
still remain registered with the given offset.  The control/info panels
now display what the offset is for each frame.

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.

.SS "Command Summary"
.TP 20
.B Ctrl-o
Set the registration offset from center
.sp -0.5
.TP 20
.B Ctrl-a
Toggle the Auto-Register feature

.SH "CONTROL PANEL"

XImtool has a control panel which can be used to exercise most of the
capabilities the program has for image display.  The control panel can be
accessed either via the \fBOptions\fP menu from the main window menubar, or by
pressing the leftmost button in the row of buttons at the upper right side
of the display in the standard GUI (in the alternate GUI the \fIControl
Bar\fP accessed by the rightmost button on the menubar provides widgets
for selecting the desired control panel).

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

.SS "VIEW CONTROLS"

The \fBFrame box\fP 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 16) will be created
automatically if requested by the client.  The number of frame buffers
created at startup can be controlled using the \fI-nframes\fP command-line
switch or the \fIdefNFrames\fP resource.

The \fBtext display\fP 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 \fIautoscale\fP 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 \fBZoom box\fP are zoom factors. Blue numbers zoom, red
numbers dezoom. \fIZoom In\fP and \fIZoom Out\fP may be used to go to
larger or smaller zoom factors, e.g. \fICtrl-5\fP 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. \fICenter\fP centers the field.  \fIToggle Zoom\fP toggles between the
current zoom/center values, and the unzoomed image.

\fIAspect\fP 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).

\fIFit Frame\fP 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.

.SS "ENHANCEMENT CONTROLS"

At the top is a scrolled list of all the available colormaps. Click on the
one you want to load. You can add your own colormaps to this list by
defining the \fIcmap[12]\fP or \fIcmapDir[12]\fP command line flags or
application resources.

The two sliders adjust the contrast (upper slider) and brightness (lower
slider) of the display. The \fIInvert\fP 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 \fINormalize\fP 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 \fIInitialize\fP button does a reset of the server.

.SS "BLINK CONTROLS"

\fIBlink frames\fP 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 \fIReset\fP button to bring up a new control panel.

The \fIBlink Rate\fP 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 \fIRegister\fP button registers all the blink frames with the current
display frame. Frames not in the blink list are not affected.

The \fIMatch LUTs\fP 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 \fIBlink\fP 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.

\fBNOTE:\fP 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.

.SS "OPTIONS:"
.TP 5
.B "Panner"
Toggles whether to display the Panner marker.
.TP 5
.B "Magnifier"
Toggles whether to display the Magnifier marker.
.TP 5
.B "Coords Box"
Toggles whether to display the coordinate box marker.
.TP 5
.B "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.
.TP 5
.B "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.
.TP 5
.B "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.
.TP 5
.B "Warnings"
The warnings options toggles whether you see warning dialog boxes in
situations like overwriting an existing file, clearing the frame
buffer, etc.
.TP 5
.B "Centroid Peaks"
If enabled, the \fBCtrl-0\fP 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.

.SH "LOAD PANEL"

The Load Panel allows you load images from disk directly to the frame
buffer, this is analogous to loading an image on the command line except
that browsing is possible. At present recognized formats include IRAF OIF
format (i.e. \fI.imh\fP extension), simple FITS files, GIF, and Sun
rasterfiles.  The task will automatically sense the format of the image
and load it appropriately. Images with private colormaps (such as GIF)
will be loaded using the private colormap (meaning that changing the
brightness/contrast enhancements will render an apparently random-colored
image), all others will be loaded with a grayscale colormap.  

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 \fIautoscale\fP 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 \fIAuto Grayscale\fP 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 \fIDISPLAY\fR task
when computing the \fIz1/z2\fP values and provides a much better initial
display than simple truncation to 8-bits.  This scaling will be done
automatically using a grid of \fINsample\fP points if the \fIZscale\fP
option is enabled.  Otherwise, if the \fIZrange\fP option is set the full
data range will be used to scale the image.  Lastly, is neither \fIZscale\fP
nor \fIZrange\fR are enabled, the z1/z2 values may be set explicitly using
the options box.

.TP 5
.B "Directory Browsing"
The load panel contains a list of files in the current directory that may
be selected for loading by selecting with left mouse button. If the file
is a directory the contents of the new directory will be loaded, if it's a
plain file an attempt will be made to load it as an image otherwise an
error popup will appear.  Directories in the list are identified with a
trailing '/' character, you will always see any subdirectories listed even
if a filter is specified.

The \fIRoot\fP button will reset the current directory to the system root
directory. The \fIHome\fP button will reset the current directory to the
user's login directory, the \fIUp\fP button moves up one directory level, and
\fIRescan\fP reloads the file list by rescanning the directory. The current
working directory is given below the file selection window.

Selecting the \fIList Image Headers\fP 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.
.TP 5
.B "File Patterns"
By default all files and directories will be listed. You may specify a
filter to select only those files with a given extension such as
"*.fits" using the \fIFilter\fP text box.  Directories will
always be seen in the list and are identified with a trailing '/'
character. Any valid unix pattern matching string will be recognized, 
multiple templates may be specified in a comma-delimited list such as
"*.imh,*.fits" to list both OIF and FITS images.
.TP 5
.B "Direct File Load"
If you know exactly which file you wish to load, you may enter its
name in the \fILoad File\fP text box and either hit <cr> or the Load button
to load it.  An absolute or relative path name may be given, if a simple
filename is specified it will be searched for in the current working directory.
.TP 5
.B "Frame Selections"
By default images will be loaded into the current frame, you may choose
a different frame using the Frame menu button to select from the
available frames.

.SH "SAVE PANEL"

The Save Panel lets you save the current contents of the main display window
to a disk file (including the Panner/Coords markers, or overlay graphics
displayed by the client program). Presently, only the contents of the main
display window may be saved, there is no facility for saving the undisplayed
contents of the entire frame buffer other than to enable the autoscale feature
or zoom out so the whole buffer is in the display window.  A limited number
of formats are currently available, others will be added in future versions.
.TP 15
.B "File Name"
The File Name text box allows you to enter the file name of the saved
file. A "%d" anywhere in the name will be replaced by a sequence number
allowing multiple frames to be saved with unique names.
.TP 15
.B "Format"
The Format box allows you to choose the format of the image to be
created however not all formats are currently implemented.  The EPS format
is similar to the \fIPrint\fR option however there is no annotation.
.TP 15
.B "Color"
The Color box lets you choose the color type of the image to be
created. The options will change depending on the format, e.g. FITS
doesn't allow color so no color options will be enabled.  Formats which
allow 24-bit images will be written using the current colormap after
converting to a 24-bit image, pseudocolor images will be written with
the current colormap.

.SH "PRINT PANEL"

The Print Panel allows you dump the contents of the main display window as
Encapsulated Postscript to either a named printer device or to a disk file.
The \fIPrint To\fP selects the type of output, the \fIPrint Command\fP box
will adjust accordingly, either as a Unix printer command or as a file name.
A "%d" anywhere in the name for disk output will be replaced by a sequence
number allowing multiple frames to be saved with unique names. Selecting 
printers from the installed list will automatically change the command to be
used to generate the output. This command does not necessarily need to be a
printer command, the printer configuration file lets you define any command
string to process the image.

.SS "COLOR OPTIONS"

The Color box lets you choose the color type of the image to be created.
PseudoColor or 24-bit postscript will be created using the current colormap
and enhancements.

.SS "POSTSCRIPT OPTIONS"

.TP 15
.B "Orientation"
Set the page orientation.
.sp 0.5
.TP 15
.B "Paper Size"
Select the paper size to be used.
.sp 0.5
.TP 15
.B "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.

.SS "PROCESSING OPTIONS"
.TP 5
.B "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.
.TP 5
.B "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.
.TP 5
.B "Max Aspect"
Automatically increases the scale so the image fills the page in the current
orientation.
.TP 5
.B "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.

.SS "ANNOTATION OPTIONS"

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

.SS "PRINTER SELECTION"

The printer selection list lets choose the printer to be used. The printer
configuration file is /usr/local/lib/ximprint.cfg by default or may be reset
using the \fI-printConfig\fP command line switch or \fIprintConfig\fP 
resource. The format of the file is simply

                       \fIname\\tcommand\fP

The \fIname\fP value is what appears in the selection list and may be more
than a single word, the \fIcommand\fP 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 \fIlpr -Pfoo\fP or some such, but can also include converters
or previewers. At most 128 printer commands may be used.

.SH "INFO PANEL"

The Info panel was revised to provide a greater variety of status
information.  The type of output is controlled by the toggle buttons on
the bottom of the frame, however all output is kept current as the program
runs.  Current info options include:
.RS
.TP 15
.B Frame
Info about the current display frame.
.TP 15
.B Server
Info about various server options, e.g. colormaps, memory model,
antialias type, etc.
.TP 15
.B Clients
Show currently connected clients.  Lists available connection channels
and active ISM clients.
.TP 15
.B WCS
List all WCS and mappings for the current frame.
.TP 15
.B ISM
Log of various ISM status messages.
.TP 15
.B Imtoolrc
Show current frame buffer configuration table.
.RE

.SH "TILE PANEL (NEW)"

With the additional frames, the default tiling scheme proved inadequate.
A new control panel Tile frame now allows you to select from a number of
tile configurations, the list of frames to be tiled, a \fIfill style\fP
(left-to-right or top-to-bottom), as well as optional labels for each of
the tiles (frame number, image title or image name).

Tile configuration will make use of all frames currently selected in the
\fITile Frame\fP group in the following manner:
.RS
.TP 15
.B "Disabled"
Do not tile the display.
.TP 15
.B "Manual"
Tile according to \fIManual Configuration\fP settings.
.TP 15
.B "Best"
Optimize layout for frame buffer aspect.
.TP 15
.B "Square"
Always force a square layout (2x2, 3x3, etc).
.TP 15
.B "Horizontal"
Preferentially tile horizontally (6 frames ==> 3x2).
.TP 15
.B "Vertical"
Preferentially tile vertically (6 frames ==> 2x3).
.TP 15
.B "One Row"
Tile all in one row (Nx1).
.TP 15
.B "One Column"
Tile all in one column (1xN).
.RE

.SH "COORDS PANEL (NEW)"

The Coords Panel is meant to provide a full-featured readout as well as
serve as a control panel for the various options.  The display window
contains the image name/title and frame buffer info, and a selection of
coordinate and image pixel readouts.  The intent is provide more infor-
mation than can fit comfortably on the main image window while still
taking up as little screen space as possible.  To this end the "Options"
button is used to hide most of the feature controls when not in use (see
below).  Other options on the main panel include:

.RS
.TP 15
.B WCS/Pix
Toggle the real-time WCS/pixel readout capability (i.e. the ISM used
to access the disk image).  This must be enabled for certain other
options to work.
.TP 15
.B "Pix Table"
Open a panel showing an image pixel table.  The panel shows an array
of pixels surrounding the cursor position, either the actual pixel
values if the ISM is enabled, or scaled display values otherwise.  The
size of the table may be selected from the menubar.
.TP 15
.B Header
Display the current image header in a new panel.  Both the entire image
header as well as WCS-specific parts of the header are available under
different tabs.  This option is only active when the ISM is enabled.
.TP 15
.B Compass
Draw an orientation compass on the display panner.  If the ISM is enabled
and a WCS is present in the header, the compass will indicate N/E
according to the WCS, otherwise the X/Y axes of the image are drawn.
.TP 15
.B Options
Pop-up/down the option control portion of the panel. When enabled, the
Coords Panel will change size to reveal the options which can be
changed (explained below). 
.RE

.LP
The "Readout Values" group controls the selection of WCS type, location
and format to be displayed.  The "Type" menu always provides a selection
of the image Logical, Physical or World systems, which may be identical
depending on the image header.  If a World system is supplied in the image
addition entries for transformations to other sky systems, (e.g.  FK5 to
ICRS or galactic/ecliptic) will also be available.  The selection is
dependent on whether the ISM is running as well as WCS information present
in the image.  The "Format" menu allows the use to select a sexigesimal
display, conversion to degrees or radians, or whichever format is most
natural for the coordinate being display.  The two toggle to the right
control whether this WCS is to be displayed on the Panel (i.e. the Coords
Panel window) or the ImgWin (i.e.  the text marker on the main image
window).

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.

.SH "TCLSHELL"

The \fITclShell\fP allows the user to type commands directly to the TCL
interpreter, letting you send messages to the object manager or execute 
specific procedures in the TCL code that makes up the GUI. It is used as a
development or debugging tool for the GUI, but for an example of what it
does, bring it up and type a command such as

		\fIsend fileButton set background red\fP


.SH "COLORMAP SELECTION"

By default XImtool will display images using either a grayscale colormap
(e.g.  if loaded by a client), or a private colormap when loading an image
from disk that contains a colormap. Each frame defines its own colormap so
you can define different colormaps or enhancements for each frame, they
will change automatically as you cycle through the frames.

.SS "BUILTIN COLORMAPS"

Once loaded, the colormap may either be changed using the builtin colormap
menu under the View menu button on the main window, or from the
Enhancement box on the control panel. XImtool has about a dozen colormap
options builtin, other user-defined colormaps may optionally be loaded.
It is not presently possible to save colormaps for later use.

.SS "USER-DEFINED COLORMAPS"

The \fIcmap[12]\fP and \fIcmapDir[12]\fP resources (or command line
arguments) are used to tell which specific colormaps to make available or
where to look for colortables respectively.  The colortables are loaded
when ximtool starts up, or when it is reinitialized (e.g. by pressing the
Initialize button in the control panel).  XImtool will ignore any files in
the colormap directory which do not look like colortables.  New
colortables will also be added automatically for each image loaded from
disk.

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.

.SS "MINIMIZING COLORMAP CONFLICTS"

The Gterm widget used by XImtool (i.e. the main display window) uses a
private global colormap for display, this allows it to have greater
control over color cell allocation but can occasionally also cause
"colormap flashing" as the mouse is moved in and out of the application.
The problem here is that in a system with only an 8-bit colormap (256
colors) all applications must compete for colors, programs such as XV or
Netscape allocate colors from the default colormap leaving only a few free
cells for XImtool.  Since XImtool defines a private global colormap it is
still able to allocate the needed cells rather than failing, but it's
allocating cells already used by other applications.  As the mouse moves
out of the ximtool window those cells are once again defined in terms of
the default colormap, so the ximtool window is then using a different
colormap.  It is this switching of the colormap context that causes the
flashing to occur, but there are a few things that can be done to help
minimize this.

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 \fIbasePixel\fP 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
\fIbasePixel\fP, either restart the X server or set the resource
\fIcmapInitialize\fP=\fITrue\fP 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
.sp 0.7
		\fIxprop -root -remove GT_image\fP
.sp 0.7
These options may also be set on the command line when first starting up.  

In general one can set the Gterm widget resources \fIbasePixel\fP and
\fImaxColors\fP to specify the region of colormap space to be used for
image display.  If you set \fImaxColors\fP 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
\fIglobal\fP 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
\fIcmapName\fP 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 \fIcmapName\fR 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 \fIiraf@noao.edu\fP.


.SH "DISPLAY CLIENT CONNECTIONS"

XImtool allows display clients to connect in any of the following ways:
.TP 5
.B "fifo pipes"
The traditional approach. The default global /dev/imt1[io] 
pipes may be used, or a private set of fifos can be specified using the
\fI-fifo\fP command line argument or \fI*fifo\fP resource.  Values should
be specified as the root pathname to a pair of fifo pipes whose last
character is 'i' or 'o',  these characters will be added automatically when
opening the pipes.  For example, to use the default pipes the path would
be specified as simply "/dev/imt1". A value of "none" disables this connection.
.TP 5
.B "tcp/ip sockets"
Clients connect via a tcp/ip socket. The default port is \fI5137\fP, or a
custom port may be specified using the \fI-port\fP command line switch or
a \fI*port\fP resource. This permits connecting to the server
over a remote network connection anywhere on the Internet.  
A port number of 0 (zero) disables this connection.
.TP 5
.B "unix domain sockets"
Like a tcp/ip socket, but limited to a single host system. Usually faster
than a tcp/ip socket, and comparable to a fifo. By default each user gets
their own unix domain socket, so this option allows multiple users to run
ximtools on the same host without having to customize things.  The default
value is "/tmp/.IMT%d", other sockets may be defined using the \fI-unix\fP
command line switch or the \fI*unixaddr\fR resource.  Legal values
should be specified as a filename to be used for the socket, up to two "%d"
fields are allowed and will be replaced by the userid. An empty string value
disables this connection.

By default ximtool listens simultaneously for client connections on all three
types of ports.   Clients may connect simultaneously by different 
means allowing up to three different displays to be loading at the same
time into different frames.


.SS "COMMUNICATIONS PROTOCOL"

The communications protocol used is a slightly modified version of
that used by the IIS Model 70; other more modern protocols will likely be
supported in the future.  The IIS protocol is basically a command packet
stream with a header describing the operation to be performed (select
frame, load display, read cursor, etc), and an optional data packet
containing e.g. pixels. 

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


.SS "IIS PROTOCOL SUMMARY"

All operations are initiated by sending a
header packet containing a \fIthing id\fR (tid) and \fIsubunit\fR selecting
the function to be performed, optionally followed by data up to 32Kb long.
The IIS header packet used is defined as
.nf
		\f(CWstruct  iism70 {
        		short   tid;
        		short   thingct;
        		short   subunit;
        		short   checksum;
        		short   x, y, z;
        		short   t;
		};\fR   
.fi

The \fIthing count\fR field contains the negative number of bytes of data
that will be sent following the header packet.  The IIS header checksum is
computed as 
.nf
\f(CW
    checksum = 0177777 - (tid + subunit + thingct + x + y + z + t);
\fR
.fi
The four IIS registers are set differently depending on the operation, a
summary of the header packets for each operation is summarized below. 
.br

.KS
.ce 1
\fBIIS Header Packet Summary\fR
.TS
tab(:);
c c c c c c c c c.
:TID:Subunit:Tct:X:Y:Z:T:Data
.T&
l | l | l | c | c | c | l | l | l |.
:_:_:_:_:_:_:_:_
Read Data:IIS_READ\fB|\fPPACKED:MEMORY:-NB:x:y:fr:-:NB
Write Data:IIS_WRITE\fB|\fPPACKED:MEMORY:-NB:x:y:fr:-:NB
Read Cursor:IIS_READ:IMCURSOR:-:-:-:-:-:-
Write Cursor:IIS_WRITE:IMCURSOR:-:x:y:wcs:-:-
Set Frame:IIS_WRITE:LUT\fB|\fPCOMMAND:-1:-:-:-:-:2
Erase Frame:IIS_WRITE \fB|\fP fb:FEEDBACK:-:-:-:fr:-:-

Old Write WCS:IIS_WRITE\fB|\fPPACKED:WCS:-N:-:-:fr:fb:320
Old Read WCS:IIS_READ:WCS:-:-:-:fr:wcs:320

WCS Version?:IIS_READ:WCS:-:1:1:-:-:320
WCS by Number?:IIS_READ:WCS:-:1:-:fr:wcs:1024 
New Write WCS:IIS_WRITE\fB|\fPPACKED:WCS:-N:1:-:fr:fb:1024
New Read WCS:IIS_READ:WCS:-:1:-:fr:wcs:1024
:_:_:_:_:_:_:_:_
.TE
.KE

.TS
l l l.
Where	NB	= number of bytes expected or written
	x	= x position of operation in frame buffer coords
	y	= y position of operation in frame buffer coords
	fr	= frame number (passed as bitflag (i.e. 1, 2 ,4 8, etc)
	fb	= frame buffer config number (zero indexed)
	N	= length of WCS string
	wcs	= WCS number (usually zero)
	Data	= the number of bytes of data to be read or written following the header packet.

	IIS_WRITE	 = 0400000
	IIS_READ	 = 0100000   
	COMMAND	 = 0100000
	PACKED	 = 0040000
	IMC_SAMPLE	 = 0040000
		
	MEMORY	 = 001
	LUT	 = 002
	FEEDBACK	 = 005
	IMCURSOR	 = 020
	WCS	 = 021
.TE

TID fields can be logically OR'd with the PACKED flag indicating the number
of data bytes is exactly \fIthingct\fR bytes long, otherwise \fIthingct\fR
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.

.SH "ISM COMMUNICATIONS"

The ISM (Image Support Module) can be any external task which 
connects to XImtool over a socket.  Communications are limited to simple
null-terminated text strings.  In most cases these strings are just the
standard OBM messages sent to XImtool objects but can also include Tcl
callback code (either ISM-specific callbacks, procedures which can be
added to the callback list for existing XImtool objects, or even new GUI
code to create panels and new objects).

.SS "ISM SOCKET CONNECTION"

The ISM first requests a connection to XImtool on a dedicated
socket whose default value is "/tmp/.ISM%d", where the '%d' is replaced
by the userid allowing multiple users on a machine to have independent
sockets.  The XImtool 'ism_addr' resource or "-ismdev" command-line option
can be used to change this address, a value of 'none' will disable ISM
communications.  The socket may also be set with an ISMDEV environment
variable which will override the resource or command-line options.

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.

.SS "COMMUNICATIONS PROTOCOL"

Messages from the ISM are written to the connection socket and must
be preceeded by one of the following keywords:
.RS
.TP 15
.B callback
Negotiate a connection on another socket
.TP 15
.B ready
Client is ready to begin processing
.TP 15
.B quit
Client is shutting down and disconnecting
.TP 15
.B send
Send a message to another object
.RE 
.sp 0.8

Where messages are of the form:
.RS
.TP 30
.B connect <\fIname\fP>
Request a connection for the <\fIname\fP> ISM
.TP 30
.B ready <\fIname\fP>
Reconnection request for the <\fIname\fP> ISM on negotiated socket, ISM is
ready to processing.
.TP 30
.B send <\fIobj\fP> '{' <\fImsg\fP> '}'
Send <\fImsg\fP> to the named <\fIobj\fP>.  The message may be any valid string that
will be understood by the recipient.  The object may be any object in
the GUI or OBM (see below).
.TP 30
.B quit
ISM is shutting down. The named is determined from the communications
channel, ISM is responsible for any cleanup of it's callbacks before
issuing the shutdown.
.RE

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.

.SS "GUI OBJECTS"

While the ISM can send a message to any object in the task, there
is a GUI Parameter object called 'ism_msg' designed especially to process
messages from the ISM.  The callback in the GUI is expecting a message
beginning with one of the following keywords:
.RS
.TP 15
.B source
Source message text as Tcl code
.TP 15
.B alert
Message contains error text to be displayed in the GUI 'alert' box
.TP 15
.B deliver
Message text should be passed to a callback routine specific to that ISM.
This processing callback may have been previously uploaded.  The message text
may be any form the processing callback is expected to understand.
.TP 15
.B info
Message text is status output intended for the XImtool 'info' panel
(connect/disconnect requests, etc)
.RE

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

	<\fIcmd\fP> <\fIism_name\fP> [ <\fIarg1\fP> <\fIarg2\fP> <...> ]

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.


.SH ENVIRONMENT
.TP 30
.B HOME
Specifies user login directory
.sp -0.5
.TP 30
.B DISPLAY
Specifies which display screen to use
.sp -0.5
.TP 30
.B "IMTOOLRC or imtoolrc"
Frame buffer configuration file
.sp -0.5
.TP 30
.B "ISMDEV"
ISM Connection socket

.TP 30
.B "DEBUG_IIS"
Debug IIS communications packets
.sp -0.5
.TP 30
.B "DEBUG_ISM"
Debug ISM communications packets
.sp -0.5
.TP 30
.B "DEBUG_MAPPINGS"
Debug WCS image mappings
.sp -0.5

.SH FILES
.TP 30
.B "/usr/local/lib/imtoolrc"
Default frame buffer configuration file
.sp -0.5
.TP 30
.B "/usr/local/lib/ximprint.cfg"
Default printer configuration file
.sp -0.5
.TP 30
.B "/usr/local/lib/imtoolcmap"
Default colormap directory
.sp -0.5
.TP 30
.B "/dev/imt1i"
Default input display fifo
.sp -0.5
.TP 30
.B "/dev/imt1o"
Default output display fifo
.sp -0.5
.TP 30
.B "/tmp/.IMT%d"
Default unix display socket
.sp -0.5
.TP 30
.B "/tmp/.ISM%d"
Default unix ISM connection socket
.sp -0.5

.SH BUGS
Users should report bugs to \fIiraf@noao.edu\fR.

.SH SEE ALSO
xgterm(1), xtapemon(1)

.SH COPYRIGHT
Copyright(c) 1986 Association of Universities for Research in Astronomy Inc.