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)
 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 SEXP object, const bool readData=true)
 Initialise from an R object. More...
 
virtual ~NiftiImage ()
 Destructor which frees the wrapped pointer, unless the object is marked as persistent.
 
 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...
 
void setPersistence (const bool persistent)
 Marked the image as persistent, so that it can be passed back to R. More...
 
bool isNull () const
 Determine whether or not the internal pointer is NULL.
 
bool isPersistent () const
 Determine whether or not the image is marked as persistent.
 
int nDims () const
 Return the number of dimensions in the image.
 
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
 Extract a vector of data from the image, casting it to any required element type.
 
void changeDatatype (const short datatype)
 Change the datatype of the image, casting the pixel data if present. More...
 
void changeDatatype (const std::string &datatype)
 Change the datatype of the image, casting the pixel data if present. More...
 
template<typename SourceType >
void replaceData (const std::vector< SourceType > &data, const short datatype=DT_NONE)
 Replace the pixel data in the image with the contents of a vector. More...
 
void dropData ()
 Drop the data from the image, retaining only the metadata.
 
void rescale (const std::vector< float > &scales)
 Rescale 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...
 
int nBlocks () const
 Return the number of blocks in the image.
 
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...
 
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 (const nifti_image *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/5]

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

Copy constructor.

Parameters
sourceAnother NiftiImage object

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

◆ 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]

void RNifti::NiftiImage::changeDatatype ( const short  datatype)
inline

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

Parameters
datatypeA NIfTI datatype code

◆ changeDatatype() [2/2]

void RNifti::NiftiImage::changeDatatype ( const std::string &  datatype)
inline

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

Parameters
datatypeA string specifying the new 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.

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.

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.

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

◆ headerToList()

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

Create an R list containing raw image metadata.

Returns
An R list

◆ initFromArray()

void RNifti::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 RNifti::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 RNifti::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 RNifti::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& 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

◆ replaceData()

template<typename SourceType >
void 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

◆ rescale()

void 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
Note
No interpolation is performed on the pixel data, which is simply dropped

◆ setPersistence()

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

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

Parameters
persistentThe new persistence state of the object

◆ 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

◆ sexpTypeToNiftiType()

static short RNifti::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 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

◆ toArray()

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

Create an R array from the image.

Returns
A numeric array object with an external pointer attribute

◆ toArrayOrPointer()

Rcpp::RObject RNifti::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 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"

◆ toPointer()

Rcpp::RObject RNifti::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 RNifti::NiftiImage::update ( const SEXP  array)
inline

Update the image from an R array.

Parameters
arrayAn R array object

◆ 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

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