In principle, iteration through a MaskedLattice can be done as:
void someFunc (const MaskedLattice<Float>& lattice)
{
RO_LatticeIterator<Float> iter(lattice);
Array<Bool> mask;
while (! iter.atEnd()) {
const Array<Float>& array = iter.cursor();
lattice.getMaskSlice (mask, iter.position(), array.shape());
iter++;
}
}
Using a MaskedLatticeIterator makes getting the mask slightly more
convenient.
void someFunc (const MaskedLattice<Float>& lattice)
{
RO_MaskedLatticeIterator<Float> iter(lattice);
Array<Bool> mask;
while (! iter.atEnd()) {
const Array<Float>& array = iter.cursor();
iter.getMask (mask);
iter++;
}
}
However, the most important reason to use MaskedLatticeIterator is
performance. If the underlying lattice is a LatticeExpr object,
the expression will be evaluated twice if a LatticeIterator object
is used. The reason is that the lattice in the LatticeIterator is
a different object from the lattice object used to get the mask.
Hence, the optimization put in LatticeExpr is not used.
When using a MaskedLatticeIterator the same lattice object is used
to get data and mask.
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).
Construct the Iterator with the supplied data, and iteration strategy
Construct the Iterator with the supplied data. It uses a LatticeStepper with the supplied cursor shape as the iteration strategy.
The copy constructor uses reference semantics (ie. NO real copy is made). The function copy can be used to make a true copy.
Destructor (cleans up dangling references and releases memory)
Assignment uses reference semantics (ie. NO real copy is made). The function copy can be used to make a true copy.
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 MaskedLattice.
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 MaskedLattice uses a cache (e.g. PagedArray), the
cache is shared by the iterators.
Return the underlying MaskedLattice object.
Is the underlying MaskedLattice really masked?
Get the mask for the current position. It returns the same flag as MaskedLattice::getMaskSlice.
Fill the pointer with a pointer to the masked lattice. This pointer is a casted copy of the lattice pointer in the base class. In this way they share the same MaskedLattice object, which is needed for optimal performance of e.g. LatticeExpr. Otherwise getting data from the lattice and from the mask would result in 2 evaluations of the expression. However, the lattice can be a PagedArray (for example, for PagedImage). In that case a clone of the original MaskedLattice is used.