rivtiler

rivtiler [-g gridWidth] [-s tableFile] [-p tableFile] [-t] [-f] inFile outFile

Description

rivtiler tiles large RivaFile images to ease parallel decomposition. The Renderer requires that input image files are decomposed into tiles. rivtiler reads a RivaFile image or Digital Elevation Model (DEM) file and writes a tiled version of the data. This tiled file can be efficiently loaded onto the nodes of a massively parallel processor.

rivtiler provides several ways to tile an image:

Regular Tiling: An NxN grid is laid down on the image; the tiles are the squares defined by the grid. N is called the grid width. A tile must include the row of data immediately below it and the column immediately to the right; thus, the actual number of pixels in each tile is (N+1)x(N+1) rather than NxN. N must be a power of 2.
Sparse Tiling: Here the image is assumed to be contained in an irregularly shaped region of a rectangular array of pixels; further, it is assumed that all non-data pixels are zero. rivtiler will tile the file such that all tiles have at least one non-zero pixel in the first row and in the first column. Large blank regions will be skipped completely.
Precomputed Tiling: It is often desirable to tile two or more files consistently, as when a sparse image is to be rendered using a non-sparse DEM. During sparse tiling, rivtiler produces a table of tile coordinates. This table is used to tile other files with the same scheme. The other files must have the same number of rows and columns as the original file.

In all cases, the tiles will contain (N+1)x(N+1) pixels.

Options

-g gridWidth: Specifies the grid width for regular and sparse tiling. The default is 64.
-s tableFile: Directs rivtiler to use sparse tiling, and save the tile table in tableFile.
-p tableFile: Directs rivtiler to tile the file using the tile table in tableFile. The input image must have the same number of rows and columns as the image whose tile table being used, and the same grid width must be specified.
-t: Tiles headers only. No data is read and written out.
-f: Reads data from IFL file.

Usage

Consider tiling two files containing image and DEM data for Mars, with a grid width of 128. The data is in a sinusoidal format, so the files contain many non-data pixels. Use the following commands:

% rivtiler -g 128 -s mars.table mars.riv tiled_mars.riv % rivtiler -g 128 -p mars.table marsdem.riv tiled_marsdem.riv

File Formats

Input Files

Input files must be RivaFiles containing image data: i.e., a rectangular array of multi-byte pixels in row-major order. The RivaFile header must contain the following fields:

NS (integer): The number of samples per line (i.e., columns in the array).
NL (integer): The number of lines in the file (i.e., rows in the array).
BPP (integer): The number of bytes per pixel.

The RivaFile header must not contain the fields "GRIDWIDTH", "NTILES", or "TILEHDRSIZ", as these fields indicate that the file contains tiled data.

Tiled Files

The output file will be a RivaFile containing tiled image data. The RivaFile header will be copied from the input file, and the following fields will be added:

GRIDWIDTH (integer): The tiling grid width and height. Since tiles contain one extra row and column, the actual tile dimensions are (GRIDWIDTH+1)x(GRIDWIDTH+1). GRIDWIDTH will be a power of 2.
NTILES (integer): The number of tiles in the file.
TILEHDRSIZ (integer): The size (in bytes) of each tile's header in the file. See below for details.
TILEHDRFMT (text): A comment field documenting the format of the tile header. See below for details.

The body of the output file is a simply a sequence of NTILES tiles. As written, each tile consists of a tile header and the tile data proper. The tile header is a NULL-terminate ASCII string with this format: 'r0 c0 nrUsed ncUsed onBoundary', where (r0,c0) is the coordinate of the upper left pixel in the original image, nrUsed and ncUsed are the number of rows and columns of data in the tile, and onBoundary is 'T' or 'F' depending on whether or not the tile is a boundary tile.

A tile is a boundary tile if nx is less than GRIDWIDTH+1 or ny is less than GRIDWIDTH+1 or any of the four corner pixels is a zero-pixel.

So that individual tiles can be addressed randomly, each tile occupies TILEHDRSIZ + BPP*(GRIDWIDTH+1)^2 bytes in the file, like this:

char header[TILEHDRSIZ]; char data[GRIDWIDTH+1][GRIDWIDTH+1][BPP];

Table Files

Tile table files are ASCII text files. The first line contains the number of rows and columns in the input file, and the tiling grid width. Subsequent lines contain the tile headers from the output file: 'r0 c0 nrUsed ncUsed onBoundary'. Thus if a 640x512 image were tiled regularly with a grid width of 128, the tile table would look like this:

640 512 128 0 0 129 129 F 0 128 129 129 F 0 256 129 129 F 0 384 129 129 F 0 512 129 128 T 0 128 129 129 F 128 128 129 129 F 128 256 129 129 F (lines skipped) 384 0 128 129 T 384 128 128 129 T 384 256 128 129 T 384 384 128 129 T 384 512 128 128 T