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
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)
 Copy constructor. 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 SEXP object, const bool readData=true)
 Initialise from an R object. More...
 
 ~NiftiImage ()
 Destructor which frees the wrapped pointer, unless the object is marked as persistent.
 
 operator nifti_image * () const
 Allows a NiftiImage object to be treated as a pointer to a nifti_image.
 
nifti_image * operator-> () const
 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...
 
void setPersistence (const bool persistent)
 Allows the image to be marked as persistent, so that it can be passed back to R. More...
 
bool isNull () const
 Determines whether or not the internal pointer is NULL.
 
bool isPersistent () const
 Determines whether or not the image is marked as persistent.
 
int nDims () const
 Returns the number of dimensions in the image.
 
NiftiImagedrop ()
 Drop unitary dimensions. More...
 
void rescale (const std::vector< float > &scales)
 Rescales the image, changing its image dimensions and pixel dimensions. More...
 
void update (const SEXP array)
 Update the image from an R array. More...
 
mat44 xform (const bool preferQuaternion=true) const
 Obtain an xform matrix, indicating the orientation of 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) 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...
 
Rcpp::RObject toArray () const
 Create an R array from the image. More...
 
Rcpp::RObject toPointer (const std::string label) const
 Create an internal image to pass back to R. More...
 
Rcpp::RObject toArrayOrPointer (const bool internal, const std::string label) const
 A conditional method that calls either toArray or toPointer. More...
 
Rcpp::RObject headerToList () const
 Create an R list containing raw image metadata. More...
 

Static Public Member Functions

static short sexpTypeToNiftiType (const int sexpType)
 Convert between R SEXP object type and nifti_image datatype codes. More...
 

Protected Member Functions

void copy (nifti_image *const source)
 Copy the contents of a nifti_image to create a new image. More...
 
void copy (const NiftiImage &source)
 Copy the contents of another NiftiImage to create a new image. More...
 
void copy (const Block &source)
 Copy the contents of a Block to create a new image. More...
 
void initFromNiftiS4 (const Rcpp::RObject &object, const bool copyData=true)
 Initialise the object from an S4 object of class "nifti". More...
 
void initFromMriImage (const Rcpp::RObject &object, const bool copyData=true)
 Initialise the object from a reference object of class "MriImage". More...
 
void initFromList (const Rcpp::RObject &object)
 Initialise the object from an R list with named elements, which can only contain metadata. More...
 
void initFromArray (const Rcpp::RObject &object, const bool copyData=true)
 Initialise the object from an R array. 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.
 
bool persistent
 Marker of persistence, which determines whether the nifti_image should be freed on destruction.
 

Detailed Description

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

Author
Jon Clayden

Constructor & Destructor Documentation

§ NiftiImage() [1/4]

NiftiImage::NiftiImage ( const NiftiImage source)
inline

Copy constructor.

Parameters
sourceAnother NiftiImage object

§ NiftiImage() [2/4]

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() [3/4]

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() [4/4]

NiftiImage::NiftiImage ( const SEXP  object,
const bool  readData = true 
)
inline

Initialise from an R object.

Parameters
objectThe source object
readDataIf true, the data will be copied as well as the metadata

Member Function Documentation

§ copy() [1/3]

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

Copy the contents of a nifti_image to create a new image.

Parameters
sourceA pointer to a nifti_image

§ copy() [2/3]

void NiftiImage::copy ( const NiftiImage source)
inlineprotected

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

Parameters
sourceA reference to a NiftiImage

§ copy() [3/3]

void NiftiImage::copy ( const Block source)
inlineprotected

Copy the contents of a Block to create a new image.

Parameters
sourceA reference to a Block

§ drop()

NiftiImage& 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

§ headerToList()

Rcpp::RObject NiftiImage::headerToList ( ) const
inline

Create an R list containing raw image metadata.

Returns
An R list

§ initFromArray()

void NiftiImage::initFromArray ( const Rcpp::RObject &  object,
const bool  copyData = true 
)
inlineprotected

Initialise the object from an R array.

Parameters
objectThe source object
copyDataIf true, the data are copied in; otherwise just the metadata is extracted

§ initFromList()

void NiftiImage::initFromList ( const Rcpp::RObject &  object)
inlineprotected

Initialise the object from an R list with named elements, which can only contain metadata.

Parameters
objectThe source object

§ initFromMriImage()

void NiftiImage::initFromMriImage ( const Rcpp::RObject &  object,
const bool  copyData = true 
)
inlineprotected

Initialise the object from a reference object of class "MriImage".

Parameters
objectThe source object
copyDataIf true, the data are copied in; otherwise just the metadata is extracted

§ initFromNiftiS4()

void NiftiImage::initFromNiftiS4 ( const Rcpp::RObject &  object,
const bool  copyData = true 
)
inlineprotected

Initialise the object from an S4 object of class "nifti".

Parameters
objectThe source object
copyDataIf true, the data are copied in; otherwise just the metadata is extracted

§ operator=() [1/2]

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

Copy assignment operator, which copies from its argument.

Parameters
sourceAnother NiftiImage

§ operator=() [2/2]

NiftiImage& 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

§ rescale()

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

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

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

§ setPersistence()

void NiftiImage::setPersistence ( const bool  persistent)
inline

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

Parameters
persistentThe new persistence state of the object

§ setPixunits()

void 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

§ sexpTypeToNiftiType()

static short NiftiImage::sexpTypeToNiftiType ( const int  sexpType)
inlinestatic

Convert between R SEXP object type and nifti_image datatype codes.

Parameters
sexpTypeA numeric R SEXP type code
Returns
A nifti_image datatype code
Exceptions
runtime_errorIf a non-numeric type is passed

§ slice() [1/2]

const Block 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 NiftiImage::slice ( const int  i)
inline

Extract a slice block from a 3D image.

Parameters
iThe slice number required
Returns
A Block object

§ toArray()

Rcpp::RObject NiftiImage::toArray ( ) const
inline

Create an R array from the image.

Returns
A numeric array object with an external pointer attribute

§ toArrayOrPointer()

Rcpp::RObject NiftiImage::toArrayOrPointer ( const bool  internal,
const std::string  label 
) const
inline

A conditional method that calls either toArray or toPointer.

Parameters
internalIf true, toPointer will be called; otherwise toArray
labelA string labelling the image
Returns
An R object

§ toFile() [1/2]

void NiftiImage::toFile ( const std::string  fileName,
const short  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

§ toFile() [2/2]

void 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"

§ toPointer()

Rcpp::RObject NiftiImage::toPointer ( const std::string  label) const
inline

Create an internal image to pass back to R.

Parameters
labelA string labelling the image
Returns
An R character string with additional attributes

§ update()

void NiftiImage::update ( const SEXP  array)
inline

Update the image from an R array.

Parameters
arrayAn R array object

§ updatePixdim()

void 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 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 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 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

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