.TH XMGNDISP 1 "1/17/92" "A&R xmgndisp.man 1.5" "Magellan A&R Command" .\"--------------------------------------------------------------------------- .\" Function: Display MIDR or GxDR image in X window .\" System: Magellan Altimetry Data Reduction .\" Phase: UTL .\" Module: xmgndisp.man .\" Revision: 1.5 .\" Date: 1/17/92 .\" Author: pgf@space.mit.edu .\" Created: Fri Dec 13 12:46:30 EST 1991 .\" Control: SCCS .\"--------------------------------------------------------------------------- .SH NAME xmgndisp \- Display MIDR or GxDR image in X window .\"--------------------------------------------------------------------------- .SH SYNOPSIS .na .TP \w'\fBxmgndisp\fPM'u .B xmgndisp .RB [ \-browse ] .RB [ \-borderwidth\ \c .IR ] .RB [ \-colormap\ \c .IR ] .RB [ \-Cmapdir\ \c .IR ] .RB [ \-display\ \c .IR ] .RB [ \-expand\ \c .IR ] .RB [ \-fn\ \c .IR ] .RB [ \-font\ \c .IR ] .RB [ \-geometry\ \c .IR ] .RB [ \-help ] .RB [ \-highvalue\ \c .IR ] .RB [ \-insertloc\ \c .IR ] .RB [ \-lowvalue\ \c .IR ] .RB [ \-match ] .RB [ \-nzoom\ \c .IR ] .RB [ \-palette\ \c .IR ] .RB [ \-shift\ \c .IR ] .RB [ \-swap ] .RB [ \-verbose ] .RB [ \-xrm\ \c .IR ] .RB [ \-zoomloc\ \c .IR ] .RI [ vicar-file ] .\"--------------------------------------------------------------------------- .SH DESCRIPTION .I Xmgndisp is a simple program that displays VICAR2 images using version 11 of the X window system, release 3 and later. It uses no .I widgets of any kind\(emonly standard .I 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. .LP All parameters required to display the image must be entered on the .I 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 .B \-colormap option between the values specified by the .B \-lowvalue and .B \-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. .LP Once the image is displayed in a window, the following operations may be performed on it: .\"-------------------------------------- .TP 4n .I Re-sizing the displayed image by dragging the window frame with the pointer device. The precise 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. .\"-------------------------------------- .TP 4n .I Displaying a zoomed insert by clicking button #1 while pointing to an image pixel. Two inserts will appear in the corners of the image\(emthe .I value insert that displays the pixel coordinates and data value, and the .I 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 .B \-expand option, the insert will magnify the .I original image pixels. .\"-------------------------------------- .TP 4n .I 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 .I smaller than the input image, this may .I not cause the cursor to move. .\"-------------------------------------- .TP 4n .I Changing the insert magnification .br hit the .B "<" .\" and .B ">" .\" keys to, respectively, shrink and expand the magnified image. The current magnification factor is shown within the insert. .\"-------------------------------------- .TP 4n .I Hiding the inserts hit the .B return key. The inserts will disappear until button #1 is pressed again. .\"-------------------------------------- .TP 4n .I Changing the insert locations hit either the .B v or the .B z key to rotate, respectively, the value insert or the zoom insert from one corner of the display to another. .\"-------------------------------------- .TP 4n .I Quitting the application hit either the .B q or the .B Q key. .\"--------------------------------------------------------------------------- .SH OPTIONS AND RESOURCES The following parameters can be supplied from several sources. In increasing order of precedence, these are .LP .RS \(bu the application resource file .I "/usr/lib/X11/app-defaults/Xmgndisp", .br \(bu the user's .I "~/.Xdefaults" .\" file, .br \(bu the user's .I "~/.Xdefaults-$HOST" .\" file, .br \(bu .I xmgndisp command-line arguments. .RE .LP Within resource files, these parameters should be specified as follows: .LP .RS .RI xmgndisp. resource: .I value .RE .LP where .I resource is identical to the command-line specification, after removing the leading .B "-" .\" sign. The possible resource names are as follows: .\"-------------------------------------- .TP 8n .B \-browse the input file is a Magellan MIDR browse image and its header variables are incorrect\(emSPECLINE and PROJSAMP must be divided by 8 and PIXSIZ must be multiplied by 8. This action will also be taken automatically whenever .I xmgndisp reads a file named "browse.img" whose PIXSIZ header variable has the value 75, or 225, or 675, or 2025. .\"-------------------------------------- .TP 8n .BI \-borderwidth\ specifies the width of all window borders, in pixels. .\"-------------------------------------- .TP 8n .BI \-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 .B \-palette option, described below. If both .B \-colormap and .B \-palette are specified, .B \-palette takes precedence. .\"-------------------------------------- .TP 8n .BI \-Cmapdir\ specifies the directory within which to search for the .B \-colormap file, if it isn't found in the current working directory. .\"-------------------------------------- .TP 8n .BI \-display\ specifies the host and display number on which to create the image window. This option cannot be specified in a resource file\(emonly in the .I xmgndisp command line. .\"-------------------------------------- .TP 8n .BI \-expand\ expands (or shrinks) the image by a .I 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. .\"-------------------------------------- .TP 8n .BI \-fn\ .br .ns .TP 8n .BI \-font\ specifies the font name or class to be used to display the coordinates in the .I value insert. For best results, the font should be of fixed width. .\"-------------------------------------- .TP 8n .BI \-geometry\ specifies the size and position of the new image window on the X display. .\"-------------------------------------- .TP 8n .B \-help writes a list of .I xmgndisp command-line options to the standard error stream, .IR stderr , and then quits. .\"-------------------------------------- .TP 8n .BI \-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, .I value must be specified in the same units as LOW_REP and HI_REP. .\"-------------------------------------- .TP 8n .BI \-insertloc\ specifies the starting location of the .I value insert. Possible values are .IR topleft , .IR topright , .IR bottomleft , and .IR bottomright . .\"-------------------------------------- .TP 8n .BI \-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, .I value must be specified in the same units as LOW_REP and HI_REP. .\"-------------------------------------- .TP 8n .B \-match instructs .I 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 .I this also fails, .I 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 .I xmgndisp quits with a rude message. The number of colors to be allocated can also be controlled with the .B \-shift option, below. .\"-------------------------------------- .TP 8n .BI \-nzoom\ specifies the default magnification of the .I zoomed insert. .\"-------------------------------------- .TP 8n .BI \-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 intensities with which to display that pixel value. An alternative format of palette may be specified by means of the .B \-colormap option, described above. If both .B \-colormap and .B \-palette are specified, .B \-palette takes precedence. .\"-------------------------------------- .TP 8n .BI \-shift\ attempts to allocate colors to pixels in groups of .IR n . For details, see the discussion of the .B \-match option, above. .\"-------------------------------------- .TP 8n .BI \-swap overrides the manner in which .I 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 .B \-swap will reverse this logic, i.e. if INTFMT=LOW, .I xmgndisp will assume that the high-order byte is first, and otherwise that it is second. The situation is similar for FORMAT=REAL: Unless REALFMT=VAX is specified in the header, .I xmgndisp will assume that the pixels are IEEE-754 floating-point numbers written with the sign-bit first. Specifying .B \-swap will force .I xmgndisp to make the opposite assumption, i.e. that the pixels are VAX floats. .\"-------------------------------------- .TP 8n .B \-verbose lists the values of important VICAR2 header keywords and values, the characteristics of the saved image, and details of colormap allocation. .\"-------------------------------------- .TP 8n .BI \-xrm\ supplies additional X window resource values. See an X manual for further details. .\"-------------------------------------- .TP 8n .BI \-zoomloc\ specifies the starting location of the .I zoom insert. Possible values are .IR topleft , .IR topright , .IR bottomleft , and .IR bottomright . .\"--------------------------------------------------------------------------- .SH AUTHOR Peter G. Ford, MIT CSR .\"--------------------------------------------------------------------------- .SH DIAGNOSTICS .TP 8n .B VICAR label error in byte \fInum\fP .br a syntax error was found while parsing the VICAR image label. .\"----------------------------------------- .TP 8n .B bad \fIkeyword\fP value .br the value was not in a recognizable numeric format. .\"----------------------------------------- .TP 8n .B bad -expand value: \fInum\fP .br the value must be greater than 0 and not greater than 16. .\"----------------------------------------- .TP 8n .B bad -strip value: \fInum\fP .br the value must lie in the range 0\-7. .\"----------------------------------------- .TP 8n .B bad colormap entry: \fIstr\fP .br the line should contain three integers, separated by whitespace. .\"----------------------------------------- .TP 8n .B bad location: \fIstr\fP .br allowed location designators are .IR topleft , .IR topright , .IR bottomleft , and .IR bottomright . .\"----------------------------------------- .TP 8n .B can't allocate \fInum\fP colors out of \fInum\fP .br some of the requested colors could not be allocated; the nearest available colors will be used instead. .\"----------------------------------------- .TP 8n .B can't allocate colors .br the display is unable to allocate .I any colors to the image. .\"----------------------------------------- .TP 8n .B can't allocate desired colors .br the display is unable to allocate .I any colors to the image. The default colormap will be used, so pixel colors may appear .I really weird. .\"----------------------------------------- .TP 8n .B can't create a \fInum\fP byte image .br there isn't sufficient memory to store the image array. .\"----------------------------------------- .TP 8n .B can't open display: \fIname\fP .br the application can't find the designated display and/or screen. .\"----------------------------------------- .TP 8n .B can't open main window .br the application can't open a window on the display. .\"----------------------------------------- .TP 8n .B couldn't open \fI'name'\fP font .br the named font could not be loaded. .\"----------------------------------------- .TP 8n .B inconsistent \-highvalue, -lowvalue values .br the values must be different. .\"----------------------------------------- .TP 8n .B inconsistent LOW_DN, HI_DN values .br the values must be different. .\"----------------------------------------- .TP 8n .B insufficient colormap entries .br the colormap file must contain at least 256 color triplet values. .\"----------------------------------------- .TP 8n .B insufficient memory .br the application cannot allocate an image array buffer. .\"----------------------------------------- .TP 8n .B keyword not in header: \fIstr\fP .br a required VICAR2 header keyword wasn't found in the image label. .\"----------------------------------------- .TP 8n .B missing -lowvalue or -highvalue value .br you must supply these parameters for images with FORMAT=REAL pixels. .\"----------------------------------------- .TP 8n .B non-numeric \fIkeyword\fP value .br the VICAR2 keyword should have a numeric value. .\"----------------------------------------- .TP 8n .B non-string \fIkeyword\fP value .br the VICAR2 keyword should have a non-numeric value, i.e. a string enclosed in quotes. .\"----------------------------------------- .TP 8n .B program requires color display .br the display depth must be at least 8. .\"----------------------------------------- .TP 8n .B unable to create XImage .br the application was unable to attach the image array to the display window. .\"----------------------------------------- .TP 8n .B unexpected EOF .br an end-of-file was encountered when reading the image label or pixels. .\"----------------------------------------- .TP 8n .B unsupported DIM value: \fInum\fP .br DIM must have the value 2. .\"----------------------------------------- .TP 8n .B unsupported FORMAT value: \fIstr\fP .br FORMAT must be 'BYTE', 'HALF', or 'REAL'. .\"----------------------------------------- .TP 8n .B unsupported ORG value: \fIstr\fP .br ORG must be 'BSQ'. .\"----------------------------------------- .TP 8n .B EOF labels ignored .br the EOL header variable is non-zero, indicating that the VICAR file contains end-of-file labels, which will not be interpreted by .IR xmgndisp . These labels should be absent from Magellan images. .\"--------------------------------------------------------------------------- .SH BUGS .LP The program should use .I widgets to create a more user-friendly interface. Conversely, the world should decide on a common set of widget definitions. .br .\"---------------------------------------------------------------------------