casacore
Loading...
Searching...
No Matches
MaskedLatticeIterator.h
Go to the documentation of this file.
1//# MaskedLatticeIterator.h: Iterators for Masked Lattices: readonly
2//# Copyright (C) 2003
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef LATTICES_MASKEDLATTICEITERATOR_H
29#define LATTICES_MASKEDLATTICEITERATOR_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/lattices/Lattices/MaskedLattice.h>
34#include <casacore/lattices/Lattices/LatticeIterator.h>
35#include <casacore/casa/Utilities/CountedPtr.h>
36
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40// <summary>
41// A readonly iterator for masked Lattices.
42// </summary>
43
44// <use visibility=export>
45
46// <reviewed reviewer="" date="" tests="tMaskedLatticeIterator.cc">
47// </reviewed>
48
49// <prerequisite>
50// <li> <linkto class="MaskedLattice">MaskedLattice</linkto>
51// <li> <linkto class="RO_LatticeIterator">RO_LatticeIterator</linkto>
52// </prerequisite>
53
54// <etymology>
55// The leading "RO" is shorthand for "readonly", which indicates that an
56// RO_MaskedLatticeIterator is used for traversing a masked lattice,
57// examining and possibly extracting its contents, but not for modifying it.
58// </etymology>
59
60// <synopsis>
61// This class provides a convenient way to traverse any class derived from
62// MaskedLattice. It is derived from class
63// <linkto class=RO_LatticeIterator>RO_LatticeIterator</linkto>, so it
64// provides the same iterator capabilities.
65// On top of that it offers the function <src>getMask</src> to get the
66// contents of the mask at the current iterator position.
67//
68// In principle, iteration through a MaskedLattice can be done as:
69// <srcblock>
70// void someFunc (const MaskedLattice<Float>& lattice)
71// {
72// RO_LatticeIterator<Float> iter(lattice);
73// Array<Bool> mask;
74// while (! iter.atEnd()) {
75// const Array<Float>& array = iter.cursor();
76// lattice.getMaskSlice (mask, iter.position(), array.shape());
77// iter++;
78// }
79// }
80// </srcblock>
81// Using a MaskedLatticeIterator makes getting the mask slightly more
82// convenient.
83// <srcblock>
84// void someFunc (const MaskedLattice<Float>& lattice)
85// {
86// RO_MaskedLatticeIterator<Float> iter(lattice);
87// Array<Bool> mask;
88// while (! iter.atEnd()) {
89// const Array<Float>& array = iter.cursor();
90// iter.getMask (mask);
91// iter++;
92// }
93// }
94// </srcblock>
95// However, the most important reason to use MaskedLatticeIterator is
96// performance. If the underlying lattice is a LatticeExpr object,
97// the expression will be evaluated twice if a LatticeIterator object
98// is used. The reason is that the lattice in the LatticeIterator is
99// a different object from the lattice object used to get the mask.
100// Hence, the optimization put in LatticeExpr is not used.
101// When using a MaskedLatticeIterator the same lattice object is used
102// to get data and mask.
103// </synopsis>
104
105// <motivation>
106// The performance gain for LatticeExpr was the most important reason
107// to develop this class.
108// </motivation>
109
110//# <todo asof="2003/11/10">
111//# <li>
112//# </todo>
113
114
115template<class T> class RO_MaskedLatticeIterator: public RO_LatticeIterator<T>
116{
117 //# Make members of parent class known.
118public:
123
124public:
125 // The default constructor creates an empty object which is practically
126 // unusable.
127 // It can only be used as the source or target of an assignment. It can
128 // also be used as the source for the copy constructor and the copy function.
129 // Other functions do not check if the object is empty and will usually
130 // give a segmentation fault.
131 // The function isNull() can be used to test if the object is empty.
133
134 // Construct the Iterator with the supplied data.
135 // It uses a TileStepper as the default iteration strategy.
136 // useRef=True means that if possible the cursor arrays returned
137 // reference the data in the underlying lattice. This is only possible
138 // for ArrayLattice objects (or e.g. a SubLattice using it).
140 Bool useRef=True);
141
142 // Construct the Iterator with the supplied data, and iteration strategy
144 const LatticeNavigator& method,
145 Bool useRef=True);
146
147 // Construct the Iterator with the supplied data.
148 // It uses a LatticeStepper with the supplied cursor shape as the
149 // iteration strategy.
151 const IPosition& cursorShape,
152 Bool useRef=True);
153
154 // The copy constructor uses reference semantics (ie. NO real copy is made).
155 // The function <src>copy</src> can be used to make a true copy.
157
158 // Destructor (cleans up dangling references and releases memory)
160
161 // Assignment uses reference semantics (ie. NO real copy is made).
162 // The function <src>copy</src> can be used to make a true copy.
164
165 // Make a copy of the iterator object.
166 // This means that an independent navigator object is created to
167 // be able to iterate independently through the same MaskedLattice.
168 // The position in the copied navigator is the same as the original.
169 // The reset function has to be used to start at the beginning.
170 // <br>Note that if the MaskedLattice uses a cache (e.g. PagedArray), the
171 // cache is shared by the iterators.
173
174 // Return the underlying MaskedLattice object.
176 { return const_cast<MaskedLattice<T>&>(*itsMaskLattPtr); }
177
178 // Is the underlying MaskedLattice really masked?
180 { return itsMaskLattPtr->isMasked(); }
181
182 // Get the mask for the current position.
183 // It returns the same flag as
184 // <linkto class=MaskedLattice>MaskedLattice::getMaskSlice</linkto>.
185 // <group>
186 Bool getMask (COWPtr<Array<Bool> >&, Bool removeDegenerateAxes=False) const;
187 Bool getMask (Array<Bool>&, Bool removeDegenerateAxes=False) const;
188 Array<Bool> getMask (Bool removeDegenerateAxes=False) const;
189 // </group>
190
191private:
192 // Construct from a LatticeIterator (for copy function).
195
196 // Fill the pointer with a pointer to the masked lattice.
197 // This pointer is a casted copy of the lattice pointer in the base class.
198 // In this way they share the same MaskedLattice object, which is needed
199 // for optimal performance of e.g. LatticeExpr.
200 // Otherwise getting data from the lattice and from the mask would
201 // result in 2 evaluations of the expression.
202 // However, the lattice can be a PagedArray (for example, for PagedImage).
203 // In that case a clone of the original MaskedLattice is used.
204 void fillPtr (const MaskedLattice<T>& mlattice);
205
207};
208
209
210
211} //# NAMESPACE CASACORE - END
212
213#ifndef CASACORE_NO_AUTO_TEMPLATES
214#include <casacore/lattices/Lattices/MaskedLatticeIterator.tcc>
215#endif //# CASACORE_NO_AUTO_TEMPLATES
216#endif
Referenced counted pointer for constant data.
Definition CountedPtr.h:81
Bool isNull() const
Is the iterator object empty?
IPosition endPosition() const
Function which returns the current position of the end of the cursor.
IPosition position() const
Function which returns the current position of the beginning of the cursor within the Lattice.
IPosition cursorShape() const
Function which returns the shape of the cursor which is iterating through the Lattice.
RO_MaskedLatticeIterator(const MaskedLattice< T > &data, Bool useRef=True)
Construct the Iterator with the supplied data.
RO_MaskedLatticeIterator(const MaskedLattice< T > &data, const IPosition &cursorShape, Bool useRef=True)
Construct the Iterator with the supplied data.
void fillPtr(const MaskedLattice< T > &mlattice)
Fill the pointer with a pointer to the masked lattice.
Bool getMask(Array< Bool > &, Bool removeDegenerateAxes=False) const
CountedPtr< MaskedLattice< T > > itsMaskLattPtr
RO_MaskedLatticeIterator(const RO_LatticeIterator< T > &, const RO_MaskedLatticeIterator< T > &)
Construct from a LatticeIterator (for copy function).
RO_MaskedLatticeIterator< T > copy() const
Make a copy of the iterator object.
MaskedLattice< T > & lattice() const
Return the underlying MaskedLattice object.
~RO_MaskedLatticeIterator()
Destructor (cleans up dangling references and releases memory)
RO_MaskedLatticeIterator(const MaskedLattice< T > &data, const LatticeNavigator &method, Bool useRef=True)
Construct the Iterator with the supplied data, and iteration strategy.
RO_MaskedLatticeIterator()
The default constructor creates an empty object which is practically unusable.
Bool isMasked() const
Is the underlying MaskedLattice really masked?
RO_MaskedLatticeIterator(const RO_MaskedLatticeIterator< T > &other)
The copy constructor uses reference semantics (ie.
RO_MaskedLatticeIterator< T > & operator=(const RO_MaskedLatticeIterator< T > &)
Assignment uses reference semantics (ie.
Array< Bool > getMask(Bool removeDegenerateAxes=False) const
Bool getMask(COWPtr< Array< Bool > > &, Bool removeDegenerateAxes=False) const
Get the mask for the current position.
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
const Bool True
Definition aipstype.h:43