| Programmer's Reference for the BIC Volume IO Library | ||
|---|---|---|
| <<< Previous | Next >>> | |
Processing tasks within the lab where this software was developed deal with multi-dimensional volumes of data such as created by Magnetic Resonance and PET scanners. Therefore, an extensive set of routines is provided to represent volumes, and to read and write volumes in the MINC format.
The basic type of a volume is Volume, which is actually a pointer to an allocated structure which contains all the information about the type of volume, number of dimensions, voxel values, etc. In order to use a volume structure, the volume must first be created, then the size of the volume set, then the large array of voxel values is allocated. Alternately, a volume may be automatically created by calling the appropriate function to read a MINC file and create a volume.
A volume has an associated number of dimensions, which must be in the range from one to five, but typically is three. The volume is thought of as a multi-dimensional array of any of a variety of types, including all sizes of integer and real types. Even though a volume may be stored in say, a 1 byte type, with values from zero to 255, there is a real value range which provides mapping a mapping from voxel values to any arbitrary real range. In this way, the real range may be any valid real interval and is independent of the particular storage type.
Since most volumes will be created by reading from a MINC file, this method will be presented first, followed by a description of how to create a volume from scratch. Finally a lower level of MINC input and output for more advanced applications will be presented.
public Status input_volume(
STRING filename,
int n_dimensions,
STRING dim_names[],
nc_type volume_nc_data_type,
BOOLEAN volume_signed_flag,
Real volume_voxel_min,
Real volume_voxel_max,
BOOLEAN create_volume_flag,
Volume *volume,
minc_input_options *options ) |
This routine reads a volume from a MINC file, first creating the volume if the create_volume_flag is specified as TRUE (the usual case). The number of dimensions is the desired number of dimensions for the volume. If this is less than the number of dimensions in the file, then only the first part of the file, corresponding to this number of dimensions, is read. If the number of dimensions specified is less than 1, then the number of dimensions in the file is used. The argument dim_names specifies in what order the volume is to be stored in the volume variable. For each dimension in the stored volume, there is a corresponding name, which is one of MIxspace, MIyspace, MIzspace, ANY_SPATIAL_DIMENSION, or an empty string. These are matched up with corresponding dimensions in the file and the dimension ordering of the volume array is reordered on input. So, if the user wishes to represent the volume in X-Z-Y order, then the value passed as the dim_names array should be the three strings, MIxspace, MIzspace, and MIyspace. This choice of ordering is important, as it defines the order of any subsequent reference to voxel indices.
The four arguments, volume_nc_data_type through volume_voxel_max can be used to specified the desired storage type within the volume variable, automatically converted from the storage type in the file. The volume_nc_data_type is one of MI_ORIGINAL_TYPE, NC_BYTE, NC_SHORT, NC_LONG, NC_FLOAT, or NC_DOUBLE. For the integer types, the volume_signed_flag is TRUE if a signed type is desired, otherwise, it is FALSE. The volume_voxel_min and volume_voxel_max specify the range of valid voxel values, and are usually set equal to indicate to use the full range of the type, e.g. zero to 255.0 for unsigned NC_BYTE. If MI_ORIGINAL_TYPE is passed, then the type, sign, and voxel range in the file are used.
If the create_volume_flag is TRUE, the usual case, then the volume is automatically created. Otherwise, it is assumed that the volume already exists and will only be recreated if its current size is different from the new size resulting from the file, thus reducing the amount of memory allocation when reading multiple files.
The options argument specifies some special options to the input process, and is usually passed just a NULL pointer, indicating that the default options should be used. Currently the possible options are:
public void set_default_minc_input_options(
minc_input_options *options ) |
Fills in the default options into an options structure which will subsequently be passed to input_volume().
public void set_minc_input_promote_invalid_to_min_flag(
minc_input_options *options,
BOOLEAN flag ) |
By default, any voxel value which is outside the valid range of voxel values is promoted to the minimum valid voxel value. If this flag is set to FALSE, this promotion is disabled.
public void set_minc_input_vector_to_scalar_flag(
minc_input_options *options,
BOOLEAN flag ) |
By default, any volume which contains a dimension which is of type vector, for instance, an RGB colour volume, is converted to a scalar volume by averaging the components of each vector. This can be disabled by passing the flag as FALSE.
public void set_minc_input_vector_to_colour_flag(
minc_input_options *options,
BOOLEAN flag )
public void set_minc_input_colour_dimension_size(
minc_input_options *options,
int size )
public void set_minc_input_colour_indices(
minc_input_options *options,
int indices[4] ) |
By default, any volume which contains a dimension which is of type vector, for instance, an RGB colour volume, is converted to a scalar volume by averaging the components of each vector. If this option is set to true, any vector volume with the number of components specified by set_minc_input_colour_dimension_size (default 3) is converted to a colour volume, using the indices specified by set_minc_input_colour_indices (default 0, 1, 2).
public void set_minc_input_user_real_range(
minc_input_options *options,
double minimum,
double maximum ) |
By default, files read into an integer-type volume will be scaled so that the real range is the full range of the data in the input file. The user can define another range by calling this function with an appropriate real minimum and maximum. For float-type Volumes, setting the range will change the real range of the volume, but not change the actual values in the volume. If minimum is greater than or equal to maximum, then the default behaviour is restored.
| <<< Previous | Home | Next >>> |
| Time | Alternative Volume Input Methods |