xrastool(n) manual page

HTML automatically generated with rman
Table of Contents

Name

xrastool - animate rasterfiles in an XView window

Synopsis

xrastool [generic_options] [other_options] [filename...]

xrastool is an animation package written in XView. Currently only the 8-bit Sun Rasterfile (RLE or standard) image format is supported, but many other formats can be converted to 8-bit rasterfiles using the PBMplus image utilities or xv. xrastool provides the user with an XView panel interface for convenient access to animation, display, and colormap functions. There are a number of options to help maximize the display rate. On an unloaded Sparc IPX running twm under X11R5, a display rate of 50 frames/sec can be achieved with 400x400 8-bit images. These speeds are obtained by first loading the rasterfiles into client-resident Ximages then transferring them to server-resident pixmaps. Consequently, the maximum number of frames displayable (and hence the duration of the animation) is limited only by the core memory available to the server.

Layout

xrastool consists of two panels, a canvas frame for displaying images, and a pop-up info window. When invoked without any options or filenames specified, xrastool displays the Main Panel in its default state. If any images were specified and at least one was loaded successfully, the first will be displayed in the Canvas frame, also in the default state. The cursor is moved automatically to point to the More... button (see below) on the Main Panel for convenience. This also ensures that the colormap is displayed correctly for the first image by forcing the window manager to load xrastool’s colormap segment. The Sub Panel and Info window can be called up from the Main Panel. The following two sections describe the control panels in detail.

Section 1: The Main Panel

The Main Panel contains all the controls needed to prepare and run an animation. Features include image loading facilities, sizing controls, timer controls, and cycling buttons. All the controls are described in detail in what follows. Note that any equivalent command-line options are given in parentheses beside the control name (see Section 4).

Image # (-start): The current image number is shown here and may be modified, either using the text field or the incremental buttons. Only numbers in the range 1 to N, where N is the number of images loaded, are accepted as input, although the value N + 1 may be displayed prior to loading a new image (see New button).
New: Click on this button to clear the image filename field and set the image number to N + 1 in preparation for a new image. Any displayed image will be replaced with the current background.
Load: Clicking this button will cause xrastool to load the image shown in the Image field. The image will be assigned the image number shown in the Image # field, so Load can be used to replace existing images if desired. Note that if there is insufficient server memory to store the image, the functions XCreateImage() or XCreatePixmap() function may abort with an error.
Logical Functions: The buttons at the top right of the main panel are used to change the logical function of the main Graphics Context (GC). The logical function is applied to the next and all subsequent images to be displayed on the Canvas. Use Refresh to apply the function to the current image. Choices are:
+ (-logical SRC): This applies the GXcopy function to the images so that any existing image (destination) is entirely replaced with each new image (source). This is the default behavior.
| (-logical OR): This applies GXor between the source and destination images, effectively merging them together (color behavior may be surprising).
& (-logical AND): Applies GXand between the source and destination.
x (-logical XOR): Applies GXxor. Two invocations of GXxor on the same image returns the original image.
e (-logical ERA): Applies GXandInverted.
- (-logical NEG): Applies GXcopyInverted, giving the negative of the image.

Image: The filename of the current image is displayed in the text field. Typing a new filename and pressing RETURN or clicking on Load instructs xrastool to replace the current image with the contents of the specified rasterfile. A new image can be appended to the existing set by first clicking on New, then supplying the new filename.
W (-w (width)): This is the image width field. Changing this number either using the text field or the incremental buttons causes the current Sizing option to change to Fixed. Any existing image will have its frame adjusted to accommodate the new size.
H (-h (height)): The height of the Canvas frame can be adjusted with this control, in the same way as the width (W).
Sizing: There are three sizing options that can be used for displaying images.
Auto (-auto): With this option, images are displayed up to a specified maximum size, by default 640x480. The maximum size can be changed by first setting W and H, then clicking on Auto. The display frame will shrink to accommodate images with dimensions smaller than the maximum dimensions. For larger images, the scrollbars can be used to view hidden portions of the image.
Full (-full): With this option, the entire image is displayed as long as it can be accommodated on the default screen. The W and H fields show the displayed image dimensions.
Fixed (-fixed): This option fixes the image size to the current values displayed in the W and H fields. Fixed canvases are the fastest to draw, so this is the preferred option when maximizing display rates. Hidden portions of images can still be viewed with the scrollbars. Images that are smaller than the fixed size are padded with the current background (see the Backdrops item in the Sub Panel) and may be centered in the frame by choosing Centering from the Sub Panel.

Set: This button is used to set the W and H fields to the currently displayed size. This means the frame size can be adjusted by first using the mouse (e.g. dragging the resize corners if the window manager is olwm) and then clicking on Set. This button also causes Fixed to be selected automatically.
Timer Scale: The MINIMUM delay between displaying one frame and the next during animation is set by the Timer Scale and Timer Slider. The former is a coarse adjustment and the latter a fine adjustment. It is possible to select delay ranges between 1 microsecond and 999 seconds (about 15 min), though 20 milliseconds (i.e. 50 frames/sec) is about the best achievable on a Sparc IPX. The practical lower limit is set by hardware CPU and I/O rating. Note that at the fastest speeds, the xrastool controls may become very sluggish -- be patient! Ideally, all display options should be set PRIOR to animating at top speed.
us (-timerscale us): This control selects the microseconds timer scale.
ms (-timerscale ms): Use this for the milliseconds timer scale, which is the practical range for animations.
sec (-timerscale sec): The seconds scale can be used for slideshows.

Timer Slider (-timervalue (timer)): This slider is used for fine adjustments of the delay timer for animations. The range is 1 to 999 in the units selected on the Timer Scale. The value can be set using the text field or by dragging the slider control. Unit increments or decrements can be performed by clicking either side of the control.
Fast (-fast): Fast mode can be selected by pressing this button. This sets Fixed sizing, us timer scale, unit timer value, and many of the options on the Sub Panel. In this mode, xrastool will display frames at the fastest possible rate. Any default fast setting can be overridden by adjusting the appropriate control in the usual way.
Direction (-fwd -rev): Cycling direction can be toggled between forward (FWD) and reverse (REV) using this control. Blink mode and the Loop Back and One Way cycling options will take over direction control when invoked.
Step: Clicking on this button will display either the next or previous image depending on the current Direction. The step function is called internally when animating.
Blink (+|-blink): This button toggles blinking on and off. The current image and the next or previous image are blinked at the current display rate.
Cycle (+|-cycle): This button displays the stored images in sequence, subject to the current Direction, Cycling Option, and display rate. The animation can be stopped by clicking on Cycle again.
Cycling Option: There are three choices of cycling option:
Loop (-loop): This is the default. When the end of the current sequence of images is reached, cycling continues from the beginning ad infinitum.
Loop Back (-loopback): When the end of the current sequence of images is reached, the current Direction is reversed and cycling continues.
One Way (-oneway): When the end of the current sequence of images is reached, cycling is terminated. Clicking on Cycle again will repeat the sequence, starting with the first or last image depending on the current Direction.

Refresh: Clicking here redisplays the current image. This can be used on an image to apply a Logical Function to itself. It is also useful if the window manager has corrupted the image display for whatever reason.
More... (+|-subpanel): This pops up the Sub Panel.
Info...: Use this button for info relating to the author and copyright.
Quit: Clicking here terminates the xrastool session.

Section 2: The Sub Panel

When selected using More... on the Main Panel or by including the -subpanel option on the command line, the Sub Panel is displayed. The user can perform various fine-tuning operations, including colormap manipulation, using the Sub Panel.

No Scrolling (+|-scrolling): Selecting this removes the scrollbars from the image. Deselecting replaces them.
No Resizing (+|-sizing): This option overrides all sizing requests. The frame size can still be adjusted manually using the mouse, but a new size cannot be Set until No Resizing is deselected.
No Moving (+|-moving): When an image is to be displayed, xrastool attempts to reposition the frame so that no part of the image will be off-screen. Selecting No Moving disables this behavior.
No Scaling (+|-scaling): Selecting this option disables all color Scaling effects.
No Updates (+|-updates): Normally when cycling, the Image # and Image fields, as well the size fields and Main Panel footer, are updated between images. Selecting No Updates disables this behavior when cycling. Updates when using Step manually cannot be suppressed.
No Backdrops (+|-backdrops): By default when cycling, images smaller than a Fixed frame will have undefined regions painted with the current backdrop. No Backdrops disables this feature when cycling.
Lock Colors (+|-lockcolors): Selecting this locks the current image colormap so that all subsequently displayed images use the locked colormap rather than their own. This feature results in interesting effects between images with very different colormaps, but significantly improves the display rate for images with identical or nearly identical colormaps. If the command line option -onecmap is used, the Lock Colors control is made redundant.
Centering (+|-centering): When selected, and if the Sizing is Fixed, the current image and all subsequently displayed images will be centered in the display frame, assuming the frame is larger than the image. Any gaps will be filled with the current backdrop.
Live Cursor (+|-livecursor): With a live cursor, the mouse can be used to examine the current color Scaling of an image. Simply moving the mouse across the image will display the cursor coordinates with respect to the top left corner of the image, the value of the pixel at that location, the original color RGB triad to which the pixel value corresponded (after compression -- see below), and the current color at that location. For example:
(122,36) = 53 (96,96,96) --> (255,0,0)

shows that the pixel at x = 122, y = 36 on the image has a value of 53,: which originally corresponded to the gray-scale value (96,96,96) but has since been mapped into the color red (255,0,0). The coordinates and mapping information are displayed in the footer of the Canvas frame.
Backdrops (-backdrop (index)): Various bitmap backdrops can be selected for filling gaps left when an image is smaller than its frame. The patterns available are displayed on the choice buttons (blank means white).
Scaling: There are six color scaling options available with xrastool. The RGB color sliders below the options allow fine tuning of the scaling. If the code was compiled with LIVE_SLIDERS, changing one color slider may instantaneously affect the other sliders, depending on the option. Otherwise the other sliders will be updated after the slider control of the first is released. The x and / buttons to the right of each slider are only used with the Color option. Each scaling option has a default slider setting built in which is used when the option is first selected.
BW (-bw): The slider controls a fractional cutoff: colormap entries with a total intensity less than (slider/100) * 255 are mapped to black while the remainder are mapped to white. The default setting is 50. Any slider can be used to change the setting.
Gray (-gray): The sliders control the fractional contributions of each color in the image to a gray scale map R_new = (R/100) * R_old + (G/100) * G_old + (B/100) * B_old, B_new = G_new = R_new. The sum of the slider values R + G + B is fixed at 100 unless any two sliders have a zero setting. The default setting is R = 30, G = 59, B = 11 which is the map used by ppmtopgm in the PBMplus package.
Color (-color): This is the default scaling option. With this option, the sliders move independently, controlling the fractional intensity of their respective colors in the image. Selecting x or / for each slider determines whether the color contribution is diminished (former) or enhanced (latter).
Cutoff (-cutoff): With this option, the sliders control the pixel value above which no colors are displayed. Hence the first color in the colormap can be displayed by setting a slider to 1. All colors are displayed for a setting of 100 (the default). In a future release, the colormap will be sorted in order of usage, so that the most or least "important" colors can be screened out using the Cutoff option.
Contour (-contour): This option maps the image colors by intensity into 10 repeating colors, with the total number of contours controlled by the sliders (from 1 to 100, default 25). The contour colors have been selected in order of intensity so that the brightest colors in the image get the brightest contours.
Random (-random): This option simply maps the image colors into random values. The values can be changed with the sliders.

Section 3: Keyboard Accelerators

Limited keyboard support is provided on the Canvas window. Pressing the spacebar while the cursor is on the Canvas is equivalent to pushing the Step button. Pressing RETURN performs a Set operation. Press ’c’ to toggle cycling, and ’q’ to quit the program.

Section 4: Command Line Options

Most of the panel controls have command-line equivalents so that an xrastool session can be started with various options already set. The usage is:

xrastool: [-fast] [+|-onecmap] [+|-subpanel] [-start (index)] [-private|-hist|-pair] [-logical (function)] [-w (width)] [-h (height)] [-auto|-full|-fixed] [-timerscale us|ms|sec] [-timervalue (timer)] [-fwd|-rev] [-blink|-cycle] [-loop|-loopback|-oneway] [+|-scrolling] [+|-resizing] [+|-moving] [+|-scaling] [+|-updates] [+|-backdrops] [+|-lockcolors] [+|-centering] [+|-livecursor] [-backdrop (index)] [-bw|-gray|-color|-cutoff|-contour|-random] [-red (value)] [-green (value)] [-blue (value)] [filename...].
Most of these options have been described in the previous sections. Note that the "+" prefix is used to override defaults or previous values. For example, -fast invokes many of the Sub Panel options; if it was desired to retain scrollbars, then +scrolling should be placed after -fast on the command line. Options appearing last take precedence over those appearing first. The options that have not yet been described are:
-onecmap: Instructs xrastool to store only the first image’s colormap and automatically Lock Colors to it. This speeds up the image loading considerably as it bypasses any colormap compression (see below). Of course, the colormaps of all the images loaded should be similar, or, ideally, the same. The -fast option automatically invokes -onecmap.
-start (index): Instructs xrastool to display image (index) first. If image (index) does not exist, the first image will be displayed.
-private: Instructs xrastool to use a private colormap for each image so that no attempt at colormap compression is made. Window colors, including those of the xrastool control panels, may be severely affected when viewing these images.
-hist: Constructs a histogram of color usage for each image (or just the first in the case of -onecmap), and eliminates those colors that are least used until the image colormap can be melded with the existing USED portion of the default display colormap. Currently xrastool reserves 30 colors for this purpose, so at most 226 colors from any image can be displayed. If more colors are added to the window session after xrastool has started up, they may be "switched out" when viewing the images. (NOTE: under twm, the panels and canvas "black out" when they no longer have the keyboard focus; under olwm, all colors can be seen at all times).
-pair: Determines which colors are most alike in pair-wise fashion for each image until 30 colors are eliminated. This method is much slower than -hist, but it has the advantage that it does not rely on the same colors being used in EACH image for a multi-image animation (under -hist it is possible that a color in one image may not be used in a second -- even though they have the same colormaps -- and hence be eliminated from the latter and not the former, resulting in noticeable flickering when animating). The -pair option is recommended when using -onecmap.
-red (value) -green (value) -blue (value): These options allow the user to override the initial default color Scaling settings. For Gray scale, the images may be "burned out": it is up to the user to ensure R + G + B = 100 if desired. Changing the color sliders, however, will restore the constraint. For Color, the + and - choices can be selected by supplying positive or negative color values, respectively.

Hints

For best results, never exceed the core memory of the server when loading images. Swapping will make the animator painfully slow. Even with more careful use of memory, xrastool may need to perform one or even two cycles through the images before the animation becomes smooth. Once everything is up to speed, the animator controls should respond better as well. Also, to load animations that consist of a large number of files, it is best to use the Unix wildcard facility (e.g. xrastool -fast movie*.ras), so be sure that the image sequence is the same chronologically as alphabetically.

History

xrastool replaces its Sunview predecessor rastool, which was never officially released. These tools were designed to aid in visualization of gravitational N-body problems carried out at the Institute of Astronomy, Cambridge in partial fulfillment of the author’s Ph.D. thesis.

Name
Synopsis
Description
Layout
Section 1: The Main Panel
Section 2: The Sub Panel
Section 3: Keyboard Accelerators
Section 4: Command Line Options
Hints
History
Copyright
Author
Bugs