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 std::string &path, const std::vector< int > &volumes)
| Initialise using a path string and sequence of required volumes. 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 bool useSlope=true) const
| Extract a vector of data from the image, casting it to any required element type. More...
NiftiImage & | changeDatatype (const short 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 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...
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...

## Static Public Member Functions
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 | 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 | 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 std::string & | path,
|  | const std::vector< int > & | volumes
| ) |  |
| inline

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

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

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

## ◆ changeDatatype() [2/2]

NiftiImage & RNifti::NiftiImage::changeDatatype | ( | const std::string & | datatype,
|  | const bool | useSlope = `false`
| ) |  |
| inline

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

## ◆ copy() [1/3]

void RNifti::NiftiImage::copy | ( | const nifti_image * | source | ) |
| inline protected

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

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

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

## ◆ fileVersion()

static int RNifti::NiftiImage::fileVersion | ( | const std::string & | path | ) |
| inline 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
| inline

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

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

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

Modify the pixel dimension units.

Parameters

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

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

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

## ◆ updatePixdim()

void RNifti::NiftiImage::updatePixdim | ( | const std::vector< float > & | pixdim | ) |
| inline 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
| 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

## ◆ xformToRotation()

static mat33 RNifti::NiftiImage::xformToRotation | ( | const mat44 | matrix | ) |
| inline 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 | ) |
| inline 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/lib/NiftiImage.h