QccIMGImageCubePrint.3

NAME

QccIMGImageCube - data structure QccIMGImageCube and corresponding ICB file format for a 3D image cube

int QccIMGImageCubeInitialize(QccIMGImageCube *image_cube);
int QccIMGImageCubeAlloc(QccIMGImageCube *image_cube);
void QccIMGImageCubeFree(QccIMGImageCube *image_cube);
int QccIMGImageCubePrint(const QccIMGImageCube *image_cube);

int QccIMGImageCubeSetMin(QccIMGImageCube *image_cube);
int QccIMGImageCubeSetMax(QccIMGImageCube *image_cube);
int QccIMGImageCubeSetMaxMin(QccIMGImageCube *image_cube);

int QccIMGImageCubeResize(QccIMGImageCube *image_cube, int num_frames, int num_rows, int num_cols);

DESCRIPTION

QccPack provides data structure QccIMGImageCube for representing a three-dimensional image cube, which can be used for various applications involving volumetric imagery, such as multispectral and hyperspectral data. This image-cube structure can be read from and written to ICB-format files, or a QccIMGImageCube structure can be used without file input or output.

The main component of a QccIMGImageCube structure is a three-dimensional array of floating-point values representing the cube's voxels. The image cube is represented as a collection of two-dimensional "frames," where each frame has the same number of rows and columns. For multispectral and hyperspectral imagery, these 2D frames would usually be spectral bands.

DATA STRUCTURE

The QccIMGImageCube data structure is defined as:

typedef QccVolume QccIMGImageVolume;
typedef struct
{
QccString filename;
QccString magic_num;
int major_version;
int minor_version;
int num_frames;
int num_rows;
int num_cols;
double min_val;
double max_val;
QccIMGImageVolume volume;
} QccIMGImageCube;

The fields of QccIMGImageCube are as follows:

filename: The name of the file.
magic_num, major_version, minor_version: The magic number and version of the file.
num_frames, num_rows, num_cols: The number of frames, rows, and columns of the image cube.
min_val, max_val: The minimum and maximum voxel values in the image cube.
volume: The array of voxels.

FILE FORMAT

For reading and writing structures of type QccIMGImageCube, QccPack provides the ICB file format. This file format starts with an ASCII header followed by binary data. The ASCII header starts with a magic number, and can be followed with any amount of white space (blanks, `\t' (tab), `\n' (newline), `\r' (carriage return)) and/or comments lines (lines starting with "#"). Following this white space, additional ASCII header information is given, separated by blanks and newlines. Binary data follows this ASCII header information. Note: one (and only one) newline must immediately follow the last component of ASCII header information before the start of the binary data.

The ICB file format consists of the following information:

ICBX.X
<white space>
C R F
min max
i111 i112...
i121 i122...
.
.
.
i211 i212...
i221 i222...
.
.
.

where ICB is the magic number, X.X is the version number, <white space> is white space and/or comment lines, C is the number of columns of the image cube, R is the number of rows, F is the number of frames, and min and max give the range of the values of the image cube. ifrc is the voxel for the fth frame, the rth row, and the cth column of the image cube. C, R, F, min, and max are stored in ASCII. The image cube itself, ifrc, is stored as binary floating-point numbers (4 bytes each, MSB first, see QccFileWriteDouble(3) ). In the nomenclature common to multispectral and hyperspectral applications, the image cube data is stored in band-sequential (BSQ) format.

ROUTINES

QccIMGImageCubeInitialize() should be called before any use of a QccIMGImageCube structure. QccIMGImageCubeInitialize() initializes the fields of image_cube to the following values:

filename: NULL string
magic_num: QCCIMGIMAGECUBE_MAGICNUM
major_version, minor_version: initialized to output of QccGetQccPackVersion(3)
num_frames: 0
num_rows: 0
num_cols: 0
min_val: 0
max_val: 0
volume: NULL

QccIMGImageCubeAlloc() allocates storage space for image_cube->volume. If image_cube->volume is not NULL, QccIMGImageCubeAlloc() returns immediately without changing the state of any memory allocation. Otherwise, the image_cube->volume array is allocated. The fields image_cube->num_frames, image_cube->num_rows, and image_cube->num_cols must be set prior to calling QccIMGImageCubeAlloc().

QccIMGImageCubeFree() frees the image_cube->volume array previously allocated by QccIMGImageCubeAlloc().

QccIMGImageCubePrint() prints the contents of image_cube to stdout.

QccIMGImageCubeSetMin() determines the smallest voxel value in image_cube->volume and sets image_cube->min_val to that minimum value.

QccIMGImageCubeSetMax() determines the largest voxel value in image_cube->volume and sets image_cube->max_val to that maximum value.

QccIMGImageCubeSetMaxMin() sets both image_cube->max_val and image_cube->min_val by calling QccIMGImageCubeSetMax() and QccIMGImageCubeSetMin() in succession.

QccIMGImageCubeResize() calls QccVolumeResize(3) to change the size of image_cube to num_frames x num_rows x num_cols.

RETURN VALUE

These routines return 0 on success, and 1 on failure.

AUTHOR

Table of Contents

NAME
SYNOPSIS
DESCRIPTION
DATA STRUCTURE
FILE FORMAT
ROUTINES
RETURN VALUE
SEE ALSO
AUTHOR