diff options
Diffstat (limited to 'unix/sun/imtool.man')
| -rw-r--r-- | unix/sun/imtool.man | 713 |
1 files changed, 713 insertions, 0 deletions
diff --git a/unix/sun/imtool.man b/unix/sun/imtool.man new file mode 100644 index 00000000..f4af4d1c --- /dev/null +++ b/unix/sun/imtool.man @@ -0,0 +1,713 @@ +.\" @(#)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. |