RNifti
Fast R and C++ Access to NIfTI Images
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
RNifti::NiftiImage Class Reference

Thin wrapper around a C-style nifti_image struct that allows C++-style destruction. More...

#include <NiftiImage.h>

Classes

struct  Block
 Inner class referring to a subset of an image. More...
 

Public Member Functions

 NiftiImage ()
 Default constructor.
 
 NiftiImage (const NiftiImage &source, const bool copy=true)
 Copy constructor. More...
 
 NiftiImage (const Block &source)
 Initialise from a block, copying in the data. More...
 
 NiftiImage (nifti_image *const image, const bool copy=false)
 Initialise using an existing nifti_image pointer. More...
 
 NiftiImage (const std::string &path, const bool readData=true)
 Initialise using a path string. More...
 
 NiftiImage (const std::string &path, const std::vector< int > &volumes)
 Initialise using a path string and sequence of required volumes. More...
 
virtual ~NiftiImage ()
 Destructor which decrements the reference counter, and releases the wrapped pointer if the counter drops to zero.
 
 operator const nifti_image * () const
 Allows a NiftiImage object to be treated as a pointer to a const nifti_image.
 
 operator nifti_image * ()
 Allows a NiftiImage object to be treated as a pointer to a nifti_image.
 
const nifti_image * operator-> () const
 Allows a NiftiImage object to be treated as a pointer to a const nifti_image.
 
nifti_image * operator-> ()
 Allows a NiftiImage object to be treated as a pointer to a nifti_image.
 
NiftiImageoperator= (const NiftiImage &source)
 Copy assignment operator, which copies from its argument. More...
 
NiftiImageoperator= (const Block &source)
 Copy assignment operator, which allows a block to be used to replace the contents of a suitably sized image. More...
 
NiftiImagesetPersistence (const bool persistent)
 Mark the image as persistent, so that it can be passed back to R. More...
 
bool isNull () const
 Determine whether or not the wrapped pointer is NULL. More...
 
bool isShared () const
 Determine whether the wrapped pointer is shared with another NiftiImage. More...
 
bool isPersistent () const
 Determine whether or not the image is marked as persistent. More...
 
bool isDataScaled () const
 Determine whether nontrivial scale and slope parameters are set. More...
 
int nDims () const
 Return the number of dimensions in the image. More...
 
std::vector< int > dim () const
 Return the dimensions of the image. More...
 
std::vector< float > pixdim () const
 Return the dimensions of the pixels or voxels in the image. More...
 
NiftiImagedrop ()
 Drop unitary dimensions. More...
 
template<typename TargetType >
std::vector< TargetType > getData (const bool useSlope=true) const
 Extract a vector of data from the image, casting it to any required element type. More...
 
NiftiImagechangeDatatype (const short datatype, const bool useSlope=false)
 Change the datatype of the image, casting the pixel data if present. More...
 
NiftiImagechangeDatatype (const std::string &datatype, const bool useSlope=false)
 Change the datatype of the image, casting the pixel data if present. More...
 
template<typename SourceType >
NiftiImagereplaceData (const std::vector< SourceType > &data, const short datatype=DT_NONE)
 Replace the pixel data in the image with the contents of a vector. More...
 
NiftiImagedropData ()
 Drop the data from the image, retaining only the metadata. More...
 
NiftiImagerescale (const std::vector< float > &scales)
 Rescale the image, changing its image dimensions and pixel dimensions. More...
 
NiftiImagereorient (const int i, const int j, const int k)
 Reorient the image by permuting dimensions and potentially reversing some. More...
 
NiftiImagereorient (const std::string &orientation)
 Reorient the image by permuting dimensions and potentially reversing some. More...
 
mat44 xform (const bool preferQuaternion=true) const
 Obtain an xform matrix, indicating the orientation of the image. More...
 
int nBlocks () const
 Return the number of blocks in the image. More...
 
const Block block (const int i) const
 Extract a block from the image. More...
 
Block block (const int i)
 Extract a block from the image. More...
 
const Block slice (const int i) const
 Extract a slice block from a 3D image. More...
 
Block slice (const int i)
 Extract a slice block from a 3D image. More...
 
const Block volume (const int i) const
 Extract a volume block from a 4D image. More...
 
Block volume (const int i)
 Extract a volume block from a 4D image. More...
 
void toFile (const std::string fileName, const short datatype=DT_NONE) const
 Write the image to a NIfTI-1 file. More...
 
void toFile (const std::string fileName, const std::string &datatype) const
 Write the image to a NIfTI-1 file. More...
 

Static Public Member Functions

static mat33 xformToRotation (const mat44 matrix)
 Extract the pure rotation part of a 4x4 xform matrix. More...
 
static std::string xformToString (const mat44 matrix)
 Convert a 4x4 xform matrix to a string describing its canonical axes. More...
 
static int fileVersion (const std::string &path)
 Get the NIfTI format version used by the file at the specified path. More...
 

Protected Member Functions

void acquire (nifti_image *const image)
 Acquire the specified pointer to a nifti_image struct, taking (possibly shared) responsibility for freeing the associated memory. More...
 
void acquire (const NiftiImage &source)
 Acquire the same pointer as another NiftiImage, incrementing the shared reference count. More...
 
void release ()
 Release the currently wrapped pointer, if it is not NULL, decrementing the reference count and releasing memory if there are no remaining references to the pointer.
 
void copy (const nifti_image *source)
 Copy the contents of a nifti_image to create a new image, acquiring the new pointer. More...
 
void copy (const NiftiImage &source)
 Copy the contents of another NiftiImage to create a new image, acquiring a new pointer. More...
 
void copy (const Block &source)
 Copy the contents of a Block to create a new image, acquiring a new pointer. More...
 
void updatePixdim (const std::vector< float > &pixdim)
 Modify the pixel dimensions, and potentially the xform matrices to match. More...
 
void setPixunits (const std::vector< std::string > &pixunits)
 Modify the pixel dimension units. More...
 

Protected Attributes

nifti_image * image
 The wrapped nifti_image pointer.
 
int * refCount
 A reference counter, shared with other objects wrapping the same pointer.
 

Detailed Description

Thin wrapper around a C-style nifti_image struct that allows C++-style destruction.

Reference counting is used to allow multiple NifiImage objects to wrap the same nifti_image pointer, akin to a std::shared_ptr (but without requiring C++11).

Author
Jon Clayden (code@.nosp@m.clay.nosp@m.den.o.nosp@m.rg)

Constructor & Destructor Documentation

◆ NiftiImage() [1/5]

RNifti::NiftiImage::NiftiImage ( const NiftiImage source,
const bool  copy = true 
)
inline

Copy constructor.

Parameters
sourceAnother NiftiImage object
copyIf true, the underlying nifti_image will be copied; otherwise the new object wraps the same nifti_image and increments the shared reference count

◆ NiftiImage() [2/5]

RNifti::NiftiImage::NiftiImage ( const Block source)
inline

Initialise from a block, copying in the data.

Parameters
sourceA Block object, referring to part of another NiftiImage

◆ NiftiImage() [3/5]

RNifti::NiftiImage::NiftiImage ( nifti_image *const  image,
const bool  copy = false 
)
inline

Initialise using an existing nifti_image pointer.

Parameters
imageAn existing nifti_image pointer, possibly NULL
copyIf true, the image data will be copied; otherwise this object just wraps the pointer passed to it

◆ NiftiImage() [4/5]

RNifti::NiftiImage::NiftiImage ( const std::string &  path,
const bool  readData = true 
)
inline

Initialise using a path string.

Parameters
pathA string specifying a path to a valid NIfTI-1 file, possibly gzipped
readDataIf true, the data will be read as well as the metadata
Exceptions
runtime_errorIf reading from the file fails

◆ NiftiImage() [5/5]

RNifti::NiftiImage::NiftiImage ( const std::string &  path,
const std::vector< int > &  volumes 
)
inline

Initialise using a path string and sequence of required volumes.

Parameters
pathA string specifying a path to a valid NIfTI-1 file, possibly gzipped
volumesThe volumes to read in (squashing all dimensions above the third together)
Exceptions
runtime_errorIf reading from the file fails, or volumes is empty

Member Function Documentation

◆ acquire() [1/2]

void RNifti::NiftiImage::acquire ( nifti_image *const  image)
inlineprotected

Acquire the specified pointer to a nifti_image struct, taking (possibly shared) responsibility for freeing the associated memory.

If the object currently wraps another pointer, it will be released

Parameters
imageThe pointer to wrap

◆ acquire() [2/2]

void RNifti::NiftiImage::acquire ( const NiftiImage source)
inlineprotected

Acquire the same pointer as another NiftiImage, incrementing the shared reference count.

Parameters
sourceA reference to a NiftiImage

◆ block() [1/2]

const Block RNifti::NiftiImage::block ( const int  i) const
inline

Extract a block from the image.

Parameters
iThe block number required
Returns
A Block object
Note
slice and volume are variants of this function specific to 3D and 4D images, respectively, which may be preferred in some cases for clarity

◆ block() [2/2]

Block RNifti::NiftiImage::block ( const int  i)
inline

Extract a block from the image.

Parameters
iThe block number required
Returns
A Block object
Note
slice and volume are variants of this function specific to 3D and 4D images, respectively, which may be preferred in some cases for clarity

◆ changeDatatype() [1/2]

NiftiImage & RNifti::NiftiImage::changeDatatype ( const short  datatype,
const bool  useSlope = false 
)
inline

Change the datatype of the image, casting the pixel data if present.

Parameters
datatypeA NIfTI datatype code
useSlopeIf true, and conversion is to an integer type, the data will be rescaled and the image's slope and intercept set to capture the full range of original values
Returns
Self, after changing the datatype

◆ changeDatatype() [2/2]

NiftiImage & RNifti::NiftiImage::changeDatatype ( const std::string &  datatype,
const bool  useSlope = false 
)
inline

Change the datatype of the image, casting the pixel data if present.

Parameters
datatypeA string specifying the new datatype
useSlopeIf true, and conversion is to an integer type, the data will be rescaled and the image's slope and intercept set to capture the full range of original values
Returns
Self, after changing the datatype

◆ copy() [1/3]

void RNifti::NiftiImage::copy ( const nifti_image *  source)
inlineprotected

Copy the contents of a nifti_image to create a new image, acquiring the new pointer.

Parameters
sourceA pointer to a nifti_image

◆ copy() [2/3]

void RNifti::NiftiImage::copy ( const NiftiImage source)
inlineprotected

Copy the contents of another NiftiImage to create a new image, acquiring a new pointer.

Parameters
sourceA reference to a NiftiImage

◆ copy() [3/3]

void RNifti::NiftiImage::copy ( const Block source)
inlineprotected

Copy the contents of a Block to create a new image, acquiring a new pointer.

Parameters
sourceA reference to a Block

◆ dim()

std::vector<int> RNifti::NiftiImage::dim ( ) const
inline

Return the dimensions of the image.

Returns
A vector of integers giving the width in each dimension

◆ drop()

NiftiImage& RNifti::NiftiImage::drop ( )
inline

Drop unitary dimensions.

Returns
Self, after possibly reducing the dimensionality of the image
Note
This function differs from its R equivalent in only dropping unitary dimensions after the last nonunitary one

◆ dropData()

NiftiImage& RNifti::NiftiImage::dropData ( )
inline

Drop the data from the image, retaining only the metadata.

Returns
Self, after dropping the data

◆ fileVersion()

static int RNifti::NiftiImage::fileVersion ( const std::string &  path)
inlinestatic

Get the NIfTI format version used by the file at the specified path.

Parameters
pathA string specifying a file path
Returns
An integer: -1 if the file is not present or not valid, 0 for ANALYZE-7.5, or a value greater than 0 for NIfTI

◆ getData()

template<typename TargetType >
std::vector< TargetType > RNifti::NiftiImage::getData ( const bool  useSlope = true) const
inline

Extract a vector of data from the image, casting it to any required element type.

Parameters
useSlopeIf true, the default, then the data will be adjusted for the slope and intercept stored with the image, if any
Returns
A vector of data values, cast to the required type
Note
If the slope and intercept are applied, there is no guarantee that the adjusted values will fit within the requested type. No check is made for this

◆ isDataScaled()

bool RNifti::NiftiImage::isDataScaled ( ) const
inline

Determine whether nontrivial scale and slope parameters are set.

Returns
true if the object wraps an image pointer, its slope is not zero and the slope and intercept are not exactly one and zero; false otherwise

◆ isNull()

bool RNifti::NiftiImage::isNull ( ) const
inline

Determine whether or not the wrapped pointer is NULL.

Returns
true if the wrapped pointer is NULL; false otherwise

◆ isPersistent()

bool RNifti::NiftiImage::isPersistent ( ) const
inline

Determine whether or not the image is marked as persistent.

Returns
false, always
Deprecated:
The persistence mechanism has been replaced with reference counting, so this function will always return false. Use isShared instead.

◆ isShared()

bool RNifti::NiftiImage::isShared ( ) const
inline

Determine whether the wrapped pointer is shared with another NiftiImage.

Returns
true if the reference count is greater than 1; false otherwise

◆ nBlocks()

int RNifti::NiftiImage::nBlocks ( ) const
inline

Return the number of blocks in the image.

Returns
An integer giving the number of blocks in the image

◆ nDims()

int RNifti::NiftiImage::nDims ( ) const
inline

Return the number of dimensions in the image.

Returns
An integer giving the image dimensionality

◆ operator=() [1/2]

NiftiImage& RNifti::NiftiImage::operator= ( const NiftiImage source)
inline

Copy assignment operator, which copies from its argument.

Parameters
sourceAnother NiftiImage

◆ operator=() [2/2]

NiftiImage& RNifti::NiftiImage::operator= ( const Block source)
inline

Copy assignment operator, which allows a block to be used to replace the contents of a suitably sized image.

Parameters
sourceA reference to a suitable Block object

◆ pixdim()

std::vector<float> RNifti::NiftiImage::pixdim ( ) const
inline

Return the dimensions of the pixels or voxels in the image.

Returns
A vector of floating-point values giving the pixel width in each dimension

◆ reorient() [1/2]

NiftiImage & RNifti::NiftiImage::reorient ( const int  i,
const int  j,
const int  k 
)
inline

Reorient the image by permuting dimensions and potentially reversing some.

Parameters
i,j,kConstants such as NIFTI_L2R, NIFTI_P2A and NIFTI_I2S, giving the canonical axes to reorient to
Returns
Self, after reorientation
Note
The pixel data is reordered, but not resampled. The xform matrices will also be adjusted in line with the transformation

◆ reorient() [2/2]

NiftiImage & RNifti::NiftiImage::reorient ( const std::string &  orientation)
inline

Reorient the image by permuting dimensions and potentially reversing some.

Parameters
orientationA string containing some permutation of the letters L or R, P or A, I or S, giving the canonical axes to reorient to
Returns
Self, after reorientation
Note
The pixel data is reordered, but not resampled. The xform matrices will also be adjusted in line with the transformation

◆ replaceData()

template<typename SourceType >
NiftiImage & RNifti::NiftiImage::replaceData ( const std::vector< SourceType > &  data,
const short  datatype = DT_NONE 
)
inline

Replace the pixel data in the image with the contents of a vector.

Parameters
dataA data vector, whose elements will be cast to match the datatype of the image. An exception will be raised if this does not have a length matching the image
datatypeThe final datatype required. By default the existing datatype of the image is used
Returns
Self, after replacing the data

◆ rescale()

NiftiImage & RNifti::NiftiImage::rescale ( const std::vector< float > &  scales)
inline

Rescale the image, changing its image dimensions and pixel dimensions.

Parameters
scalesVector of scale factors along each dimension
Returns
Self, after rescaling the metadata
Note
No interpolation is performed on the pixel data, which is simply dropped

◆ setPersistence()

NiftiImage& RNifti::NiftiImage::setPersistence ( const bool  persistent)
inline

Mark the image as persistent, so that it can be passed back to R.

Parameters
persistentThe new persistence state of the object
Returns
A reference to the callee.
Deprecated:
The persistence mechanism has been replaced with reference counting, so this function no longer has any effect. Instead it returns *this, unmodified.

◆ setPixunits()

void RNifti::NiftiImage::setPixunits ( const std::vector< std::string > &  pixunits)
inlineprotected

Modify the pixel dimension units.

Parameters
pixunitsVector of new pixel units, specified using their standard abbreviations

◆ slice() [1/2]

const Block RNifti::NiftiImage::slice ( const int  i) const
inline

Extract a slice block from a 3D image.

Parameters
iThe slice number required
Returns
A Block object

◆ slice() [2/2]

Block RNifti::NiftiImage::slice ( const int  i)
inline

Extract a slice block from a 3D image.

Parameters
iThe slice number required
Returns
A Block object

◆ toFile() [1/2]

void RNifti::NiftiImage::toFile ( const std::string  fileName,
const short  datatype = DT_NONE 
) const
inline

Write the image to a NIfTI-1 file.

Parameters
fileNameThe file name to write to, with appropriate suffix (e.g. ".nii.gz")
datatypeThe datatype to use when writing the file

◆ toFile() [2/2]

void RNifti::NiftiImage::toFile ( const std::string  fileName,
const std::string &  datatype 
) const
inline

Write the image to a NIfTI-1 file.

Parameters
fileNameThe file name to write to, with appropriate suffix (e.g. ".nii.gz")
datatypeThe datatype to use when writing the file, or "auto"

◆ updatePixdim()

void RNifti::NiftiImage::updatePixdim ( const std::vector< float > &  pixdim)
inlineprotected

Modify the pixel dimensions, and potentially the xform matrices to match.

Parameters
pixdimVector of new pixel dimensions

◆ volume() [1/2]

const Block RNifti::NiftiImage::volume ( const int  i) const
inline

Extract a volume block from a 4D image.

Parameters
iThe volume number required
Returns
A Block object

◆ volume() [2/2]

Block RNifti::NiftiImage::volume ( const int  i)
inline

Extract a volume block from a 4D image.

Parameters
iThe volume number required
Returns
A Block object

◆ xform()

mat44 RNifti::NiftiImage::xform ( const bool  preferQuaternion = true) const
inline

Obtain an xform matrix, indicating the orientation of the image.

Parameters
preferQuaternionIf true, use the qform matrix in preference to the sform
Returns
A 4x4 matrix

◆ xformToRotation()

static mat33 RNifti::NiftiImage::xformToRotation ( const mat44  matrix)
inlinestatic

Extract the pure rotation part of a 4x4 xform matrix.

Parameters
matrixAn xform matrix
Returns
A 3x3 rotation matrix

◆ xformToString()

static std::string RNifti::NiftiImage::xformToString ( const mat44  matrix)
inlinestatic

Convert a 4x4 xform matrix to a string describing its canonical axes.

Parameters
matrixAn xform matrix
Returns
A string containing three characters

The documentation for this class was generated from the following file: