Developer documentation
Version 3.0.3-105-gd3941f44
MR::Image< ValueType > Class Template Reference

functions and classes related to image data input/output More...

#include "image.h"

Inheritance diagram for MR::Image< ValueType >:

Classes

class  Buffer
 

Public Types

using value_type = ValueType
 

Public Member Functions

void * operator new (std::size_t size)
 
void * operator new[] (std::size_t size)
 
void operator delete (void *ptr)
 
void operator delete[] (void *ptr)
 
 Image ()
 
 Image (const Image &)=default
 
 Image (Image &&)=default
 
Imageoperator= (const Image &image)=default
 
Imageoperator= (Image &&)=default
 
 ~Image ()
 
 Image (const std::shared_ptr< Buffer > &, const Stride::List &=Stride::List())
 used internally to instantiate Image objects More...
 
bool valid () const
 
bool operator! () const
 
const KeyValueskeyval () const
 get generic key/value text attributes More...
 
const std::string & name () const
 
const transform_typetransform () const
 
size_t ndim () const
 
ssize_t size (size_t axis) const
 
default_type spacing (size_t axis) const
 
ssize_t stride (size_t axis) const
 
size_t offset () const
 offset to current voxel from start of data More...
 
void reset ()
 reset index to zero (origin) More...
 
ssize_t get_index (size_t axis) const
 get position of current voxel location along axis More...
 
void move_index (size_t axis, ssize_t increment)
 move position of current voxel location along axis More...
 
bool is_direct_io () const
 
ValueType get_value () const
 get voxel value at current location More...
 
void set_value (ValueType val)
 set voxel value at current location More...
 
std::string dump_to_mrtrix_file (std::string filename, bool use_multi_threading=true) const
 write out the contents of a direct IO image to file More...
 
Image with_direct_io (Stride::List with_strides=Stride::List())
 return a new Image using direct IO More...
 
Image with_direct_io (int axis)
 return a new Image using direct IO More...
 
ValueType * address () const
 return RAM address of current voxel More...
 

Static Public Member Functions

static Image open (const std::string &image_name, bool read_write_if_existing=false)
 
static Image create (const std::string &image_name, const Header &template_header, bool add_to_command_history=true)
 
static Image scratch (const Header &template_header, const std::string &label="scratch image")
 

Public Attributes

std::shared_ptr< Bufferbuffer
 shared reference to header/buffer More...
 

Protected Attributes

void * data_pointer
 pointer to data address whether in RAM or MMap More...
 
vector< ssize_t > x
 voxel indices More...
 
Stride::List strides
 voxel indices More...
 
size_t data_offset
 offset to currently pointed-to voxel More...
 

Friends

std::ostream & operator<< (std::ostream &stream, const Image &V)
 use for debugging More...
 

Detailed Description

template<typename ValueType>
class MR::Image< ValueType >

functions and classes related to image data input/output

Definition at line 39 of file image.h.

Member Typedef Documentation

◆ value_type

template<typename ValueType >
using MR::Image< ValueType >::value_type = ValueType

Definition at line 43 of file image.h.

Constructor & Destructor Documentation

◆ Image() [1/4]

template<typename ValueType >
MR::Image< ValueType >::Image ( )

◆ Image() [2/4]

template<typename ValueType >
MR::Image< ValueType >::Image ( const Image< ValueType > &  )
inlinedefault

◆ Image() [3/4]

template<typename ValueType >
MR::Image< ValueType >::Image ( Image< ValueType > &&  )
inlinedefault

◆ ~Image()

template<typename ValueType >
MR::Image< ValueType >::~Image ( )

◆ Image() [4/4]

template<typename ValueType >
MR::Image< ValueType >::Image ( const std::shared_ptr< Buffer > &  ,
const Stride::List = Stride::List() 
)

used internally to instantiate Image objects

Member Function Documentation

◆ address()

template<typename ValueType >
ValueType * MR::Image< ValueType >::address ( ) const
inline

return RAM address of current voxel

Note
this will only work if image access is direct (i.e. for a scratch image, with preloading, or when the data type is native and without scaling.

Definition at line 185 of file image.h.

◆ create()

template<typename ValueType >
static Image MR::Image< ValueType >::create ( const std::string &  image_name,
const Header template_header,
bool  add_to_command_history = true 
)
inlinestatic

Definition at line 192 of file image.h.

◆ dump_to_mrtrix_file()

template<typename ValueType >
std::string MR::Image< ValueType >::dump_to_mrtrix_file ( std::string  filename,
bool  use_multi_threading = true 
) const

write out the contents of a direct IO image to file

returns the name of the image - needed by display() to get the name of the temporary file to supply to MRView.

Note
this is not the recommended way to save an image - only use this function when you absolutely need to minimise RAM usage on write-out (this avoids any further buffering before write-out).
this will only work for images accessed using direct IO (i.e. opened as a scratch image, or using with_direct_io(), and only supports output to MRtrix format images (*.mif / *.mih). There is a chance that images opened in other ways may also use direct IO (e.g. if the datatype & strides match, and the image is single-file), you can check using the is_direct_io() method. If there is any possibility that this image might use indirect IO, you should use the save() function instead (and even then, it should only be used for debugging purposes).

◆ get_index()

template<typename ValueType >
ssize_t MR::Image< ValueType >::get_index ( size_t  axis) const
inline

get position of current voxel location along axis

Definition at line 80 of file image.h.

◆ get_value()

template<typename ValueType >
ValueType MR::Image< ValueType >::get_value ( ) const
inline

get voxel value at current location

Definition at line 87 of file image.h.

◆ is_direct_io()

template<typename ValueType >
bool MR::Image< ValueType >::is_direct_io ( ) const
inline

Definition at line 84 of file image.h.

◆ keyval()

template<typename ValueType >
const KeyValues & MR::Image< ValueType >::keyval ( ) const
inline

get generic key/value text attributes

Definition at line 60 of file image.h.

◆ move_index()

template<typename ValueType >
void MR::Image< ValueType >::move_index ( size_t  axis,
ssize_t  increment 
)
inline

move position of current voxel location along axis

Definition at line 82 of file image.h.

◆ name()

template<typename ValueType >
const std::string & MR::Image< ValueType >::name ( ) const
inline

Definition at line 62 of file image.h.

◆ ndim()

template<typename ValueType >
size_t MR::Image< ValueType >::ndim ( ) const
inline

Definition at line 65 of file image.h.

◆ offset()

template<typename ValueType >
size_t MR::Image< ValueType >::offset ( ) const
inline

offset to current voxel from start of data

Definition at line 71 of file image.h.

◆ open()

template<typename ValueType >
static Image MR::Image< ValueType >::open ( const std::string &  image_name,
bool  read_write_if_existing = false 
)
inlinestatic

Definition at line 189 of file image.h.

◆ operator delete()

template<typename ValueType >
void MR::Image< ValueType >::operator delete ( void *  ptr)
inline

Definition at line 41 of file image.h.

◆ operator delete[]()

template<typename ValueType >
void MR::Image< ValueType >::operator delete[] ( void *  ptr)
inline

Definition at line 41 of file image.h.

◆ operator new()

template<typename ValueType >
void * MR::Image< ValueType >::operator new ( std::size_t  size)
inline

Definition at line 41 of file image.h.

◆ operator new[]()

template<typename ValueType >
void * MR::Image< ValueType >::operator new[] ( std::size_t  size)
inline

Definition at line 41 of file image.h.

◆ operator!()

template<typename ValueType >
bool MR::Image< ValueType >::operator! ( ) const
inline

Definition at line 57 of file image.h.

◆ operator=() [1/2]

template<typename ValueType >
Image & MR::Image< ValueType >::operator= ( const Image< ValueType > &  image)
inlinedefault

◆ operator=() [2/2]

template<typename ValueType >
Image & MR::Image< ValueType >::operator= ( Image< ValueType > &&  )
inlinedefault

◆ reset()

template<typename ValueType >
void MR::Image< ValueType >::reset ( )
inline

reset index to zero (origin)

Definition at line 74 of file image.h.

◆ scratch()

template<typename ValueType >
static Image MR::Image< ValueType >::scratch ( const Header template_header,
const std::string &  label = "scratch image" 
)
inlinestatic

Definition at line 195 of file image.h.

◆ set_value()

template<typename ValueType >
void MR::Image< ValueType >::set_value ( ValueType  val)
inline

set voxel value at current location

Definition at line 92 of file image.h.

◆ size()

template<typename ValueType >
ssize_t MR::Image< ValueType >::size ( size_t  axis) const
inline

Definition at line 66 of file image.h.

◆ spacing()

template<typename ValueType >
default_type MR::Image< ValueType >::spacing ( size_t  axis) const
inline

Definition at line 67 of file image.h.

◆ stride()

template<typename ValueType >
ssize_t MR::Image< ValueType >::stride ( size_t  axis) const
inline

Definition at line 68 of file image.h.

◆ transform()

template<typename ValueType >
const transform_type & MR::Image< ValueType >::transform ( ) const
inline

Definition at line 63 of file image.h.

◆ valid()

template<typename ValueType >
bool MR::Image< ValueType >::valid ( ) const
inline

Definition at line 56 of file image.h.

◆ with_direct_io() [1/2]

template<typename ValueType >
Image MR::Image< ValueType >::with_direct_io ( int  axis)
inline

return a new Image using direct IO

this is a convenience function, performing the same function as with_direct_io(Stride::List). The difference is that the axis argument specifies which axis should be contiguous, or if axis is negative, that the spatial axes should be contiguous (the SpatiallyContiguous constexpr, set to -1, is provided for clarity). In other words:

auto image = Image<float>::open (filename).with_direct_io (3);
Image with_direct_io(Stride::List with_strides=Stride::List())
return a new Image using direct IO
static Image open(const std::string &image_name, bool read_write_if_existing=false)
Definition: image.h:189

is equivalent to:

auto header = Header::open (filename);
auto image = header.get_image<float>().with_direct_io (Stride::contiguous_along_axis (3, header));
List contiguous_along_axis(size_t axis)
convenience function to get volume-contiguous strides
Definition: stride.h:386

and

auto image = Image<float>::open (filename).with_direct_io (-1);
// or;
constexpr int SpatiallyContiguous
Definition: image.h:35

is equivalent to:

auto header = Header::open (filename);
auto image = header.get_image<float>().with_direct_io (Stride::contiguous_along_spatial_axes (header));
List contiguous_along_spatial_axes(const HeaderType &header)
convenience function to get spatially contiguous strides
Definition: stride.h:402

Definition at line 174 of file image.h.

◆ with_direct_io() [2/2]

template<typename ValueType >
Image MR::Image< ValueType >::with_direct_io ( Stride::List  with_strides = Stride::List())

return a new Image using direct IO

this will preload the data into RAM if the datatype on file doesn't match that on file (or if any scaling is applied to the data). The optional with_strides argument is used to additionally enforce preloading if the strides aren't compatible with those specified.

Example:

auto image = Header::open (argument[0]).get_image().with_direct_io();
vector< ParsedArgument > argument
the list of arguments parsed from the command-line
Note
this invalidate the invoking Image - do not use the original image in subsequent code.

Friends And Related Function Documentation

◆ operator<<

template<typename ValueType >
std::ostream & operator<< ( std::ostream &  stream,
const Image< ValueType > &  V 
)
friend

use for debugging

Definition at line 98 of file image.h.

Member Data Documentation

◆ buffer

template<typename ValueType >
std::shared_ptr<Buffer> MR::Image< ValueType >::buffer

shared reference to header/buffer

Definition at line 200 of file image.h.

◆ data_offset

template<typename ValueType >
size_t MR::Image< ValueType >::data_offset
protected

offset to currently pointed-to voxel

Definition at line 209 of file image.h.

◆ data_pointer

template<typename ValueType >
void* MR::Image< ValueType >::data_pointer
protected

pointer to data address whether in RAM or MMap

Definition at line 203 of file image.h.

◆ strides

template<typename ValueType >
Stride::List MR::Image< ValueType >::strides
protected

voxel indices

Definition at line 207 of file image.h.

◆ x

template<typename ValueType >
vector<ssize_t> MR::Image< ValueType >::x
protected

voxel indices

Definition at line 205 of file image.h.


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