casacore
Public Member Functions | Private Member Functions | Private Attributes | List of all members
casacore::RO_MaskedLatticeIterator< T > Class Template Reference

More...

#include <MaskedLatticeIterator.h>

Public Member Functions

 RO_MaskedLatticeIterator ()
 The default constructor creates an empty object which is practically unusable. More...
 
 RO_MaskedLatticeIterator (const MaskedLattice< T > &data, Bool useRef=True)
 Construct the Iterator with the supplied data. More...
 
 RO_MaskedLatticeIterator (const MaskedLattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
 Construct the Iterator with the supplied data, and iteration strategy. More...
 
 RO_MaskedLatticeIterator (const MaskedLattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
 Construct the Iterator with the supplied data. More...
 
 RO_MaskedLatticeIterator (const RO_MaskedLatticeIterator< T > &other)
 The copy constructor uses reference semantics (ie. More...
 
 ~RO_MaskedLatticeIterator ()
 Destructor (cleans up dangling references and releases memory) More...
 
RO_MaskedLatticeIterator< T > & operator= (const RO_MaskedLatticeIterator< T > &)
 Assignment uses reference semantics (ie. More...
 
RO_MaskedLatticeIterator< T > copy () const
 Make a copy of the iterator object. More...
 
MaskedLattice< T > & lattice () const
 Return the underlying MaskedLattice object. More...
 
Bool isMasked () const
 Is the underlying MaskedLattice really masked? More...
 
Bool getMask (COWPtr< Array< Bool > > &, Bool removeDegenerateAxes=False) const
 Get the mask for the current position. More...
 
Bool getMask (Array< Bool > &, Bool removeDegenerateAxes=False) const
 
Array< BoolgetMask (Bool removeDegenerateAxes=False) const
 
- 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...
 

Private Member Functions

 RO_MaskedLatticeIterator (const RO_LatticeIterator< T > &, const RO_MaskedLatticeIterator< T > &)
 Construct from a LatticeIterator (for copy function). More...
 
void fillPtr (const MaskedLattice< T > &mlattice)
 Fill the pointer with a pointer to the masked lattice. More...
 

Private Attributes

CountedPtr< MaskedLattice< T > > itsMaskLattPtr
 

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::RO_MaskedLatticeIterator< T >

A readonly iterator for masked Lattices.

Intended use:

Public interface

Review Status

Test programs:
tMaskedLatticeIterator

Prerequisite

Etymology

The leading "RO" is shorthand for "readonly", which indicates that an RO_MaskedLatticeIterator is used for traversing a masked lattice, examining and possibly extracting its contents, but not for modifying it.

Synopsis

This class provides a convenient way to traverse any class derived from MaskedLattice. It is derived from class RO_LatticeIterator, so it provides the same iterator capabilities. On top of that it offers the function getMask to get the contents of the mask at the current iterator position.

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++;
}
}
MaskedLattice< T > & lattice() const
Return the underlying MaskedLattice object.
TableExprNode array(const TableExprNode &values, const TableExprNodeSet &shape)
Create an array of the given shape and fill it with the values.
Definition: ExprNode.h:1929
LatticeExprNode mask(const LatticeExprNode &expr)
This function returns the mask of the given expression.

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.

Motivation

The performance gain for LatticeExpr was the most important reason to develop this class.

Definition at line 115 of file MaskedLatticeIterator.h.

Constructor & Destructor Documentation

◆ RO_MaskedLatticeIterator() [1/6]

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.

◆ RO_MaskedLatticeIterator() [2/6]

template<class T >
casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator ( const MaskedLattice< 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).

◆ RO_MaskedLatticeIterator() [3/6]

template<class T >
casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator ( const MaskedLattice< T > &  data,
const LatticeNavigator method,
Bool  useRef = True 
)

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

◆ RO_MaskedLatticeIterator() [4/6]

template<class T >
casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator ( const MaskedLattice< 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.

◆ RO_MaskedLatticeIterator() [5/6]

The copy constructor uses reference semantics (ie.

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

◆ ~RO_MaskedLatticeIterator()

Destructor (cleans up dangling references and releases memory)

◆ RO_MaskedLatticeIterator() [6/6]

template<class T >
casacore::RO_MaskedLatticeIterator< T >::RO_MaskedLatticeIterator ( const RO_LatticeIterator< T > &  ,
const RO_MaskedLatticeIterator< T > &   
)
private

Construct from a LatticeIterator (for copy function).

Member Function Documentation

◆ copy()

template<class T >
RO_MaskedLatticeIterator<T> casacore::RO_MaskedLatticeIterator< 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 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.

◆ fillPtr()

template<class T >
void casacore::RO_MaskedLatticeIterator< T >::fillPtr ( const MaskedLattice< T > &  mlattice)
private

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.

◆ getMask() [1/3]

template<class T >
Bool casacore::RO_MaskedLatticeIterator< T >::getMask ( Array< Bool > &  ,
Bool  removeDegenerateAxes = False 
) const

◆ getMask() [2/3]

template<class T >
Array<Bool> casacore::RO_MaskedLatticeIterator< T >::getMask ( Bool  removeDegenerateAxes = False) const

◆ getMask() [3/3]

template<class T >
Bool casacore::RO_MaskedLatticeIterator< T >::getMask ( COWPtr< Array< Bool > > &  ,
Bool  removeDegenerateAxes = False 
) const

Get the mask for the current position.

It returns the same flag as MaskedLattice::getMaskSlice.

◆ isMasked()

template<class T >
Bool casacore::RO_MaskedLatticeIterator< T >::isMasked ( ) const
inline

Is the underlying MaskedLattice really masked?

Definition at line 179 of file MaskedLatticeIterator.h.

References casacore::RO_MaskedLatticeIterator< T >::itsMaskLattPtr.

◆ lattice()

template<class T >
MaskedLattice<T>& casacore::RO_MaskedLatticeIterator< T >::lattice ( ) const
inline

Return the underlying MaskedLattice object.

Definition at line 175 of file MaskedLatticeIterator.h.

◆ operator=()

template<class T >
RO_MaskedLatticeIterator<T>& casacore::RO_MaskedLatticeIterator< T >::operator= ( const RO_MaskedLatticeIterator< T > &  )

Assignment uses reference semantics (ie.

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

Member Data Documentation

◆ itsMaskLattPtr

template<class T >
CountedPtr<MaskedLattice<T> > casacore::RO_MaskedLatticeIterator< T >::itsMaskLattPtr
private

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