ome-files 0.2.2

Public Types | Public Member Functions | Private Attributes | List of all members
ome::files::PixelBuffer< T > Class Template Reference

Buffer for a specific pixel type. More...

`#include <ome/files/PixelBuffer.h>`

Inheritance diagram for ome::files::PixelBuffer< T >:
[legend]
Collaboration diagram for ome::files::PixelBuffer< T >:
[legend]

## Public Types
typedef T | value_type
| Pixel value type.
typedef boost::multi_array_ref< value_type, dimensions > | array_ref_type
| Type for multi-dimensional pixel array view referencing external data. More...
typedef boost::multi_array< value_type, dimensions > | array_type
| Type for multi-dimensional pixel array view. More...
Public Types inherited from ome::files::PixelBufferBase
typedef boost::multi_array_types::size_type | size_type
| Size type.
typedef boost::multi_array_types::index | index
| Index type.
typedef ome::compat::array< boost::multi_array_types::index, PixelBufferBase::dimensions > | indices_type
| Type used to index all dimensions in public interfaces.
typedef boost::general_storage_order< dimensions > | storage_order_type
| Storage ordering type for controlling pixel memory layout.
typedef boost::detail::multi_array::extent_gen< dimensions > | range_type
| Extent range type.

## Public Member Functions
| PixelBuffer ()
| Default constructor. More...
template<class ExtentList >
| PixelBuffer (const ExtentList &extents, ::ome::xml::model::enums::PixelType pixeltype=::ome::xml::model::enums::PixelType::UINT8, EndianType endiantype=ENDIAN_NATIVE, const storage_order_type &storage=PixelBufferBase::default_storage_order())
| Construct from extents (internal storage). More...
template<class ExtentList >
| PixelBuffer (value_type *pixeldata, const ExtentList &extents, ::ome::xml::model::enums::PixelType pixeltype=::ome::xml::model::enums::PixelType::UINT8, EndianType endiantype=ENDIAN_NATIVE, const storage_order_type &storage=PixelBufferBase::default_storage_order())
| Construct from extents (external storage). More...
| PixelBuffer (const range_type &range, ::ome::xml::model::enums::PixelType pixeltype=::ome::xml::model::enums::PixelType::UINT8, EndianType endiantype=ENDIAN_NATIVE, const storage_order_type &storage=PixelBufferBase::default_storage_order())
| Construct from ranges (internal storage). More...
| PixelBuffer (value_type *pixeldata, const range_type &range, ::ome::xml::model::enums::PixelType pixeltype=::ome::xml::model::enums::PixelType::UINT8, EndianType endiantype=ENDIAN_NATIVE, const storage_order_type &storage=PixelBufferBase::default_storage_order())
| Construct from ranges (external storage). More...
| PixelBuffer (const PixelBuffer &buffer)
| Copy constructor. More...
virtual | ~PixelBuffer ()
| Destructor.
array_ref_type & | array ()
| Get the pixel data. More...
const array_ref_type & | array () const
| Get the pixel data. More...
value_type * | data ()
| Get the raw data. More...
const value_type * | data () const
| Get the raw data. More...
bool | valid () const
| Check the buffer validity. More...
bool | managed () const
| Check if the buffer is internally managed. More...
size_type | num_elements () const
| Get the number of pixel elements in the multi-dimensional array.
size_type | num_dimensions () const
| Get the number of dimensions in the multi-dimensional array.
const size_type * | shape () const
| Get the shape of the multi-dimensional array. More...
const boost::multi_array_types::index * | strides () const
| Get the strides of the multi-dimensional array. More...
const boost::multi_array_types::index * | index_bases () const
| Get the index bases of the multi-dimensional array. More...
const value_type * | origin () const
| Get the origin of the array. More...
const storage_order_type & | storage_order () const
| Get the array storage order. More...
PixelBuffer & | operator= (const PixelBuffer &rhs)
| Assign a pixel buffer. More...
PixelBuffer & | operator= (const array_ref_type &rhs)
| Assign a pixel buffer. More...
bool | operator== (const PixelBuffer &rhs) const
| Compare a pixel buffer for equality. More...
bool | operator== (const array_ref_type &rhs) const
| Compare a pixel buffer for equality with a multiarray. More...
bool | operator!= (const PixelBuffer &rhs) const
| Compare a pixel buffer for inequality. More...
bool | operator!= (const array_ref_type &rhs) const
| Compare a pixel buffer for inequality with a multiarray. More...
bool | operator< (const PixelBuffer &rhs) const
| Less than comparison with a pixel buffer. More...
bool | operator< (const array_ref_type &rhs) const
| Less than comparison with a multiarray. More...
bool | operator<= (const PixelBuffer &rhs) const
| Less than or equal comparison with a pixel buffer. More...
bool | operator<= (const array_ref_type &rhs) const
| Less than or equal comparison with a multiarray. More...
bool | operator> (const PixelBuffer &rhs) const
| Greater than comparison with a pixel buffer. More...
bool | operator> (const array_ref_type &rhs) const
| Greater than comparison with a multiarray. More...
bool | operator>= (const PixelBuffer &rhs) const
| Greater than or equal comparison with a pixel buffer. More...
bool | operator>= (const array_ref_type &rhs) const
| Greater than or equal comparison with a multiarray. More...
template<typename InputIterator >
void | assign (InputIterator begin, InputIterator end)
| Assign pixel values. More...
value_type & | at (const indices_type &indices)
| Get the pixel value at an index. More...
const value_type & | at (const indices_type &indices) const
| Get the pixel value at an index. More...
template<class charT , class traits >
void | read (std::basic_istream< charT, traits > &stream)
| Read raw pixel data from a stream in physical storage order. More...
template<class charT , class traits >
void | write (std::basic_ostream< charT, traits > &stream) const
| Write raw pixel data to a stream in physical storage order. More...
Public Member Functions inherited from ome::files::PixelBufferBase
virtual | ~PixelBufferBase ()
| Destructor.
::ome::xml::model::enums::PixelType | pixelType () const
| Get the pixel type in use. More...
EndianType | endianType () const
| Get the endian type in use. More...

## Private Attributes
boost::variant< ome::compat::shared_ptr< array_type >, ome::compat::shared_ptr< array_ref_type > > | multiarray
| Multi-dimensional pixel array. More...

## Additional Inherited Members
Static Public Member Functions inherited from ome::files::PixelBufferBase
static storage_order_type | make_storage_order (ome::xml::model::enums::DimensionOrder order, bool interleaved)
| Generate storage ordering for a given dimension order. More...
static storage_order_type | default_storage_order ()
| Generate default storage ordering. More...
Static Public Attributes inherited from ome::files::PixelBufferBase
static const uint16_t | dimensions = 9
| Total number of supported dimensions.
Protected Member Functions inherited from ome::files::PixelBufferBase
| PixelBufferBase (::ome::xml::model::enums::PixelType pixeltype, EndianType endiantype)
| Constructor. More...

## Detailed Description

### template<typename T>
class ome::files::PixelBuffer< T >

Buffer for a specific pixel type.

The purpose of this class is to allow transfer of pixel data of specific type and endianness, and of any dimensionality.

Internally, multi-dimensional order is achieved using `Boost.MultiArray`. The `MultiArray` data buffer is provided internally by default, but may also be provided externally, for example from a memory-mapped file.

Nine dimensions are currently supported.

See also
  Dimensions for the logical dimension ordering.

The logical dimension ordering is the order used by the interface. However, the storage ordering in memory may be completely different. These may differ when:

- the file format uses a different ordering, including direct memory-mapping of the raw pixel data
- the consumer of the data requires a specific ordering, for example to ensure optimal performance of algorithms iterating over the pixel data

If the order the data is accessed in differs from the underlying storage order, there may be a significant performance cost. It is recommended that users should query the storage ordering to iterate over the pixels in the optimal order or require a specific ordering. Reordering the data may also bear a significant cost.

Todo:
  Add support for subsetting dimensions.

## Member Typedef Documentation

## § array_ref_type

template<typename T>

typedef boost::multi_array_ref<value_type, dimensions> ome::files::PixelBuffer< T >::array_ref_type

Type for multi-dimensional pixel array view referencing external data.

This type is always a view over a separate buffer.

## § array_type

template<typename T>

typedef boost::multi_array<value_type, dimensions> ome::files::PixelBuffer< T >::array_type

Type for multi-dimensional pixel array view.

This type uses an internal data buffer.

## Constructor & Destructor Documentation

## § PixelBuffer() [1/6]

template<typename T>

ome::files::PixelBuffer< T >::PixelBuffer | ( |  | ) |
| inlineexplicit

Default constructor.

This constructs a pixel buffer of size 1 in all dimensions. The desired size should be set after construction.

## § PixelBuffer() [2/6]

template<typename T>
template<class ExtentList >

ome::files::PixelBuffer< T >::PixelBuffer | ( | const ExtentList & | extents,
|  | ::ome::xml::model::enums::PixelType | pixeltype = `::ome::xml::model::enums::PixelType::UINT8`,
|  | EndianType | endiantype = `ENDIAN_NATIVE`,
|  | const storage_order_type & | storage = `PixelBufferBase::default_storage_order()`
| ) |  |
| inlineexplicit

Construct from extents (internal storage).

Storage for the buffer will be allocated internally.

Parameters

  extents | the extent of each dimension.
  pixeltype | the pixel type to store.
  endiantype | the required endianness of the pixel type.
  storage | the storage ordering, defaulting to C array storage ordering.

## § PixelBuffer() [3/6]

template<typename T>
template<class ExtentList >

ome::files::PixelBuffer< T >::PixelBuffer | ( | value_type * | pixeldata,
|  | const ExtentList & | extents,
|  | ::ome::xml::model::enums::PixelType | pixeltype = `::ome::xml::model::enums::PixelType::UINT8`,
|  | EndianType | endiantype = `ENDIAN_NATIVE`,
|  | const storage_order_type & | storage = `PixelBufferBase::default_storage_order()`
| ) |  |
| inlineexplicit

Construct from extents (external storage).

Storage for the buffer must be pre-allocated by the caller and must exist for the lifetime of this object.

Parameters

  pixeldata | the externally-provided storage for pixel data.
  extents | the extent of each dimension.
  pixeltype | the pixel type to store.
  endiantype | the required endianness of the pixel type.
  storage | the storage ordering, defaulting to C array storage ordering.

## § PixelBuffer() [4/6]

template<typename T>

ome::files::PixelBuffer< T >::PixelBuffer | ( | const range_type & | range,
|  | ::ome::xml::model::enums::PixelType | pixeltype = `::ome::xml::model::enums::PixelType::UINT8`,
|  | EndianType | endiantype = `ENDIAN_NATIVE`,
|  | const storage_order_type & | storage = `PixelBufferBase::default_storage_order()`
| ) |  |
| inlineexplicit

Construct from ranges (internal storage).

Storage for the buffer will be allocated internally.

Parameters

  range | the range of each dimension.
  pixeltype | the pixel type to store.
  endiantype | the required endianness of the pixel type.
  storage | the storage ordering, defaulting to C array storage ordering.

## § PixelBuffer() [5/6]

template<typename T>

ome::files::PixelBuffer< T >::PixelBuffer | ( | value_type * | pixeldata,
|  | const range_type & | range,
|  | ::ome::xml::model::enums::PixelType | pixeltype = `::ome::xml::model::enums::PixelType::UINT8`,
|  | EndianType | endiantype = `ENDIAN_NATIVE`,
|  | const storage_order_type & | storage = `PixelBufferBase::default_storage_order()`
| ) |  |
| inlineexplicit

Construct from ranges (external storage).

Storage for the buffer must be pre-allocated by the caller and must exist for the lifetime of this object.

Parameters

  pixeldata | the externally-provided storage for pixel data.
  range | the range of each dimension.
  pixeltype | the pixel type to store.
  endiantype | the required endianness of the pixel type.
  storage | the storage ordering, defaulting to C array storage ordering.

## § PixelBuffer() [6/6]

template<typename T>

ome::files::PixelBuffer< T >::PixelBuffer | ( | const PixelBuffer< T > & | buffer | ) |
| inlineexplicit

Copy constructor.

Note that due to the use of shared pointers this only performs a shallow copy.

Parameters

  buffer | the buffer to copy.

## Member Function Documentation

## § array() [1/2]

template<typename T >

PixelBuffer< T >::array_ref_type & ome::files::PixelBuffer< T >::array | ( |  | ) |

Get the pixel data.

Returns
  the multidimensional pixel data array; this value will never be null.

Referenced by ome::files::PixelBuffer< T >::operator!=(), ome::files::PixelBuffer< T >::operator<(), ome::files::PixelBuffer< T >::operator<=(), ome::files::PixelBuffer< T >::operator=(), ome::files::PixelBuffer< T >::operator==(), ome::files::PixelBuffer< T >::operator>(), and ome::files::PixelBuffer< T >::operator>=().

Here is the caller graph for this function:

## § array() [2/2]

template<typename T >

const PixelBuffer< T >::array_ref_type & ome::files::PixelBuffer< T >::array | ( |  | ) | const

Get the pixel data.

Returns
  the multidimensional pixel data array; this value will never be null.

References ome::files::PixelBuffer< T >::read(), and ome::files::PixelBuffer< T >::write().

## § assign()

template<typename T>
template<typename InputIterator >

void ome::files::PixelBuffer< T >::assign | ( | InputIterator | begin,
|  | InputIterator | end
| ) |  |
| inline

Assign pixel values.

Note that the range to assign must be equal to num_elements().

Parameters

  begin | the start of the range to assign.
  end | the end of the range to assign.

## § at() [1/2]

template<typename T>

value_type& ome::files::PixelBuffer< T >::at | ( | const indices_type & | indices | ) |
| inline

Get the pixel value at an index.

Note
  If the index is out of bounds, an assertion failure will immediately abort the program, so take care to ensure it is always valid.

Parameters

  indices | the multi-dimensional array index.

Returns
  a reference to the pixel value.

## § at() [2/2]

template<typename T>

const value_type& ome::files::PixelBuffer< T >::at | ( | const indices_type & | indices | ) | const
| inline

Get the pixel value at an index.

Note
  If the index is out of bounds, an assertion failure will immediately abort the program, so take care to ensure it is always valid.

Parameters

  indices | the multi-dimensional array index.

Returns
  a constant reference to the pixel value.

## § data() [1/2]

template<typename T>

value_type* ome::files::PixelBuffer< T >::data | ( |  | ) |
| inline

Get the raw data.

This is the buffer referenced by the multidimensional pixel data array.

Returns
  a pointer to the raw data buffer.

## § data() [2/2]

template<typename T>

const value_type* ome::files::PixelBuffer< T >::data | ( |  | ) | const
| inline

Get the raw data.

This is the buffer referenced by the multidimensional pixel data array.

Returns
  a pointer to the raw data buffer.

## § index_bases()

template<typename T>

const boost::multi_array_types::index* ome::files::PixelBuffer< T >::index_bases | ( |  | ) | const
| inline

Get the index bases of the multi-dimensional array.

The index bases are the numeric index of the first element for each array dimension of the multi-dimensional array.

Returns
  an array of index bases (size is the dimension size).

## § managed()

template<typename T>

bool ome::files::PixelBuffer< T >::managed | ( |  | ) | const
| inline

Check if the buffer is internally managed.

Returns
  `true` if the `MultiArray` data is managed internally (i.e. is a `multi_array`) or `false` if not managed (i.e. is a `multi_array_ref`).

## § operator!=() [1/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator!= | ( | const PixelBuffer< T > & | rhs | ) | const
| inline

Compare a pixel buffer for inequality.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

References ome::files::PixelBuffer< T >::array().

## § operator!=() [2/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator!= | ( | const array_ref_type & | rhs | ) | const
| inline

Compare a pixel buffer for inequality with a multiarray.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

## § operator<() [1/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator< | ( | const PixelBuffer< T > & | rhs | ) | const
| inline

Less than comparison with a pixel buffer.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

References ome::files::PixelBuffer< T >::array().

## § operator<() [2/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator< | ( | const array_ref_type & | rhs | ) | const
| inline

Less than comparison with a multiarray.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

## § operator<=() [1/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator<= | ( | const PixelBuffer< T > & | rhs | ) | const
| inline

Less than or equal comparison with a pixel buffer.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

References ome::files::PixelBuffer< T >::array().

## § operator<=() [2/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator<= | ( | const array_ref_type & | rhs | ) | const
| inline

Less than or equal comparison with a multiarray.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

## § operator=() [1/2]

template<typename T>

PixelBuffer& ome::files::PixelBuffer< T >::operator= | ( | const PixelBuffer< T > & | rhs | ) |
| inline

Assign a pixel buffer.

The dimension extents must be compatible, but the storage ordering does not. The buffer contents will be assigned in the logical order rather than the storage order.

Parameters

  rhs | the pixel buffer to assign.

Returns
  the assigned buffer.

References ome::files::PixelBuffer< T >::array().

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

template<typename T>

PixelBuffer& ome::files::PixelBuffer< T >::operator= | ( | const array_ref_type & | rhs | ) |
| inline

Assign a pixel buffer.

The dimension extents must be compatible, but the storage ordering does not. The buffer contents will be assigned in the logical order rather than the storage order.

Parameters

  rhs | the pixel buffer to assign.

Returns
  the assigned buffer.

## § operator==() [1/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator== | ( | const PixelBuffer< T > & | rhs | ) | const
| inline

Compare a pixel buffer for equality.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if equal, `false` if not equal.

References ome::files::PixelBuffer< T >::array().

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

template<typename T>

bool ome::files::PixelBuffer< T >::operator== | ( | const array_ref_type & | rhs | ) | const
| inline

Compare a pixel buffer for equality with a multiarray.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if equal, `false` if not equal.

## § operator>() [1/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator> | ( | const PixelBuffer< T > & | rhs | ) | const
| inline

Greater than comparison with a pixel buffer.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

References ome::files::PixelBuffer< T >::array().

## § operator>() [2/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator> | ( | const array_ref_type & | rhs | ) | const
| inline

Greater than comparison with a multiarray.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

## § operator>=() [1/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator>= | ( | const PixelBuffer< T > & | rhs | ) | const
| inline

Greater than or equal comparison with a pixel buffer.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

References ome::files::PixelBuffer< T >::array().

## § operator>=() [2/2]

template<typename T>

bool ome::files::PixelBuffer< T >::operator>= | ( | const array_ref_type & | rhs | ) | const
| inline

Greater than or equal comparison with a multiarray.

Parameters

  rhs | the pixel buffer to compare with.

Returns
  `true` if not equal, `false` if equal.

## § origin()

template<typename T>

const value_type* ome::files::PixelBuffer< T >::origin | ( |  | ) | const
| inline

Get the origin of the array.

This is the address of the element at ``[0][0][0][0][0][0][0][0][0]. Note that this is not always the buffer start address, depending upon the dimension ordering.

Returns
  the address of the array origin.

## § read()

template<typename T>
template<class charT , class traits >

void ome::files::PixelBuffer< T >::read | ( | std::basic_istream< charT, traits > & | stream | ) |
| inline

Read raw pixel data from a stream in physical storage order.

Note that the pixels will be read in the physical storage order. This will typically be a contiguous read, but this is not guaranteed. The current implementation iterates over each pixel and so may be slower than strictly necessary.

Parameters

  stream | the stream to read from.

Referenced by ome::files::PixelBuffer< T >::array().

Here is the caller graph for this function:

## § shape()

template<typename T>

const size_type* ome::files::PixelBuffer< T >::shape | ( |  | ) | const
| inline

Get the shape of the multi-dimensional array.

The shape is the extent of each array dimension.

Returns
  an array of extents (size is the dimension size).

## § storage_order()

template<typename T>

const storage_order_type& ome::files::PixelBuffer< T >::storage_order | ( |  | ) | const
| inline

Get the array storage order.

Returns
  the storage order.

## § strides()

template<typename T>

const boost::multi_array_types::index* ome::files::PixelBuffer< T >::strides | ( |  | ) | const
| inline

Get the strides of the multi-dimensional array.

The strides are the stride associated with each array dimension.

Returns
  an array of strides (size is the dimension size).

## § valid()

template<typename T>

bool ome::files::PixelBuffer< T >::valid | ( |  | ) | const
| inline

Check the buffer validity.

This tests if the `MultiArray` is not null, and hence safe to use. Note that this is not a guarantee of safety in the case of using an externally managed data buffer, in which case the external buffer must still be valid in addition.

Returns
  `true` if not null, `false` if null.

## § write()

template<typename T>
template<class charT , class traits >

void ome::files::PixelBuffer< T >::write | ( | std::basic_ostream< charT, traits > & | stream | ) | const
| inline

Write raw pixel data to a stream in physical storage order.

Note that the pixels will be written in the physical storage order. This will typically be a contiguous read, but this is not guaranteed. The current implementation iterates over each pixel and so may be slower than strictly necessary.

Parameters

  stream | the stream to write to.

Referenced by ome::files::PixelBuffer< T >::array().

Here is the caller graph for this function:

## Member Data Documentation

## § multiarray

template<typename T>

boost::variant<ome::compat::shared_ptr<array_type>, ome::compat::shared_ptr<array_ref_type> > ome::files::PixelBuffer< T >::multiarray
| private

Multi-dimensional pixel array.

This may be either a `multi_array` containing the data directly, or a `multi_array_ref` using an external buffer. If using an external buffer, the lifetime of the buffer must exceed that of this class instance.

Note that a `boost::variant` is used here because it's not possible to safely reference the common base or cast between them. A `shared_ptr` is used here so that it is possible to resize the array by replacing the existing array and avoid the overhead of large array copies during assignment. It also permits efficient shallow copying in the absence of a C++11 move constructor for `MultiArray` types.

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

- ome/files/PixelBuffer.h