A read/write lattice iterator. More...

#include <LatticeIterator.h>

Inheritance diagram for casacore::LatticeIterator< T >:

Public Member Functions
	LatticeIterator ()
	The default constructor creates an empty object which is practically unusable. More...

	LatticeIterator (Lattice< T > &data, Bool useRef=True)
	Construct the Iterator with the supplied data. More...

	LatticeIterator (Lattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
	Construct the Iterator with the supplied data, and iteration strategy. More...

	LatticeIterator (Lattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
	Iterate through the data with a LatticeStepper that has uses the supplied cursorShape. More...

	LatticeIterator (const LatticeIterator< T > &other)
	The copy constructor uses reference semantics (ie. More...

	~LatticeIterator ()
	destructor (cleans up dangling references and releases memory) More...

LatticeIterator< T > &	operator= (const LatticeIterator< T > &other)
	Assignment uses reference semantics (ie. More...

LatticeIterator< T >	copy () const
	Make a copy of the iterator object. More...

Vector< T > &	rwVectorCursor ()
	Functions to return a window to the data in the Lattice. More...

Matrix< T > &	rwMatrixCursor ()

Cube< T > &	rwCubeCursor ()

Array< T > &	rwCursor ()

Vector< T > &	woVectorCursor ()

Matrix< T > &	woMatrixCursor ()

Cube< T > &	woCubeCursor ()

Array< T > &	woCursor ()

Bool	ok () const
	Function which checks the internals of the class for consistency. More...

Public Member Functions inherited from casacore::RO_LatticeIterator< T >
	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...

Additional Inherited Members
Protected Attributes inherited from casacore::RO_LatticeIterator< T >
CountedPtr < LatticeIterInterface< T > >	itsIterPtr
	The pointer to the Iterator. More...

Detailed Description

template<class T>
class casacore::LatticeIterator< T >

A read/write lattice iterator.

Intended use:

Public interface

Review Status

Reviewed By:: Peter Barnes
Date Reviewed:: 1999/10/30
Test programs:: tLatticeIterator

Prerequisite

Synopsis

LatticeIterator differs from the RO_LatticeIterator class in that the window into the Lattice data which moves with each iterative step may be used to alter the Lattice data itself. The moving "cursor" gives the user the door to reach in and change the basic Lattice before moving to another section of the Lattice.

LatticeIterator can be used in 3 ways:
- For readonly purposes using the cursor() functions. Note that if the entire iteration is readonly, it is better to use an RO_LatticeIterator object.
- To update (part of)the contents of the lattice (e.g. clip the value of some pixels). For this purpose the rwCursor functions should be used. They read the data (if not read yet) and mark the cursor for write.
- To fill the lattice. For this purpose the woCursor functions should be used. They do not read the data, but only mark the cursor for write.

When needed, writing the cursor data is done automatically when the cursor position changes or when the iterator is destructed.

Example

Here's an iterator that runs through a cube, assigning every element of each plane of the cube a value equal to the number of the plane. See LatticeStepper for an explanation of the navigator used here.

PagedArray<Float> pa("someName");
IPosition windowShape(2,pa.shape(0), pa.shape(1));
LatticeStepper stepper(pa.shape(), windowShape);
LatticeIterator<Float> iterator(pa, stepper);
Int planeNumber = 0;
for (iterator.reset(); !iterator.atEnd(); iterator++) {
iterator.woCursor() = planeNumber++;
}

Here's an iterator that runs through a cube, subtracting the mean from each line of the cube with a mean < 0. See TiledLineStepper for an explanation of the navigator used here.

PagedArray<Float> pa("someName");
TiledLineStepper stepper(pa.shape(), pa.niceCursorShape(), 0);
LatticeIterator<Float> iterator(pa, stepper);
Int planeNumber = 0;
for (iterator.reset(); !iterator.atEnd(); iterator++) {
Float meanLine = mean(iterator.cursor());
if (meanLine < 0) {
iterator.rwCursor() -= meanLine;
}
}

Note that in this last example no more vectors than required are written. This is achieved by using the readonly function cursor in the test and using rwCursor only when data needs to be changed.
Note that rwCursor does not read the data again. They are still readily available.

Definition at line 428 of file LatticeIterator.h.

Constructor & Destructor Documentation

template<class T>

casacore::LatticeIterator< T >::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.

template<class T>

casacore::LatticeIterator< T >::LatticeIterator	(	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).

template<class T>

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

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

template<class T>

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

Iterate through the data with a LatticeStepper that has uses the supplied cursorShape.

template<class T>

casacore::LatticeIterator< T >::LatticeIterator ( const 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.

template<class T>

casacore::LatticeIterator< T >::~LatticeIterator ( )

destructor (cleans up dangling references and releases memory)

Member Function Documentation

template<class T>

LatticeIterator<T> casacore::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.

template<class T>

Bool casacore::LatticeIterator< T >::ok ( ) const

Function which checks the internals of the class for consistency.

Returns True if everything is fine. Otherwise returns False.

template<class T>

LatticeIterator<T>& casacore::LatticeIterator< T >::operator= ( const LatticeIterator< T > & other )

Assignment uses reference semantics (ie.

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

template<class T>

Cube<T>& casacore::LatticeIterator< T >::rwCubeCursor ( )

template<class T>

Array<T>& casacore::LatticeIterator< T >::rwCursor ( )

template<class T>

Matrix<T>& casacore::LatticeIterator< T >::rwMatrixCursor ( )

template<class T>

Vector<T>& casacore::LatticeIterator< T >::rwVectorCursor ( )

Functions to return a window to the data in 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) (e.g. VectorCursor cannot be used when the cursor is 2D).
When the iterator state changes (e.g. by moving, destruction) the data are automatically rewritten before the iterator state is changed.
The rw (read/write) versions should be used to read the data first. They are useful to update a lattice. The wo (writeonly) versions do not read the data. They only return a cursor of the correct shape and are useful to fill a lattice. Note that it sets the state to 'data read'. I.e., a subsequent call to, say, cursor() does not read the data, which would destroy the contents of the cursor which may just be filled by the user.

template<class T>

Cube<T>& casacore::LatticeIterator< T >::woCubeCursor ( )

template<class T>

Array<T>& casacore::LatticeIterator< T >::woCursor ( )

template<class T>

Matrix<T>& casacore::LatticeIterator< T >::woMatrixCursor ( )

template<class T>

Vector<T>& casacore::LatticeIterator< T >::woVectorCursor ( )

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

casa/casacore/lattices/Lattices/LatticeIterator.h

Public Member Functions

Additional Inherited Members

Detailed Description

template<class T> class casacore::LatticeIterator< T >

Intended use:

Review Status

Prerequisite

Synopsis

Example

Constructor & Destructor Documentation

Member Function Documentation

template<class T>
class casacore::LatticeIterator< T >