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, 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 std::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. More...

size_type	num_dimensions () const
	Get the number of dimensions in the multi-dimensional array. More...

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< std::shared_ptr< array_type >, std::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).

◆ num_dimensions()

template<typename T>

size_type ome::files::PixelBuffer< T >::num_dimensions ( ) const

inline

Get the number of dimensions in the multi-dimensional array.

Returns: the number of dimensions.

◆ num_elements()

template<typename T>

size_type ome::files::PixelBuffer< T >::num_elements ( ) const

inline

Get the number of pixel elements in the multi-dimensional array.

Returns: the number of elements.

◆ 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<std::shared_ptr<array_type>, std::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

Public Types

Public Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

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

Member Typedef Documentation

◆ array_ref_type

◆ array_type

Constructor & Destructor Documentation

◆ PixelBuffer() [1/6]

◆ PixelBuffer() [2/6]

◆ PixelBuffer() [3/6]

◆ PixelBuffer() [4/6]

◆ PixelBuffer() [5/6]

◆ PixelBuffer() [6/6]

Member Function Documentation

◆ array() [1/2]

◆ array() [2/2]

◆ assign()

◆ at() [1/2]

◆ at() [2/2]

◆ data() [1/2]

◆ data() [2/2]

◆ index_bases()

◆ managed()

◆ num_dimensions()

◆ num_elements()

◆ operator!=() [1/2]

◆ operator!=() [2/2]

◆ operator<() [1/2]

◆ operator<() [2/2]

◆ operator<=() [1/2]

◆ operator<=() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==() [1/2]

◆ operator==() [2/2]

◆ operator>() [1/2]

◆ operator>() [2/2]

◆ operator>=() [1/2]

◆ operator>=() [2/2]

◆ origin()

◆ read()

◆ shape()

◆ storage_order()

◆ strides()

◆ valid()

◆ write()

Member Data Documentation

◆ multiarray

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