Loading...
Searching...
No Matches
casacore::LatticeIterator< T > Class Template Reference
lattices package (libcasa_lattices) » Lattices_module

A read/write lattice iterator. More...

`#include <LatticeIterator.h>`

## 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.
Public Member Functions inherited from casacore::RO_LatticeIterator< T >
| RO_LatticeIterator ()
| The default constructor creates an empty object which is practically unusable.
| RO_LatticeIterator (const Lattice< T > &data, Bool useRef=True)
| Construct the Iterator with the supplied data.
| RO_LatticeIterator (const Lattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
| Construct the Iterator with the supplied data, and iteration strategy.
| RO_LatticeIterator (const Lattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
| Construct the Iterator with the supplied data.
| RO_LatticeIterator (const RO_LatticeIterator< T > &other)
| The copy constructor uses reference semantics (ie.
| ~RO_LatticeIterator ()
| Destructor (cleans up dangling references and releases memory).
RO_LatticeIterator< T > & | operator= (const RO_LatticeIterator< T > &other)
| Assignment uses reference semantics (ie.
RO_LatticeIterator< T > | copy () const
| Make a copy of the iterator object.
Bool | isNull () const
| Is the iterator object empty?
Lattice< T > & | lattice () const
| Return the underlying lattice.
Bool | operator++ ()
| Increment operator - increment the cursor to the next position.
Bool | operator++ (int)
Bool | operator-- ()
| Decrement operator - decrement the cursor to the previous position.
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.
Bool | atStart () const
| Function which returns a value of "True" if the cursor is at the beginning of the Lattice, otherwise, returns "False".
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.
uInt | nsteps () const
| Function to return the number of steps (increments or decrements) taken since construction (or since last reset).
IPosition | position () const
| Function which returns the current position of the beginning of the cursor within the Lattice.
IPosition | endPosition () const
| Function which returns the current position of the end of the cursor.
IPosition | latticeShape () const
| Function which returns the shape of the Lattice being iterated through.
IPosition | cursorShape () const
| Function which returns the shape of the cursor which is iterating through the Lattice.
const Vector< T > & | vectorCursor () const
| Functions which returns a window to the data in the Lattice.
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.

## Additional Inherited Members

Protected Attributes inherited from casacore::RO_LatticeIterator< T >
std::shared_ptr< LatticeIterInterface< T > > | itsIterPtr
| The pointer to the Iterator.

## 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

- 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++;
}
casacore::IPosition
Definition IPosition.h:117
casacore::LatticeIterator::LatticeIterator
LatticeIterator()
The default constructor creates an empty object which is practically unusable.
casacore::LatticeStepper
Definition LatticeStepper.h:266
casacore::PagedArray
Definition PagedArray.h:372
casacore::pa
LatticeExprNode pa(const LatticeExprNode &left, const LatticeExprNode &right)
This function finds 180/pi*atan2(left,right)/2.
casacore::Int
int Int
Definition aipstype.h:48

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;
}
}
casacore::TiledLineStepper
Definition TiledLineStepper.h:191
casacore::mean
LatticeExprNode mean(const LatticeExprNode &expr)
casacore::Float
float Float
Definition aipstype.h:52

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 422 of file LatticeIterator.h.

## Constructor & Destructor Documentation

## LatticeIterator() [1/5]

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.

Referenced by copy(), LatticeIterator(), and operator=().

## LatticeIterator() [2/5]

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).

References casacore::True.

## LatticeIterator() [3/5]

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.

References casacore::True.

## LatticeIterator() [4/5]

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.

References casacore::RO_LatticeIterator< T >::cursorShape(), and casacore::True.

## LatticeIterator() [5/5]

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.

References LatticeIterator().

## ~LatticeIterator()

template<class T>

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

destructor (cleans up dangling references and releases memory)

## Member Function Documentation

## copy()

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.

References LatticeIterator().

## ok()

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.

References casacore::RO_LatticeIterator< T >::cursorShape(), casacore::RO_LatticeIterator< T >::endPosition(), casacore::RO_LatticeIterator< T >::isNull(), casacore::RO_LatticeIterator< T >::itsIterPtr, casacore::RO_LatticeIterator< T >::position(), and casacore::RO_LatticeIterator< T >::RO_LatticeIterator().

## operator=()

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.

References LatticeIterator().

## rwCubeCursor()

template<class T>

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

## rwCursor()

template<class T>

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

## rwMatrixCursor()

template<class T>

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

## rwVectorCursor()

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.

## woCubeCursor()

template<class T>

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

## woCursor()

template<class T>

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

## woMatrixCursor()

template<class T>

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

## woVectorCursor()

template<class T>

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

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

- images/Images/ImageRegrid.h
- lattices/Lattices/LatticeIterator.h