Name

cell-fb — display cell-by-cell data on a frame buffer

DESCRIPTION

Cell-fb reads a stream of cell-by-cell data and displays the data, one view at a time, on a frame buffer. If file is specified, then cell-fb tries to read the data from it. Otherwise, the standard input is read.

Options

The command-line options and their meanings are given below.

-C

Interpret the first three fields for each cell as an explicit color (see the DEFINITIONS section below). The default behavior is to interpret a specified field as an indirect reference, which, through a color map, corresponds to a color.

-Ffbfile

Write graphics output to fbfile, which may be any UNIX file (or frame-buffer device). In the absence of the -F option, if the shell variable FB_FILE is defined, its value is used (see brlcad(1)). Otherwise, the host's default frame buffer is used (see libfb(3B)).

-Nscr_height

Set screen (frame-buffer) height to scr_height pixels. Scr_height may legally be any integer greater than -2. See the discussion of autosizing below.

-Sscr_size

Set screen (frame-buffer) width and height to scr_size pixels. Scr_size may legally be any integer greater than -2. See the discussion of autosizing below.

-Wscr_width

Set screen (frame-buffer) width to scr_width pixels. Scr_width may legally be any integer greater than -2. See the discussion of autosizing below.

-Xn

Set the local debug flag to the hexadecimal value n.

-a“h v”

Do not display the data, simply print out the frame-buffer coordinates of the grid-plane point (h, v). This option is useful for outboard manipulation of the pix(5) data created by cell-fb.

-bn

Ignore values not equal to n. All other cell-data values are mapped to the background color.

-cn

Assume a cell size of n user units. The default cell size is 100 user units.

-d“m n”

Scale the data values from the interval [m, n] into the unit interval [0, 1]. The scaling is performed before values are mapped to colors, so the -i, -k, and -m options always deal with the discrete values listed in the description below of the -k option. The default domain is [0, 1], for which no scaling is necessary.

-e

Erase the frame buffer before displaying each view.

-fn

Display field number n of the cell-by-cell data (see the DEFINITIONS section below). By default, field 1 is displayed.

-g

Display the grid. Causes a 1-pixel spacing between cells in the output.

-h

Force high-resolution display (1024×1024 pixels). See the discussion of autosizing below.

-i

Round values to the nearest discrete value listed in the description of the -k option below. By default, output colors are chosen by interpolation between those values.

-k

Display the color key. This option displays the color mappings for 11 discrete values underneath the picture. The values represented are, from left to right: 0.0, 0.1, 0.2, ..., 0.9, and 1.0. Given this option and snug-fit autosizing for height, the frame buffer that cell-fb opens will be taller to accommodate the key. See the discussion of autosizing below.

-l“az el”

Write log information to the standard output. When given this option, cell-fb produces a header comment and one line each reporting an azimuth/elevation pair (viz. (az, el) ) to associate with this view; the coordinates (in user units) of the lower-left and upper-right corners of the frame buffer; and the width and height (in pixels) of the frame buffer. This information may be useful in registering other images on top of a cell plot. If a single view has not been specified, this option causes an implicit -v 1, which may, of course, be overridden explicitly. N.B.—Cell-fb makes no use whatever of the values az and el, it merely writes them to the log.

-m“n color”

Map cell data value n to color. The value n will be truncated, if necessary, to the nearest lower of the discrete values listed in the description of the -k option above. The background color can be indexed by specifying the value 1.1 for n. For the meaning and format of color, see the DEFINITIONS section below.

-M“color1 color2”

Define the color map to be a ramp between color1 and color2. This allows frugality with the colors in an image: if, for example, cell data is plotted in gray scale, then many other colors remain for use in text, call outs, and sundry markings on top of the cell data. The default color map is a typical cold-to-hot, blue-to-red scale, excepting that the smallest value in the input domain is mapped to white. For the meaning and format of color1 and color2, see the DEFINITIONS section below.

-p“h v”

Offset the picture from the lower-left corner of the frame buffer display by h pixels horizontally, and v pixels vertically. If this option is specified with only one argument, then the horizontal and vertical offsets are both set to this value.

-s“w h”

Plot each cell as a rectangle of width w pixels and height hpixels. This option has the effect of scaling the picture independently in the horizontal and vertical dimensions. The default is 10 pixels per cell in each dimension, not including the grid. If this option is specified with only one argument, then the width and height are both set to this value.

-vn

Display only view number n. Views are numbered starting at 1. If n = 0, all views are displayed sequentially, which is the default behavior. The option -v 0 implicitly turns off logging. (see the -l option above).

-xn

Set the libbu(3) debug flag to the hexadecimal value n. This option is useful primarily in debugging memory allocation.