iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
nrt::Array2D< T > Class Template Reference

#include <nrt/Core/Memory/Array2D.H>

template<class T>
class nrt::Array2D< T >

A shared, copy-on-write 2D addressable storage class for holding arbitrary types.

The nrt::Array2D class is a simple wrapper around nrt::Array which provides convenience methods for addressing nrt::Array as if it spanned 2 dimensions. If you are trying to represent a 2D array of pixels, you should instead create an nrt::Image, of which nrt::Array2D is a base class. The most notable difference between nrt::Array2D and nrt::Image is that nrt::Array2D will allow you to store any data type, whereas an nrt::Image can only hold data types derived from nrt::PixelBase.

Note
Unlike Image, Array2D will never check the make sure the coordinates you pass to at() or operator() are valid.
See Also
Image

Definition at line 66 of file Array2D.H.

Inheritance diagram for nrt::Array2D< T >:
nrt::Image< T > nrt::Image< T, Flags >

Public Types

typedef T * iterator
 Read-write iterator over the data, scans in standard raster fashion (x varies fastest, then y)
 
typedef T const * const_iterator
 Constant iterator over data, scans in standard raster fashion (x varies fastest, then y)
 
- Public Types inherited from nrt::Array2DBase
typedef Dims< int32 > DimsType
 

Public Member Functions

 Array2D ()
 Create an empty Array2D (will have size 0x0)
 
 Array2D (DimsType const &dims)
 Allocate an uninitialized Array2D with the given size.
 
 Array2D (DimsType const &dims, T const &val)
 Allocate an uninitialized Array2D, and fill every element with a copy of val.
 
 Array2D (Array2D< T > const &other)
 Copy constructor. More...
 
 Array2D (Array2D &&other)
 Move constructor. More...
 
 Array2D (std::initializer_list< std::initializer_list< T >> vals)
 Construct from a 2D initializer list.
 
 Array2D (T const *data, DimsType const &dims)
 Construct a 2D array from foreign memory by making a deep copy of it.
 
Array2Doperator= (Array2D< T > const &other)
 Assignment operator. More...
 
Array2Doperator= (Array2D< T > &&other)
 Move assignment operator. More...
 
void clear (T const &val=T())
 Clear contents (or set to given value) without changing the size of the Array2D.
 
T const & at (int32 x, int32 y) const
 Read the value at position (x, y) More...
 
T const & at (Point2D< int32 > p) const
 A convenient overload of at(int32 x, int32 y) const.
 
T const & at (uint32 idx) const
 A convenient overload of at(int32 x, int32 y) const for linear read-only access to the Array2D.
 
T & operator() (int32 x, int32 y)
 Get a mutable reference to the value at position (x, y) More...
 
T const & operator() (int32 x, int32 y) const
 Get a const reference to the value at position (x, y)
 
T & operator() (Point2D< int32 > p)
 A convenient overload of operator()(int32 x, int32 y)
 
T const & operator() (Point2D< int32 > p) const
 A convenient overload of operator()(int32 x, int32 y)
 
T & operator() (uint32 idx)
 A convenient overload of operator()(int32 x, int32 y) for linear write access to the Image.
 
T const & operator() (uint32 idx) const
 A convenient overload of operator()(int32 x, int32 y) for linear write access to the Image.
 
template<class U >
bool coordsOk (const U x, const U y) const
 Test whether point falls inside array boundaries.
 
template<class U >
bool rectangleOk (const Rectangle< U > rect) const
 Test whether a rectangle falls inside array boundaries.
 
template<class U >
bool coordsOk (const Point2D< U > &P) const
 Convenient overload of coordsOk(int32 x, int32 y)
 
DimsType const & dims () const
 Get the dimensions of the Array2D.
 
Rectangle< int32 > const bounds () const
 Get the bounding rectangle of the Array2D.
 
int32 const width () const
 Get the width of the Array2D.
 
int32 const height () const
 Get the height of the Array2D.
 
int32 const size () const
 Get the total number of elements in the Array2D; if it is zero then the image is un-initialized.
 
bool const empty () const
 Let the caller know whether the Array2D is empty (0x0 dimensions) More...
 
void reshape (Dims< int32 > const &newDims)
 Reshape an Array2D to new Dims without changing the number of elements in the underlying data. More...
 
void reshape (int32 newWidth, int32 newHeight)
 Reshape an image to new dims without changing the underlying data. More...
 
Array2D< T > const & cref () const
 Get a const reference to a (potentially non-const) Array2D. More...
 
const_iterator const_begin () const
 Get constant (read-only) iterators to the beginning of the Image. More...
 
const_iterator begin () const
 Get constant (read-only) iterators to the beginning of the Image. More...
 
const_iterator const_end () const
 Get constant (read-only) iterators to the end of the Image. More...
 
const_iterator end () const
 Get constant (read-only) iterators to the beginning of the Image. More...
 
iterator begin ()
 Gets a read-write iterator to the beginning of the Image. More...
 
iterator end ()
 Gets a read-write iterator to the end of the Image. More...
 
void deepCopy ()
 Make a deep copy of our Memory. More...
 

Protected Member Functions

template<class Archive >
void serialize (Archive &ar)
 

Protected Attributes

DimsType itsDims
 
Array< T > itsArray
 

Friends

class cereal::access
 

Constructor & Destructor Documentation

template<class T>
nrt::Array2D< T >::Array2D ( nrt::Array2D< T > const &  other)
inline

Copy constructor.

Copy another Array2D into this one.

Note
This constructor uses nrt::Array's copy-on-write functionality, meaning that when this constructor is called no actual data will be copied. The underlying data will only be copied if either Array attempts to write to the data.

Definition at line 59 of file Array2DImpl.H.

template<class T>
nrt::Array2D< T >::Array2D ( Array2D< T > &&  other)
inline

Move constructor.

Move constructs another Array2D into this one. This will cause the other Array2D to become invalid; using an invalid array will result in undefined behavior.

Definition at line 68 of file Array2DImpl.H.

Member Function Documentation

template<class T>
nrt::Array2D< T > & nrt::Array2D< T >::operator= ( nrt::Array2D< T > const &  other)
inline

Assignment operator.

Copy another Array2D into this one.

Note
This assignment uses nrt::Array's copy-on-write functionality, meaning that when this constructor is called no actual data will be copied. The underlying data will only be copied if either Array attempts to write to the data.

Definition at line 96 of file Array2DImpl.H.

template<class T>
nrt::Array2D< T > & nrt::Array2D< T >::operator= ( nrt::Array2D< T > &&  other)
inline

Move assignment operator.

Move assigns another Array2D into this one. This will cause the other Array2D to become invalid; using an invalid array will result in undefined behavior.

Definition at line 108 of file Array2DImpl.H.

template<class T >
T const & nrt::Array2D< T >::at ( nrt::int32  x,
nrt::int32  y 
) const
inline

Read the value at position (x, y)

Use this method to read elements of your Array2D, e.g.

int val = myArray.at(5, 2);

This method can be much faster than operator() because it will never make a copy of the Array2D.

Definition at line 159 of file Array2DImpl.H.

template<class T >
T & nrt::Array2D< T >::operator() ( nrt::int32  x,
nrt::int32  y 
)
inline

Get a mutable reference to the value at position (x, y)

Use this method to set elements of your Array2D, e.g.

myArray2D(5, 2) = 17;

Note that this method can be much slower than the .at() method when just reading values because it may make a deep-copy of the underlying memory if it is shared with another Array2D.

Definition at line 125 of file Array2DImpl.H.

template<class T >
bool const nrt::Array2D< T >::empty ( ) const
inline

Let the caller know whether the Array2D is empty (0x0 dimensions)

This is equivalent to (size() == 0)

Definition at line 227 of file Array2DImpl.H.

template<class T >
void nrt::Array2D< T >::reshape ( Dims< int32 > const &  newDims)
inline

Reshape an Array2D to new Dims without changing the number of elements in the underlying data.

This just changes the Dims but does not affect the pixel array. The new dims must have a size() equal to the old size(), otherwise this throws BadDimsImageException.

Definition at line 232 of file Array2DImpl.H.

References nrt::Dims< T >::size().

template<class T >
void nrt::Array2D< T >::reshape ( int32  newWidth,
int32  newHeight 
)
inline

Reshape an image to new dims without changing the underlying data.

See Also
reshape(Dims<int32>)

Definition at line 240 of file Array2DImpl.H.

template<class T >
nrt::Array2D< T > const & nrt::Array2D< T >::cref ( ) const
inline

Get a const reference to a (potentially non-const) Array2D.

The main purpose of this method is to allow easy and efficient read-only access via C++0x's range-based for loop. Beware that if you just call begin() on an Array2D that is not instantiated as const, then the non-const begin() will be called, potentially triggering an (expensive) deep copy. This would occur in the following cases:

Array2D<int> img1 = { { 1, 2, 3, 4 }, { 5, 6, 7, 8 } }, img2 = img1;
for (auto const & pix : img1) { ... } // Deep copy here because img1 is non const and data shared with img2

So the Array2D has to be non-const and shared for this problem to surface, if it is const, then the const version of begin() will be called by our for() loop, or if it is not shared, then the non-const begin() is called but no deep copy will occur anyway. To always avoid the deep copy, just use:

for (auto const & pix : img1.cref()) { ... } // no deep copy, const begin() used

Definition at line 245 of file Array2DImpl.H.

template<class T >
nrt::Array2D< T >::const_iterator nrt::Array2D< T >::const_begin ( ) const
inline

Get constant (read-only) iterators to the beginning of the Image.

If you only need to inspect elements of an Image, then this is the very fastest way to do so.

Definition at line 260 of file Array2DImpl.H.

Referenced by nrt::Image< T, Flags >::begin(), nrt::Image< T, Flags >::const_begin(), nrt::Image< T, Flags >::const_row_begin(), nrt::Image< T, Flags >::const_row_end(), nrt::Image< T, Flags >::row_begin(), and nrt::Image< T, Flags >::row_end().

template<class T >
nrt::Array2D< T >::const_iterator nrt::Array2D< T >::begin ( ) const
inline

Get constant (read-only) iterators to the beginning of the Image.

If you only need to inspect elements of a known-to-be-const Image, then this is the very fastest way to do so, but see cref() for caveats.

Definition at line 265 of file Array2DImpl.H.

Referenced by nrt::Image< T, Flags >::row_begin(), and nrt::Image< T, Flags >::row_end().

template<class T >
nrt::Array2D< T >::const_iterator nrt::Array2D< T >::const_end ( ) const
inline

Get constant (read-only) iterators to the end of the Image.

If you only need to inspect elements of an Image, then this is the very fastest way to do so.

Definition at line 270 of file Array2DImpl.H.

Referenced by nrt::Image< T, Flags >::const_end(), and nrt::Image< T, Flags >::end().

template<class T >
nrt::Array2D< T >::const_iterator nrt::Array2D< T >::end ( ) const
inline

Get constant (read-only) iterators to the beginning of the Image.

If you only need to inspect elements of a known-to-be-const Image, then this is the very fastest way to do so, but see cref() for caveats.

Definition at line 275 of file Array2DImpl.H.

Referenced by nrt::Image< T, Flags >::end().

template<class T >
nrt::Array2D< T >::iterator nrt::Array2D< T >::begin ( )
inline

Gets a read-write iterator to the beginning of the Image.

Use this method only if you really do need to modify elements of your Image because they may invoke a deep-copy of the Image memory if it is shared by another Image. If only read access is necessary, use the const_begin() method instead.

Definition at line 250 of file Array2DImpl.H.

template<class T >
nrt::Array2D< T >::iterator nrt::Array2D< T >::end ( )
inline

Gets a read-write iterator to the end of the Image.

See Also
begin()

Definition at line 255 of file Array2DImpl.H.

template<class T >
void nrt::Array2D< T >::deepCopy ( )
inline

Make a deep copy of our Memory.

Immediately after a call to deepCopy(), our reference count is guaranteed to be 1

Definition at line 280 of file Array2DImpl.H.


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