ome-files  0.1.1
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 >:
+ Collaboration diagram for ome::files::PixelBuffer< T >:

Public Types

typedef T value_type
 Pixel value type.
 
typedef boost::multi_array_ref< value_type, dimensionsarray_ref_type
 Type for multi-dimensional pixel array view referencing external data. More...
 
typedef boost::multi_array< value_type, dimensionsarray_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::dimensionsindices_type
 Type used to index all dimensions in public interfaces.
 
typedef boost::general_storage_order< dimensionsstorage_order_type
 Storage ordering type for controlling pixel memory layout.
 
typedef boost::detail::multi_array::extent_gen< dimensionsrange_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_typearray ()
 Get the pixel data. More...
 
const array_ref_typearray () const
 Get the pixel data. More...
 
value_typedata ()
 Get the raw data. More...
 
const value_typedata () 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_typeshape () 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_typeorigin () const
 Get the origin of the array. More...
 
const storage_order_typestorage_order () const
 Get the array storage order. More...
 
PixelBufferoperator= (const PixelBuffer &rhs)
 Assign a pixel buffer. More...
 
PixelBufferoperator= (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_typeat (const indices_type &indices)
 Get the pixel value at an index. More...
 
const value_typeat (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:

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

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.

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

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.

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
extentsthe extent of each dimension.
pixeltypethe pixel type to store.
endiantypethe required endianness of the pixel type.
storagethe storage ordering, defaulting to C array storage ordering.
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
pixeldatathe externally-provided storage for pixel data.
extentsthe extent of each dimension.
pixeltypethe pixel type to store.
endiantypethe required endianness of the pixel type.
storagethe storage ordering, defaulting to C array storage ordering.
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
rangethe range of each dimension.
pixeltypethe pixel type to store.
endiantypethe required endianness of the pixel type.
storagethe storage ordering, defaulting to C array storage ordering.
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
pixeldatathe externally-provided storage for pixel data.
rangethe range of each dimension.
pixeltypethe pixel type to store.
endiantypethe required endianness of the pixel type.
storagethe storage ordering, defaulting to C array storage ordering.
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
bufferthe buffer to copy.

Member Function Documentation

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:

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().

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
beginthe start of the range to assign.
endthe end of the range to assign.
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
indicesthe multi-dimensional array index.
Returns
a reference to the pixel value.
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
indicesthe multi-dimensional array index.
Returns
a constant reference to the pixel value.
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.
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.
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).
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).
template<typename T>
bool ome::files::PixelBuffer< T >::operator!= ( const PixelBuffer< T > &  rhs) const
inline

Compare a pixel buffer for inequality.

Parameters
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.

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

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
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.
template<typename T>
bool ome::files::PixelBuffer< T >::operator< ( const PixelBuffer< T > &  rhs) const
inline

Less than comparison with a pixel buffer.

Parameters
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.

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

template<typename T>
bool ome::files::PixelBuffer< T >::operator< ( const array_ref_type rhs) const
inline

Less than comparison with a multiarray.

Parameters
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.
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
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.

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

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
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.
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
rhsthe pixel buffer to assign.
Returns
the assigned buffer.

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

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
rhsthe pixel buffer to assign.
Returns
the assigned buffer.
template<typename T>
bool ome::files::PixelBuffer< T >::operator== ( const PixelBuffer< T > &  rhs) const
inline

Compare a pixel buffer for equality.

Parameters
rhsthe pixel buffer to compare with.
Returns
true if equal, false if not equal.

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

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
rhsthe pixel buffer to compare with.
Returns
true if equal, false if not equal.
template<typename T>
bool ome::files::PixelBuffer< T >::operator> ( const PixelBuffer< T > &  rhs) const
inline

Greater than comparison with a pixel buffer.

Parameters
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.

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

template<typename T>
bool ome::files::PixelBuffer< T >::operator> ( const array_ref_type rhs) const
inline

Greater than comparison with a multiarray.

Parameters
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.
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
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.

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

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
rhsthe pixel buffer to compare with.
Returns
true if not equal, false if equal.
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.
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
streamthe stream to read from.

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

+ Here is the caller graph for this function:

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).
template<typename T>
const storage_order_type& ome::files::PixelBuffer< T >::storage_order ( ) const
inline

Get the array storage order.

Returns
the storage order.
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).
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.
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
streamthe stream to write to.

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

+ Here is the caller graph for this function:

Member Data Documentation

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: