Volume Manipulation

Once a volume has been created and allocated, there are many macros and functions for manipulating the volume. Note that associated with each volume is a valid voxel range indicating the range of values actually stored in the volume, for instance, zero to 200 is one possible range for an unsigned byte volume. There is a second range, the real range, which is the mapping of the valid voxel range to an arbitrary real range, for instance, the zero to 200 of valid voxels could map to -1.5 to 1.5 in the real range. When dealing with volumes, one is generally interested in the real range.

GET_VOXEL( value, volume, v1, v2, v3, v4, v5 )

Given a volume and from one to five voxel indices, depending on the volume dimensions, stores the corresponding voxel value in the variable value, which may be of any type. For instance, if the volume is three dimensional, then the final two arguments are ignored.

GET_VOXEL_1D( value, volume, v1 )
GET_VOXEL_2D( value, volume, v1, v2 )
GET_VOXEL_3D( value, volume, v1, v2, v3 )
GET_VOXEL_4D( value, volume, v1, v2, v3, v4 )
GET_VOXEL_5D( value, volume, v1, v2, v3, v4, v5 )

More convenient versions of GET_VOXEL. Given a volume and the required number of voxel indices for the volume, assigns the corresponding voxel value to the argument value. This is more efficient than GET_VOXEL because the macro does not look up the number of dimensions in the volume.

CONVERT_VOXEL_TO_VALUE( volume, voxel )

Given a volume and a voxel value, converts this to a value in the real range, and returns it.

CONVERT_VALUE_TO_VOXEL( volume, value )

Given a volume and a real value, converts this to a voxel value in the valid voxel range, and returns it.

GET_VALUE( value, volume, v1, v2, v3, v4, v5 )

Given a volume and from one to five voxel indices, depending on the volume dimensions, stores the corresponding real value in the variable value, which may be of any type. For instance, if the volume is three dimensional, then the final two arguments are ignored. This macro just performs the two macros GET_VOXEL and CONVERT_VOXEL_TO_VALUE.

GET_VALUE_1D( value, volume, v1 )
GET_VALUE_2D( value, volume, v1, v2 )
GET_VALUE_3D( value, volume, v1, v2, v3 )
GET_VALUE_4D( value, volume, v1, v2, v3, v4 )
GET_VALUE_5D( value, volume, v1, v2, v3, v4, v5 )

More convenient versions of GET_VALUE. Given a volume and the required number of voxel indices for the volume, assigns the corresponding real value to the argument value. This just performs one of the GET_VOXEL_?D macros, then a CONVERT_VOXEL_TO_VALUE. Typically, the GET_VALUE_3D macro is used for many applications.

SET_VOXEL( volume, v1, v2, v3, v4, v5, value )

Given a volume, one to five voxel indices, and a voxel value, assigns this value to the corresponding voxel in the volume. Note that no conversion from the valid real range to the valid voxel range is performed, so the user may need to use the CONVERT_VALUE_TO_VOXEL macro first.

public  void  delete_volume(
    Volume   volume )

Deletes all the memory associated with an volume.

public  nc_type  get_volume_nc_data_type(
    Volume       volume,
    BOOLEAN      *signed_flag )

Returns the storage type of the volume (for instance, NC_SHORT), and passes back an indication of whether it is signed or unsigned.

public  int  get_volume_n_dimensions(
    Volume   volume )

Returns the number of dimensions of the volume.

public  void  get_volume_sizes(
    Volume   volume,
    int      sizes[] )

Stores the size of each dimension in the array sizes. This is the number of voxels in each dimension. The array sizes must be at least as large as the number of dimensions of the volume.

public  void  get_volume_separations(
    Volume   volume,
    Real     separations[] )

Stores the slice separation for each dimension in the array separations. The array separations must be at least as large as the number of dimensions of the volume.

public  Real  get_volume_voxel_min(
    Volume   volume )
public  Real  get_volume_voxel_max(
    Volume   volume )
public  void  get_volume_voxel_range(
    Volume     volume,
    Real       *voxel_min,
    Real       *voxel_max )

The first two functions return the minimum or maximum allowable voxel value. The third function passes back both values.

public  Real  get_volume_real_min(
    Volume     volume )
public  Real  get_volume_real_max(
    Volume     volume )
public  void  get_volume_real_range(
    Volume     volume,
    Real       *min_value,
    Real       *max_value )

The first two functions return the minimum or maximum real value. The third function passes back both values. The mapping to this real space linearly maps the minimum voxel value to the minimum real value and the maximum voxel value to the maximum real value.

public  char  **get_volume_dimension_names(
    Volume   volume )

Returns a pointer to the list of names of each dimension.

• Volume Coordinate Systems