RNifti Fast R and C++ Access to NIfTI Images

Classes | Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
RNifti::NiftiImageData Class Reference

Wrapper class encapsulating a NIfTI data blob, with responsibility for handling data scaling and polymorphism. More...

`#include <NiftiImage.h>`

## Classes
struct | ConcreteTypeHandler
| Concrete inner class template defining behaviour specific to individual data types. More...
struct | ConcreteTypeHandler< rgba32_t, alpha >
struct | ConcreteTypeHandler< std::complex< ElementType >, false >
struct | Element
| Inner class representing a single element in the data blob. More...
class | Iterator
| Iterator type for `NiftiImageData`, with `Element` as its value type. More...
struct | TypeHandler
| Abstract inner class defining the type-specific functions required in concrete subclasses. More...

## Public Member Functions
| NiftiImageData ()
| Default constructor, creating an empty data object.
| NiftiImageData (void *data, const size_t length, const int datatype, const double slope=1.0, const double intercept=0.0)
| Primary constructor.
| NiftiImageData (nifti_image *image)
| Convenience constructor for a `nifti_image`.
| NiftiImageData (const NiftiImageData &source, const int datatype=DT_NONE)
| Copy constructor with optional type conversion.
template<class InputIterator>
| NiftiImageData (InputIterator from, InputIterator to, const int datatype)
| Iterator-based constructor.
virtual | ~NiftiImageData ()
| Destructor which frees the type handler, and the data blob if it is owned by this object.
NiftiImageData & | operator= (const NiftiImageData &source)
| Copy assignment operator.
void * | blob () const
| Return an opaque pointer to the blob.
int | datatype () const
| Return stored datatype code.
size_t | length () const
| Return the number of elements in the data.
size_t | size () const
| Return the number of elements in the data.
size_t | bytesPerPixel () const
| Return the number of bytes used per element, or zero if the datatype is undefined or the blob is `NULL`.
size_t | totalBytes () const
| Return the total size of the data blob, in bytes.
bool | isEmpty () const
| Determine whether or not the object is empty.
bool | isScaled () const
| Determine whether the object uses data scaling.
bool | isComplex () const
| Determine whether the datatype is complex.
bool | isFloatingPoint () const
| Determine whether the datatype is floating point.
bool | isInteger () const
| Determine whether the datatype is an integer type.
bool | isRgb () const
| Determine whether the datatype corresponds to an RGB type.
NiftiImageData | unscaled () const
| Return a similar object to the callee, but with the slope and intercept values reset.
NiftiImageData & | disown ()
| Disown the data blob, removing responsibility for freeing it upon destruction.
const Iterator | begin () const
| Obtain a constant iterator corresponding to the start of the blob.
const Iterator | end () const
| Obtain a constant iterator corresponding to the end of the blob.
Iterator | begin ()
| Obtain a mutable iterator corresponding to the start of the blob.
Iterator | end ()
| Obtain a mutable iterator corresponding to the end of the blob.
const Element | operator[] (const size_t i) const
| Indexing operator, returning a constant element.
Element | operator[] (const size_t i)
| Indexing operator, returning a mutable element.
void | minmax (double *min, double *max) const
| Calculate the minimum and maximum values in the blob, as doubles.

## Public Attributes
double | slope
| The slope term used to scale data values.
double | intercept
| The intercept term used to scale data values.

## Protected Member Functions
TypeHandler * | createHandler ()
| Create a concrete type handler appropriate to the datatype code stored with the data.
void | init (void *data, const size_t length, const int datatype, const double slope, const double intercept, const bool alloc=true)
| Initialiser method, used by constructors.
void | calibrateFrom (const NiftiImageData &data)
| Update the slope and intercept to cover the range of another data object.

## Protected Attributes
void * | dataPtr
| Opaque pointer to the underlying data blob.
int | _datatype
| Datatype code indicating the actual type of the elements.
TypeHandler * | handler
| Type handler, which is created to match the datatype.
size_t | _length
| The number of data elements in the blob.
bool | owner
| An indicator of whether this object is responsible for cleaning up the data.

## Detailed Description

Wrapper class encapsulating a NIfTI data blob, with responsibility for handling data scaling and polymorphism.

This class provides read/write data access, iterators, etc., which internally handle conversion to and from the data's native type. It can be linked to the data in a `nifti_image` or used independently.

Author
  Jon Clayden (code@.nosp@m.clay.nosp@m.den.o.nosp@m.rg)

## Constructor & Destructor Documentation

## ◆ NiftiImageData() [1/4]

RNifti::NiftiImageData::NiftiImageData | ( | void * | data,
|  | const size_t | length,
|  | const int | datatype,
|  | const double | slope = 1.0,
|  | const double | intercept = 0.0 )
| inline

Primary constructor.

Parameters

  data | A pointer to a pre-allocated data blob, or `NULL`. In the latter case, memory will be allocated by the object, and cleaned up at destruction unless it is disowned
  length | The number of elements in the blob
  datatype | The NIfTI datatype code corresponding to the type of the data elements
  slope | The slope parameter to use for data scaling, if any
  intercept | The intercept parameter to use for data scaling, if any

## ◆ NiftiImageData() [2/4]

RNifti::NiftiImageData::NiftiImageData | ( | nifti_image * | image | ) |
| inline

Convenience constructor for a `nifti_image`.

Parameters

  image | The image struct whose data the object will wrap

## ◆ NiftiImageData() [3/4]

RNifti::NiftiImageData::NiftiImageData | ( | const NiftiImageData & | source,
|  | const int | datatype = DT_NONE )
| inline

Copy constructor with optional type conversion.

Parameters

  source | Another `NiftiImageData` object to copy data from
  datatype | The datatype to convert to, or `DT_NONE`, the default, for no conversion. If the range of the source data cannot be represented by the chosen type, the slope and intercept parameters will be set to adjust the range

## ◆ NiftiImageData() [4/4]

template<class InputIterator>

RNifti::NiftiImageData::NiftiImageData | ( | InputIterator | from,
|  | InputIterator | to,
|  | const int | datatype )
| inline

Iterator-based constructor.

Parameters

  from | Iterator type representing the start of the source data to be copied
  to | Iterator type representing the end of the source data to be copied
  datatype | The NIfTI datatype to use within the data blob

## Member Function Documentation

## ◆ calibrateFrom()

void RNifti::NiftiImageData::calibrateFrom | ( | const NiftiImageData & | data | ) |
| inline protected

Update the slope and intercept to cover the range of another data object.

If the current object's datatype can capture the required range without scaling, the slope and intercept are simply reset

Parameters

  data | Another data object

## ◆ createHandler()

TypeHandler * RNifti::NiftiImageData::createHandler | ( |  | ) |
| inline protected

Create a concrete type handler appropriate to the datatype code stored with the data.

Returns
  The newly allocated type handler, or `NULL`

Exceptions

  runtime_error | If the current datatype is unsupported

## ◆ disown()

NiftiImageData & RNifti::NiftiImageData::disown | ( |  | ) |
| inline

Disown the data blob, removing responsibility for freeing it upon destruction.

Returns
  A reference to the modified callee

## ◆ init()

void RNifti::NiftiImageData::init | ( | void * | data,
|  | const size_t | length,
|  | const int | datatype,
|  | const double | slope,
|  | const double | intercept,
|  | const bool | alloc = true )
| inline protected

Initialiser method, used by constructors.

Parameters

  data | Pointer to a preallocated data blob, or `NULL`
  length | Number of elements in the blob
  datatype | NIfTI datatype code appropriate to the blob
  slope | Slope parameter for scaling values
  intercept | Intercept parameter for scaling values
  alloc | If `true`, the default, and `data` is `NULL`, memory will be allocated for the blob. If `false`, the blob will be `NULL` in this case

## ◆ isComplex()

bool RNifti::NiftiImageData::isComplex | ( |  | ) | const
| inline

Determine whether the datatype is complex.

Returns
  `true` if the data represents complex floating point values; `false` otherwise

## ◆ isEmpty()

bool RNifti::NiftiImageData::isEmpty | ( |  | ) | const
| inline

Determine whether or not the object is empty.

Returns
  `true` if the data pointer is `NULL`; `false` otherwise

## ◆ isFloatingPoint()

bool RNifti::NiftiImageData::isFloatingPoint | ( |  | ) | const
| inline

Determine whether the datatype is floating point.

Returns
  `true` if the data represents 32-bit or 64-bit floating point values; `false` otherwise

## ◆ isInteger()

bool RNifti::NiftiImageData::isInteger | ( |  | ) | const
| inline

Determine whether the datatype is an integer type.

Returns
  `true` if the data represents integers; `false` otherwise

## ◆ isRgb()

bool RNifti::NiftiImageData::isRgb | ( |  | ) | const
| inline

Determine whether the datatype corresponds to an RGB type.

Returns
  `true` if the data represents RGB colour values; `false` otherwise

## ◆ isScaled()

bool RNifti::NiftiImageData::isScaled | ( |  | ) | const
| inline

Determine whether the object uses data scaling.

Returns
  `true` if the slope and intercept parameters are set to nontrivial values; `false` otherwise

## ◆ minmax()

void RNifti::NiftiImageData::minmax | ( | double * | min,
|  | double * | max ) const
| inline

Calculate the minimum and maximum values in the blob, as doubles.

Parameters

  min | Pointer to the minimum value (output parameter). Will be set to zero if the datatype is unknown or the data is empty
  max | Pointer to the maximum value (output parameter). Will be set to zero if the datatype is unknown or the data is empty

## ◆ operator=()

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

Copy assignment operator.

Parameters

  source | Another `NiftiImageData` object, from which the data and metadata are copied

Returns
  A reference to the callee

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

Element RNifti::NiftiImageData::operator[] | ( | const size_t | i | ) |
| inline

Indexing operator, returning a mutable element.

Parameters

  i | Index value, where the first dimension moves fastest

Returns
  Mutable element proxy type

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

const Element RNifti::NiftiImageData::operator[] | ( | const size_t | i | ) | const
| inline

Indexing operator, returning a constant element.

Parameters

  i | Index value, where the first dimension moves fastest

Returns
  Constant element proxy type

## ◆ unscaled()

NiftiImageData RNifti::NiftiImageData::unscaled | ( |  | ) | const
| inline

Return a similar object to the callee, but with the slope and intercept values reset.

Returns
  A new `NiftiImageData` object, pointing to the same memory as the callee

## Member Data Documentation

## ◆ slope

double RNifti::NiftiImageData::slope

The slope term used to scale data values.

Ignored if zero.

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

- inst/include/RNifti/NiftiImage.h