xvu [ -display display ] [ -position sxsy ]
[ -iconic ] [ -icon_position sxsy ]
[ -maxwin n ] [ -imcolors n ]
[ -fg colorname ] [ -bg colorname ]
[ -workdir directory ] [ -font fontname ]
[ -script scriptfile ]
xvu is used to visualize data, primarily images, from TeraScan datasets. In xvu, a user interacts with both user interface panels and display windows. xvu has a main user interface panel, from which the user invokes its many popup panels via buttons and pulldown menus. Display windows are created by displaying images or plots, or by transforming other display windows. Other windows encountered by the user when running xvu are alert panels, shell windows, and non-shell text windows.
The xvu user interface is based on an enhanced version of the LXT Toolkit from the Lamont-Doherty Geological Observatory in New York. This toolkit supplies much of the functionality of SunView (a proprietary toolkit developed by Sun Microsystems, Inc.) under X Windows. Applications based on this toolkit are not as prevalent as applications based on OSF Motif or Sun Microsystems' OpenLook. However, LXT-based applications typically are MUCH smaller (with respect to code-size) than applications based on other toolkits.
The following primitive items are used in the xvu user interface:
Fillin Item Label ___________________________
Button Item (Label)
Pulldown Item Label [v]
Choice Item Label: Choice-1 ... Choice-N
Toggle Item Label:: Option-1 ... Option-N
Cycle Item Label @@ Choice-K
_ ____________________________
List Item |_| |_ Last Selected Entry ______|
| |
| | Entry-1
| | Entry-2
|_| :
|_| Entry-K
Output File n7.84191.2315
--------------^------------------
The caret can be positioned before any character or after the last character in a fillin item using the left mouse button. User-entered characters always appear before the caret. Text before the caret in the current fillin item can be erased using control-U.
The following composite items are used in the XVU user interface:
One File or Var Item (Label) ________________________ Many File or Var Item (Label) ________________________
Each of these items consists of a button item, followed by a fillin item with no label. The button label indicates whether one or more than one entry is allowed. Each var item is always associated with a file item, usually the item directly above it in the panel.
Given a panel P requiring a single input variable from a single input dataset, the user typically will
Press the button for the composite file item in P, bringing up the file list panel.
Make and confirm a file selection on the file list panel, causing the file list panel to go away, and updating the file item's fillin space.
Press the button for the composite variable item in P, bringing up the variable list panel, showing the variables contained in the selected file.
Make and confirm a variable selection on the variable list panel, causing the variable list panel to disappear, and updating the variable item's fillin space.
(FileList) (ImageSet) (PlotSet) (MiscSet) (ColorPal) (NewShell) (Help)
Current Pal @@ 1
____________________________________________________________________
| |
| Color Wedge |
|____________________________________________________________________|
Select[v] Plot[v] Overlay[v] Image[v] Window[v] Transform[v] Utils[v]
All functions in xvu are accessed from this main panel. It consists of a row of buttons across the top, a row of pulldown menus on the bottom, and a palette selector in between.
The buttons across the top have the following functions:
File List - popup panel for finding and selecting files Image Set - popup panel for setting image display parameters Plot Set - popup panel for setting plot parameters Misc Set - popup panel for setting cursor characteristics Color Pal - popup panel for finding and loading palettes New Shell - shell window relative to current directory
The pulldown menus across the bottom have the following options, each of which brings up a popup panel:
Select With Cursor - get data at points/area defined by cursor Dim Subset - extract subsets by clipping dimensions Point List - extract data at the same points/area Var Range - exclude data when out of range Merge Vars - laminate, concatenate, assemble, copy Locations - select points/areas defined with cursor Motion - select vectors while flickering images Plot From Image - histogram, profiles, contour, enhancement XY - simple XY plot of two variables Series - simple Y series plot of one variable Histogram - univariate and bivariate histograms Metafile - display previously created XY metafile Overlay Coast - coast, lakes, rivers, countries, states LL Grid - latitude/longitude grids Topog - topography and bathymetry contours Metafile - render a metafile created outside xvu Points - post and label points, plot tracks Contour - contours from random or gridded data Legend - multi-line legends for displayed images Vectors - draw and label vectors Image Display - display 2-D variables with masking Zoom - zoom or pan displayed images Enhance - change window pixel -> color gun mapping Filter - smoothing and edge-detection filters Values - roving through image data with cursor Animate - animate sequence of images with masking Navigate - edit earth location Window Combine - add, subtract, mask, dither, mosaic Flicker - animate a sequence of windows Save/Get - save to disk, retrieve, print, photo Annotate - text, geometry, fill, change color Embed - embed window in another window Orient - rotate, flip, mirror, transpose, invert Wedge - insert or attach color wedge Test - solid, wedge, uniform noise patterns Transform Elem Math - element -by- element math Nhood Math - neighborhood math Box Filter - statistical and convolution filters Register - register data to standard map projection Composite - composite using mean, min, max, first, last Utils Misc Reports - contents, audit, values, statistics Edit Var Def - edit units, min, max, bad value, scaling Edit Palette - edit color palette using cursor Export Ascii - export variables in ASCII format Export Binary- export variables in binary format Run Script - run an xvu script file
The palettes selector specifies the current palette for such operations as image display and animation. Up to four palettes can be loaded at a time; the set of image colors is shared across all loaded palettes. If N palettes are loaded, each palette is allocated (# image colors)/N colors. (See the section on IMAGE AND DRAW COLORS below.)
The main panel can be moved, iconized, and terminated via the window manager. The size of the main panel is fixed; it cannot be resized.
Popup panels are created via buttons or pulldown menus on the main panel, or by the buttons in composite file items. (See COMPOSITE UIF ITEMS above.) Several popup panels can be active at once.
Popup panels can be moved, iconized, and deleted via the window manager. Popup panels that are deleted by the window manager are simply unmapped. Each popup panel has a Quit button for safely unmapping the panel until it is needed later.
Note: If the window manager allows both delete and kill operations on windows, users must be careful not to use the kill operation, which is fatal to xvu.
The sizes of most popup panels are fixed. Only popup panels containing scrolling lists can be resized. Such panels cannot shrink below their original sizes.
As a convenience, iconizing any panel causes all other panels (including the main panel) to be unmapped. Opening an iconized panel remaps all panels that were unmapped with it.
The file list panel and variable list panel are blocking panels. When either of these panels is popped up, input to all other panels is blocked until a list selection is made and confirmed, or until the user cancels (quits) without making a selection. If input to a panel is blocked, the cursor appears in that panel as a stopwatch. Ordinarily the cursor appears as an arrow.
Alert panels appear when an error is encountered, or when confirmation is required to compete a given operation. For example, the following alert panel appears when trying to exit xvu:
+--------------------------------------+
| Clear workspace and exit program ? |
| |
| (Yes) (No) |
+--------------------------------------+
Error alerts typically contain Continue buttons. Confirmation alerts usually contain Yes/No or Continue/Cancel buttons. Alert panels are blocking to xvu; all xvu activity is stopped until the alert is resolved or acknowledged.
Alert panels are not managed by the window manager nor by xvu. They have no frames, so they cannot be moved or iconized.
Display windows are created by displaying images, generating plots, or by transforming existing display windows. Display windows are classified as either image, plot or other windows.
Image windows have one or more associated image variables. An image window has a mapping for converting window pixel coordinates to image variable dimension coordinates. Because there is only one such mapping per window, all associated images are assumed to be parallel. Each image window has an image area; outside this area, the mapping from window to image coordinates is undefined. Each image associated with a window has a scale minimum and maximum for converting from image color index to image variable value.
Plot windows have one or more associated (file, x var, y var, z var) tuples. Each such tuple represents a separate plot. A plot window has a mapping for converting from window pixel coordinates to plot (X,Y) coordinates. Because there is only one such mapping per window, all associated plots are assumed to have the same plot axes. Each plot window has a plot area; outside this area, the mapping from window to plot coordinates is undefined.
Other windows have no associated image or plot variables. They are created by test patterns or by mosaic operations. A mosaic window typically would need several mappings for converting from window pixel to data coordinates. This is not allowed for image or plot windows.
Each display window consists of the following components: a window manager frame, a current display window focus bar, and a picture.
+------------------------------------------------------+ | Window # - filename varname | +------------------------------------------------------+ | window (x, y) data (x, y, value) earth (lat, lon) | +------------------------------------------------------+ | | | Picture | | |
The window manager frame includes a 1-relative window number, and for image windows, the name of the first associated dataset and image variable.
The focus bar across the top of the picture is highlighted when the display window is the current display window. On/off colors for this focus bar can be initialized by FocusBorderColor, FocusTextColor, and NormalBorderColor resources. (See RESOURCE OPTIONS below.) A display window is made current by moving the cursor inside of it and pressing the left mouse button when no other xvu functions are running.
Corresponding window, data, and earth coordinates can be made to appear in the focus bar by placing the cursor in the display window and pressing the left mouse button when no other xvu functions are running. (Data and earth coordinates are only shown when relevant.) When an xvu function is running and requires the user to specify points or define figures in the current display window, coordinates in the focus bar change to reflect the position of the cursor in the current display window, regardless of whether any mouse buttons are pressed.
A display window's picture appears below its focus bar. There are really three copies of the picture: (1) what is seen on the screen, (2) a backing pixmap which is used to restore parts of the picture on the screen when they are hidden and then exposed, and (3) an XImage which serves as a second copy for erasing overlays or annotation.
When a display window is first created, what is seen on the screen, the backing pixmap, and the XImage are identical. With the exception of temporary geometry (e.g., uncommitted rubberband line or box), the pixmap is always kept consistent with what is seen on the screen.
+--------+ +--------+ restore +--------+ | | | | <------ | | | screen | <------ | pixmap | | XImage | | | refresh | | ------> | | +--------+ +--------+ checkpt +--------+
Many xvu functions require the user to select points or define figures within the current display window with the cursor. When running such a function, window, data, and earth coordinates are displayed in the focus bar, reflecting the position of the cursor in the current display window, regardless of whether any mouse buttons are down. If the user attempts to select points in a display window other than the current one, the following alert will appear:
+-----------------------------------+
| Not current input window |
| |
| (Continue) (Cancel) |
+-----------------------------------+
Also, when running a function requiring the user to select points or define figures within a display window, input to all user interface panels is blocked. The cursor within any user interface panel appears as a stopwatch.
The general convention for selecting points or defining figures in the current display window is as follows:
When selecting points, defining single lines or rectangles, or positioning text, define the starting point by positioning the cursor and then pressing the left mouse button. Drag lines and rectangles, or position text by moving the cursor while keeping the left mouse button down. This process can be repeated over and over until the user is satisfied.
When defining polylines or polygons, select the first vertex by positioning the cursor and then pressing the left mouse button. Drag the first segment to the second vertex by moving the cursor while keeping the left mouse button down. Define the second vertex by letting go of the left mouse button. Identify subsequent vertices by holding the left mouse button down, dragging the cursor to the desired point, and releasing the left mouse button.
Confirm the operation by pressing the middle mouse button with the cursor anywhere in the current display window.
Cancel the operation by pressing the right mouse button with the cursor anywhere in the current display window.
When not running any xvu functions, the following popup menu will appear when the cursor is in a display window and the right mouse button is pressed:
+----------+
| Describe |
| CheckPt |
| Restore |
| ShowMain |
| NewPal |
| ResetMap |
+----------+
The menu always applies to the display window from which it popped.
The Describe option creates a non-shell text window, containing a description of the window. The following is an example of such a description for a typical image window:
+----------------------------------+
| Describe Window 1 |
|_ ________________________________|
|_|_|____________________________|_|
|_| |
| | Window Type : Image |
| | Window NX/NY : 628 377 |
| | Num Palettes : 4 |
| | Background : AntiqueWhite |
| | X Dim Range : 1 - 628 |
| | Y Dim Range : 1 - 377 |
| | |
| | File Name : n7.84191.2315 |
| | Variable : avhrr_ch4 |
| | Min/Max : 10.5 49.16 |
| | Palette : 2 |
|_| |
|_|________________________________|
The CheckPt option copies the pixmap of the display window to its XImage. The Restore option has the opposite effect, copying the XImage of the display window to its pixmap, and then redraws the window.
The ShowMain option brings the xvu main panel to the front of the screen. This is useful when display windows are large, occupying most of the area on the screen.
The NewPal option changes the palette for the display window to the current one shown on the xvu main panel. This applies only when the display window is based on the same number of palettes as are currently loaded, and the window uses only one of those palettes.
The ResetMap option resets the enhancement mapping for all palettes associated with the display window. Again, this only applies when the display window is based on the same number of palettes as are currently loaded.
Shell windows are created by xvu via the New Shell button on the main panel, by requesting help, or by generating reports using the Misc Reports panel. All help and report output is piped into the UNIX more command running in a shell window. When more terminates, a <Done> message appears at the bottom of the shell window, and the window sleeps until it is taken down by the user.
Shell windows created by the New Shell button are created relative to the current working directory, as indicated by the Directory item in the File List panel. Such shell windows run the user's default UNIX shell (e.g., csh), and can be used for creating directories, removing files, running TeraScan standalone functions, etc.
All shell windows created via xvu are actually independent of xvu. They are managed by the window manager; they can be moved, resized, iconized, and terminated. They do not go away when xvu exits. The type of shell window used by xvu is controlled by the ShellTool resource (See below).
Non-shell text windows are created by the display window Describe menu choice, or via the Image Values panel. These windows have scroll bars that work like the scroll bars on panel list items.
Non-shell text windows are managed by the window manager; they can be moved, resized, iconized, and terminated. They are also managed by xvu; they go away when xvu exits.
Each non-shell text window is associated with a display window. Each display window can have at most one associated text window. Text windows are automatically destroyed to enforce this rule. When a display window is destroyed, any associated text window is destroyed as well.
The 256 possible colors in a typical 8-bit display environment are divided up logically as follows:
+------------+-----------+----------+----------+
| window mgr | xvu image | xvu draw | leftover |
| colors | colors | colors | colors |
+------------+-----------+----------+----------+
Window managers typically need up to ten or more colors for the screen background, window frames, popup menus, and so on. This leaves less than 256 colors available for xvu and other X windows applications. xvu is implemented to allow a variable number of image colors, between 32 and 240, and up to 16 draw colors. Image colors are used for displaying images and for shading certain plots; e.g., variable data values are mapped into the range of image colors. Draw colors are used for: (1) panel foreground and background colors, (2) image backgrounds, annotation and overlays, and (3) plot backgrounds, axes, label, and curves.
xvu allows the set of image colors to be shared by up to four palettes. For example, if there are 192 image colors, indexed starting at 0, then
# pals pal pal 1 pal 2 pal 3 pal 4
size range range range range
1 192 0-191
2 96 0- 95 96-191
3 64 0- 63 64-127 128-191
4 48 0- 47 48- 95 96-143 144-191
The obvious tradeoff is that if more palettes are being used, then fewer image colors are available for each palette. See palettes for palette file formats.
Palettes are loaded via the Color Palette panel. Each palette is subsampled or over-sampled to match the number of colors allotted to them. The color wedge on the main panel shows the currently loaded palettes.
The initial number and names of palettes can be set using the Image.Palette resource. The default palette directory can be initialized using the ColorDirectory resource. It typically is $TSCANROOT/refdata/palettes.
The palettes loaded into xvu may be remapped before loading them into the display hardware. This process is called image or palette enhancement, and is controlled via the Image Enhance panel.
for each palette
for min palette index <= i <= max palette index
if map[i] < min palette index
set enhanced red[i], green[i], blue[i] to
correspond to underflow color
else if map[i] > max palette index
set enhanced red[i], green[i], blue[i] to
correspond to overflow color
else
enhanced red [i] = palette red [map[i]]
enhanced green[i] = palette green[map[i]]
enhanced blue [i] = palette blue [map[i]]
This mapping is shared across display windows. There are two methods for independently enhancing display windows. The first is to use different palettes in different windows. The second is to use the Embed feature of the Image Enhance panel.
Many xvu functions are implemented by invoking standalone TeraScan functions. Often times, temporary datasets are created, used and discarded in this process. These temporary datasets are created in a work directory that can be defined either by the XVUWORKDIR environment variable, or the WorkDirectory resource. The WorkDirectory resource has precedence.
xvu uses an infinitely scalable Courier font for drawing text in display windows under Sun's Open Windows environment. Unfortunately, infinitely scalable fonts (and sometimes Courier fonts) are not available under most X11 distributions.
For systems other than Sun running Open Windows, a limited number of Courier fonts for use with xvu are supplied in the directory terascan/refdata/fonts. They can be compiled in the X server's native font format by changing directories to terascan/refdata/fonts and typing install. Then, to make sure the X server finds these fonts, the following line should be added to the user's .xinitrc file:
xset +fp $REFDATA/fonts/snf
Users may set the following options in their .Xdefaults file. Note that several options involve named colors. These colors are referred to collectively in xvu as draw colors (See above). There can be at most 16 draw colors. Draw colors must be known the X server, which typically looks up colors by name in the file /usr/lib/X11/rgb.txt.
Display used for user interface panels, plot and image windows. The default is 0:0. Display can be set on the command line using the -display option.
Initial position of the main user interface panel. The default is dependent on the window manager. Format is sxsy, where x denotes the pixel offset in the horizontal direction, y indicates the pixel offset in the vertical direction, and s indicates sign (either + or -). Positive x/y offsets are measured from the left/top of the screen. Negative x/y offsets are measured from the right/bottom of the screen.
Position can be set on the command line using the -position option.
Initial state of the application. If defined, the main user interface panel is iconified. Iconic can be set on the command line using the -iconic option.
Initial position of the icon for the main user interface panel. The default is dependent on the window manager. Icon_Position has the same format as Position. IconPosition can be set on the command line using the -icon_position option.
Shell window tool to use for displaying text reports and help. Must be in user's execution path. Default is cmdtool. Whatever shell window tool is chosen must have the following syntax:
shell-tool-string [ command args ... ]
ASCII file containing startup script for xvu. There is no default startup script. See run_script for script syntax.
Scratch file directory. Default is $XVUWORKDIR if defined, otherwise /tmp. WorkDirectory can be set on the command line using the -workdir option.
Directory containing palettes. Default is terascan/refdata/palettes.
Initial number of visible rows in scrolling file list. Default is 8. Acceptable range is [4,24].
Initial number of visible rows in scrolling variable list. Default is 8. Acceptable range is [4,24].
Initial number of visible rows in scrolling palette list. Default is 8. Acceptable range is [4,24].
Maximum number of windows. Default is 32. Acceptable range is [8,128]. MaxWindows can be set on the command line using the -maxwin option.
Maximum window width for images and plots. The default is the screen width. The upper limit is 4 times the screen width.
Maximum window height for images and plots. The default is the screen height. The upper limit is 4 times the screen height.
List of colors to use for image annotation and plot drawing. Default list is black, white, red, green, blue, cyan, violet, yellow, orange.
Color of focus bar for current display window. Default is white.
Color of focus bar for non-current display window. Default is black.
Color of focus bar text for current display window. Default is black.
Name of color to use for red lines in palette editor. Default is red.
Name of color to use for green lines in palette editor. Default is green.
Name of color to use for blue lines in palette editor. Default is blue.
Number of colors to use for image display. Default is 192. Acceptable range is [32,240]. Image.MaxColors can be set on the command line using the -imcolors option.
List of palettes to load initially. Palettes should be in ColorDirectory. There can be up to four palettes. Default is black-white.
Color for bad or missing data. Default is black.
Background color for image windows. Default is white. Image.Background can be set on the command line using the -bg option.
Default window width in pixels for images displayed with fixed window size. Default is max_window_width/2.
Default window height in pixels for images displayed with fixed window size. Default is max_window_height/2.
Strategy for selecting window size for image display. Options are variable and fixed. The default is variable.
Resampling strategy for displaying images. Options are integer and real. The default is real. If integer, either the number of image pixels per window pixel is an integer, or the number of window pixels per image pixel is an integer.
Positioning strategy for images displayed in fixed size windows. Options are center and upperleft. The default is center.
Background color for plot windows. Default is white. Plot.Background can be set on the command line using the -bg option.
Color for plot axes and labels. Default is black. Plot.Foreground can be set on the command line using the -fg option.
Default plot window width in pixels. Default is max_window_width/2.
Default plot window height in pixels. Default is max_window_height/2.
Initial style of plot axes. Valid styles are grid, box, upperleft, and lowerleft. The default is lowerleft.
User interface panel text and highlight color. Default is black. Panel.Foreground can be set on the command line using the -fg option.
User interface panel background color. Default is white. Panel.Background can be set on the command line using the -bg option.
User interface panel text font. Default is 6x13. Recommend only fixed width fonts. Font can be set on the command line using the -font option.
Primary cursor color. Default is black. Cursor.Foreground can be set on the command line using the -fg option.
Cursor outline color. Default is white. Cursor.Background can be set on the command line using the -bg option.
Initial cursor shape. Valid shapes are arrow and crosshair. The default shape is crosshair.
Initial cursor style. Valid styles are plain, bold, or outline. The default style is outline.
Initial crosshair cursor size. Valid sizes are 32, 64, 96, 128. The default size is 32.
Delays in seconds after the first, middle, and last windows or images in an animation loop. Valid delays are 0.1, 0.2, 0.5, 1.0, 1.5, 2.0, 2.5, and 5.0 seconds. All three delays must be specified.
Names of the Outline toggle item in the Overlay Coast panel, not counting the last Specify choice. The default is Oceans/Lakes, Rivers, Political, States. There must be the same number of CoastNames as CoastFiles. There can be at most 5 names, with at most 31 characters per name. See overlay_coast.
Names of the files corresponding to CoastNames. The default is wdb2.cil, wdb2.riv, wdb2.bdy, wdb2.states. There must be the same number of CoastFiles as CoastNames. There can be at most 5 files, with at most 31 characters per name. See overlay_coast.
The print command, including options, to use when printing windows. The default is lpr. Windows are saved as temporary files in SunRaster format and then printed. See window_save.
$TSCANROOT/refdata/palettes, /usr/X11/lib/rgb.txt, ~/.Xdefaults
palettes, file_list, var_list, run_script
xvu can only be run under X windows versions starting with 11.4.
Last Update: $Date: 1998/05/29 21:00:40 $