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...
class | Extension
| Inner class wrapping a NIfTI extension, a weakly-specified standard for attaching additional metadata to NIfTI-1 and NIfTI-2 images. More...
class | Xform
| Inner class representing an xform matrix, which indicates the orientation and other spatial properties of an image. More...

## Public Member Functions
| NiftiImage ()
| Default constructor.
| NiftiImage (const NiftiImage &source, const bool copy=true)
| Copy constructor.
| NiftiImage (const Block &source)
| Initialise from a block, copying in the data.
| NiftiImage (nifti_image *const image, const bool copy=false)
| Initialise using an existing `nifti_image` pointer.
| NiftiImage (const nifti_1_header &header)
| Initialise using a NIfTI-1 header.
| NiftiImage (const std::vector< dim_t > &dim, const int datatype)
| Initialise from basic metadata, allocating and zeroing pixel data.
| NiftiImage (const std::vector< dim_t > &dim, const std::string &datatype)
| Initialise from basic metadata, allocating and zeroing pixel data.
| NiftiImage (const std::string &path, const bool readData=true)
| Initialise using a path string.
| NiftiImage (const std::string &path, const std::vector< dim_t > &volumes)
| Initialise using a path string and sequence of required volumes.
| 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.
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.
NiftiImage & | operator= (const Block &source)
| Copy assignment operator, which allows a block to be used to replace the contents of a suitably sized image.
NiftiImage & | setPersistence (const bool persistent)
| Mark the image as persistent, so that it can be passed back to R.
bool | isNull () const
| Determine whether or not the wrapped pointer is `NULL`.
bool | isShared () const
| Determine whether the wrapped pointer is shared with another `NiftiImage`.
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< dim_t > | dim () const
| Return the dimensions of the image.
std::vector< pixdim_t > | pixdim () const
| Return the dimensions of the pixels or voxels in the image.
NiftiImage & | drop ()
| Drop unitary dimensions.
const NiftiImageData | data () const
| Obtain the pixel data within the image.
NiftiImageData | data ()
| Obtain the pixel data within the image.
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.
NiftiImage & | changeDatatype (const int datatype, const bool useSlope=false)
| Change the datatype of the image, casting the pixel data if present.
NiftiImage & | changeDatatype (const std::string &datatype, const bool useSlope=false)
| Change the datatype of the image, casting the pixel data if present.
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.
NiftiImage & | replaceData (const NiftiImageData &data)
| Replace the pixel data in the image with the contents of a `NiftiImageData` object.
NiftiImage & | dropData ()
| Drop the data from the image, retaining only the metadata.
NiftiImage & | rescale (const std::vector< pixdim_t > &scales)
| Rescale the image, changing its image dimensions and pixel dimensions.
NiftiImage & | reorient (const int i, const int j, const int k)
| Reorient the image by permuting dimensions and potentially reversing some.
NiftiImage & | reorient (const std::string &orientation)
| Reorient the image by permuting dimensions and potentially reversing some.
NiftiImage & | update (const Rcpp::RObject &object)
| Update the image from an R array.
const Xform | xform (const bool preferQuaternion=true) const
| Obtain an xform matrix, indicating the orientation of the image.
const Xform | qform () const
| Access the qform matrix.
Xform | qform ()
| Access the qform matrix.
const Xform | sform () const
| Access the sform matrix.
Xform | sform ()
| Access the sform matrix.
dim_t | nBlocks () const
| Return the number of blocks in the image.
const Block | block (const int i) const
| Extract a block from the image.
Block | block (const int i)
| Extract a block from the image.
const Block | slice (const int i) const
| Extract a slice block from a 3D image.
Block | slice (const int i)
| Extract a slice block from a 3D image.
const Block | volume (const int i) const
| Extract a volume block from a 4D image.
Block | volume (const int i)
| Extract a volume block from a 4D image.
int | nChannels () const
| Return the number of colour channels used by the image.
size_t | nVoxels () const
| Return the number of voxels in the image.
int | nExtensions () const
| Return the number of extensions associated with the image.
std::list< Extension > | extensions (const int code=-1) const
| Return a list of the extensions associated with the image.
NiftiImage & | addExtension (const Extension &extension)
| Add an extension to the image.
NiftiImage & | replaceExtensions (const std::list< Extension > extensions)
| Replace all extensions with new ones.
NiftiImage & | dropExtensions ()
| Remove any extensions from the image.
std::pair< std::string, std::string > | toFile (const std::string fileName, const int datatype=DT_NONE, const int filetype=-1, const int compression=6) const
| Write the image to a NIfTI-1 file.
std::pair< std::string, std::string > | toFile (const std::string fileName, const std::string &datatype, const int filetype=-1, const int compression=6) const
| Write the image to a NIfTI-1 file.
Rcpp::RObject | toArray () const
| Create an R array from the image.
Rcpp::RObject | toPointer (const std::string label) const
| Create an internal image to pass back to R.
Rcpp::RObject | toArrayOrPointer (const bool internal, const std::string label) const
| A conditional method that calls either toArray or toPointer.

## Static Public Member Functions
static int | sexpTypeToNiftiType (const int sexpType)
| Convert between R `SEXP` object type and `nifti_image` datatype codes.
static int | fileVersion (const std::string &path)
| Get the NIfTI format version used by the file at the specified path.

## 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.
void | acquire (const NiftiImage &source)
| Acquire the same pointer as another `NiftiImage`, incrementing the shared reference count.
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.
void | copy (const NiftiImage &source)
| Copy the contents of another `NiftiImage` to create a new image, acquiring a new pointer.
void | copy (const Block &source)
| Copy the contents of a Block to create a new image, acquiring a new pointer.
void | initFromNiftiS4 (const Rcpp::RObject &object, const bool copyData=true)
| Initialise the object from an S4 object of class `"nifti"`.
void | initFromMriImage (const Rcpp::RObject &object, const bool copyData=true)
| Initialise the object from a reference object of class `"MriImage"`.
void | initFromList (const Rcpp::RObject &object)
| Initialise the object from an R list with named elements, which can only contain metadata.
void | initFromArray (const Rcpp::RObject &object, const bool copyData=true)
| Initialise the object from an R array.
void | initFromDims (const std::vector< dim_t > &dim, const int datatype)
| Initialise an empty object from basic metadata.
void | updatePixdim (const std::vector< pixdim_t > &pixdim)
| Modify the pixel dimensions, and potentially the xform matrices to match.
void | setPixunits (const std::vector< std::string > &pixunits)
| Modify the pixel dimension units.

## 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/9]

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

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

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

RNifti::NiftiImage::NiftiImage | ( | const nifti_1_header & | header | ) |
| inline

Initialise using a NIfTI-1 header.

Parameters

  header | A reference to a NIfTI-1 header struct

## ◆ NiftiImage() [5/9]

RNifti::NiftiImage::NiftiImage | ( | const std::vector< dim_t > & | 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() [6/9]

RNifti::NiftiImage::NiftiImage | ( | const std::vector< dim_t > & | 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() [7/9]

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

RNifti::NiftiImage::NiftiImage | ( | const std::string & | path,
|  | const std::vector< dim_t > & | 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() [9/9]

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 | ( | const NiftiImage & | source | ) |
| inline protected

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

Parameters

  source | A reference to a `NiftiImage`

## ◆ acquire() [2/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

## ◆ addExtension()

NiftiImage & RNifti::NiftiImage::addExtension | ( | const Extension & | extension | ) |
| inline

Add an extension to the image.

Parameters

  The | new image extension, an Extension object

Returns
  Self, with the extension appended

## ◆ block() [1/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

## ◆ block() [2/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

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

## ◆ copy() [2/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() [3/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`

## ◆ data() [1/2]

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

Obtain the pixel data within the image.

Returns
  A mutable `NiftiImageData` object encapsulating the data

## ◆ data() [2/2]

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

Obtain the pixel data within the image.

Returns
  A constant `NiftiImageData` object encapsulating the data

## ◆ dim()

std::vector< dim_t > 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.

This method invalidates any NiftiImageData objects referencing the old data

Returns
  Self, after dropping the data

## ◆ dropExtensions()

NiftiImage & RNifti::NiftiImage::dropExtensions | ( |  | ) |
| inline

Remove any extensions from the image.

Returns
  Self, with extensions removed

## ◆ extensions()

std::list< Extension > RNifti::NiftiImage::extensions | ( | const int | code = -1 | ) | const
| inline

Return a list of the extensions associated with the image.

Parameters

  code | Integer specifying the code corresponding to the extensions required. If -1, the default, all extensions are returned. There may be more than one extension with a given code

Returns
  A list of Extension objects

## ◆ fileVersion()

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

## ◆ 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< dim_t > & | 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()

dim_t 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

## ◆ nExtensions()

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

Return the number of extensions associated with the image.

Returns
  An integer giving the number of extensions

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

## ◆ operator=() [2/2]

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

Copy assignment operator, which copies from its argument.

Parameters

  source | Another `NiftiImage`

## ◆ pixdim()

std::vector< pixdim_t > 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

## ◆ qform() [1/2]

Xform RNifti::NiftiImage::qform | ( |  | ) |
| inline

Access the qform matrix.

Returns
  An Xform object

## ◆ qform() [2/2]

const Xform RNifti::NiftiImage::qform | ( |  | ) | const
| inline

Access the qform matrix.

Returns
  An Xform object

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

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

## ◆ replaceData() [2/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

## ◆ replaceExtensions()

NiftiImage & RNifti::NiftiImage::replaceExtensions | ( | const std::list< Extension > | extensions | ) |
| inline

Replace all extensions with new ones.

Parameters

  A | list of Extension objects

Returns
  Self, with the new extensions attached

## ◆ rescale()

NiftiImage & RNifti::NiftiImage::rescale | ( | const std::vector< pixdim_t > & | 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()

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

## ◆ sform() [1/2]

Xform RNifti::NiftiImage::sform | ( |  | ) |
| inline

Access the sform matrix.

Returns
  An Xform object

## ◆ sform() [2/2]

const Xform RNifti::NiftiImage::sform | ( |  | ) | const
| inline

Access the sform matrix.

Returns
  An Xform object

## ◆ slice() [1/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

## ◆ slice() [2/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

## ◆ 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 int | filetype = -1,
|  | const int | compression = 6 ) 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
  filetype | The file type to create: a `NIFTI_FTYPE` constant or -1. In the latter case the file name is used to determine the file type
  compression | The `zlib` compression level to use, if appropriate. Valid values are between 0 and 9

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 int | filetype = -1,
|  | const int | compression = 6 ) 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"
  filetype | The file type to create: a `NIFTI_FTYPE` constant or -1. In the latter case the file name is used to determine the file type
  compression | The `zlib` compression level to use, if appropriate. Valid values are between 0 and 9

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< pixdim_t > & | pixdim | ) |
| protected

Modify the pixel dimensions, and potentially the xform matrices to match.

Parameters

  pixdim | Vector of new pixel dimensions

## ◆ volume() [1/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

## ◆ volume() [2/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

## ◆ xform()

const Xform 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; otherwise prefer the sform

Returns
  An Xform object

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

- inst/include/RNifti/NiftiImage.h