.\" @(#)imtool.1 1.1 14-Aug-87 DCT .TH IMTOOL 1 "29 June 1989" .SH NAME imtool \- image display server for the SunView environment .SH SYNOPSIS .B imtool [ .B \-fbconfig \fIN\fP ] [ .B \-raster \fIfilename\fP ] .ti +0.5i [ .B \-maptype \fB\fR(\fPmono \fR|\fP linear \fR|\fP random \fR|\fP crandom\fR) ] .ti +0.5i [ .B \-\fR[\fPno\fR]\fPcolorbar\fR ] [ .B \-white \fR|\fP \-black\fR ] [ \fIframeargs\fR ] .SH OPTIONS .TP \fB\-fbconfig \fIN\fP Specifies the initial frame buffer configuration (specifying the number and size of the internal frame buffers) for the server. The set of acceptable frame buffer configurations is defined in a private or public \fIimtoolrc\fR file (discussed below). .TP \fB\-raster \fIfilename\fP Specifies that the server is to start up with the image in the standard Sun raster format file \fIfilename\fR already loaded into frame buffer 1. The size of the specified raster need not match the size of the frame buffer configuration specified with the \fI\-fbconfig\fR argument. .TP \fB\-maptype \fR(\fPmono \fR|\fP linear \fR|\fP random \fR|\fP crandom\fR)\fP Specifies the type of greyscale mapping to be used. \fBmono\fR means render the image in black and white (shades of gray). \fBlinear\fR means render the image in linear pseudocolor, with the range of displayed pixel values corresponding to a range of colors from black to blue to green to red to white. \fBrandom\fR means render the image in random pseudocolor, with a random color being assigned to each greyscale value. \fBcrandom\fR means render the image in random pseudocolor, updating the colortable every second or so while the mouse is in the display window. .TP \fB\-\fR[\fPno\fR]\fPcolorbar\fR Specifies whether or not a colorbar is to be displayed at the bottom of the display window. The colorbar graphically illustrates the relationship between pixel intensity and displayed color or greylevel, and is particularly useful with pseudocolor, or when windowing the display. The minimum pixel intensity (1) is at the left and the maximum (200) is at the right. .TP [\fB\-white\fR |\fP \-black\fR] Specifies whether the image is to be displayed on a white (default) or black background. .TP [\fIframeargs\fR] \fIimtool\fR also takes generic tool arguments, used to set the position, size, etc. of the display window; see \fIsuntools\fR(1) for a list of these arguments. .if t .sp 0.08i .SH DESCRIPTION .SS Image Display Server .LP \fIimtool\fR implements a simple image display server for the SunView window environment. The server runs as an independent process, managing the display window and listening for connections on a pseudodevice entry in \fB/dev\fR. All communications with the server are via a simple data stream protocol described below. .if t .sp 0.05i .SS Prototype Status .LP The current implementation of the imtool image display server is a limited prototype, and can be expected to change substantially in the future as the prototype continues to evolve. The main capabilities lacking in the current version are flexibility in lookup table control, overlaid graphics and text, miscellaneous functions such as split screen, and a fully interactive interface to applications programs. .if t .sp 0.05i .SS Basic Concepts .LP The display server consists of a set of N \fBframe buffers\fR and a single \fBdisplay window\fR. A frame buffer is a two dimensional array in memory into which the image to be displayed is loaded, and which is used to refresh the display window when portions of the window are uncovered. In the current prototype display server only 8 bit deep frame buffers are supported, but the number and size of the frame buffers is user configurable. .PP The display window is literally a window into the image stored in the frame buffer. While the size of the frame buffer is fixed (subject to periodic reconfiguration), the display window may be any size, and the size may be changed at any time without affecting the contents of the frame buffer. Likewise, the position of a small display window upon a larger frame buffer is arbitrary and may be changed at any time by \fBpanning\fR the window across the image. While there may be multiple frame buffers, there is only a single display window, and only a single image may be displayed at any one time, although a single keystroke suffices to change the frame being viewed. .PP With few exceptions, all display server functions are both \fIindependent\fR and \fIasynchronous\fR. Hence, one can display one frame while another is being loaded, or even resize or pan the display window and adjust the greyscale mapping of a frame while the frame is being loaded. .PP The primary function of the display server is to provide image display and interactive image oriented user interface capabilities to a concurrently executing client program via a bidirectional datastream interface. Hence, to make use of the display server for image display one also needs an applications program capable of talking to the server, and sending it image data to be displayed (a rudimentary builtin capability for displaying Sun raster files is however provided). The \fBdisplay\fR program in the IRAF \fBimages.tv\fR package is an example of such a client program. .if t .sp 0.05i .SS The Frame Menu The imtool frame menu provides the following selections: .if t .sp .05i .if n .sp .RS .IP \fBFrame\fR 15 Displays the standard SunView frame menu. .IP \fBSetup\fR Displays (or hides) the imtool interactive setup panel. .IP \fBRegister\fR Adjusts the pan offset of all frame buffers to match that of the image currently being displayed. Normally, the individual frame buffers are independently panned. .IP "\fBBlink \fR[\fPon\fR|\fPoff\fR]" Turns frame blink (alternate display of a series of frames) on or off. Alternatively the \fBctrl/B\fR key may be used to manually cycle through the blink frames. .IP \fBFitFrame\fR Adjusts the size of the display window to display the entire frame buffer. .IP \fBNextFrame\fR Displays the next frame buffer in sequence. Used to cycle through and alternately display all frames (the \fBalternate\fR or \fBctrl/F\fR and \fBctrl/R\fR keys may also be used to cycle forward or reverse through the frames). .IP \fBGclear\fR Clear the graphics overlay of the frame currently being displayed. .IP \fBIclear\fR Clear the image, i.e., frame buffer, currently being displayed. .IP \fBImcopy\fR Make a hardcopy of the image window. .RE .if t .sp .05i .if n .sp .LP The image hardcopy output function is an entry point to the general screen capture facility, discussed in the next section. This is the same facility used by the \fIgterm\fR program. .if t .sp 0.05i .SS Hardcopy Output .LP The image hardcopy function produces a "what you see is what you get" bitmap of the rectangular region of the screen occupied by the display window. If the region of interest is partially covered by another window, then the hardcopy will be a picture of a partially covered window. Any interactive adjustment of the grayscale mapping will be reflected in the hardcopy output. .LP The screen capture software reads out the full memory of the workstation in the region of interest, and in the case of a color workstation, processes the screen pixels through the colortable to produce an image corresponding to what appears on the screen. No full color output options are currently provided, hence the average of the red, green, and blue color values is next computed. If rasterfile output is being generated, the raw pixel values and RGB color table entries are saved directly in the rasterfile, rather than applying the tables in software to produce a monochrome or bitmap image. .LP Two output options are currently provided, i.e., \fBPostscript\fR output suitable for output directly to a laser writer to produce the final graphics hardcopy, or \fBSun rasterfile\fR output. The default action is to output a Postscript program to the device "lw", e.g., the Apple Laserwriter (any 300 dpi Postscript device should do), using the dithering capability of Postscript to produce a pseudogreyscale representation of the 8 bit output image. These defaults may be changed by defining the following environment variables: .IP R_RASTERFILE If this variable is defined a Sun rasterfile will be generated, otherwise a Postscript plotfile is generated. The string value of the variable is a \fIprintf\fR style format string to be used to generate the filename of the rasterfile. If multiple rasterfiles are to be generated, the format string may contain a decimal integer field (e.g., "\fLframe.%d\fR") to be replaced by the \fIfile number\fR of the current rasterfile. The first file generated will be number zero, with the file number being incremented once for every rasterfile produced. If Postscript plotfile output is desired, the plotfile will be a uniquely named temporary file in \fB/tmp\fR. (Postscript output is text and you can read this file if you are curious what it looks like). .IP R_DISPOSE The string value of this variable is a \fIprintf\fR style format string with one string valued subfield to be replaced by the plotfile or rasterfile name, to be used to generate the command used to dispose of the output file. If this variable is not defined and the output file is a Postscript plotfile, the default format string \fL"lpr -Plw -r -s %s"\fR will be used. If the variable is not defined and the output file is a rasterfile, no action is taken. It is the responsibility of the dispose command to delete the output file. .LP It should only take several seconds to capture the screen and produce the output rasterfile or queue the Postscript job to the printer. The screen is flashed to indicated when the operation has completed (provided the user has not turned off the \fIvisible bell\fR feature in their SunView defaults startup file). .PP The Postscript processing time is usually several minutes (of laserwriter time). Since most Postscript printers are interfaced via a serial interface at 9600 baud, data compression is used to reduce the amount of data to be transmitted, and the current bottleneck is the processing speed of the Postscript engine itself, which does all the dithering and coordinate transformations. (This is true for bitmaps, but the data compression algorithm used is not very effective for 8 bit image data, and the serial interface can still be a bottleneck in this case). .if t .sp 0.05i .SS The Setup Panel .LP The setup panel is used to interactively modify imtool options. Two types of selections are provided, \fImultiple choice\fR selections, and \fIpush button\fR selections. Clicking on a multiple choice selection cycles through the choices (left mouse button) or displays the choices as a menu (right mouse button). String valued options are modified by clicking on the old value, rubbing out all or part of the old value if necessary, and then typing in a new value followed by return. If there several string valued fields in a panel, return may be used to cycle through the fields. Clicking on a push button (use the left mouse button) "pushes" the button, causing the action indicated on the button to be executed. .LP The multiple choice options in the setup panel are the following: .IP "\fBNumber of frame buffers\fR" Specifies the number of frame buffers for which space is currently allocated. The number of frame buffers may be changed at any time. If a client program references a frame which does not yet exist, the number of frame buffers will automatically be increased, hence it is not necessary to preallocate space for the frame buffers. .IP "\fBGreyscale mapping\fR" Specifies the method to be used to map pixel intensity values to RGB color intensity values. \fBmono\fR specifies that the image is to be rendered in shades of grey. \fBlinear pseudocolor\fR specifies that the image is to be rendered in pseudocolor, with pixel intensities mapped into the range of colors from black to blue to green to red to white. \fBrandom pseudocolor\fR assigns a random color to each possible pixel greylevel. \fBcontinuous random pseudocolor\fR is like random pseudocolor, but the colors are changed every few seconds, where the interval between color changes is specified by the \fBrate\fR option below. .IP "\fBRate (sec) for Crandom Option\fR Specifies the frequency (1 to 32 seconds) with which new colors are to be assigned for the continuous random pseudocolor option. .IP "\fBBackground color\fR Specifies the frame background color, i.e., the color to which the frame will be set when cleared (black or white), or when displaying an image which fills only part of the frame, the color of the portion of the frame buffer which has not been written into. .IP "\fBInclude Frame Border in Imcopy\fR Specifies whether the frame border, including the frame label, is to be included in image hardcopies. By default the frame border is included since the frame label is often used to identify the displayed image. If the frame border is excluded then so is the colormap, if any. .IP "\fBShow colorbar\fR Specifies whether or not a colorbar is to be shown at the bottom of the display window. .IP "\fBBlink rate (sec)\fR When blink is enabled, specifies the amount of time a single frame is to be displayed. The value may range from 1/2 second to 32 seconds. The maximum blink rate may be achieved by holding down the \fBalternate\fR key long enough to cause autorepeat. .IP "\fBFrames to be blinked\fR The string value of this parameter specifies the list of frames to be blinked. The special value "all" may be specified to blink all frames in sequence. If the frames are explicitly listed, the same frame may appear in the list multiple times. .IP "\fBZoom factors\fR Specifies the positive integer zoom factors to be used for the zoom and pan function. Up to eight zoom factors may be specified (more would be undesirable due to the time required to cycle through the zooms to get back to an unzoomed image). The default zoom factors are "1 2 4 8"; depending upon the application, one might want to add, e.g., a zoom factor of 3, or a large zoom factor of 32 or 64 to make it easy to identify individual pixels. .IP "\fBCoordinate list output file\fR Specifies the name of the file to be used for cursor lists (text files containing lists of object coordinates - see below). .IP "\fBRaster filename (load/save)\fR Specifies the filename of the Sun rasterfile to be loaded into the current frame buffer (\fBload\fR push button, below), or the filename into which to current frame is to be written (\fBsave\fR push button). .LP The following "push buttons" are also provided in the setup panel. Many of these are equivalent to the comparable selections in the frame menu. .RS .IP "\fBRegister Frames\fR" 15 Adjust the pan offset of all frames to match that of the current frame. .IP "\fBFit Window\fR" Adjust the size of the display window to match that of the frame buffer. .IP \fBReset\fR Reset the display. The mapping type, transfer function, and pan offsets are restored to their initial values, but the contents of the frames are not affected. .IP \fBIclear\fR Clear the frame buffer currently being displayed. .IP \fBGclear\fR Clear the graphics overlay (may also be cleared whenever the display window is refreshed). .IP \fBLoad\fR Load the Sun rasterfile named by the \fIRaster filename\fR panel string parameter into the frame buffer currently being displayed. If the rasterfile is smaller than the frame buffer the raster will be loaded into the upper left corner of the frame buffer. If the rasterfile is larger than the frame buffer part of the raster will be discarded. Any colortable information present in the rasterfile is ignored. .IP \fBSave\fR Save the contents of the frame buffer currently being displayed in the Sun rasterfile named by the \fIRaster filename\fR panel string parameter. The new raster will be the same size as the frame buffer. No colortable, WCS, or any information other than the pixel values is saved in the rasterfile. .IP \fBBlink\fR Turn frame blink on or off. .IP \fBFrame\fR Display the next frame in sequence. Equivalent to the \fBNextFrame\fR frame menu selection, and to the \fBalternate\fR and \fBctrl/F\fR keys. .IP \fBQuit\fR Close the setup panel. .RE .if t .sp 0.05i .SS Function Keys .LP The following function keys have special significance to \fIimtool\fR: .RS .IP F4 15 Calls up the setup panel, or closes it if already displayed. .IP F5 15 Causes the current cursor list file to be rewound and reread, marking all objects on the cursor list by drawing a number beside each object in the display window. Each object is marked by its ordinal number in the cursor list, ignoring comment lines and blank lines. The precise object position is at the lower left corner of the first digit. Each time the cursor list is redrawn the color of the digits toggles between black and white, making it possible for the user to manually "blink" the object numbers, or select the representation which provides the best visibility for their data. Note that objects are marked only in the display window, i.e., the frame buffer is not modified, hence the numerals will be lost whenever the display is refreshed. .IP F6 Enables and disables \fBcursor readout mode\fR. While cursor readout mode is in effect a box is displayed in the lower right corner of the display window, in which the coordinates and corresponding pixel intensity at the position of the the mouse cursor are continuously updated as the mouse is moved. The cursor coordinates are given in \fIworld coordinates\fR if a WCS (world coordinate system) has been defined for the frame, otherwise display window relative pixel coordinates and display pixel intensity values are given. If the pixel intensity is saturated (set to the extreme high or low value), a + or - is appended to the printed value to flag the value as saturated. .IP F7 Hitting this key while the mouse is in the display window causes an image hardcopy to be generated. This is equivalent to selecting the \fBimagecopy\fR item in the frame menu, except that it can be done without moving the mouse. This may be important to avoid changing the greyscale mapping, which also depends upon the mouse position. .RE .LP Note that the mouse must be in the display window for these function keys to have any effect. .if t .sp 0.05i .SS Mouse Buttons .LP The mouse buttons are used with \fIimtool\fR as follows: .RS .IP "Left Button" 15 In cursor readout mode, used to mark objects, adding each object to the cursor list for the current frame. Ignored when not in cursor readout mode. .IP "Middle Button" The middle button on the mouse is the \fBpan/zoom\fR button. If the pan button is held down and released at a position in the display window, the object under the cursor will be moved to the center of the display. \fBcontrol-pan\fR is the same except that the image will pan smoothly to the new position, rather than all at once. \fBshift-pan\fR causes the image to be panned in the indicated direction in large steps. Shift and control may be combined to smoothly pan in large steps. .IP The \fBzoom\fR function is also controlled by the middle mouse button. Placing the mouse on an object and pressing pan/zoom once causes the object to be moved to the center of the display; pressing the button again causes the image to be zoomed about the mouse position. Repeated presses without moving the mouse cycle through the predefined set of zoom factors until the cycle wraps around and the unzoomed image is restored. Zoom is almost as fast as a normal unzoomed window refresh, so there is no problem with, for example, panning on a zoomed image. .IP If the middle button is held down while in cursor readout mode the mouse may be moved without updating the displayed cursor coordinates. This is useful when moving the mouse to a different window, e.g., to type the displayed object coordinates into an application running in some other window. An attempt to pan while already at the edge of the frame is ignored. .IP "Right Button" Used to interactively adjust the greyscale mapping (colortable) for the window. .RE .LP To window the display, i.e., adjust the \fBtransfer function\fR for the window, hold the right mouse button down and move the cursor about within the window. Zero contrast (one greylevel) is at the center of the window, with positive contrast above, negative contrast below, and contrast increasing the further the mouse is moved from the centerline. Moving the mouse to the left or right adjusts the greyscale range to lower or higher intensities. The colorbar provides a graphic display of the effect of the transfer function. If the right mouse button is pressed and then released without moving the mouse the transfer function will be adjusted according to the position of the mouse. By alternately displaying several frames and tapping the right mouse button for each frame without moving the mouse, the transfer functions of several frames may be matched. .if t .sp 0.05i .SS Frame Buffer Configuration Files .LP While the prototype display server does support dynamic reconfiguration of the frame buffers, allowing multiple frame buffers of virtually any size, it is currently necessary to define the possible frame buffer configurations at startup time. This is done via a table file called the \fBimtoolrc\fR file. An example illustrating the contents of such a file is shown below. Note that this may differ from the default configuration file used at your site. .sp .nf 1 2 512 512 # imt1|imt512 2 2 800 800 # imt2|imt800 3 2 1024 1024 # imt3|imt1024 4 1 1600 1600 # imt4|imt1600 5 1 2048 2048 # imt5|imt2048 6 1 4096 4096 # imt6|imt4096 7 1 4096 1024 # imt7|imt4x1 8 1 1024 4096 # imt8|imt1x4 9 2 1144 880 # imt9|imtfs full screen (1152x900 minus frame) 10 2 1144 764 # imt10|imtfs35 full screen at 35mm film aspect ratio 11 2 128 128 # imt11|imt128 12 2 256 256 # imt12|imt256 20 2 388 576 # imt20|imtgec GEC CCD detector format 21 1 3040 976 # imt21|imtkpca KPCA detector format (also 2D-Frutti) 22 1 128 1520 # imt22|imt2df1 2D-Frutti 23 1 256 1520 # imt23|imt2df2 2D-Frutti 24 1 512 1520 # imt24|imt2df5 2D-Frutti 25 1 960 1520 # imt25|imt2df9 2D-Frutti 26 1 512 800 # imt26|imtcryo Cryogenic Camera 27 1 348 800 # imt27|imtgcam Gold Camera 28 1 976 3040 # imt28|imt2df9x3 2D-Frutti .fi .LP Each entry in the file contains four numbers, the configuration number (e.g., as used in \fI\-fbconfig N\fR), the number of frames to be created initially (frames may be added or deleted once the configuration is specified), and the width and height of the frame in screen pixels. Blank lines and comments are ignored. Note that \fIthe frame width must evenly divisible by 4\fR, due to alignment restrictions on memory pixrects in SunView. .LP Selection of the frame buffer configuration to be used is done at run time by the client application program when a frame is loaded. Since the frame buffer size to be used is controlled by the client application program rather than by the server, there is no entry in the setup panel for changing the configuration. Rather, it is expected that a command will be provided at the applications level for specifying the frame buffer size to be used. In the case of IRAF, this is done with a command such as \fBreset stdimage = imt800\fR, where the logical device name used on the right is given in the comments in the configuration table above, and must correspond to an equivalent entry in the IRAF \fBgraphcap\fR file. The imtoolrc file may be customized by the user for special applications, if desired, but a custom version of the graphcap file will be required too. .LP The frame buffer configuration file may be located in a default public directory, e.g., \fB/usr/local/lib/imtoolrc\fR, or the user may have a private version of the file, e.g., \fB.imtoolrc\fR. During startup, imtool looks first for an environment variable IMTOOLRC defining the pathname of the imtoolrc file, then it checks for a .imtoolrc file in the user's login directory, and finally it checks for the file /usr/local/lib/imtoolrc. If none of these are found, a default configuration of a single 512 square frame buffer is used. .if t .sp 0.05i .SS World Coordinate Systems .LP \fIimtool\fR provides a simple mechanism for associating a linear \fBworld coordinate system\fR (WCS) with the displayed image. A WCS consists of an image title string to be displayed in the frame label, a rotation matrix expressing the translation from window pixel coordinates (zero-indexed, origin in the upper left corner of the display window) to \fIworld coordinates\fR, e.g., the image pixel coordinates of the displayed image, and a pair of image intensity values defining the transformation between display server pixel intensity units (range 1-200 currently) and image pixel intensity units. .LP The WCS for a frame is passed to imtool as a set-WCS command in the datastream input from the client process (applications display program). A sample WCS descriptor is shown below. .if t .sp 0.03i .if n .sp .RS .nf dev$pix - m51 B 600s .br 1. 0. 0. -1. 1. 512. 0. 1481.635 1 .fi .RE .if t .sp 0.03i .if n .sp .LP The first line is simply a line of text to be displayed in the frame label when the WCS is read. This should normally contain the name of the image and a few words describing the image being displayed. .LP The first six numbers in the second line define a rotation matrix specifying the translation from window pixel coordinates to world coordinates, according to the following relations: .if t .sp 0.03i .if n .sp .RS .nf x' = ax + cy + tx .br y' = bx + dy + ty .fi .RE .if t .sp 0.03i .if n .sp The coefficients of the transformation matrix are given in the order \fBa b c d tx ty\fR. The example defines the image pixel coordinates for a 512 square image, displayed with the origin at [1,1] in the lower left corner of the display window. Note that the world coordinates are flipped in Y and shifted to an origin at [1,1]. .LP The final three numbers on the second line define the transformation from display pixel intensity units to image pixel intensity units. The first two values specify the image pixel intensities corresponding to display pixel intensities 1 and 200. The third number is an integer defining the type of transformation used; currently the value must be 1, indicating a linear transformation. .LP The WCS is initially undefined when a new frame is created. The first cursor or function key event thereafter which attempts to use WCS information will cause the WCS information to be interpreted if it has been passed in via the set-WCS datastream command. You will know if the server succeeds in reading the WCS because the \fBframe label\fR will change when the WCS is read. The first field of the frame label is the frame name, which will be the filename of any cursor list files created for the frame. .if t .sp 0.05i .SS Coordinate List Files .LP Cursor readout mode provides a convenient means of displaying the cursor coordinates, but the coordinates are lost as soon as the cursor is moved. To permanently record the positions of objects of interest one may generate a \fIcoordinate list file\fR by marking objects with the mouse. The contents of existing list files may also be displayed, and one may append to an existing list. List files generated by foreign programs may easily be displayed. .LP A coordinate list file is a simple text file with the X-Y coordinate pairs of objects recorded on successive lines in the file. The object number is not recorded explicitly, but is determined by the relative position of a coordinate pair within the file, ignoring comment lines (#...) and blank lines. List files may be edited and redisplayed if desired, and although the object numbers may change they will always agree with whatever is shown on the screen. A hardcopy of the screen may be made to provide a pictorial record of the contents of a list file, e.g., so that objects may be referred to by number if the list is used as input to another program. .LP The filename of the list file associated with the displayed frame is shown in the frame label, e.g., "frame.1". By default the list file will be created in the WCSDIR, i.e., in the directory defined by the user environment variable WCSDIR. .PP These defaults may be overridden by entering via the setup panel the \fIprintf\fR style format string to be used to construct the filename of the list file. If the name given begins with a / an absolute pathname is assumed and the filename is not modified in any way. Otherwise, a directory prefix is prepended, e.g., "$wcsdir/frame.\fIN\fP". The directory prefix is specified by the value of the WCSDIR environment variable if defined, otherwise the user's UNIX login directory is assumed. The frame number will appear in the generated filename only if a numeric format is included in the format string, e.g., \fBframe.%d\fR to specify a frame number file extension. .if t .sp 0.05i .SS Colortable Usage .LP To permit simultaneous viewing of both the display window and any other windows under SunView, \fIimtool\fR uses only a portion of the 256 element hardware colortable. Image pixels range in value from 1 to 200 (colortable entry 0 is reserved for the background or foreground color by SunView). Additional colortable entries are used for the cursor color and a set of graphics overlay colors, reserving 50 or so colortable entries for use by other windows. The graphics colortable entries are in the range 202-217. These are assigned predefined colors, which are unaffected by windowing the display. The graphics colortable assignments are summarized below. .if t .sp 0.03i .RS .nf 202 black 206 blue 210 coral 214 orchid 203 white 207 yellow 211 maroon 215 turquoise 204 red 208 cyan 212 orange 216 violet 205 green 209 magenta 213 khaki 217 wheat .fi .RE .if t .sp 0.03i .PP When imtool is started it reads the hardware color table, which is assumed to contain the entries for the other windows on the screen, replaces entries 1 through 200+, and uses the resultant table to update the hardware colortable thereafter at a rate of twice a second. It is necessary to continuously update the hardware colortable to permit image display while the mouse is not in the display window, however, this scheme will cause colortable conflicts f one attempts to run a second window tool which also uses a large number of colortable entries. .if t .sp 0.05i .SS Hints for Blinking Frames .LP Blink is most effective when used to compare two or more frames which are very similar, e.g., a frame and an edited version of the same frame. For blink to be most effective the images should be displayed as similarly as possible. Start by loading the two frames using the same spatial and greyscale transformation for both frames (IRAF users should use the \fBrepeat\fR option to the \fIdisplay\fR task). Select one of the frames and adjust the window size, pan offset, and greyscale mapping as desired. After adjusting the greyscale with the mouse, repeatedly hit the \fBalternate\fR key followed by the right mouse button to match the greyscale mapping of the first frame to the remaining frames. Then select \fBregister\fR in the frame menu or setup panel to register all the frames, followed by \fBblink\fR to blink the frames. Blink works best if the display window is not too large, e.g., a 400 or 500 pixel square window is fine. .if t .sp 0.05i .SS Data Stream Protocol .LP The display server is started like any other SunView tool by executing the \fIimtool\fR command either directly or indirectly via the \fB.suntools\fR file or via the mouse from the \fBrootmenu\fR. When first started a checkered test pattern is displayed, and the display server opens the pseudodevice files \fB/dev/imt1o\fR (used by the client to send commands and data to the display server) and \fB/dev/imt1i\fR (for data read back from the display server) and begins listening for commands from client programs. All commands and data are passed to the display server as a data stream by applications writing directly to /dev/imt1o. .LP The data stream protocol used in the prototype server (this will change) mimics that of the IIS Model 70 image display, with an extension added for specifying the frame buffer configuration to be used. The server will automatically sense if the datastream is byte swapped, allowing use of the server with, for example, IRAF running on a large VAX compute server. Only byte packed data is supported. .LP Note that any process may write to the server, but if more than one process writes to the server at the same time, the output may be garbled. Also, multiple display servers may be spawned, but since only a single pseudodevice entry is currently supported, all such servers would be trying to read from the same input stream. .SH SEE ALSO suntools(1), gterm(1), images.tv.display(IRAF) .br \fIWindows and Window-Based Tools: Beginner's Guide\fR .SH ENVIRONMENT .IP IMTOOLRC 15 The full pathname of the \fIimtoolrc\fR (frame buffer configuration) file to be used (optional). .IP WCSDIR The full pathname of the user directory into which imtool will write any files it creates that are not specified by a full pathname (alias \fBwcsdir\fR also permitted). .IP R_RASTERFILE If defined, a Sun rasterfile rather than Postscript file is generated by the \fIimcopy\fR function. The string value is a format used to generate the filename of the rasterfile. .IP R_DISPOSE The command to be executed to dispose of the Sun rasterfile or Postscript output file created by \fIimcopy\fR. If not defined and Postscript output is indicated (R_RASTERFILE also not defined), then the Postscript output file is disposed of via \fIlpr\fR to device \fIlw\fR. .SH FILES .LP .nf /dev/imt1[io] $WCSDIR/frame.* /usr/bin/suntools /usr/lib/rootmenu $iraf/local/sun/imtool.c .fi .SH BUGS .IP (1) The display server is continuously updating the hardware colortable even while the mouse is not in the display window. This is necessary to be able to see the image while the mouse is not in the window, but may interfere with other windows which also use many colortable entries. Under normal circumstances (only one greyscale window) this should not be a problem. If it is a problem, close the display window when not in use; updating of the hardware colortable is disabled while the display window is closed. .IP (2) Only a single display server should be used at any one time. Only a single client process should write to the server at any one time. .IP (3) The environment variables affecting IMTOOL operation must be defined before starting suntools if they are to have any effect. .IP (4) An error message is printed if imtool encounters a bad data header checksum, e.g., if synchronization is lost on the input datastream or if illegal data is input. Recovery from such an error can be difficult, possibly requiring killing the imtool and starting a new one. This error should not occur if the software (i.e., the client applications program) is functioning properly. .SH AUTHOR Doug Tody, National Optical Astronomy Observatories (NOAO), IRAF project.