f3dformat package documentation

5.3

Introduction

f3d (Format 3 Dimensional) is a simple format for storage of 3D datasets supporting different voxel types (8, 16, 32 bit signed/unsigned integers and 32 bit floats) and different grids (cartesian, regular, rectilinear). It does not support curvilinear and unstructured grids. The package includes basic routines for storage/retrieval of such data into/from a file.

Detailed reference

• The f3dHeader structure
• Voxel types
• Reading f3d files
• Writing f3d files
• Miscelanous functions

Installation

There are several possibilities, how to install the f3dformat package:

• From binaries by means of the rpm tool. The latest rpm-s for for i386 GNU/Linux systems can be found at http://www.viskom.oeaw.ac.at/~milos/Download
• From a source tarball by means of the `configure' shell script. This works well for the gnu systems. The tarball is available at http://www.viskom.oeaw.ac.at/~milos/Download
• From a source tarball by means of the provided Makefile.defs and Makefile.nognu files. For details see the Makefile.defs file.

Description

The f3d (Format 3 Dimensional) is aimed at storage and manipulation of volumetric grids. It was designed with the following aims on mind:

Support of different kinds of voxels Single and multiband data, 8, 16, 32 bit integers, signed and unsigned, floats Different kinds of grids Cartesian, regular and rectilinear grids

width = 3cm

Self descriptive An f3d file contains all information necessary for its processing. This information is to be accessible with basic tools as, for example UNIX head command or a general image or text file viewers (xv, {vi}). Application specific comments provide a means to transfer information between different applications (for example, from voxelization to visualization). Data compression Volumetric data are usually huge, but they often compress very well (especially segmented masks or voxelized data). Preview image An icon image, giving a notion about the contents of the file. Should be viewable by regular image viewers ({ xv}). Unbearable Lightness of Usage

Basic structure of an f3d file

The f3d format is an extension of the well known Portable Graymap (pgm) format, defined in the pbmplus and netpbm packages, which make it viewable (at least a part of it - an icon image) by standard image viewers. f3d extends pgm in several directions:

f3d specific comments

The pgm format enables to include arbitrary text comments in the header part of the file. f3d takes advantage of this feature by specifying f3d comments with the following structure:

#!keyword value

The keywords have their counterparts in members of the f3dHeader structure. Detailed description can be found directly in the source code of the f3dReadHeader and f3dWriteHeader functions. The commLines keyword specifies number of application dependent comments, which can be used to transfer information between different application and do not have any specific format. These comments are labeled by the comment keyword. Of course, commLines must precede any comment line.

f3d file header example: A single band cubic grid of unsigned char type voxels.

#P5 - pgm format (magic number)
#128 128 - pgm format (image dimensions - in this case the icon image)
#!f3d 5.3 - f3d parameter
#*******************************************************
#** f3d
#** Format for storage of 3D volumetric data sets
#**
#** http://www.cs.sunysb.edu/~milos/f3d
#*******************************************************
#!endian f3dBigEndian - f3d parameter
#!vdim 128 128 128 - f3d parameter
#!vtype f3dCubic - f3d parameter
#!px 1.000000 - f3d parameter
#!bands 1 - f3d parameter
#!dtype f3dUChar - f3d parameter
#!units f3dUmm - f3d parameter
#!comment vxt thresh 0.5 - f3d comment
#!comment vxt profile linear 1.8 - f3d comment
#!comment File created by 'vxtGrid3D' - f3d comment
#!last - f3d parameter
255 - pgm format

f3d icon image

The purpose of the icon image is to provide the user with a notion of what data is in the file. If f3dWriteSlice or f3dWriteCubGrid functions are used for storing the data, a standard icon image is created by summation of density values along X, Y or Z grid axis. This direction is determined by the iconDir} member of the f3dHeader structure and can have f3dIconX, f3dIconY and f3dIconZ values respectively.

Appended volumetric data

Volumetric data are appended directly after the pgm image data. The data is stored slice by slice, with the following fields for each slice:

1. length of the compressed slice. It is stored as a 32 bit unsigned integer with MSB first order.
2. the compressed slice data. The compress} / uncompress} pair of routines from the zlib(http://www.cdrom.com/pub/infozip/zlib/) package is used. multiband volumes are stored as consecutive monochromatic layers in each with the length a compressed data fields.

f3d has been written in a GNU/Linux environment. However, it compiles also under the Borland and Microsoft compilers in the Windows enwironment.

---