iLab Neuromorphic Vision Toolkit

This function is necessary for safe use of attach()/detach(). That is, unfortunately attach()/detach() are not safe for use with shared image objects -- consider the following code:

      double d[4] = { 0.0, 1.0, 2.0, 3.0};

      // create an Image that is attach()'ed to the double array
      Image<double> a;
      a.attach(&d[0], 2, 2);

      const Image<double> b = a;
      // now 'b' thinks it has a safe lock on some const values:

      d[0] = -1.0;
      // OOPS! By changing values in the 'd' array directly, we'll now
      // have changed things to that b[0] == -1.0, even though 'b' was
      // declared as 'const'

The solution to this problem is to prohibit the copy done in 'b=a' above (this triggers an LFATAL() in ArrayData::acquire()). That assures us that any ArrayData that has a StoragePolicy of WRITE_THRU will be un-shareable.

So, back to the point -- the correct way to write the code above would be to use deepcopy():

      double d[4] = { 0.0, 1.0, 2.0, 3.0};

      Image<double> a;
      a.attach(&d[0], 2, 2);

      const Image<double> b = a.deepcopy();

      d[0] = -1.0;
      // Now, 'b' is insulated from any changes to 'd' since we've
      // done a deep copy, so even now we'll still have b[0]==0.0


Iterators
There are const and non-const versions of iterators, which are returned by begin()/end() and beginw()/endw(), respectively. The "w" in beginw()/endw() is a mnemonic for "write" or "writeable". Beware that the non-const versions of these functions will invoke the copy-on-write mechanism (see ArrayHandle), so a deep copy of all the image data will be made if the current image object is not the unique owner of its image data. Thus, begin()/end() should always be used unless write access is specifically needed. (It is for this reason that we don't overload the const/non-const functions with the same names (even though this is possible in C++, as done in the STL containers)). Debugging iterators (CheckedIterator) will be used if the macro INVT_MEM_DEBUG is define'd. A checked iterator will check that it is within its proper bounds every time that it is dereferenced with either operator*() or operator->(). Note that the existence of the checked iterators means you cannot rely on an image iterator being a raw pointer. Instead, getArrayPtr() is available in case you unconditionally need a raw pointer to the image data.
typedef T *	iterator
	Read/write iterator.
typedef const T *	const_iterator
	Read-only iterator.
const_iterator	begin () const
	Returns a read-only iterator to the beginning of the image data.
const_iterator	end () const
	Returns a read-only iterator to one-past-the-end of the image data.
iterator	beginw ()
	Returns a read-write iterator to the beginning of the image data.
iterator	endw ()
	Returns a read-write iterator to one-past-the-end of the image data.
Public Member Functions
Constructors, destructors, assignment
	Image (const T *inarray, int width, int height)
	Construct from C array.
	Image (const T *inarray, const Dims &dims)
	Construct from C array.
	Image (int width, int height, InitPolicy init)
	Allocates memory for given size, and optionally zero-clear that memory.
	Image (const Dims &dims, InitPolicy init)
	Constructor that only allocates memory for given size.
	Image ()
	Construct an empty (0-by-0) image (useful for arrays of Images).
	Image (const Image< T > &A)
	Copy constructor.
template<class T2>
	Image (const Image< T2 > &A)
	Conversion copy constructor.
Image< T > &	operator= (const Image< T > &A)
	Assigment operator.
template<class T2>
Image< T > &	operator= (const Image< T2 > &A)
	Conversion assigment operator.
	~Image ()
	Destructor.
void	freeMem ()
	Free memory and switch to uninitialized state.
Memory management functions
void	swap (Image< T > &other)
	Swap the contents of two images.
void	attach (T *array, const int width, const int height)
	Use existing memory.
void	detach ()
	Detach previously attach()'ed image.
Image< T >	deepcopy () const
	Return a new image object with a deep copy of the underlying data.
void	resize (const Dims &dims, const bool clear=false)
	Free mem and realloc new array (array contents are lost).
void	resize (const int width, const int height, const bool clear=false)
	Free mem and realloc new array (array contents are lost).
Access functions
bool	initialized () const
	Check whether image is non-empty (i.e., non-zero height and width).
int	getSize () const
	Get image size (width * height).
uint	size () const
	Get image size (width * height).
int	getWidth () const
	Get image width.
int	getHeight () const
	Get image height.
const Dims &	getDims () const
	Get image width+height in Dims struct.
Rectangle	getBounds () const
	Get image bounds as a rectangle with upper-left point at (0,0) and dims matching the image dims.
template<class C>
bool	isSameSize (const C &other) const
	Check if *this is the same size as the other thing.
bool	is1D () const
	Check if the image is 1D, i.e., width == 1 or height == 1.
bool	isVector () const
	Check if the image is a vector, i.e., width == 1.
bool	isTransposedVector () const
	Check if the image is a transposed vector, i.e., height == 1.
bool	isSquare () const
	Check if the image is square, i.e., width == height.
T &	operator[] (const int index)
	Access image elements through C array index interface.
const T &	operator[] (const int index) const
	Access image elements through C array index interface.
T &	operator[] (const Point2D< int > &p)
	Access image elements through C array index interface.
const T &	operator[] (const Point2D< int > &p) const
	Access image elements through C array index interface.
const T &	getVal (const int index) const
	Get pixel value at index in image.
const T &	getVal (const int x, const int y) const
	Get pixel value at (x, y) in image.
const T &	getVal (const Point2D< int > &p) const
	Get pixel value at specified coordinates in image.
template<class T2>
void	getVal (const int x, const int y, T2 &val) const
	Get value at (x,y), put in val rather that return it.
T	getValInterp (const float x, const float y) const
	Get pixel value at (x, y) in image with bilinear interpolation.
T	getValInterp (const Point2D< float > &p) const
	Get pixel value at (x, y) in image with bilinear interpolation.
T	getValInterpScaled (const Point2D< int > &p, const Dims &pdims) const
	Get pixel value with bilinear interpolation at a location (x,y) specified in a different Dims scale.
template<class T2>
void	setVal (const int index, const T2 &value)
	Set value in image at index.
template<class T2>
void	setVal (const int x, const int y, const T2 &value)
	Set value in image at (x, y).
template<class T2>
void	setVal (const Point2D< int > &p, const T2 &value)
	Set value in image at Point2D<int>.
const T *	getArrayPtr () const
	Returns read-only (const) pointer to internal image array.
T *	getArrayPtr ()
	Returns read/write (non-const) pointer to internal image array.
bool	coordsOk (const Point2D< int > &P) const
	Test whether point falls inside array boundaries.
bool	coordsOk (const int i, const int j) const
	Test whether point falls inside array boundaries.
bool	coordsOk (const Point2D< float > &p) const
	Test whether point falls inside array boundaries.
bool	coordsOk (const float i, const float j) const
	Test whether point falls inside array boundaries.
bool	rectangleOk (const Rectangle &rect) const
	Test whether rectangle fits in image.
Operator overloads and basic image manipulations
Note that many other image manipulation functions are available in Image_ColorOps.H, Image_FilterOps.H, Image_IO.H, Image_MathOps.H, Image_Omni.H, Image_ShapeOps.H, Image_Transforms.H, and Image_Conversions.H.
bool	operator== (const Image< T > &that) const
	Equality: true if the images are the same size and all pixels are equal.
Image< T > &	operator+= (const T &val)
	Add constant to image, clamp result as necessary.
Image< T > &	operator-= (const T &val)
	Subtract constant from image, clamp result as necessary.
Image< T > &	operator *= (const T &val)
	Multiply image by constant, clamp result as necessary.
Image< T > &	operator/= (const T &val)
	Divide image by constant, clamp result as necessary.
Image< T > &	operator<<= (const unsigned int nbits)
	Bit-shift left by constant (type T must have operator<<()).
Image< T > &	operator>>= (const unsigned int nbits)
	Bit-shift right by constant (type T must have operator>>()).
template<class T2>
Image< T > &	operator+= (const Image< T2 > &A)
	Add image to image, clamp result as necessary.
template<class T2>
Image< T > &	operator-= (const Image< T2 > &A)
	Subtract image from image, clamp result as necessary.
template<class T2>
Image< T > &	operator *= (const Image< T2 > &A)
	Multiply image by image, point-by-point, clamp result as necessary.
template<class T2>
Image< T > &	operator/= (const Image< T2 > &A)
	Divide image by image, point-by-point, clamp result as necessary.
template<class T2>
Image< T > &	operator\|= (const Image< T2 > &A)
	Bitwise-or image by image, point-by-point, clamp result as necessary.
template<class T2>
Image< typename promote_trait< T, T2 >::TP >	operator+ (const T2 &val) const
	Add scalar to each point in *this and return result.
template<class T2>
Image< typename promote_trait< T, T2 >::TP >	operator- (const T2 &val) const
	Subtract scalar from each point in *this and return result.
template<class T2>
Image< typename promote_trait< T, T2 >::TP >	operator * (const T2 &val) const
	Multiply scalar each point in *this by scalar and return result.
template<class T2>
Image< typename promote_trait< T, T2 >::TP >	operator/ (const T2 &val) const
	Divide each point in *this by scalar and return result.
Image< T >	operator<< (const unsigned int nbits) const
	Bit-shift left by constant and return result (type T must have operator<<()).
Image< T >	operator>> (const unsigned int nbits) const
	Bit-shift right by constant and return result (type T must have operator>>()).
template<class T2>
Image< typename promote_trait< T, T2 >::TP >	operator+ (const Image< T2 > &img) const
	Point-wise add img to image and return result.
template<class T2>
Image< typename promote_trait< T, T2 >::TP >	operator- (const Image< T2 > &img) const
	Point-wise subtract img from *this and return result.
template<class T2>
Image< typename promote_trait< T, T2 >::TP >	operator * (const Image< T2 > &img) const
	Point-wise multiply *this by img and return result.
template<class T2>
Image< typename promote_trait< T, T2 >::TP >	operator/ (const Image< T2 > &img) const
	Point-wise divide *this by img and return result.
void	clear (const T &val=T())
	clear contents (or set to given value)
Functions for testing/debugging only
bool	hasSameData (const Image< T > &b) const
	For testing/debugging only.
long	refCount () const throw ()
	For testing/debugging only.
bool	isShared () const throw ()
	For testing/debugging only.

Image< T > Class Template Reference

Detailed Description

template<class T>
class Image< T >

Iterators

Public Member Functions

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation