What is the Volio Library ?  

VOLIO is a set of functions in ANSI C designed for transparent reading and writing of multidimensional data files. In the field of brain imaging, most research groups have a bad habit of inventing their own file formats for storing brain scans. This makes data interchange more cumbersome.

Therefore, I set forward to write a set of easy-to-use functions that could read and write brain data files independent of file format. The user calls a standard function (e.g. read_volume()) to read in a volume, and the library would concern about which format the file is stored in, endian conversion, compression scheme etc.

Specifications

At present, three file formats are supported: ANALYZE, VAPET and XPRIME format. The following data types are supported : unsigned char, unsigned short, signed short, long, float, double. Two types of compression are supported: unix compress (extension .Z) and (.gz) gzip.

The VOLIO library supports simple database-like operations to help looking for specific information in a volume file header. Once a header has been read, it is possible to ask for information regarding a key string (get_description(), get_description_value()). It is also possible to add new key-value pairs to a header (add_description()) and to delete certain key-value pairs (delete_lhs_description() and delete_description()).

Type conversion is possible between between the supported data types (convert_volume()). Functions for mirroring a volume in any 3 directions are also present (flip_lr(), flip_tb(), flip_ud()).

If a volume is compressed when read, the compression type is stored in the header, so that the file can be written back on top of the original file(s). Care is taken so that is should be transparant to the user whether the current volume consists of one or two files. Whenever a volume is read (using e.g. read_volume()) the struct members filename1 (and filename2 if the file tyoe is ANALYZE) are initialized with the actual file name(s) on disk, including the same leading paths as specified when loading. The library searches for file names in a special manner, see read_header() for a description.

The header struct  

The basic idea of the header struct is to have the header information organized in two ways: required information and optional information. Required information is image rank (n.o. dimensions), dimensions in voxels, size of each voxel and data type used. Optional information is everything else (scan date, isotope, patient name, etc.).

In the header struct, the required fields are stored in the header struct directly. The optional information is stored in a chain of key-value string pairs.

Functions exist to manipulate and search in the chain of information contained in the header.

  

Figure 1: The structure of information in the header struct.

Because the header contains this chain of information, it is very easy to add new information to the header.

Special definitions in volio.h

The following constants are defined in the volio.h file:

enum data_type {T_UNKNOWN=0, T_BYTE=1, T_USHORT, T_SSHORT, T_LONG, T_FLOAT, T_DOUBLE};
enum open_mode  {TRUNCATE, CONSERVE};
enum file_type {VAPET=2, ANALYZE=3, XPRIME=4, UNKNOWNFILETYPE};
enum error_signals {OK, ERROR};

const char *filetype2str[] = {"unknown", "unknown", "VAPET", "ANALYZE", "XPRIME"};

static int auto_convert = 1;

const int type2bpv[7] = {0, 1, 2, 2, 4, 4, 8};
const char *type2str[7]={"unknown", "byte", "ushort", "sshort", "long", "float", "double"};

---------------------------------------------------------------------------------------------

data_type               Enumerates for the supported data types. 
                        Used e.g. by hdr->type and convert_volume().

file_type               The supported data file types.

error_signals           Return values from volio functions.

filetype2str[]          Use this to generate a string from the file type.

type2bpv                bpv is short for ``byte per voxel''. Use this array to 
                        compute the size need for e.g. memcpy() etc.

type2str[]              Generates a data type string from an  enum data_type

auto_convert            A global flag to indicate whether data should be 
                        automatically converted for reverse endian-ness
                        after reading and before writing if the computer has reverse
                        endians (Intel style endians). IEEE floating point numbers 
                        are assumed.

open_mode               Used by open_write() to signify wether the
                        file's data contents should be preserved or truncated 
                        when a file is opened.

-----------------------------------------------------------------------------
1997 Ulrik Kjems, DSP/IMM, Technical University of Denmark, uk@imm.dtu.dk
-----------------------------------------------------------------------------
 This software is FREE for non-commercial use, but the author holds all
 rights, and any use of the software should clearly indicate the author.
-----------------------------------------------------------------------------

VOLIO 0.4

This file contains the ANSI C source for functions relating to the general file-handling of N-dimensional volumes.

The basic idea is to have a single dynamically flexible data structure be useable to both read and write transparantly in as many file formats as possible. Currently, both VAPET, XPRIME and ANALYZE file format is supported. Reading of MINC format files is also planned.

This code runs on standard unix ANSI C compilers, and has been tested on the following operating systems: Linux, HP, SGI, Sun, DEC.

Ulrik Kjems, November 1997

--------------------------------------- 1997 Ulrik Kjems, DSP/IMM, Technical University of Denmark, uk@imm.dtu.dk --------------------------------------- This software is FREE for non-commercial use, but the author holds all rights, and any use of the software should clearly indicate the author. ---------------------------------------