casacore::RO_LatticeIterator< T > Class Template Reference

More...

#include <LatticeIterator.h>

Public Member Functions
	RO_LatticeIterator ()
	The default constructor creates an empty object which is practically unusable. More...
	RO_LatticeIterator (const Lattice< T > &data, Bool useRef=True)
	Construct the Iterator with the supplied data. More...
	RO_LatticeIterator (const Lattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
	Construct the Iterator with the supplied data, and iteration strategy. More...
	RO_LatticeIterator (const Lattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
	Construct the Iterator with the supplied data. More...
	RO_LatticeIterator (const RO_LatticeIterator< T > &other)
	The copy constructor uses reference semantics (ie. More...
	~RO_LatticeIterator ()
	Destructor (cleans up dangling references and releases memory) More...
RO_LatticeIterator< T > &	operator= (const RO_LatticeIterator< T > &other)
	Assignment uses reference semantics (ie. More...
RO_LatticeIterator< T >	copy () const
	Make a copy of the iterator object. More...
Bool	isNull () const
	Is the iterator object empty? More...
Lattice< T > &	lattice () const
	Return the underlying lattice. More...
Bool	operator++ ()
	Increment operator - increment the cursor to the next position. More...
Bool	operator++ (int)
Bool	operator-- ()
	Decrement operator - decrement the cursor to the previous position. More...
Bool	operator-- (int)
void	reset ()
	Function which resets the cursor to the beginning of the Lattice and resets the number of steps taken to zero. More...
Bool	atStart () const
	Function which returns a value of "True" if the cursor is at the beginning of the Lattice, otherwise, returns "False". More...
Bool	atEnd () const
	Function which returns a value of "True" if an attempt has been made to move the cursor beyond the end of the Lattice. More...
uInt	nsteps () const
	Function to return the number of steps (increments or decrements) taken since construction (or since last reset). More...
IPosition	position () const
	Function which returns the current position of the beginning of the cursor within the Lattice. More...
IPosition	endPosition () const
	Function which returns the current position of the end of the cursor. More...
IPosition	latticeShape () const
	Function which returns the shape of the Lattice being iterated through. More...
IPosition	cursorShape () const
	Function which returns the shape of the cursor which is iterating through the Lattice. More...
const Vector< T > &	vectorCursor () const
	Functions which returns a window to the data in the Lattice. More...
const Matrix< T > &	matrixCursor () const
const Cube< T > &	cubeCursor () const
const Array< T > &	cursor () const
Bool	ok () const
	Function which checks the internals of the class for consistency. More...

Protected Attributes
CountedPtr< LatticeIterInterface< T > >	itsIterPtr
	The pointer to the Iterator. More...

Detailed Description

template<class T>
class casacore::RO_LatticeIterator< T >

A readonly iterator for Lattices

Intended use:

Public interface

Review Status

Reviewed By:

Peter Barnes

Date Reviewed:

1999/10/30

Test programs:

tLatticeIterator

Prerequisite

• Lattice
• LatticeNavigator
• Array

Etymology

The leading "RO" is shorthand for "readonly", which indicates that an RO_LatticeIterator is used for traversing a Lattice, examining and possibly extracting its contents, but not for modifying it.

Synopsis

This class provides a convenient way to traverse any class derived from Lattice. You can iterate through the Lattice's data from "start" to "end" by calling operator++, and reverse direction by calling operator--. You can return immediately to the beginning by calling the reset function. The RO_LatticeIterator gives the user the opportunity to methodically walk through the data, in an efficient way.

The supplied LatticeNavigator determines how to step through the Lattice. It can, for instance, be line by line, but it can also be in a more complicated way. When no navigator is supplied, a default navigator will be used which steps in the optimum way.

A cursor (which is an Array object) is used to return the data for each step in the iteration process. Depending on the navigator used the cursor can have a different shape for each step of the iteration. This is especially true when the end of an axis is reached for a non-integrally fitting cursor shape.
The cursor() function returns an Array which has the same dimensionality as the Lattice. It is, however, also possible to get an Array with a lower dimensionality by using the correct function in the group vectorCursor(), matrixCursor(), and cubeCursor(). Those functions remove (some) degenerated axes resulting in a vector, matrix or cube. When, for example, a LatticeStepper with shape [64,1,1] is used, the vectorCursor() can be used. It will remove the degenerated axes (length 1) and return the cursor as a Vector object. Note that matrixCursor() cannot be used, because removing the degenerated axes results in a 1D array.

Generally iterators should not be long-lived objects - create new ones when needed rather than keeping one around for a long time to be reused. This is because the cache memory used by the cursor will be released when the iterator is destroyed.

The purpose of this class is to hide the possibly complicated implementation and structure of the Lattice classes, and allow you to iterate through a Lattice with the same ease as one iterates through a Fortran or C vector. For example, and assuming that initialization has been done properly, here's a typical 'for' loop:

// code omitted  which associates Lattice object and the iterator
for (iterator.reset(); !iterator.atEnd(); iterator++) {
meanValue = mean(iterator.cursor()); 
}

The iterator's cursor() member function returns a reference to that part of the Lattice data which is presently "seen" by the LatticeIterator.

Before explaining the initialization of an iterator, the LatticeNavigator class must be further introduced. This is an abstract base class, from which concrete navigators are derived. After one of these is created, you attach it to the LatticeIterator, and it provides a specific technique for navigating through the Lattice. Different navigators deliver different traversal schemes. The most basic is LatticeStepper, which moves a specified shape sequentially through the Lattice – for example, by moving one plane at a time, front to back, through a cube. Another (future) navigator might be designed to move a small, 2-dimensional plane through a cube, centering each iteration on the brightest pixel of the cube's plane, and ignoring the darker regions of the cube.

The performance and memory usage of an iteration through a lattice (in particular through a PagedArray) depends very heavily on the navigator used. Currently there are three navigators available:

1. LatticeStepper steps sequentially through a lattice with the given cursor shape. This can use a lot of memory for the PagedArray cache.
2. TiledLineStepper steps line by line through a lattice. However, it is doing that in such a way that as few tiles as possible need to kept in the PagedArray cache. This reduces memory usage considerably.
3. TileStepper steps tile by tile through a lattice. This navigator requires a PagedArray cache of 1 tile only. However, it can only be used for application in which the iteration order is not important (e.g. addition, determining max).

The class LatticeApply is very useful to iterate through a Lattice while applying an algorithm. It makes it possible for the user to concentrate on the algorithm.

Here's a typical iterator declaration:

RO_LatticeIterator<Float> iterator(pagedArray, stepper);

The template identifier Float defines the data type of Array object that will be the iterator's cursor.
The pagedArray constructor argument names a PagedArray object, which is what the iterator will traverse. The stepper argument is a LatticeStepper which defines the method of iteration.

Example

When passed the name of a previously created PagedArray stored on disk, this function will traverse the whole array, and report the average value of all of the elements. Imagine that the filename contains a PagedArray with dimension 64 x 64 x 8.

void demonstrateIterator (const String& filename)
{
PagedArray<Float> pagedArray(filename);
IPosition latticeShape = pagedArray.shape();
cout << "paged array has shape: " << latticeShape << endl;
 
// Construct the iterator.  since we only want to read the PagedArray,
// use the read-only class, which disallows writing back to the cursor.
// No navigator is given, so the default TileStepper is used
// which ensures optimum performance.
RO_LatticeIterator<Float> iterator(pagedArray);
 
// Add for each iteration step the sum of the cursor elements to the sum.
// Note that the cursor is an Array object and that the function sum
// is defined in ArrayMath.h.
Float runningSum = 0.0;
for (iterator.reset(); !iterator.atEnd(); iterator++) {
runningSum += sum(iterator.cursor());
}
cout << "average value, from demonstrateIterator: " 
<< runningSum / latticeShape.product() << endl;
}

Motivation

Iterator classes are a standard feature in C++ libraries – they provide convenience and allow the implementation of the "iteratee" to be kept hidden.

Definition at line 204 of file LatticeIterator.h.

Constructor & Destructor Documentation

RO_LatticeIterator() [1/5]

template<class T >

casacore::RO_LatticeIterator< T >::RO_LatticeIterator

(

)

The default constructor creates an empty object which is practically unusable.

It can only be used as the source or target of an assignment. It can also be used as the source for the copy constructor and the copy function. Other functions do not check if the object is empty and will usually give a segmentation fault. The function isNull() can be used to test if the object is empty.

RO_LatticeIterator() [2/5]

template<class T >

casacore::RO_LatticeIterator< T >::RO_LatticeIterator ( const Lattice< T > &  data, Bool  useRef = True  )

explicit

Construct the Iterator with the supplied data.

It uses a TileStepper as the default iteration strategy. useRef=True means that if possible the cursor arrays returned reference the data in the underlying lattice. This is only possible for ArrayLattice objects (or e.g. a SubLattice using it).

RO_LatticeIterator() [3/5]

template<class T >

casacore::RO_LatticeIterator< T >::RO_LatticeIterator	(	const Lattice< T > &	data,
		const LatticeNavigator &	method,
		Bool	useRef = True
	)

Construct the Iterator with the supplied data, and iteration strategy.

RO_LatticeIterator() [4/5]

template<class T >

casacore::RO_LatticeIterator< T >::RO_LatticeIterator	(	const Lattice< T > &	data,
		const IPosition &	cursorShape,
		Bool	useRef = True
	)

Construct the Iterator with the supplied data.

It uses a LatticeStepper with the supplied cursor shape as the iteration strategy.

RO_LatticeIterator() [5/5]

template<class T >

casacore::RO_LatticeIterator< T >::RO_LatticeIterator

(

const RO_LatticeIterator< T > &

other

)

The copy constructor uses reference semantics (ie.

NO real copy is made). The function copy can be used to make a true copy.

~RO_LatticeIterator()

template<class T >

casacore::RO_LatticeIterator< T >::~RO_LatticeIterator

(

)

Destructor (cleans up dangling references and releases memory)

Member Function Documentation

atEnd()

template<class T >

Bool casacore::RO_LatticeIterator< T >::atEnd

(

)

const

Function which returns a value of "True" if an attempt has been made to move the cursor beyond the end of the Lattice.

atStart()

template<class T >

Bool casacore::RO_LatticeIterator< T >::atStart

(

)

const

Function which returns a value of "True" if the cursor is at the beginning of the Lattice, otherwise, returns "False".

copy()

template<class T >

RO_LatticeIterator<T> casacore::RO_LatticeIterator< T >::copy

(

)

const

Make a copy of the iterator object.

This means that an independent navigator object is created to be able to iterate independently through the same Lattice. The position in the copied navigator is the same as the original. The reset function has to be used to start at the beginning.
Note that if the Lattice uses a cache (e.g. PagedArray), the cache is shared by the iterators.

cubeCursor()

template<class T >

const Cube<T>& casacore::RO_LatticeIterator< T >::cubeCursor

(

)

const

cursor()

template<class T >

const Array<T>& casacore::RO_LatticeIterator< T >::cursor

(

)

const

cursorShape()

template<class T >

IPosition casacore::RO_LatticeIterator< T >::cursorShape

(

)

const

Function which returns the shape of the cursor which is iterating through the Lattice.

The returned IPosition will have the same number of axes as the underlying Lattice.

endPosition()

template<class T >

IPosition casacore::RO_LatticeIterator< T >::endPosition

(

)

const

Function which returns the current position of the end of the cursor.

The returned IPosition will have the same number of axes as the underlying Lattice.

isNull()

template<class T >

Bool casacore::RO_LatticeIterator< T >::isNull ( ) const

inline

Is the iterator object empty?

Definition at line 255 of file LatticeIterator.h.

References casacore::RO_LatticeIterator< T >::itsIterPtr.

lattice()

template<class T >

Lattice<T>& casacore::RO_LatticeIterator< T >::lattice ( ) const

inline

Return the underlying lattice.

Definition at line 259 of file LatticeIterator.h.

References casacore::RO_LatticeIterator< T >::itsIterPtr.

latticeShape()

template<class T >

IPosition casacore::RO_LatticeIterator< T >::latticeShape

(

)

const

Function which returns the shape of the Lattice being iterated through.

The returned IPosition will always have the same number of axes as the underlying Lattice.

matrixCursor()

template<class T >

const Matrix<T>& casacore::RO_LatticeIterator< T >::matrixCursor

(

)

const

nsteps()

template<class T >

uInt casacore::RO_LatticeIterator< T >::nsteps

(

)

const

Function to return the number of steps (increments or decrements) taken since construction (or since last reset).

This is a running count of all cursor movement, thus doing N increments followed by N decrements results in 2N steps.

ok()

template<class T >

Bool casacore::RO_LatticeIterator< T >::ok

(

)

const

Function which checks the internals of the class for consistency.

Returns True if everything is fine otherwise returns False.

operator++() [1/2]

template<class T >

Bool casacore::RO_LatticeIterator< T >::operator++

(

)

Increment operator - increment the cursor to the next position.

These functions are forwarded to the current LatticeNavigator and both postfix and prefix versions will do the same thing.
They return True if the cursor moved (which should always be the case if the iterator is not at the end).

operator++() [2/2]

template<class T >

Bool casacore::RO_LatticeIterator< T >::operator++

(

int

)

operator--() [1/2]

template<class T >

Bool casacore::RO_LatticeIterator< T >::operator--

(

)

Decrement operator - decrement the cursor to the previous position.

These functions are forwarded to the current LatticeNavigator and both postfix and prefix versions will do the same thing.
They return True if the cursor moved (which should always be the case if the iterator is not at the start).

operator--() [2/2]

template<class T >

Bool casacore::RO_LatticeIterator< T >::operator--

(

int

)

operator=()

template<class T >

RO_LatticeIterator<T>& casacore::RO_LatticeIterator< T >::operator=

(

const RO_LatticeIterator< T > &

other

)

Assignment uses reference semantics (ie.

NO real copy is made). The function copy can be used to make a true copy.

position()

template<class T >

IPosition casacore::RO_LatticeIterator< T >::position

(

)

const

Function which returns the current position of the beginning of the cursor within the Lattice.

The returned IPosition will have the same number of axes as the underlying Lattice.

reset()

template<class T >

void casacore::RO_LatticeIterator< T >::reset

(

)

Function which resets the cursor to the beginning of the Lattice and resets the number of steps taken to zero.

vectorCursor()

template<class T >

const Vector<T>& casacore::RO_LatticeIterator< T >::vectorCursor

(

)

const

Functions which returns a window to the data in the Lattice.

These are used to read the data within the Lattice. Use the function that is appropriate to the current cursor dimension, AFTER REMOVING DEGENERATE AXES, or use the cursor function which works with any number of dimensions in the cursor. A call of the function whose return value is inappropriate with respect to the current cursor dimension will throw an exception (AipsError).

Member Data Documentation

itsIterPtr

template<class T >

CountedPtr<LatticeIterInterface<T> > casacore::RO_LatticeIterator< T >::itsIterPtr

protected

The pointer to the Iterator.

Definition at line 340 of file LatticeIterator.h.

Referenced by casacore::RO_LatticeIterator< T >::isNull(), and casacore::RO_LatticeIterator< T >::lattice().

---

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

• lattices/Lattices/LatticeIterator.h