Programmer's Reference for the BIC Volume IO Library
<<< Previous	Volumes	Next >>>

Volume Manipulation

Once a volume has been created and allocated, there are many 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.

public  Real  get_volume_voxel_value(
    Volume   volume,
    int      v0,
    int      v1,
    int      v2,
    int      v3,
    int      v4 )

Given a volume and from one to five voxel indices, depending on the volume dimensions, returns the corresponding voxel value. For instance, if the volume is three dimensional, then the final two arguments are ignored.

value = 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.

voxel = 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.

public  Real  get_volume_real_value(
    Volume   volume,
    int      v0,
    int      v1,
    int      v2,
    int      v3,
    int      v4 )

Given a volume and from one to five voxel indices, depending on the volume dimensions, returns the corresponding real value. For instance, if the volume is three dimensional, then the final two arguments are ignored.

public  void  set_volume_voxel_value(
    Volume   volume,
    int      v0,
    int      v1,
    int      v2,
    int      v3,
    int      v4,
    Real     voxel )

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 function first or use the set_volume_real_value function.

public  void  set_volume_real_value(
    Volume   volume,
    int      v0,
    int      v1,
    int      v2,
    int      v3,
    int      v4,
    Real     value )

Given a volume, one to five voxel indices, and a value, assigns this value to the corresponding voxel in the volume, after converting to a voxel value.

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  STRING  *get_volume_dimension_names(
    Volume   volume )

Returns a pointer to the list of names of each dimension. This memory must be freed by the calling function using the following function.

public  void  delete_dimension_names(
    Volume   volume,
    STRING   dimension_names[] )

Frees the memory allocated for the dimension names.

public  void  set_rgb_volume_flag(
    Volume   volume,
    BOOLEAN  flag )

Sets the volume flag indicating whether the volume is of type red-green-blue colour. Only volumes whose data type is unsigned long may be rgb volumes.

public  BOOLEAN  is_an_rgb_volume(
    Volume   volume )

Returns TRUE if the volume is a red-green-blue colour volume, as can be created on volume input.

Volume Coordinate Systems

A volume has two coordinate systems. The voxel coordinate system is simply the n-dimensional indexing coordinate system for a volume. A voxel coordinate of (0.0, 0.0, 0.0), for instance, corresponds to the centre of the first voxel in a three dimensional volume. A voxel coordinate of ( 99.0, 0.0, 0.0 ) corresponds to the centre of the last voxel in the first direction of a three dimensional volume of size ( 100, 200, 150 ). The second coordinate system is an arbitrary three dimensional coordinate system, usually referred to as the world coordinate system, often the Talairach coordinate system. The following functions provide conversion to and from these two coordinate systems:

public  void  convert_voxel_to_world(
    Volume   volume,
    Real     voxel[],
    Real     *x_world,
    Real     *y_world,
    Real     *z_world )

Given a volume and a real valued voxel index, passes back the corresponding world coordinate.

public  void  convert_3D_voxel_to_world(
    Volume   volume,
    Real     voxel1,
    Real     voxel2,
    Real     voxel3,
    Real     *x_world,
    Real     *y_world,
    Real     *z_world )

Same as convert_voxel_to_world except it applies only to three dimensional volumes.

public  void  convert_world_to_voxel(
    Volume   volume,
    Real     x_world,
    Real     y_world,
    Real     z_world,
    Real     voxel[] )

Converts a world coordinate into a voxel. In order to use these voxel coordinates as integer indices, for instance, as arguments to the GET_VALUE macros, each component of the argument voxel must first be rounded to the nearest integer.

public  void  convert_3D_world_to_voxel(
    Volume   volume,
    Real     x_world,
    Real     y_world,
    Real     z_world,
    Real     *voxel1,
    Real     *voxel2,
    Real     *voxel3 )

Same as convert_world_to_voxel except it applies only to three dimensional volumes.

public  void  convert_voxel_vector_to_world(
    Volume          volume,
    Real            voxel_vector[],
    Real            *x_world,
    Real            *y_world,
    Real            *z_world )
public  void  convert_world_vector_to_voxel(
    Volume          volume,
    Real            x_world,
    Real            y_world,
    Real            z_world,
    Real            voxel_vector[] )

These two functions convert vectors between the voxel and world spaces. This is done by transforming the point (0,0,0) to the other space, in addition to treating the vector as a point and transforming it to the other space, and passing back the vector between the two results.

public  void  convert_voxel_normal_vector_to_world(
    Volume          volume,
    Real            voxel1,
    Real            voxel2,
    Real            voxel3,
    Real            *x_world,
    Real            *y_world,
    Real            *z_world )

Converts a vector which is assumed to be a surface normal to the world coordinate system.

Volume Interpolation

In addition to the routines for accessing particular voxel values, the volume can be interpolated using nearest neighbour, linear, or cubic interpolation, specified in either voxel or world space.

public  int   evaluate_volume(
    Volume         volume,
    Real           voxel[],
    BOOLEAN        interpolating_dimensions[],
    int            degrees_continuity,
    BOOLEAN        use_linear_at_edge,
    Real           outside_value,
    Real           values[],
    Real           **first_deriv,
    Real           ***second_deriv )

Interpolates a volume at the specified voxel, where degrees_continuity has values -1, 0, or 2, for nearest neighbour, linear, or cubic interpolation. If use_linear_at_edge is true, then any cubic interpolation will be downgraded to linear interpolation near the edge of the volume. This option is only needed in special cases. The parameter outside_value is the value for any point outside the volume. The argument interpolating_dimensions indicates which dimensions are being interpolated, typically a NULL pointer indicating that all dimensions are being interpolated. The interpolated values are placed in the values array. The number of values is equal to the number of values in the non-interpolated dimensions, which is one, if all dimensions are being interpolated. If the derivative arguments are non-null, then the resulting derivatives are placed in the appropriate places. The first_deriv is a two dimensional array of size number of values by number of interpolating dimensions. The second_deriv is a three dimensional array of size number of values by number of interpolating dimensions by number of interpolating dimensions.

public  void   evaluate_volume_in_world(
    Volume         volume,
    Real           x,
    Real           y,
    Real           z,
    int            degrees_continuity,
    BOOLEAN        use_linear_at_edge,
    Real           outside_value,
    Real           values[],
    Real           deriv_x[],
    Real           deriv_y[],
    Real           deriv_z[],
    Real           deriv_xx[],
    Real           deriv_xy[],
    Real           deriv_xz[],
    Real           deriv_yy[],
    Real           deriv_yz[],
    Real           deriv_zz[] )

Interpolates a volume at the specified world position, where degrees_continuity has values -1, 0, or 2, for nearest neighbour, linear, or cubic interpolation. If use_linear_at_edge is true, then any cubic interpolation will be downgraded to linear interpolation near the edge of the volume. This option is only needed in special cases. The parameter outside_value is the value for any point outside the volume. The interpolated values are placed in the values array. The number of values is equal to the number of values in the non-spatial dimensions, which is one if all dimensions are spatial. If the derivative arguments are non-null, then the resulting derivatives are placed in the appropriate places.

public  void  set_volume_interpolation_tolerance(
    Real   tolerance )

For speed considerations, if a volume is evaluated at or near a voxel centre, then no interpolation is performed, and the voxel value is returned. The tolerance defines how close to the voxel centre this occurs, and defaults to 0. Note that if derivatives are desired and the degree of continuity specified is 0 or greater, then interpolation will be performed, even when within the specified tolerance of the voxel.

<<< Previous	Home	Next >>>
Volume Output	Up	Volume Creation from Scratch