BitMaskIterator Class Reference

Traverses selected pixels within a BitMask. More...

#include <BitMaskIterator.h>

List of all members.

Public Member Functions
	BitMaskIterator (const BitMask *pBitMask, unsigned int x1, unsigned int y1, unsigned int x2, unsigned int y2)
	BitMaskIterator (const BitMask *pBitMask, const RasterElement *pRasterElement)
void	firstPixel ()
int	getCount () const
bool	getPixel (int col, int row) const
void	getPixelLocation (LocationType &pixelLocation) const
void	getBoundingBox (int &x1, int &y1, int &x2, int &y2) const
void	nextPixel ()
bool	operator++ ()
bool	operator++ (int)
BitMaskIterator	begin ()
BitMaskIterator	end ()
int	getNumSelectedRows () const
int	getNumSelectedColumns () const
LocationType	getOffset () const
bool	useAllPixels () const
bool	operator* () const
bool	operator== (const BitMaskIterator &other) const
bool	operator!= (const BitMaskIterator &other) const
int	getNumRows () const
int	getNumColumns () const
int	getBoundingBoxStartRow () const
int	getBoundingBoxStartColumn () const
int	getBoundingBoxEndRow () const
int	getBoundingBoxEndColumn () const
int	getRowOffset () const
int	getColumnOffset () const
int	getPixelRowLocation () const
int	getPixelColumnLocation () const

---

Detailed Description

Traverses selected pixels within a BitMask.

This class provides a convenient way to traverse the selected pixels within a given area of a BitMask object. The BitMaskIterator extents can be set to either custom values or the extents of a RasterElement.

The iterator incorporates the outside flag of the BitMask when determining whether a pixel is selected. The getPixel(int,int) const method is provided to query the selected state of any pixel within the extents. A call to getPixel() for pixel locations outside the extents of the BitMasKIterator will return false.

This class is intended to be used in place of directly traversing the BitMask.

Warning:

The iterator does not assume ownership over the BitMask. It is intended to be used in place of directly traversing the BitMask. Also for efficiency purposes, this class assumes that the BitMask is valid (i.e. not deleted) throughout the lifetime of the iterator.

Definition at line 44 of file BitMaskIterator.h.

---

Constructor & Destructor Documentation

BitMaskIterator::BitMaskIterator	(	const BitMask *	pBitMask,
		unsigned int	x1,
		unsigned int	y1,
		unsigned int	x2,
		unsigned int	y2
	)

Constructs a BitMaskIterator with given extents.

All parameters are zero-based and inclusive. Upon construction, the iterator's pixel location is set to the first selected pixel within the iterator's bounding box (the intersection of the iterator extents and the BitMask minimal bounding box). If no pixels within the iterator's bounding box are selected, the pixel location is set to (-1, -1), which is equivalent to BitMaskIterator::end().

Parameters:

	pBitMask	The BitMask to traverse. NULL is a valid value for the BitMask. Use of a NULL BitMask allows algorithms to be designed with a single code path, e.g., BitMaskIterator bit(pAoi, 0, 0, 100, 100) where pAoi can be NULL or a valid pointer.
	x1	The first column of the area over which the iterator may operate. The intersection between this area and the BitMask determines the area to be traversed. This value must be non-negative and less than or equal to the maximum value that the int type will support on the platform. This is enforced by setting larger values to that maximum value.
	y1	The first row of the area over which the iterator may operate. The intersection between this area and the BitMask determines the area to be traversed. This value must be non-negative and less than or equal to the maximum value that the int type will support on the platform. This is enforced by setting larger values to that maximum value.
	x2	The last column of the area over which the iterator may operate. The intersection between this area and the BitMask determines the area to be traversed. This value must be non-negative and less than or equal to the maximum value that the int type will support on the platform. This is enforced by setting larger values to that maximum value.
	y2	The last row of the area over which the iterator may operate. The intersection between this area and the BitMask determines the area to be traversed. This value must be non-negative and less than or equal to the maximum value that the int type will support on the platform. This is enforced by setting larger values to that maximum value.

BitMaskIterator::BitMaskIterator	(	const BitMask *	pBitMask,
		const RasterElement *	pRasterElement
	)

Constructs a BitMaskIterator using the extents from a given RasterElement.

Upon construction, the iterator's pixel location is set to the first selected pixel within the iterator's bounding box (the intersection of the iterator extents and the BitMask minimal bounding box). If no pixels within the iterator's bounding box are selected, the pixel location is set to (-1, -1), which is equivalent to BitMaskIterator::end().

Parameters:

	pBitMask	The BitMask to traverse. NULL is a valid value for the BitMask. Use of a NULL BitMask allows algorithms to be designed with a single code path, e.g., BitMaskIterator bit(pAoi, pRaster) where pAoi can be NULL or a valid pointer.
	pRasterElement	The RasterElement supplying the extents that will define the area over which the iterator may operate. The extents are defined by the number of rows and columns in the RasterElement, i.e., (0, 0) to (num cols - 1, num rows - 1). Any offset to other elements is ignored.

---

Member Function Documentation

void BitMaskIterator::firstPixel

(

)

Resets the pixel location to the first pixel.

This method re-initializes the state of the BitMaskIterator to point at the first selected pixel of the BitMask within the extents provided when the iterator was constructed (the iterator's bounding box).

See also:

nextPixel()

int BitMaskIterator::getCount

(

)

const

Gets the number of selected pixels.

To get the number of selected pixels, this method must iterate over the entire extents, which may be slow based on the size of the extents. After this method is called once, the selected pixel count is stored internally, so subsequent calls to getCount() are much faster.

Returns:

Returns the number of selected pixels within the extents.

bool BitMaskIterator::getPixel	(	int	col,
		int	row
	)			const

Queries whether a given pixel is selected.

Parameters:

	col	The zero-based column number of the pixel to query.
	row	The zero-based row number of the pixel to query.

Returns:

Returns true if the given pixel is selected or if the BitMask is NULL and the pixel is contained within the iterator's extents; otherwise returns false. Also returns false if the given pixel is outside the iterator's extents.

See also:

getPixelLocation()

void BitMaskIterator::getPixelLocation

(

LocationType &

pixelLocation

)

const

Gets the current pixel location.

Parameters:

pixelLocation

Populated with the current pixel location. When an iterator is constructed, its pixel location is the first selected pixel. If no pixels are selected, the pixel location is (-1, -1), which is equivalent to BitMaskIterator::end().

void BitMaskIterator::getBoundingBox	(	int &	x1,
		int &	y1,
		int &	x2,
		int &	y2
	)			const

Gets the bounding box over which the iterator iterates.

If the outside flag in the underlying BitMask is on, this method populates the given parameters with the iterator extents set in the constructor. All parameter values are zero-based and inclusive.

Parameters:

	x1	The starting column for iteration.
	y1	The starting row for iteration.
	x2	The ending column for iteration.
	y2	The ending row for iteration.

See also:

getNumSelectedRows() getNumSelectedColumns()

void BitMaskIterator::nextPixel

(

)

Advances the pixel location to the next selected pixel.

If there are no more selected pixels within the extents, the state of the iterator is equivalent to BitMaskIterator::end().

See also:

operator++(), operator++(int)

bool BitMaskIterator::operator++

(

)

Advances the pixel location to the next selected pixel.

This overloads the prefix increment operator.

Returns:

Returns true if the iterator advanced to the next selected pixel or the BitMask is NULL and the pixel is contained within the extents of the iterator. If there are no more selected pixels within the iterator extents, the state of the iterator is equivalent to BitMaskIterator::end() and false is returned.

See also:

nextPixel(), operator++(int)

bool BitMaskIterator::operator++

(

int

)

Advances the pixel location to the next selected pixel.

This overloads the postfix increment operator. A dummy parameter is used to differentiate between the signatures of the postfix (var++) operator and the prefix (++var) operator.

Returns:

Returns true if the iterator advanced to the next selected pixel or the BitMask is NULL and the pixel is contained within the extents of the iterator. If there are no more selected pixels within the iterator extents, the state of the iterator is equivalent to BitMaskIterator::end() and false is returned.

See also:

nextPixel(), operator++()

BitMaskIterator BitMaskIterator::begin

(

)

Creates an iterator that is ready to start traversing the BitMask.

Returns:

Returns a valid iterator with the conditions set to the initial conditions of this iterator.

BitMaskIterator BitMaskIterator::end

(

)

Creates an iterator that has finished traversing the BitMask.

Returns:

Returns an invalid iterator with invalid conditions to represent an iterator that has finished traversing the BitMask.

int BitMaskIterator::getNumSelectedRows

(

)

const

Gets the number of rows contained within the intersection of the iterator extents and the minimal bounding box for the BitMask selected pixels.

If the BitMask Outside flag is set, this will be equal to the number of rows in the iterator extents.

Returns:

Returns the number of rows spanning the range of the BitMaskIterator bounding box.

See also:

getBoundingBox()

int BitMaskIterator::getNumSelectedColumns

(

)

const

Gets the number of columns contained within the intersection of the iterator extents and the minimal bounding box for the BitMask selected pixels.

If the BitMask Outside flag is set, this will be equal to the number of columns in the iterator extents.

Returns:

Returns the number of columns spanning the range of the BitMaskIterator bounding box.

See also:

getBoundingBox()

LocationType BitMaskIterator::getOffset

(

)

const

Gets the distance in pixels from the beginning of the iterator extents to the start of the iterator bounding box.

For an unrotated, rectangular BitMap, it will be the distance between the beginning of the iterator extents and the first selected pixel in the BitMask.

Returns:

Returns the offset in (column, row) coordinates from the beginning of the iterator extents to the start of the iterator bounding box. A default constructed LocationType indicating no offset is returned in the following cases:

• The BitMask is NULL.
• The method BitMask::isOutsideSelected() returns true.

See also:

getBoundingBox()

bool BitMaskIterator::useAllPixels

(

)

const

Determines if the iterator will iterate over every every pixel within the iterator extents, i.e., every pixel within the iterator extends is selected.

Returns:

Returns true if every pixel within the iterator extents is selected; otherwise returns false.

See also:

getBoundingBox()

bool BitMaskIterator::operator*

(

)

const

Queries whether the current pixel is selected.

Returns:

Returns true if the current pixel is selected or the BitMask is NULL and the pixel is contained within the iterator extents; otherwise returns false.

See also:

getPixel(int,int) const

bool BitMaskIterator::operator==

(

const BitMaskIterator &

other

)

const

Compares the position of this iterator with that of another.

Parameters:

other

The iterator with which to compare its position.

Returns:

Returns true if the position of the given iterator matches the position of this iterator; otherwise returns false.

See also:

operator!=()

bool BitMaskIterator::operator!=

(

const BitMaskIterator &

other

)

const

Compares the position of this iterator with that of another.

Parameters:

other

The iterator with which to compare its position.

Returns:

Returns true if the position of the given iterator does not match the position of this iterator; otherwise returns false.

See also:

operator==()

int BitMaskIterator::getNumRows

(

)

const

Gets the number of rows contained within the full extents of the iterator.

This method just returns either the number of rows in the extents passed to the constructor or the number of rows in the raster element passed to the constructor. It should not be used in iterating over the BitMask passed to the constructor. Use getNumSelectedRows() instead.

Returns:

Returns the number of rows within the iterator extents.

See also:

getNumSelectedRows(), getNumSelectedColumns()

int BitMaskIterator::getNumColumns

(

)

const

Gets the number of columns contained within the full extents of the iterator.

This method just returns either the number of columns in the extents passed to the constructor or the number of columns in the raster element passed to the constructor. It should not be used in iterating over the BitMask passed to the constructor. Use getNumSelectedColumns() instead.

Returns:

Returns the number of columns within the iterator extents.

See also:

getNumSelectedRows(), getNumSelectedColumns()

int BitMaskIterator::getBoundingBoxStartRow

(

)

const

Gets the starting row in pixel coordinates of the bounding box over which the iterator iterates.

Returns:

Returns the starting row for iteration. This will be the number in pixel coordinates of the first row in the iterator bounding box if the Outside flag in the underlying BitMask is off. If the Outside flag is on, this method returns the number of the first row in the full extents of the iterator. The return value is zero-based and inclusive.

See also:

getBoundingBox(), getBoundingBoxStartColumn()

int BitMaskIterator::getBoundingBoxStartColumn

(

)

const

Gets the starting column in pixel coordinates of the bounding box over which the iterator iterates.

Returns:

Returns the starting column for iteration. This will be the number in pixel coordinates of the first column in the iterator bounding box if the Outside flag in the underlying BitMask is off. If the Outside flag is on, this method returns the number of the first column in the full extents of the iterator. The return value is zero-based and inclusive.

See also:

getBoundingBox(), getBoundingBoxStartRow()

int BitMaskIterator::getBoundingBoxEndRow

(

)

const

Gets the ending row in pixel coordinates of the bounding box over which the iterator iterates.

Returns:

Returns the ending row for iteration. This will be the number in pixel coordinates of the last row in the iterator bounding box if the Outside flag in the underlying BitMask is off. If the Outside flag is on, this method returns the number of the last row in the full extents of the iterator. The return value is zero-based and inclusive.

See also:

getBoundingBox(), getBoundingBoxEndColumn()

int BitMaskIterator::getBoundingBoxEndColumn

(

)

const

Gets the ending column in pixel coordinates of the bounding box over which the iterator iterates.

Returns:

Returns the ending column for iteration. This will be the number in pixel coordinates of the last column in the iterator bounding box if the Outside flag in the underlying BitMask is off. If the Outside flag is on, this method returns the number of the last column in the full extents of the iterator. The return value is zero-based and inclusive.

See also:

getBoundingBox(), getBoundingBoxEndRow()

int BitMaskIterator::getRowOffset

(

)

const

Gets the distance in pixels from the beginning of the iterator extents to the first row in the iterator bounding box.

Returns:

Returns the offset in row coordinates from the beginning of the iterator extents to the first row in the iterator bounding box. A value of zero indicating no offset is returned in the following cases:

• The BitMask is NULL.
• The method BitMask::isOutsideSelected() returns true.

See also:

getOffset(), getColumnOffset()

int BitMaskIterator::getColumnOffset

(

)

const

Gets the distance in pixels from the beginning of the iterator extents to the first column in the iterator bounding box.

Returns:

Returns the offset in column coordinates from the beginning of the iterator extents to the first column in the iterator bounding box. A value of zero indicating no offset is returned in the following cases:

• The BitMask is NULL.
• The method BitMask::isOutsideSelected() returns true.

See also:

getOffset(), getRowOffset()

int BitMaskIterator::getPixelRowLocation

(

)

const

Gets the row of the current pixel.

Returns:

Returns the row of the current pixel location. When an iterator is constructed, its pixel row location is the row of the first selected pixel. If no pixels are selected, the pixel row and column are -1, which is equivalent to BitMaskIterator::end().

See also:

getPixelColumnLocation()

int BitMaskIterator::getPixelColumnLocation

(

)

const

Gets the column of the current pixel.

Returns:

Returns the column of the current pixel location. When an iterator is constructed, its pixel column location is the column of the first selected pixel. If no pixels are selected, the pixel row and column are -1, which is equivalent to BitMaskIterator::end().

See also:

getPixelRowLocation()