casa::LatticeIterator< T > Class Template Reference

A read/write lattice iterator. More...

#include <LatticeIterator.h>

Inheritance diagram for casa::LatticeIterator< T >:

List of all members.

Public Member Functions
	LatticeIterator ()
	The default constructor creates an empty object which is practically unusable.
	LatticeIterator (Lattice< T > &data, Bool useRef=True)
	Construct the Iterator with the supplied data.
	LatticeIterator (Lattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
	Construct the Iterator with the supplied data, and iteration strategy.
	LatticeIterator (Lattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
	Iterate through the data with a LatticeStepper that has uses the supplied cursorShape.
	LatticeIterator (const LatticeIterator< T > &other)
	The copy constructor uses reference semantics (ie.
	~LatticeIterator ()
	destructor (cleans up dangling references and releases memory)
LatticeIterator< T > &	operator= (const LatticeIterator< T > &other)
	Assignment uses reference semantics (ie.
LatticeIterator< T >	copy () const
	Make a copy of the iterator object.
Vector< T > &	rwVectorCursor ()
	Functions to return a window to the data in the Lattice.
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.

---

Detailed Description

template<class T>
class casa::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

• RO_LatticeIterator
• Lattice
• LatticeNavigator
• Array

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>

casa::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>

casa::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>

casa::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>

casa::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>

casa::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>

casa::LatticeIterator< T >::~LatticeIterator

(

)

destructor (cleans up dangling references and releases memory)

---

Member Function Documentation

template<class T>

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

Reimplemented from casa::RO_LatticeIterator< T >.

template<class T>

Bool casa::LatticeIterator< T >::ok

(

)

const

Function which checks the internals of the class for consistency.

Returns True if everything is fine. Otherwise returns False.

Reimplemented from casa::RO_LatticeIterator< T >.

template<class T>

LatticeIterator<T>& casa::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>& casa::LatticeIterator< T >::rwCubeCursor

(

)

template<class T>

Array<T>& casa::LatticeIterator< T >::rwCursor

(

)

template<class T>

Matrix<T>& casa::LatticeIterator< T >::rwMatrixCursor

(

)

template<class T>

Vector<T>& casa::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>& casa::LatticeIterator< T >::woCubeCursor

(

)

template<class T>

Array<T>& casa::LatticeIterator< T >::woCursor

(

)

template<class T>

Matrix<T>& casa::LatticeIterator< T >::woMatrixCursor

(

)

template<class T>

Vector<T>& casa::LatticeIterator< T >::woVectorCursor

(

)

---

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

• casacore/lattices/Lattices/LatticeIterator.h