RNifti: RNifti::NiftiImage Class Reference

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`.
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...
NiftiImage & | 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.
bool | isDataScaled () const
| Determine whether nontrivial scale and slope parameters are set.
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...
NiftiImage & | drop ()
| 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.
NiftiImage & | changeDatatype (const short datatype)
| Change the datatype of the image, casting the pixel data if present. More...
NiftiImage & | changeDatatype (const std::string &datatype)
| Change the datatype of the image, casting the pixel data if present. More...
template<typename SourceType >
NiftiImage & | 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...
NiftiImage & | dropData ()
| Drop the data from the image, retaining only the metadata.
NiftiImage & | rescale (const std::vector< float > &scales)
| Rescale the image, changing its image dimensions and pixel dimensions. More...
NiftiImage & | reorient (const int i, const int j, const int k)
| Reorient the image by permuting dimensions and potentially reversing some. More...
NiftiImage & | reorient (const std::string &orientation)
| Reorient the image by permuting dimensions and potentially reversing some. More...
NiftiImage & | 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...
static std::string | xformToString (const mat44 matrix)
| Convert a 4x4 xform matrix to a string describing its canonical axes. 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

  source | Another `NiftiImage` object

## § NiftiImage() [2/5]

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

Initialise from a block, copying in the data.

Parameters

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

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

RNifti::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() [5/5]

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

## § block() [1/2]

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

Extract a block from the image.

Parameters

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

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

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

Parameters

  datatype | A NIfTI datatype code

## § changeDatatype() [2/2]

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

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

Parameters

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

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

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

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

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

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

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

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

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

  source | A 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,k | Constants such as `NIFTI_L2R`, `NIFTI_P2A` and `NIFTI_I2S`, giving the canonical axes to reorient to

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

  orientation | A string containing some permutation of the letters `L` or `R`, `P` or `A`, `I` or `S`, giving the canonical axes to reorient to

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

  data | A 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
  datatype | The final datatype required. By default the existing datatype of the image is used

## § rescale()

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

Rescale 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()

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

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

Parameters

  persistent | The new persistence state of the object

## § setPixunits()

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

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

  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 RNifti::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 RNifti::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()

NiftiImage & RNifti::NiftiImage::update | ( | const SEXP | array | ) |
| inline

Update the image from an R array.

Parameters

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

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

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

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

  preferQuaternion | If `true`, use the qform matrix in preference to the sform

Returns
  A 4x4 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

  matrix | An xform matrix

Returns
  A string containing three characters

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

- inst/include/lib/NiftiImage.h