Next: Volume Output Up: Volumes Previous: Volumes

Volume Input

public  Status  input_volume(
    char                 filename[],
    int                  n_dimensions,
    char                 *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. 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 NC_UNSPECIFIED, 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 NC_UNSPECIFIED 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.

Next: Volume Output Up: Volumes Previous: Volumes
Fri Feb 17 15:37:42 EST 1995