RAZ(1)

NAME
raz - disk based raster viewer

SYNOPSIS
raz < script
cmdraz [ options ] files | raz

DESCRIPTION
Raz loads image files to either raw disk or memory, and then plays them back to the screen. At the AHPCRC several striped disk partitions are kept open, with no file system on them, for 2D and 3D raster streaming. We call these drives "raw disks". Using fast drives we have been able to stream at 13 MB/sec from disk to screen. A couple of gigabytes on each system are kept open so that long movies can be viewed and manipulated.

Raz can use a simple file as it's "raw disk" if high performance isn't an issue.

The image file format for raz is very simple. Mapped color images use one byte per pixel. Full color images use three bytes per pixel, in either interleaved (rgbrgbrgb...) order or as planes (rrr...ggg...bbb...). The image rows are ordered top to bottom. There is no image header.

When loaded to raw disk, raz stores images in the most natural format for the given graphics hardware. All images are padded to a multiple of four wide and rows are ordered bottom to top. Full color images are stored in BGR order. The image data is padded to the next block size, to support devices that only seek to block boundaries.

On machines without full support for the pixmode() call, such as Indigo and the Personal Iris, full color images are stored in ABGR order, and mapped color images are stored two bytes per pixel. A constant value of 1024 is also added to each pixel of mapped color images if there are more than eight color planes.

In practice, once loaded to raw disk, image sequences can be saved and reloaded from tape. Careful users can also directly transfer prepared images to raw disk, using the dd command.

The program raz is only half of a user-friendly image display program. raz has no useful command line options, but instead takes commands from standard input.

The other half, xraz, feeds commands to raz, giving the user a nice push button interface. Without xraz the way to use raz is to feed it ascii commands directly, or from a file.

In practice there are two ways to use raz directly:

    raz < script
    cmdraz [ options ] [ files ] | raz

The first reads in a complete script, in which the last command should probably be play. raz will run until quit from the window menu or interrupted.

The second drives raz from a command line. cmdraz is a shell script that composes raz commands from a command line. Type

    cmdraz -h

to learn how to use cmdraz.

OPTION
The -a option makes raz acknowledge each input line with a null byte on output. If there is a reply the null byte is appended to the reply. This option is used by xraz to synchronize with raz.

RAZ COMMANDS

To save on typing, only the first three characters of any keyword need to be typed. Blank lines and lines that begin with # are ignored. Each line should have one command. Commands may not span lines, and there cannot not be multiple commands on a line. The filename and colors commands read additional lines of input.

play [begin_frame [end_frame]]
    Play, stepping in the set direction. If the direction is +1, the default, then:

    play 1 100    play from frame one to frame 100
    play beg end    play from beginning to end

    If an ending frame is given raz will ignore commands until the end frame is reached.

stop
    Stops playing.

goto frame#
    Jumps to a frame. goto beg jumps to the first frame.

load
    Loads files specified by set filename into memory or raw disk. A load is automatically performed by play or goto if needed.

zoom on | off
    Controls presence of zoom window. The zoom window shows a blowup of the region around the cursor.
    zoom on    exposes the zoom window.
    zoom off    hides the zoom window.

cmap on | off
    Controls whether color map is loaded. This should only mater for 8 bit machines. For full color machines the colormap is loaded above the standard X colors, so they do not conflict.

ping
    Responds pong. Not useful for interactive use.

quit
    Exits raz with grace.

mark
    Prints the frames per second and I/O throughput since the last mark command.

sleep #tick
    Sleep #tick hundredths of a second.

print
    Print the current set variables on standard output.

print frame
    Print the current frame number.

print numframe
    Print the total number of frames.

print colors
    Print the color table.

print filename
    Print file names.

set [variable] [arguments]
    Sets the state of raz. Specifically:

set speed #fps
    Set the play frame rate to be no faster than #fps frames per second. The maximum frame rate is 60 fps, and the minimum is 1 fps.

set direction #dir
    Set the frame step direction to #dir. A value of 1 goes forward, -1 reverses.

set rawdiskname diskname
    Name of raw disk partition.
    set rawdiskname /dev/anim0    Default partition.

set double on | off
    Turns double buffering of the main image on or off.
    set double on    Default setting.

set bounce on | off
    Normally when playing the movie cycles to image #0 when the end of the frames are reached (and visa versa).
    set bounce on    Reverse play direction at end.
    set bounce off    Default.  Cycle movie.

set playmode raw | memory
    Where to store images when loading, and where to fetch images when playing.
    set playmode raw    Default.  Use raw disk partition
    set playmode memory    Stuff images into memory

set source file | raw
    Where to read images from when loading. If the source is raw and the playmode is raw, then the load step does not require transferring any images. This is the proper setting when images have been pre-loaded to disk.
    set source file    Default.  Load files from file list
    set source raw    Images already on raw disk

set offset #bytes
    When playing or storing images on raw partition, start at #bytes into partition. #bytes can be specified using the letters k and m to stand for kilo and mega respectively.
    set offset 0    Default setting
    set offset 120m    Start 120 megabytes into raw disk

set blocksize #bytes
    When playing or storing images on raw partition, read and write in #bytes size pieces.
    set blocksize 4k    Default setting.

set chunksize #frames
    When playing images from a raw partition, read frames in multiples of chunksize when possible. Set chunksize to one to turn this feature off
    set chunksize 1    Default setting.

set colors
    Set color map from 256 integer "index R G B" quadruples. This is only useful for pseudo color images. Default is a grey scale map, with 0 = black and 255 = white. For example:
    set colors
    0 10 100 203
    1 12 98 210
    [ 254 more quadruples ]

set imgformat pseudo8 | rgbplane | rgbbyte
    Sets image format to full color or mapped color. Images are stored row by row, first row at the top of the screen. A pseudo8 image has one byte per pixel. An rgbplane full color image is composed of DimXxDimY red bytes followed by the green bytes and the blue bytes, as in rrr...ggg...bbb.... An rgbbyte full color image is composed of DimXxDimY triples of bytes, as in rgbrgbrgb....
    set imgformat pseudo8    Default setting.

set datadim #DimX #DimY
    Sets the image dimensions, in pixels.
    set datadim 512 512    Default setting.

set toptobot on | off
    Paints images top to bottom, if possible.
    set toptobot off    Default setting.

set border #borderX #borderY
    Sets the black image border, in pixels.
    set border 0 0    Default setting.

set replication #RepX #RepY
    Sets replication, or fill factor, of pixels in the main window. Floating point replication factors work on the VGX.
    set replication 1.0 1.0    Default setting.

set zoom #ZoomX #ZoomY
    Sets zoom factor for zoom window. This is on top of the replication factor for the main window. Floating point zoom factors work on the VGX.
    set zoom 2.0 2.0    Default setting.

set prefix pathname
    Prepend pathname to all file names.

set filename #files
    Specifies the file names to load images from with a load command. For example:
    set filename 4
    /usr/local/tmp/ken/q42Hw0006ae33
    /usr/local/tmp/ken/q42Hw0007ae33
    /usr/local/tmp/ken/q42Hw0008ae33
    /usr/local/tmp/ken/q42Hw0009ae33

CAVEATS
The command syntax is very unsophisticated.

Loading can take a long time, during which the program will not accept commands. To cleanly exit during a load, select Quit from the window manager menu.

AUTHOR
Ken Chin-Purcell, AHPCRC
Mail to gvlware@ahpcrc.umn.edu.