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

#include <nrt/Core/Image/Image.H>

template<class T, uint32 Flags = 0>
class nrt::Image< T, Flags >

The standard Image class used to store pixel data.

The Image class is used (not surprisingly!) to hold image data in memory. The class has a number of features which make is easy to use and high-performance. It is a thin wrapper around the nrt::Array2D class, which is a copy-on-write ref-counting memory storage class. This means that copying an Image is a nearly instant operation that essentially equates to just a pointer copy. Whenever the Image data is modified, the class will check to see if its memory pointer is shared with another Image, and if so will create a unique copy of that data for itself. It is therefore up to the user to use read-only methods of Image whenever possible to avoid having to unecessarily copy the Image. Follow these guidelines to ensure high-performance:

1) Use the myImage.at(x,y) method to read pixel values - this is guaranteed to never cause a copy. Use myImage(x,y) only when you actually need to modify the pixel value, e.g.

// Retrieve a pixel value (no copy here)
myPixel = myImage.at(0, 0);
// Assign a pixel value (this may copy the image data if it is shared with another Image)
yourImage(0, 0) = myPixel;

2) Follow the same guidelines as above when iterating through the Image using begin() / const_begin() and end() / const_end(). Also use cref().

3) Feel free to return Images from functions - this can lead to very natural syntax of Image filters and will be essentially free. e.g.

Image<PixGray<byte>> MyImage = filter3(filter2(filter1(YourImage)));

4) Basic math operators (+,-,*,/,+=,*=,/=,-=) are defined as well as several overloaded wrappers around std::accumulate(...), std::transform(...), std::foreach(...). Instead of chaining operators together it is more efficient to use nrt::transform(...) for per-pixel operations that are more complex than a single operator:

Image<PixGray<float>> im1, im2;
im1 += im2 //ok only one operation
im2 = (im1 - im2) / (im1 + im2) //pretty, but wrong!
//efficiently apply the operation with a lamda (alternatively a functor, functional, function or function ptr)
im2 = transform(im1, im2,
[](PixGray<float>> const & v1, PixGray<float>> const & v2) { return (v1 - v2)/(v1 + v2); });

Note: The operators accept arguments by const &, which is efficient but not entirely thread-safe due to the ref-counting mechanism in the Image class. This would only present a problem if you spawned the operator or an accumulate or a transform function in a new thread passing in a non-unique image.

Template Parameters
TThe pixel type of this Image. T must be a class which derives from nrt::PixelBase
FlagsA bitfield which describes various flags to control the behavior or the Image. See ImageFlags for more info.
Examples:
tests/test-EigenConversions.C, tests/test-GenericImage.C, tests/test-Geometry.C, tests/test-Image.C, tests/test-ImageCopy.C, tests/test-ImagePerformance.C, tests/test-ImagePolyIter.C, tests/test-ImageReader.C, tests/test-Pyramid.C, tests/test-rgb2hsv-Image_vs_Blitz_vs_OpenCV.C, tests/test-stream.C, and tests/test-UKF.C.

Definition at line 178 of file Image.H.

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

Public Types

typedef nrt_traits< T >
::pixel_traits::pod_type 
PODType
 Convenient typedef for the POD type stored by our Pixel type.
 
typedef T PixelType
 Convenient typedef for our Pixel type.
 
typedef Array2DBase::DimsType DimsType
 Convenent typedef for our Dims type.
 
Image Iterator Types
typedef T * iterator
 Read-write iterator over image pixels, scans in standard raster fashion (x varies fastest, then y) More...
 
typedef T const * const_iterator
 Constant iterator over image pixels, scans in standard raster fashion (x varies fastest, then y)
 
typedef PODTypepod_iterator
 Read-write iterator over the raw POD data stored in the Image. More...
 
typedef PODType const * const_pod_iterator
 Constant iterator over the raw POD data stored in the Image.
 
typedef iterator row_iterator
 Read-Write iterator onto a given row of the image.
 
typedef const_iterator const_row_iterator
 Constant iterator onto a given row of the image.
 
- Public Types inherited from nrt::Array2D< T >
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

 Image ()
 Construct an empty (0 by 0) Image.
 
 Image (DimsType const &dims, ImageInitPolicy const p=ImageInitPolicy::None)
 Construct an Image of size dims using the given ImageInitPolicy. More...
 
 Image (int width, int height, ImageInitPolicy const p=ImageInitPolicy::None)
 Construct an Image of size width and height using given InitPolicy. More...
 
 Image (DimsType const &dims, T const val)
 Construct an Image of size Dims filled with val.
 
template<uint32 OtherFlags>
 Image (Image< T, OtherFlags > const &other)
 Copy constructor.
 
 Image (std::initializer_list< std::initializer_list< T >> vals)
 Construct from a 2D initializer list. More...
 
template<class U , uint32 OtherFlags>
 Image (Image< U, OtherFlags > const &other)
 Color space conversion copy constructor. More...
 
 Image (T *data, DimsType const &dims)
 Construct an Image from a raw array. More...
 
template<uint32 OtherFlags>
Image< T, Flags > & operator= (Image< T, OtherFlags > const &other)
 Assignment operator.
 
template<class U , uint32 OtherFlags>
Image< T, Flags > & operator= (Image< U, OtherFlags > const &other)
 Color space conversion assignment operator. More...
 
void clear (T const &val=T())
 Clear contents (or set to given value) without changing the size of the Image.
 
nrt::Range< T > const range () const
 Get the range (min,max) of pixel values contained in the image. If the image is empty then range is [0 .. 0]. More...
 
template<class U , template< typename > class ColorType>
std::enable_if
< std::is_base_of
< PixelWithAlpha< U >
, ColorType< U > >::value,
void >::type 
draw (Point2D< int32 > const &p, ColorType< U > color)
 Draw the given color onto the Image pixel at point p. More...
 
template<class U >
void draw (Point2D< int32 > const &p, U color)
 Draw the given color onto the Image pixel at point p. More...
 
T const & at (int32 x, int32 y) const
 Read the pixel 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 Image.
 
interpolate (float x, float y) const
 Read the bilinearly interpolated value at position (x, y)
 
interpolate (Point2D< float > p) const
 A convenient overload of interpolate(float x, float y) const.
 
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
 
T & operator() (Point2D< int32 > p)
 A convenient overload of operator()(int32 x, int32 y)
 
T const & operator() (Point2D< int32 > p) const
 
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
 
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. More...
 
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 Image.
 
Rectangle< int32 > const bounds () const
 Get the bounding rectangle of the Image.
 
int32 const width () const
 Get the width of the Image.
 
int32 const height () const
 Get the height of the Image.
 
int32 const size () const
 Get the total number of pixels in the Image; if it is zero then the image is un-initialized.
 
bool const empty () const
 Let the caller know whether the image is empty (0x0 dimensions) More...
 
void reshape (Dims< int32 > const &newDims)
 Reshape an image to new dims without changing the underlying data. More...
 
void reshape (int32 newWidth, int32 newHeight)
 Reshape an image to new dims without changing the underlying data. More...
 
nrt::Image< nrt::PixGray
< PODType > > 
channel (size_t chan) const
 Create a new single-channel Image from the chan'th channel of this Image. More...
 
Image< T, Flags > const & cref () const
 Get a const reference to a (potentially non-const) Image. More...
 
template<class T, nrt::uint32 Flags>
 Image (std::initializer_list< std::initializer_list< T > > vals)
 
template<nrt::uint32 OtherFlags>
nrt::Image< T, Flags > & operator= (nrt::Image< T, OtherFlags > const &other)
 
template<class U, nrt::uint32 OtherFlags>
nrt::Image< T, Flags > & operator= (nrt::Image< U, OtherFlags > const &other)
 
template<class U , template< typename > class ColorType>
std::enable_if
< std::is_base_of
< nrt::PixelWithAlpha< U >
, ColorType< U > >::value,
void >::type 
draw (Point2D< int32 > const &p, ColorType< U > color)
 
Image Iterator Accessors
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...
 
pod_iterator pod_begin ()
 Gets a read-write pod iterator to the first channel of the first Pixel of the Image. More...
 
pod_iterator pod_end ()
 Gets a read-write pod iterator to one place past the last channel of the lat Pixel of the Image. More...
 
const_pod_iterator pod_begin () const
 Gets a constant (read-only) pod iterator to the first channel of the first Pixel of the const Image. More...
 
const_pod_iterator pod_end () const
 
const_pod_iterator const_pod_begin () const
 Gets a constant (read-only) pod iterator to the first channel of the first Pixel of the Image. More...
 
const_pod_iterator const_pod_end () const
 Gets a constant (read-only) pod iterator to one place past the last channel of the lat Pixel of the Image. More...
 
const_row_iterator const_row_begin (int32 row) const
 Get a read-only iterator to the beginning of a row.
 
const_row_iterator const_row_end (int32 row) const
 Get a read-only iterator to the end of a row.
 
const_row_iterator row_begin (int32 row) const
 Gets a read-only iterator to the beginning of a row.
 
const_row_iterator row_end (int32 row) const
 Gets a read-only iterator to the end of a row.
 
row_iterator row_begin (int32 row)
 Gets a read-write iterator to the beginning of a row.
 
row_iterator row_end (int32 row)
 Gets a read-write iterator to the end of a row.
 
const_col_iterator const_col_begin (int32 col) const
 Get a read-only iterator to the beginning of a column.
 
const_col_iterator const_col_end (int32 col) const
 Get a read-only iterator to the end of a column.
 
const_col_iterator col_begin (int32 col) const
 Get a read-only iterator to the beginning of a column.
 
const_col_iterator col_end (int32 col) const
 Get a read-only iterator to the end of a column.
 
col_iterator col_begin (int32 col)
 Get a read-write iterator to the beginning of a column.
 
col_iterator col_end (int32 col)
 Get a read-write iterator to the end of a column.
 
const_rect_iterator const_rect_begin (Rectangle< int32 > const &rect) const
 Get a read-only iterator to the beginning of a rectangle.
 
const_rect_iterator const_rect_end (Rectangle< int32 > const &rect) const
 Get a read-only iterator to the end of a rectangle.
 
const_rect_iterator rect_begin (Rectangle< int32 > const &rect) const
 Get a read-only iterator to the beginning of a rectangle.
 
const_rect_iterator rect_end (Rectangle< int32 > const &rect) const
 Get a read-only iterator to the end of a rectangle.
 
rect_iterator rect_begin (Rectangle< int32 > const &rect)
 Get a read-only iterator to the beginning of a rectangle.
 
rect_iterator rect_end (Rectangle< int32 > const &rect)
 Get a read-only iterator to the end of a rectangle.
 
convex_poly_iterator convex_poly_begin (Polygon< int32 > const &poly)
 Get a read-write iterator to the beginning of a polygon.
 
convex_poly_iterator convex_poly_end (Polygon< int32 > const &poly)
 Get a read-write iterator to the end of a polygon.
 
const_convex_poly_iterator const_convex_poly_begin (Polygon< int32 > const &poly) const
 Get a read-only iterator to the beginning of a polygon.
 
const_convex_poly_iterator const_convex_poly_end (Polygon< int32 > const &poly) const
 Get a read-only iterator to the end of a polygon.
 
const_convex_poly_iterator convex_poly_begin (Polygon< int32 > const &poly) const
 Get a read-only iterator to the beginning of a polygon.
 
const_convex_poly_iterator convex_poly_end (Polygon< int32 > const &poly) const
 Get a read-only iterator to the end of a polygon.
 
- Public Member Functions inherited from nrt::Array2D< T >
 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...
 

Friends

template<class U , uint32 OtherFlags>
class Image
 
class cereal::access
 

Related Functions

(Note that these are not member functions.)

enum  ImageInitPolicy { ImageInitPolicy::Zeros, ImageInitPolicy::None }
 Initialization policy for the pixels inside an Image, used during construction of the Image. More...
 
enum  ImageFlags : uint32 { SafeAccess = 1, UniqueAccess = 2 }
 Flags to control the behavior of Images. More...
 

Additional Inherited Members

- Protected Member Functions inherited from nrt::Array2D< T >
template<class Archive >
void serialize (Archive &ar)
 
- Protected Attributes inherited from nrt::Array2D< T >
DimsType itsDims
 
Array< T > itsArray
 

Member Typedef Documentation

template<class T, uint32 Flags = 0>
typedef T* nrt::Image< T, Flags >::iterator

Read-write iterator over image pixels, scans in standard raster fashion (x varies fastest, then y)

The following methods and types provide various ways to iterate over Image data.

Definition at line 393 of file Image.H.

template<class T, uint32 Flags = 0>
typedef PODType* nrt::Image< T, Flags >::pod_iterator

Read-write iterator over the raw POD data stored in the Image.

By iterating over the PODType using a pod_iterator, you can have direct access to the underlying plain-old-data (POD) type stored by your pixels.

For example:

Image<PixRGB<byte>> img(640,480);
Image<PixRGB<byte>>::pod_iterator iter; // Create a pod_iterator, which in this case
// is just a typedef for byte*
iter = img.pod_begin(); // iter now points to the 'red' channel of the first pixel.
++iter; // iter now points to the 'green' channel of the first pixel.
++iter; // iter now points to the 'blue' channel of the first pixel.
++iter; // iter now points to the 'red' channel of the second pixel.

Definition at line 414 of file Image.H.

Constructor & Destructor Documentation

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::Image ( DimsType const &  dims,
nrt::ImageInitPolicy const  p = ImageInitPolicy::None 
)
inline

Construct an Image of size dims using the given ImageInitPolicy.

If you need to construct a blank image filled with 0's then this method is the way to go, as it is faster than the standard value constructor.

Definition at line 49 of file ImageImpl.H.

References nrt::Image< T, Flags >::dims(), nrt::Array2D< T >::height(), nrt::Image< T, Flags >::size(), and nrt::Array2D< T >::width().

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::Image ( int  width,
int  height,
nrt::ImageInitPolicy const  p = ImageInitPolicy::None 
)
inline

Construct an Image of size width and height using given InitPolicy.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 62 of file ImageImpl.H.

References nrt::Array2D< T >::height(), nrt::Image< T, Flags >::height(), nrt::Image< T, Flags >::size(), nrt::Array2D< T >::width(), and nrt::Image< T, Flags >::width().

template<class T, uint32 Flags = 0>
nrt::Image< T, Flags >::Image ( std::initializer_list< std::initializer_list< T >>  vals)

Construct from a 2D initializer list.

This constructs an image from the passed initializer data, for example:

Image<int> img1 = { { 1, 2, 3, 4 }, { 5, 6, 7, 8 } }; // image with width=4, height=2. The "=" is optional.
Image<int> img2 = { { 1, 2, 3 } }; // image with width=3, height=1 (row vector)
Image<int> img3 = { { 1 }, { 2 }, { 3 } }; // image with width=1, height=3 (column vector)
template<class T, nrt::uint32 Flags>
template<class U, nrt::uint32 OtherFlags>
nrt::Image< T, Flags >::Image ( nrt::Image< U, OtherFlags > const &  other)
inlineexplicit

Color space conversion copy constructor.

This constructor will convert an Image from one color space to another. It is made explicit to avoid possibly expensive pixel type conversions without the user being aware that it is happening.

Example:

Image<PixHSV<byte>> hsvImage;
Image<PixLAB<float>> labImage(hsvImage);

This method works through the toRGB and fromRGB methods required for any deriver of PixelBase. In the above example, the Image<PixRGB<float>> constructor is essentially equivalent to:

for (size_t i=0; i<labImage.size(); i++)
labImage(i) = PixLAB<float>::fromRGB(hsvImage.at(i).toRGB());

Definition at line 106 of file ImageImpl.H.

References nrt::Image< T, Flags >::begin(), nrt::Image< T, Flags >::const_begin(), and nrt::Image< T, Flags >::const_end().

template<class T, nrt::uint32 Flags>
nrt::Image< T, Flags >::Image ( T *  data,
DimsType const &  dims 
)

Construct an Image from a raw array.

This constructor simply drops the data pointer into the Image's underlying nrt::Array, which has the following important effects:

  1. This constructor does not copy data, so be aware that data will be shared between this Image and whoever created data.
  2. The constructed Image will believe that it owns data, and will thus attempt to free it when the Image goes out of scope.

Definition at line 122 of file ImageImpl.H.

Member Function Documentation

template<class T, uint32 Flags = 0>
template<class U , uint32 OtherFlags>
Image<T, Flags>& nrt::Image< T, Flags >::operator= ( Image< U, OtherFlags > const &  other)

Color space conversion assignment operator.

See Also
Image(Image<U> const& other);
template<class T , nrt::uint32 Flags>
nrt::Range< T > const nrt::Image< T, Flags >::range ( ) const
inline

Get the range (min,max) of pixel values contained in the image. If the image is empty then range is [0 .. 0].

Note that we do not cache the range, as this would incur the cost of having to invalidate it each time the image contents are modified in some way. So you should consider that calling range() is an "expensive" operation that performs a loop over all pixels in the image each time it is called. If your pixel type T does not support std::min(T, T) and std::max(T, T) then you will not be able to compile.

Definition at line 165 of file ImageImpl.H.

Referenced by nrt::inplaceNormalize().

template<class T, uint32 Flags = 0>
template<class U , template< typename > class ColorType>
std::enable_if<std::is_base_of<PixelWithAlpha<U>, ColorType<U> >::value, void>::type nrt::Image< T, Flags >::draw ( Point2D< int32 > const &  p,
ColorType< U >  color 
)

Draw the given color onto the Image pixel at point p.

This method is for safely drawing onto Images. Bounds checking is performed internally, and this method will have no effect if the Point p lies outside of the Image.

The compiler will automatically choose which version of draw() to use based on whether or not ColorType contains an alpha channel. If so, then draw() will correctly mix the new color with the old one.

template<class T , nrt::uint32 Flags>
template<class U >
void nrt::Image< T, Flags >::draw ( Point2D< int32 > const &  p,
color 
)
inline

Draw the given color onto the Image pixel at point p.

This method is for safely drawing onto Images. Bounds checking is performed internally, and this method will have no effect if the Point p lies outside of the Image.

The compiler will automatically choose which version of draw() to use based on whether or not ColorType contains an alpha channel. If so, then draw() will correctly mix the new color with the old one.

Definition at line 412 of file ImageImpl.H.

References nrt::Point2D< T >::x(), and nrt::Point2D< T >::y().

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

Read the pixel value at position (x, y)

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

PixRGB<byte> val = myImage.at(5, 2);

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

Definition at line 302 of file ImageImpl.H.

Referenced by nrt::getIntegralImage().

template<class T , nrt::uint32 Flags>
T & nrt::Image< T, Flags >::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 Image, e.g.

myImage(5, 2) = PixGray<byte>(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 Image.

Definition at line 176 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
template<class U >
bool nrt::Image< T, Flags >::rectangleOk ( const Rectangle< U >  rect) const
inline

Test whether a rectangle falls inside array boundaries.

Test whether rectangle falls inside array boundaries.

Definition at line 429 of file ImageImpl.H.

References nrt::Rectangle< T >::bottomRight(), and nrt::Rectangle< T >::topLeft().

template<class T , nrt::uint32 Flags>
bool const nrt::Image< T, Flags >::empty ( ) const
inline

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

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

Definition at line 470 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
void nrt::Image< T, Flags >::reshape ( Dims< int32 > const &  newDims)
inline

Reshape an image to new dims without changing 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 image size(), otherwise this throws BadDimsImageException.

Definition at line 475 of file ImageImpl.H.

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

template<class T , nrt::uint32 Flags>
void nrt::Image< T, Flags >::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 483 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
nrt::Image< nrt::PixGray< typename nrt::Image< T, Flags >::PODType > > nrt::Image< T, Flags >::channel ( size_t  chan) const

Create a new single-channel Image from the chan'th channel of this Image.

Note that this will make a deep copy of the data and is an expensive operation.

Definition at line 488 of file ImageImpl.H.

References nrt::Image< T, Flags >::begin(), nrt::None, and nrt::transform().

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags > const & nrt::Image< T, Flags >::cref ( ) const
inline

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

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 Image that is not instantiated as a const Image, then the non-const begin() will be called, potentially triggering an (expensive) deep copy. This would occur in the following cases:

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

So the image 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 avoid the deep copy, just use:

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

See the examples in test-ImageCopy.C

Definition at line 559 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::const_iterator nrt::Image< T, Flags >::const_begin ( ) const
inline

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

The following methods and types provide various ways to iterate over Image data.

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

Examples:
tests/test-Image.C.

Definition at line 509 of file ImageImpl.H.

References nrt::Array2D< T >::const_begin().

Referenced by nrt::accumulate(), nrt::decimateX(), nrt::decimateXY(), nrt::decimateY(), nrt::for_each(), nrt::Image< T, Flags >::Image(), nrt::lowPass5x(), nrt::lowPass5xDecX(), nrt::lowPass5y(), nrt::lowPass5yDecY(), nrt::lowPass9x(), nrt::lowPass9y(), nrt::paste(), nrt::transform(), and nrt::transformInPlace().

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::const_iterator nrt::Image< T, Flags >::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.

Examples:
tests/test-Image.C.

Definition at line 514 of file ImageImpl.H.

References nrt::Array2D< T >::const_begin().

Referenced by nrt::Image< T, Flags >::channel(), nrt::decimateX(), nrt::decimateXY(), nrt::decimateY(), nrt::Image< T, Flags >::Image(), nrt::inplaceAttenuateBorders(), nrt::lowPass5x(), nrt::lowPass5xDecX(), nrt::lowPass5y(), nrt::lowPass5yDecY(), nrt::lowPass9x(), nrt::lowPass9y(), nrt::morphologyKernel(), nrt::normalizedCrossCorrelation(), nrt::paste(), and nrt::transformInPlace().

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::const_iterator nrt::Image< T, Flags >::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 519 of file ImageImpl.H.

References nrt::Array2D< T >::const_end().

Referenced by nrt::accumulate(), nrt::for_each(), nrt::Image< T, Flags >::Image(), nrt::lowPass5yDecY(), nrt::transform(), and nrt::transformInPlace().

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::const_iterator nrt::Image< T, Flags >::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 524 of file ImageImpl.H.

References nrt::Array2D< T >::const_end().

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::iterator nrt::Image< T, Flags >::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 499 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::iterator nrt::Image< T, Flags >::end ( )
inline

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

See Also
begin()

Definition at line 504 of file ImageImpl.H.

References nrt::Array2D< T >::end().

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::pod_iterator nrt::Image< T, Flags >::pod_begin ( )
inline

Gets a read-write pod iterator to the first channel of the first Pixel of the Image.

See Also
pod_iterator

Definition at line 529 of file ImageImpl.H.

Referenced by nrt::copyImage2CvMat(), nrt::copyImage2Ipl(), and nrt::gaborKernel().

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::pod_iterator nrt::Image< T, Flags >::pod_end ( )
inline

Gets a read-write pod iterator to one place past the last channel of the lat Pixel of the Image.

See Also
pod_iterator

Definition at line 534 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::const_pod_iterator nrt::Image< T, Flags >::pod_begin ( ) const
inline

Gets a constant (read-only) pod iterator to the first channel of the first Pixel of the const Image.

See Also
pod_iterator

Definition at line 539 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::const_pod_iterator nrt::Image< T, Flags >::pod_end ( ) const
inline

Gets a constant (read-only) pod iterator to one place past the last channel of the lat Pixel of the const Image

See Also
pod_iterator

Definition at line 544 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::const_pod_iterator nrt::Image< T, Flags >::const_pod_begin ( ) const
inline

Gets a constant (read-only) pod iterator to the first channel of the first Pixel of the Image.

See Also
pod_iterator

Definition at line 549 of file ImageImpl.H.

template<class T , nrt::uint32 Flags>
nrt::Image< T, Flags >::const_pod_iterator nrt::Image< T, Flags >::const_pod_end ( ) const
inline

Gets a constant (read-only) pod iterator to one place past the last channel of the lat Pixel of the Image.

See Also
pod_iterator

Definition at line 554 of file ImageImpl.H.

Friends And Related Function Documentation

template<class T, uint32 Flags = 0>
enum ImageInitPolicy
related

Initialization policy for the pixels inside an Image, used during construction of the Image.

Enumerator
Zeros 

Fill the image with all zeros. This costs some CPU.

None 

No initialization of each pixel. This saves some CPU.

Definition at line 59 of file Image.H.

template<class T, uint32 Flags = 0>
enum ImageFlags : uint32
related

Flags to control the behavior of Images.

You can pass combinations of flags to an Image using the bitwise 'or' operator:

// Construct an Image that will check for out-of-bounds pixel access, but won't check for shared memory.
Image<PixGray<byte>, SafeAccess | UniqueAccess> myImage;
Enumerator
SafeAccess 

Image coordinate access will be checked, and an exception will be thrown if you try to access a pixel which is out of bounds. If you don't set this flag, then you will be on your own to ensure that you don't try to access pixels outside of the Image (as doing so may result in a segfault). However, SafeAccess comes with a big performance hit, so we recommend you only use it when debugging

UniqueAccess 

Image reference counting will not be checked during pixel level access. If you are sure that you have the only copy of your image data (and have full understanding of the copy-on-write behavior!), then you can declare your Image with the UniqueAccess flag. A good practice is to always call Image::deepCopy() before making a UniqueAccess alias of an Image.

For Example:

Image<PixRGB<byte>> myImage;
// ... Do some processing ...
// Make a UniqueAccess alias of myImage. Notice that we make a deep-copy of myImage before we do this,
// ensuring that we hold a unique reference to the underlying memory.
myImage.deepCopy();
Image<PixRGB<byte>, UniqueAccess> myUniqueImage = myImage;
// Now, we can mess around with myUniqueImage and all pixel operations will be very fast, as they won't perform
// any checks to ensure that we aren't sharing our memory with any other Images.
for(int y=0; y<myUniqueImage.height(); y++)
for(int x=0; x<myUniqueImage.width(); x++)
myUniqueImage(x,y) = ...

Definition at line 74 of file Image.H.


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