CCSD3ZF0000100000001NJPL3IF0PDS200000001 = SFDU_LABEL RECORD_TYPE = FIXED_LENGTH RECORD_BYTES = 80 OBJECT = TEXT PUBLICATION_DATE = 1992-02-01 BYTES = 80 NOTE = "Description of the UNIX X Window program xmgndisp" END_OBJECT = TEXT END XMGNDISP(1) Magellan A&R Command XMGNDISP(1) NAME xmgndisp - Display MIDR or GxDR image in X window SYNOPSIS xmgndisp [-browse] [-borderwidth ] [-colormap ] [-Cmapdir ] [-display ] [-expand ] [-fn ] [-font ] [-geometry ] [-help] [-highvalue ] [-insertloc ] [-lowvalue ] [-match] [-nzoom ] [-palette ] [-shift ] [-swap] [-verbose] [-xrm ] [-zoomloc ] [vicar-file] DESCRIPTION Xmgndisp is a simple program that displays VICAR2 images using ver- sion 11 of the X window system, release 3 and later. It uses no widgets of any kind-only standard Xlib subroutine calls, and should therefore compile and run on a wide variety of X11 implementations. It has been tested on MicroVax, Sun, and DecStation hardware. It can read 2-dimensional VICAR images containing pixels in BYTE, HALF, and REAL format, and it recognizes sinusoidal, Mercator, and (polar) stereographic map projections. All parameters required to display the image must be entered on the xmgndisp command line, as described in the following section, including information necessary to "stretch" the image for best visibility. The pixels will be linearly mapped to the colors specified by the -colormap option between the values specified by the -lowvalue and -highvalue options, which default to the header variables LOW_DN and HI_DN, respectively. If these, too, are absent, the limits are 0 to 255 for FORMAT=BYTE pixels, and 0 to 65535 for FORMAT=HALF pixels. Once the image is displayed in a window, the following operations may be performed on it: Re-sizing the displayed image by dragging the window frame with the pointer device. The pre- cise method for doing this will depend on the window manager program. When an image is resized, the pixels are resampled to fit the window outline, while preserving the original aspect ratio. Displaying a zoomed insert by clicking button #1 while pointing to an image pixel. Two inserts will appear in the corners of the image-the value insert that displays the pixel coordinates and data value, and the zoomed insert that shows a magnified replica of the pixels surrounding the pointer. If the image has been re-sized, or expanded by means of the -expand option, the insert will mag- nify the original image pixels. A&R xmgndisp.man 1.4 Last change: 1/8/92 1 XMGNDISP(1) Magellan A&R Command XMGNDISP(1) Panning the insert by means of the arrow keys on the keyboard. These move the center of the magnified image by one pixel in any direction. The cursor will point to the corresponding location in the displayed image. Note that, if the main display image is smaller than the input image, this may not cause the cursor to move. Changing the insert magnification hit the "<" and ">" keys to, respectively, shrink and expand the magnified image. The current magnification factor is shown within the insert. Hiding the inserts hit the return key. The inserts will disappear until button #1 is pressed again. Changing the insert locations hit either the v or the z key to rotate, respectively, the value insert or the zoom insert from one corner of the display to another. Quitting the application hit either the q or the Q key. OPTIONS AND RESOURCES The following parameters can be supplied from several sources. In increasing order of precedence, these are + the application resource file "/usr/lib/X11/app- defaults/Xmgndisp", + the user's "~/.Xdefaults" file, + the user's "~/.Xdefaults-$HOST" file, + xmgndisp command-line arguments. Within resource files, these parameters should be specified as fol- lows: xmgndisp.resource: value where resource is identical to the command-line specification, after removing the leading "-" sign. The possible resource names are as follows: -browse the input file is a Magellan MIDR browse image and its header variables are incorrect-SPECLINE and PROJSAMP must be divided by 8 and PIXSIZ must be multiplied by 8. This action will also be taken automatically whenever xmgndisp reads a file named "browse.img" whose PIXSIZ header vari- able has the value 75, or 225, or 675, or 2025. -borderwidth A&R xmgndisp.man 1.4 Last change: 1/8/92 2 XMGNDISP(1) Magellan A&R Command XMGNDISP(1) specifies the width of all window borders, in pixels. -colormap specifies the name of a file that contains information on the colors to be assigned to pixel values. Within the file, blank lines and lines whose first non-whitespace character is "#" are treated as comments. Otherwise, the file should contain exactly 256 lines, and each line should contain 3 integers, separated by whitespace. The integers represent, respectively, the red, green, and blue intensities with which to display pixel values 0-255. An alternative format of color table may be specified by means of the -palette option, described below. If both -colormap and -palette are specified, -palette takes precedence. -Cmapdir specifies the directory within which to search for the -colormap file, if it isn't found in the current working directory. -display specifies the host and display number on which to create the image window. This option cannot be specified in a resource file-only in the xmgndisp command line. -expand expands (or shrinks) the image by a factor (which must be greater that 0 and less than or equal to 16, but need not be an integer). If a window-manager program is controlling the X display, the image may also be expanded or shrunk after it is first displayed. -fn -font specifies the font name or class to be used to display the coordinates in the value insert. For best results, the font should be of fixed width. -geometry specifies the size and position of the new image window on the X display. -help writes a list of xmgndisp command-line options to the stan- dard error stream, stderr, and then quits. -highvalue the data value to be represented by the "highest" color, i.e. by the entry in line 256 of the colormap file. If the input VICAR image is of BYTE or HALF format and the header contains values for the pixel mapping variables LOW_DN, HI_DN, LOW_REP, and HI_REP, value must be specified in the same units as LOW_REP and HI_REP. A&R xmgndisp.man 1.4 Last change: 1/8/92 3 XMGNDISP(1) Magellan A&R Command XMGNDISP(1) -insertloc specifies the starting location of the value insert. Possi- ble values are topleft, topright, bottomleft, and bottom- right. -lowvalue the data value to be represented by the "lowest" color, i.e. by the entry in line 1 of the colormap file. If the input VICAR image is of BYTE or HALF format and the header contains values for the pixel mapping variables LOW_DN, HI_DN, LOW_REP, and HI_REP, value must be specified in the same units as LOW_REP and HI_REP. -match instructs xmgndisp to try to allocate all necessary colors; then, if any cannot be allocated because the window-manager has run out of values, to draw the remaining pixels in the nearest available colors. This contrasts with the default action, which is to try to allocate the necessary colors; if any cannot be allocated, all are freed, and the process starts over again with pixel values 0 and 1 assigned to the same color, 2 and 3 assigned to the same color, and so on. If this also fails, xmgndisp tries again with pixel values 0, 1, 2, and 3 assigned to the same color, etc. Eventually, either all pixels are assigned to colors or xmgndisp quits with a rude message. The number of colors to be allocated can also be controlled with the -shift option, below. -nzoom specifies the default magnification of the zoomed insert. -palette specifies the name of a file that contains information on the colors to be assigned to pixel values. Each line must contain 4 integers delimited by whitespace. The first integer is a pixel value in the range 0-255, and the remaining integers represent, respectively, the red, green, and blue intensi- ties with which to display that pixel value. An alterna- tive format of palette may be specified by means of the -colormap option, described above. If both -colormap and -palette are specified, -palette takes precedence. -shift attempts to allocate colors to pixels in groups of n. For details, see the discussion of the -match option, above. -swap overrides the manner in which xmgndisp translates input HALF or REAL image pixels. Normally, when translating FORMAT=HALF pixels, and no INTFMT keyword is present, it assumes that the pixels are written with the high-order byte first. Specifying -swap will reverse this logic, i.e. if INTFMT=LOW, xmgndisp will assume that the high-order byte is first, and otherwise that it is second. The A&R xmgndisp.man 1.4 Last change: 1/8/92 4 XMGNDISP(1) Magellan A&R Command XMGNDISP(1) situation is similar for FORMAT=REAL: Unless REALFMT=VAX is specified in the header, xmgndisp will assume that the pixels are IEEE-754 floating-point numbers written with the sign-bit first. Specifying -swap will force xmgndisp to make the opposite assumption, i.e. that the pixels are VAX floats. -verbose lists the values of important VICAR2 header keywords and values, the characteristics of the saved image, and details of colormap allocation. -xrm supplies additional X window resource values. See an X manual for further details. -zoomloc specifies the starting location of the zoom insert. Possi- ble values are topleft, topright, bottomleft, and bottom- right. AUTHOR Peter G. Ford, MIT CSR DIAGNOSTICS VICAR label error in byte num a syntax error was found while parsing the VICAR image label. bad keyword value the value was not in a recognizable numeric format. bad -expand value: num the value must be greater than 0 and not greater than 16. bad -strip value: num the value must lie in the range 0-7. bad colormap entry: str the line should contain three integers, separated by whi- tespace. bad location: str allowed location designators are topleft, topright, bottom- left, and bottomright. can't allocate num colors out of num some of the requested colors could not be allocated; the nearest available colors will be used instead. can't allocate colors the display is unable to allocate any colors to the image. A&R xmgndisp.man 1.4 Last change: 1/8/92 5 XMGNDISP(1) Magellan A&R Command XMGNDISP(1) can't allocate desired colors the display is unable to allocate any colors to the image. The default colormap will be used, so pixel colors may appear really weird. can't create a num byte image there isn't sufficient memory to store the image array. can't open display: name the application can't find the designated display and/or screen. can't open main window the application can't open a window on the display. couldn't open 'name' font the named font could not be loaded. inconsistent -highvalue, -lowvalue values the values must be different. inconsistent LOW_DN, HI_DN values the values must be different. insufficient colormap entries the colormap file must contain at least 256 color triplet values. insufficient memory the application cannot allocate an image array buffer. keyword not in header: str a required VICAR2 header keyword wasn't found in the image label. missing -lowvalue or -highvalue value you must supply these parameters for images with FORMAT=REAL pixels. non-numeric keyword value the VICAR2 keyword should have a numeric value. non-string keyword value the VICAR2 keyword should have a non-numeric value, i.e. a string enclosed in quotes. program requires color display the display depth must be at least 8. unable to create XImage the application was unable to attach the image array to the display window. A&R xmgndisp.man 1.4 Last change: 1/8/92 6 XMGNDISP(1) Magellan A&R Command XMGNDISP(1) unexpected EOF an end-of-file was encountered when reading the image label or pixels. unsupported DIM value: num DIM must have the value 2. unsupported FORMAT value: str FORMAT must be 'BYTE', 'HALF', or 'REAL'. unsupported ORG value: str ORG must be 'BSQ'. EOF labels ignored the EOL header variable is non-zero, indicating that the VICAR file contains end-of-file labels, which will not be interpreted by xmgndisp. These labels should be absent from Magellan images. BUGS The program should use widgets to create a more user-friendly interface. Conversely, the world should decide on a common set of widget definitions. A&R xmgndisp.man 1.4 Last change: 1/8/92 7