|
casacore
|
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
|
casacore
|
A readonly iterator for Lattices. 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... | |
A readonly iterator for Lattices.
Public interface
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.
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:
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:
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:
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.
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.
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.
| 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.
|
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).
| 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.
| 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.
| 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.
| casacore::RO_LatticeIterator< T >::~RO_LatticeIterator | ( | ) |
Destructor (cleans up dangling references and releases memory)
| Bool casacore::RO_LatticeIterator< T >::atEnd | ( | ) | const |
| Bool casacore::RO_LatticeIterator< T >::atStart | ( | ) | const |
| 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.
| const Cube<T>& casacore::RO_LatticeIterator< T >::cubeCursor | ( | ) | const |
| const Array<T>& casacore::RO_LatticeIterator< T >::cursor | ( | ) | const |
| IPosition casacore::RO_LatticeIterator< T >::cursorShape | ( | ) | const |
| IPosition casacore::RO_LatticeIterator< T >::endPosition | ( | ) | const |
|
inline |
Is the iterator object empty?
Definition at line 255 of file LatticeIterator.h.
References casacore::RO_LatticeIterator< T >::itsIterPtr.
|
inline |
Return the underlying lattice.
Definition at line 259 of file LatticeIterator.h.
References casacore::RO_LatticeIterator< T >::itsIterPtr.
| IPosition casacore::RO_LatticeIterator< T >::latticeShape | ( | ) | const |
| const Matrix<T>& casacore::RO_LatticeIterator< T >::matrixCursor | ( | ) | const |
| 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.
| 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.
| 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).
| Bool casacore::RO_LatticeIterator< T >::operator++ | ( | int | ) |
| 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).
| Bool casacore::RO_LatticeIterator< T >::operator-- | ( | int | ) |
| 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.
| IPosition casacore::RO_LatticeIterator< T >::position | ( | ) | const |
| void casacore::RO_LatticeIterator< T >::reset | ( | ) |
| 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).
|
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().
1.8.5