casacore
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 
38 namespace 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 
115 template<class T> class RO_MaskedLatticeIterator: public RO_LatticeIterator<T>
116 {
117  //# Make members of parent class known.
118 public:
123 
124 public:
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?
179  Bool isMasked() const
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 
191 private:
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
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.
Array< Bool > getMask(Bool removeDegenerateAxes=False) const
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()
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< T > copy() const
Make a copy of the iterator object.
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.
MaskedLattice< T > & lattice() const
Return the underlying MaskedLattice object.
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