FSL User Guide - NEWIMAGE Reference Guide

| # FSL User Guide - NEWIMAGE Reference Guide |

This document describes the two templated container classes ( volume and volume4D) in NEWIMAGE. In addition, it describes the general functions supporting them, including file I/O operations, in AVW format.

Both classes are templated by a single basic type <T>. As the classes are precompiled into the library, only certain types are available. Currently, these are: char, short, int, float, double.

## HEADER FILES

Both classes can be used by using the following line:

    #include "newimage.h"

and all classes are contained in the namespace: NEWIMAGE

## VOLUME

This is the basic 3D container class.

### Constructors

- volume<T>( )
  Creates an empty volume, which allocates no data storage.
- volume<T>(int xsize, int ysize, int zsize)
  Creates a volume of specified size (number of voxels in each dimension), allocating the required amount of data storage.
- volume<T>(int xsize, int ysize, int zsize, T* d, bool d_owner)
  Creates a volume of specified size, but using the data block pointed to by d. The final argument d_owner specifies whether the volume should take over ownership of this data block. That is, whether the volume will free up the memory allocation (using delete[]) when the destructor is called.
- volume<T>(volume T and source)
  Basic copy constructor.

Note that none of the constructors described above initialize the data values. To do this the assignment operator should be used.

### Data Access

- T& operator()(int x, int y, int z)
  Returns a reference to data value at position (x,y,z), with bounds checking/extrapolation.
- T& value(int x, int y, int z)
  Returns a reference to data value at position (x,y,z) without any bounds checking or extrapolation.

Note that both const and non- const versions of the above access operators exist. The first form operator() is the most general form, and should be used initially when coding. The second form value is the fastest, most basic access routine and should be used when speed is a priority.

Related functions:

- bool in_bounds(int x, int y, int z) const
  Determines whether the specified position is within the current image bounds. Note that it uses the ROI if it is active.
- void setextrapolation(extrapolation extrapmethod) const
  Sets the type of extrapolation to be performed. Can taken any of the following values (from the enumerated type extrapolation):
  zeropad, constpad, extraslice, mirror, periodic, boundsassert, boundsexception
- extrapolation getextrapolationmethod() const
  Returns the extrapolation method that is currently set.
- void setpadvalue(T padval) const
  Sets the pad value to be used in the constpad and extraslice extrapolation methods.
- T getpadvalue() const
  Returns the pad value that is currently set.

### Basic Properties

- int xsize() const
  Returns the number of voxels in the x dimension.
- int ysize() const
  Returns the number of voxels in the y dimension.
- int zsize() const
  Returns the number of voxels in the z dimension.
- float xdim() const
  Returns the length of a voxel in the x dimension (in mm).
- float ydim() const
  Returns the length of a voxel in the y dimension (in mm).
- float zdim() const
  Returns the length of a voxel in the z dimension (in mm).
- int xsign() const
  Returns the sign of the length of a voxel in the x dimension (+1 or -1) - here to support negative voxel lengths.
- int ysign() const
  Returns the sign of the length of a voxel in the y dimension (+1 or -1) - here to support negative voxel lengths.
- int zsign() const
  Returns the sign of the length of a voxel in the z dimension (+1 or -1) - here to support negative voxel lengths.
- void setxdim(float x)
  Sets the length of a voxel in the x dimension.
- void setydim(float y)
  Sets the length of a voxel in the y dimension.
- void setzdim(float z)
  Sets the length of a voxel in the z dimension.
- void setdims(float x, float y, float z)
  Sets all voxel length dimensions at once.
- int nvoxels() const
  Returns the number of voxels in the current ROI.

### Lazily Evaluated Properties

- T min() const
  Returns the minimum voxel value in the current ROI.
- T max() const
  Returns the maximum voxel value in the current ROI.
- float sum() const
  Returns the sum of all voxel values in the current ROI.
- float sumsquares() const
  Returns the sum of all squared voxel values in the current ROI.
- float mean() const
  Returns the mean of all the voxel values in the current ROI.
- float variance() const
  Returns the variance of all the voxel values in the current ROI.
- float stddev() const
  Returns the square root of the variance.
- ColumnVector cog() const
  Returns the Centre of Gravity of the volume (using current ROI). Note that the result is in world coordinates.
- ColumnVector principleaxis(int n) const
  Returns the nth principle axis (using current ROI). Note that the result is in world coordinates.
- T backgroundval() const
  Returns a robust estimate of the background value, using the 10th percentile of the voxel values in a thin strip around the edge of the total volume (ignores the ROI).

### Secondary Properties

- Matrix sampling_mat() const
  Returns the sampling matrix required to convert voxel coordinates to world coordinates (in mm) - note that this ignores origin settins.
- ColumnVector& getorigin() const
  Returns the origin as previously set by the user.
- void setorigin(const ColumnVector& orig) const
  Allows the user to set an origin that is carried with the volume, but not used in any internal calculations.
- void setorigin(float x, float y, float z) const
  Allows the user to set an origin that is carried with the volume, but not used in any internal calculations.

### Iterators

### ROI Functions

### Arithmetic Functions

### Other Functionality

## VOLUME4D

This is the basic 4D container class, which is built as an array of 3D volumes. Therefore, each individual volume has all the attributes described above.

### Constructors

- volume4D<T>( )
  Creates an empty 4D volume, which allocates no data storage.

### Data Access

### Basic Properties

### Lazily Evaluated Properties

### Iterators

### Other Functionality

## FILE I/O

## FUNCTIONS

#### Mark Jenkinson
Copyright © 2000, University of Oxford