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`.
NiftiImage & | operator= (const NiftiImage &source)
| Copy assignment operator, which copies from its argument. More...
NiftiImage & | operator= (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.
NiftiImage & | drop ()
| 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

  source | Another `NiftiImage` object

## § NiftiImage() [2/4]

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

Initialise using an existing `nifti_image` pointer.

Parameters

  image | An existing `nifti_image` pointer, possibly `NULL`
  copy | If `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

  path | A string specifying a path to a valid NIfTI-1 file, possibly gzipped
  readData | If `true`, the data will be read as well as the metadata

Exceptions

  runtime_error | If reading from the file fails

## § NiftiImage() [4/4]

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

Initialise from an R object.

Parameters

  object | The source object
  readData | If `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

  source | A 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

  source | A 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

  source | A 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

  object | The source object
  copyData | If `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

  object | The 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

  object | The source object
  copyData | If `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

  object | The source object
  copyData | If `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

  source | Another `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

  source | A 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

  scales | Vector 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

  persistent | The new persistence state of the object

## § setPixunits()

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

Modify the pixel dimension units.

Parameters

  pixunits | Vector 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

  sexpType | A numeric R `SEXP` type code

Returns
  A `nifti_image` datatype code

Exceptions

  runtime_error | If 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

  i | The 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

  i | The 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

  internal | If `true`, toPointer will be called; otherwise toArray
  label | A 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

  fileName | The file name to write to, with appropriate suffix (e.g. ".nii.gz")
  datatype | The 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

  fileName | The file name to write to, with appropriate suffix (e.g. ".nii.gz")
  datatype | The 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

  label | A 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

  array | An 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

  pixdim | Vector 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

  i | The 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

  i | The 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

  preferQuaternion | If `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:

- inst/include/lib/NiftiImage.h