CELL-FB(1)

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

SYNOPSIS
cell-fb [ options... ] [ file ]

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.

HINT
If multiple views are input, the user will be asked between views whether he wants to see the next view. While being prompted, the user can save the previous image by using a utility such as fb-rle(1).

DISCUSSION
Cell-fb determines the appropriate width and height of the frame buffer independently. For each there are three methods. If the sizes are provided explicitly, with the -N, -S, or -W options, cell-fb will use exactly the specified values. Otherwise, it performs autosizing for each view. Cell-fb's original behavior is called loose-fit autosizing. In that case, a frame-buffer dimension will be set to 512 pixels unless the image will not fit, in which case a 1024-pixel dimension is used. Loose-fit autosizing may be specified by any of -N0, -S0, or -W0. The third method is another form of autosizing, called snug-fit. For this method, cell-fb computes the minimum measurement required to display the plot, given the data and whatever values have been specified for the -c, -g, -k, -p, and -s options. Snug-fit autosizing is the default method for both width and height of the frame buffer, and it may be explicitly specified by any of -N-1, -S-1, or -W-1. Whenever autosizing is performed, cell-fb prints to the standard error the actual width and height used for each view.

DEFINITIONS
A stream of cell-by-cell data contains one or more views, each of which may start with view-header information and contains one line of data for each cell in the view. Each line of cell data must be in the following format:

coords fields

where coords is two real numbers and fields is one or more real numbers. All the numbers on a line of cell data are separated by non-empty strings of white space (blanks and tabs) and there may be leading white space on the line. Coords are the grid-plane coordinates of the cell, which must be spaced consistently with the cell size, and fields may have arbitrary significance. If the -fn option is specified, then there must be at least n fields of cell data, and if the -C option is specified, then there must be at least three fields of cell data. The view-header information may span multiple lines, and the only restriction on its format is that it not pass for data.

A color is specified as a triple

r g b

of integers, each between 0 and 255 (inclusive). These values represent intensities of red, green, and blue, respectively.

EXAMPLE
The following invocation will display the cell-by-cell data from inputs on the default frame buffer on the network host fictitious.brlcad.org. It will display all views with the grid turned on (space between cells), positioned with the left-most cell 20 cells to the right of the display origin (lower left), and the lowest cell 30 cells above the display origin, the color key will appear underneath the grid of cells, and the display will be erased before each view is drawn.

    $ cell-fb -F fictitious.brlcad.org: -gek -p ``20 30'' inputs

SEE ALSO
fb-rle(1), rtregis(1), libfb(3), pix(5)

AUTHORS

Gary S. Moss, BRL/VLD-VMB

Paul J. Tanenbaum, BRL/VLD-GSB