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::vector< int > &dim, const int datatype)
| Initialise from basic metadata, allocating and zeroing pixel data. More...
| NiftiImage (const std::vector< int > &dim, const std::string &datatype)
| Initialise from basic metadata, allocating and zeroing pixel data. 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...
| NiftiImage (const SEXP object, const bool readData=true, const bool readOnly=false)
| Initialise from an R object, retrieving an existing image from an external pointer attribute if available; otherwise constructing a new one from the R object itself. 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`.
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)
| 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...
NiftiImage & | drop ()
| Drop unitary dimensions. More...
const NiftiImageData | data () const
| Obtain the pixel data within the image. More...
NiftiImageData | data ()
| Obtain the pixel data within the image. 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...
NiftiImage & | changeDatatype (const int datatype, const bool useSlope=false)
| Change the datatype of the image, casting the pixel data if present. More...
NiftiImage & | changeDatatype (const std::string &datatype, const bool useSlope=false)
| Change the datatype of the image, casting the pixel data if present. More...
template<typename SourceType >
NiftiImage & | replaceData (const std::vector< SourceType > &data, const int datatype=DT_NONE)
| Replace the pixel data in the image with the contents of a vector. More...
NiftiImage & | replaceData (const NiftiImageData &data)
| Replace the pixel data in the image with the contents of a `NiftiImageData` object. More...
NiftiImage & | dropData ()
| Drop the data from the image, retaining only the metadata. More...
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 Rcpp::RObject &object)
| 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. 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...
int | nChannels () const
| Return the number of colour channels used by the image. More...
size_t | nVoxels () const
| Return the number of voxels in the image. More...
std::pair< std::string, std::string > | toFile (const std::string fileName, const int datatype=DT_NONE) const
| Write the image to a NIfTI-1 file. More...
std::pair< std::string, std::string > | 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 int | sexpTypeToNiftiType (const int sexpType)
| Convert between R `SEXP` object type and `nifti_image` datatype codes. More...
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 | 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 | initFromDims (const std::vector< int > &dim, const int datatype)
| Initialise an empty object from basic metadata. 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 `NiftiImage` 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/8]

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

Copy constructor.

Parameters

  source | Another `NiftiImage` object
  copy | If `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/8]

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/8]

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/8]

RNifti::NiftiImage::NiftiImage | ( | const std::vector< int > & | dim,
|  | const int | datatype
| ) |  |

Initialise from basic metadata, allocating and zeroing pixel data.

Parameters

  dim | A vector of image dimensions
  datatype | A datatype code for the image data

## ◆ NiftiImage() [5/8]

RNifti::NiftiImage::NiftiImage | ( | const std::vector< int > & | dim,
|  | const std::string & | datatype
| ) |  |

Initialise from basic metadata, allocating and zeroing pixel data.

Parameters

  dim | A vector of image dimensions
  datatype | A datatype string for the image data

## ◆ NiftiImage() [6/8]

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

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

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

Initialise using a path string and sequence of required volumes.

Parameters

  path | A string specifying a path to a valid NIfTI-1 file, possibly gzipped
  volumes | The volumes to read in (squashing all dimensions above the third together)

Exceptions

  runtime_error | If reading from the file fails, or `volumes` is empty

## ◆ NiftiImage() [8/8]

RNifti::NiftiImage::NiftiImage | ( | const SEXP | object,
|  | const bool | readData = `true`,
|  | const bool | readOnly = `false`
| ) |  |

Initialise from an R object, retrieving an existing image from an external pointer attribute if available; otherwise constructing a new one from the R object itself.

Parameters

  object | The source object
  readData | If `true`, the data will be retrieved as well as the metadata
  readOnly | If `true`, the caller asserts that its intent is read-only. Otherwise, if the `SEXP` may have multiple names at the R level (according to the `MAYBE_SHARED` R macro), an image retrieved from an external pointer will be duplicated to preserve R's usual semantics

## Member Function Documentation

## ◆ acquire() [1/2]

void RNifti::NiftiImage::acquire | ( | nifti_image *const | image | ) |
| protected

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

  image | The pointer to wrap

## ◆ acquire() [2/2]

void RNifti::NiftiImage::acquire | ( | const NiftiImage & | source | ) |
| inline protected

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

Parameters

  source | A reference to a `NiftiImage`

## ◆ 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 int | datatype,
|  | const bool | useSlope = `false`
| ) |  |

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

Parameters

  datatype | A NIfTI datatype code
  useSlope | If `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`
| ) |  |

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

Parameters

  datatype | A string specifying the new datatype
  useSlope | If `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 | ) |
| protected

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

Parameters

  source | A pointer to a `nifti_image`

## ◆ copy() [2/3]

void RNifti::NiftiImage::copy | ( | const NiftiImage & | source | ) |
| protected

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

Parameters

  source | A reference to a `NiftiImage`

## ◆ copy() [3/3]

void RNifti::NiftiImage::copy | ( | const Block & | source | ) |
| protected

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

Parameters

  source | A reference to a Block

## ◆ data() [1/2]

const NiftiImageData RNifti::NiftiImage::data | ( |  | ) | const
| inline

Obtain the pixel data within the image.

Returns
  A constant `NiftiImageData` object encapsulating the data

## ◆ data() [2/2]

NiftiImageData RNifti::NiftiImage::data | ( |  | ) |
| inline

Obtain the pixel data within the image.

Returns
  A mutable `NiftiImageData` object encapsulating the data

## ◆ 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 | ) |
| static

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

Parameters

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

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

Parameters

  useSlope | If `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

Deprecated:
  Use of the (ultimately more flexible) data methods is now preferred

## ◆ headerToList()

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

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`
| ) |  |
| protected

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

## ◆ initFromDims()

void RNifti::NiftiImage::initFromDims | ( | const std::vector< int > & | dim,
|  | const int | datatype
| ) |  |
| protected

Initialise an empty object from basic metadata.

Parameters

  dim | A vector of image dimensions
  datatype | A datatype code for the image data

## ◆ initFromList()

void RNifti::NiftiImage::initFromList | ( | const Rcpp::RObject & | object | ) |
| protected

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`
| ) |  |
| protected

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`
| ) |  |
| protected

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

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

## ◆ nChannels()

int RNifti::NiftiImage::nChannels | ( |  | ) | const
| inline

Return the number of colour channels used by the image.

Returns
  An integer giving the number of channels: generally 1, exception for RGB datatypes, which have 3 or 4, or the empty datatype, which has 0. Also 0 for null images

## ◆ nDims()

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

Return the number of dimensions in the image.

Returns
  An integer giving the image dimensionality

## ◆ nVoxels()

size_t RNifti::NiftiImage::nVoxels | ( |  | ) | const
| inline

Return the number of voxels in the image.

Returns
  An integer giving the number of voxels in the image

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

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

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

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

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

template<typename SourceType >

NiftiImage& RNifti::NiftiImage::replaceData | ( | const std::vector< SourceType > & | data,
|  | const int | datatype = `DT_NONE`
| ) |  |

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

Parameters

  data | A data vector, whose elements will be used to replace the image data
  datatype | The final datatype required. By default the existing datatype of the image is used

Exceptions

  runtime_error | If the length of the new data does not match the image

Returns
  Self, after replacing the data

## ◆ replaceData() [2/2]

NiftiImage& RNifti::NiftiImage::replaceData | ( | const NiftiImageData & | data | ) |

Replace the pixel data in the image with the contents of a `NiftiImageData` object.

Parameters

  data | A data object, whose elements will be case to match the datatype of the image

Exceptions

  runtime_error | If the length of the new data does not match the image

Returns
  Self, after replacing the data

## ◆ rescale()

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

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

Parameters

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

  persistent | The 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 | ) |
| protected

Modify the pixel dimension units.

Parameters

  pixunits | Vector of new pixel units, specified using their standard abbreviations

## ◆ sexpTypeToNiftiType()

static int RNifti::NiftiImage::sexpTypeToNiftiType | ( | const int | sexpType | ) |
| inline static

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

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

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]

std::pair<std::string,std::string> RNifti::NiftiImage::toFile | ( | const std::string | fileName,
|  | const int | datatype = `DT_NONE`
| ) |  | const

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

Returns
  A pair of strings, giving the final header and image paths in that order

## ◆ toFile() [2/2]

std::pair<std::string,std::string> RNifti::NiftiImage::toFile | ( | const std::string | fileName,
|  | const std::string & | datatype
| ) |  | const

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"

Returns
  A pair of strings, giving the final header and image paths in that order

## ◆ toPointer()

Rcpp::RObject RNifti::NiftiImage::toPointer | ( | const std::string | label | ) | const

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 Rcpp::RObject & | object | ) |

Update the image from an R array.

Parameters

  object | An R array or list object

Returns
  Self, after updating data and/or metadata

## ◆ updatePixdim()

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

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

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

## ◆ xformToRotation()

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

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

Parameters

  matrix | An xform matrix

Returns
  A 3x3 rotation matrix

## ◆ xformToString()

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

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/RNifti/NiftiImage.h