casacore
Loading...
Searching...
No Matches
SubLattice.h
Go to the documentation of this file.
1//# SubLattice.h: A subset of a Lattice or MaskedLattice
2//# Copyright (C) 1997,1998,1999,2000,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//#
27//# $Id$
28
29#ifndef LATTICES_SUBLATTICE_H
30#define LATTICES_SUBLATTICE_H
31
32
33//# Includes
34#include <casacore/casa/aips.h>
35#include <casacore/lattices/Lattices/MaskedLattice.h>
36#include <casacore/lattices/LRegions/LatticeRegion.h>
37#include <casacore/casa/Arrays/AxesSpecifier.h>
38#include <casacore/casa/Arrays/AxesMapping.h>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42//# Forward Declarations
43
44
45// <summary>
46// A subset of a Lattice or MaskedLattice
47// </summary>
48
49// <use visibility=export>
50
51// <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
52// </reviewed>
53
54// <prerequisite>
55// <li> <linkto class="Lattice">Lattice</linkto>
56// <li> <linkto class="LatticeRegion">LatticeRegion</linkto>
57// </prerequisite>
58
59// <synopsis>
60// A SubLattice is a lattice referencing a subset of another lattice
61// by means of a <linkto class="Slicer">Slicer</linkto> object.
62// <br>It is useful when only a subset of a lattice needs to be accessed.
63// <p>
64// When the SubLattice is created from a const <src>Lattice</src> object,
65// it is not writable, thus it can only be used as an rvalue.
66// <p>
67// Using an <linkto class=AxesSpecifier>AxesSpecifier</linkto> object
68// it is possible to remove some or all degenerate axes (i.e. axes
69// with length 1) to get a lattice with a lower dimensionality.
70// </synopsis>
71
72// <example>
73// <srcblock>
74// </srcblock>
75// </example>
76
77// <templating arg=T>
78// <li> Any type that can be used by the Tables System can also be used by
79// this class.
80// </templating>
81
82//# <todo asof="yyyy/mm/dd">
83//# </todo>
84
85template<class T> class SubLattice: public MaskedLattice<T>
86{
87public:
88 // The default constructor creates a SubLattice that is useless for just
89 // about everything, except that it can be assigned to with the assignment
90 // operator.
92
93 // Create a SubLattice from a Lattice.
94 // This results in a SubLattice without a real mask.
95 // <br>The "const Lattice" version yields a non-writable SubLattice,
96 // while for the non-const version one has to specify if the SubLattice
97 // should be writable (if the original lattice is non-writable, the
98 // SubLattice is always set to non-writable).
99 // <note>In the 2nd case the lattice could have been declared const,
100 // but is not to indicate it can be changed. </note>
101 // <group>
103 SubLattice (Lattice<T>& lattice, Bool writableIfPossible,
105 // </group>
106
107 // Create a SubLattice from a MaskedLattice.
108 // <br>The "const MaskedLattice" version yields a non-writable SubLattice,
109 // while for the non-const version one has to specify if the SubLattice
110 // should be writable (if the original lattice is non-writable, the
111 // SubLattice is always set to non-writable).
112 // <note>In the 2nd case the lattice could have been declared const,
113 // but is not to indicate it can be changed. </note>
114 // <group>
116 SubLattice (MaskedLattice<T>& lattice, Bool writableIfPossible,
118 // </group>
119
120 // Create a SubLattice from the given MaskedLattice and region.
121 // Note that the region can be constructed from an
122 // <linkto class=LCRegion>LCRegion</linkto> object or
123 // <linkto class=Slicer>Slicer</linkto> object (with an optional stride).
124 // <br>An exception is thrown if the lattice shape used in the region
125 // differs from the shape of the lattice.
126 // <note>In the 2nd and 4th case the lattice could have been declared const,
127 // but is not to indicate it can be changed. </note>
128 // <group>
129 SubLattice (const Lattice<T>& lattice, const LatticeRegion& region,
132 Bool writableIfPossible, AxesSpecifier=AxesSpecifier());
136 Bool writableIfPossible, AxesSpecifier=AxesSpecifier());
137 // </group>
138
139 // Create a SubLattice from the given (Masked)Lattice and slicer.
140 // The slicer can be strided.
141 // <br>An exception is thrown if the slicer exceeds the lattice shape.
142 // <note>In the 2nd and 4th case the lattice could have been declared const,
143 // but is not to indicate it can be changed. </note>
144 // <group>
145 SubLattice (const Lattice<T>& lattice, const Slicer& slicer,
147 SubLattice (Lattice<T>& lattice, const Slicer& slicer,
148 Bool writableIfPossible, AxesSpecifier=AxesSpecifier());
149 SubLattice (const MaskedLattice<T>& lattice, const Slicer& slicer,
151 SubLattice (MaskedLattice<T>& lattice, const Slicer& slicer,
152 Bool writableIfPossible, AxesSpecifier=AxesSpecifier());
153 // </group>
154
155 // Copy constructor (reference semantics).
156 SubLattice (const SubLattice<T>& other);
157
158 virtual ~SubLattice();
159
160 // Assignment (reference semantics).
162
163 // Make a copy of the object (reference semantics).
164 virtual MaskedLattice<T>* cloneML() const;
165
166 // Is the lattice masked?
167 // It is if its parent lattice or its region is masked.
168 virtual Bool isMasked() const;
169
170 // A SubLattice is persistent if no region is applied to the parent lattice.
171 // That is true if the region has the same shape as the parent lattice
172 // and the region has no mask.
173 virtual Bool isPersistent() const;
174
175 // Is the SubLattice paged to disk?
176 virtual Bool isPaged() const;
177
178 // Can the lattice data be referenced as an array section?
179 virtual Bool canReferenceArray() const;
180
181 // Is the SubLattice writable?
182 virtual Bool isWritable() const;
183
184 // Handle locking of the SubLattice which is delegated to its parent.
185 // <br>It is strongly recommended to use class
186 // <linkto class=LatticeLocker>LatticeLocker</linkto> to
187 // handle lattice locking. It also contains a more detailed
188 // explanation of the locking process.
189 // <group>
190 virtual Bool lock (FileLocker::LockType, uInt nattempts);
191 virtual void unlock();
193 // </group>
194
195 // Resynchronize the Lattice object with the lattice file.
196 // This function is only useful if no read-locking is used, ie.
197 // if the table lock option is UserNoReadLocking or AutoNoReadLocking.
198 // In that cases the table system does not acquire a read-lock, thus
199 // does not synchronize itself automatically.
200 virtual void resync();
201
202 // Flush the data.
203 virtual void flush();
204
205 // Close the Lattice temporarily (if it is paged to disk).
206 // It'll be reopened automatically when needed or when
207 // <src>reopen</src> is called explicitly.
208 virtual void tempClose();
209
210 // If needed, reopen a temporarily closed Lattice.
211 virtual void reopen();
212
213 // Does the SubLattice have a pixelmask?
214 virtual Bool hasPixelMask() const;
215
216 // Get access to the pixelmask.
217 // An exception is thrown if the SubLattice does not have a pixelmask.
218 // <group>
219 virtual const Lattice<Bool>& pixelMask() const;
221 // </group>
222
223 // Use the given mask as the pixelmask.
224 // If another mask was already used, the new one will be used instead.
225 // It checks if its shape matches the shape of the sublattice.
226 // <br>If <code>mayExist=False</code>, setting the pixelmask is only
227 // possible if the underlying lattice does not have a pixelmask.
228 // <br>If <code>mayExist=True</code>, the resulting pixelmask is the
229 // AND of the given pixelmask and the pixelmask of the underlying lattice.
230 void setPixelMask (const Lattice<Bool>& pixelMask, Bool mayExist);
231
232 // Get a pointer the region/mask object describing this sublattice.
233 virtual const LatticeRegion* getRegionPtr() const;
234
235 // Returns the shape of the SubLattice including all degenerate axes
236 // (i.e. axes with a length of one).
237 virtual IPosition shape() const;
238
239 // Return the name of the parent lattice.
240 virtual String name (Bool stripPath=False) const;
241
242 // This function returns the recommended maximum number of pixels to
243 // include in the cursor of an iterator.
244 virtual uInt advisedMaxPixels() const;
245
246 // Get or put a single element in the lattice.
247 // <group>
248 virtual T getAt (const IPosition& where) const;
249 virtual void putAt (const T& value, const IPosition& where);
250 // </group>
251
252 // Check class internals - used for debugging. Should always return True
253 virtual Bool ok() const;
254
255 // This function is used by the LatticeIterator class to generate an
256 // iterator of the correct type for this Lattice. Not recommended
257 // for general use.
259 Bool useRef) const;
260
261 // Do the actual getting of an array of values.
262 virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section);
263
264 // Do the actual getting of an array of values.
265 virtual void doPutSlice (const Array<T>& sourceBuffer,
266 const IPosition& where,
267 const IPosition& stride);
268
269 // Get a section of the mask.
270 virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
271
272 // Get the best cursor shape.
273 virtual IPosition doNiceCursorShape (uInt maxPixels) const;
274
275 // Set the axes mapping from the specification.
276 const AxesMapping& getAxesMap() const
277 { return itsAxesMap; }
278
279 // Convert the specified position in the sublattice to the corresponding
280 // position in the parent lattice.
281 IPosition positionInParent(const IPosition& subLatticePosition) const
282 {
283 if (itsAxesMap.isRemoved()) {
284 return itsRegion.convert (itsAxesMap.posToOld(subLatticePosition));
285 } else {
286 return itsRegion.convert (subLatticePosition);
287 }
288 }
289
290 // Set the region object using a slicer.
291 // Allows the region to be changed while keeping
292 // the same lattice, so that new SubLattice objects do not have to be
293 // created when one only wants to change the region of interest. Should
294 // only be called when performance is an issue; otherwise, just create
295 // a new SubLattice<T> object.
296 void setRegion (const Slicer& slicer);
297
298protected:
299 // Set the region object.
300 // It also fills in the parent pointer when the SubLattice is taken
301 // from a MaskedLattice.
302 // The default region is the entire lattice.
303 // <group>
305 void setRegion();
306 // </group>
307
308 // Set the various pointers needed to construct the object.
309 // One of the pointers should be zero.
310 // It takes over the pointer and deletes the object in the destructor.
311 void setPtr (Lattice<T>* latticePtr,
312 MaskedLattice<T>* maskLatPtr,
313 Bool writableIfPossible);
314
315 // Set the axes mapping from the specification.
317
318
319private:
320 // Get mask data from region and mask.
321 // <group>
322 Bool getRegionDataSlice (Array<Bool>& buffer, const Slicer& section);
323 Bool getMaskDataSlice (Array<Bool>& buffer, const Slicer& section);
324 // </group>
325
326 // And tmpbuf into buffer. If buffer is a reference, first a copy is made.
327 void andMask (Array<Bool>& buffer, Bool ref,
328 const Array<Bool>& tmpbuf) const;
329
334 Bool itsHasLattPMask; //# has underlying lattice a pixelmask?
335 Lattice<Bool>* itsPixelMask; //# AND of lattice and own pixelmask
336 Lattice<Bool>* itsOwnPixelMask; //# own pixelmask
339};
340
341//# Declare extern templates for often used types.
342 extern template class SubLattice<Bool>;
343 extern template class SubLattice<Float>;
344
345
346} //# NAMESPACE CASACORE - END
347
348#ifndef CASACORE_NO_AUTO_TEMPLATES
349#include <casacore/lattices/Lattices/SubLattice.tcc>
350#endif //# CASACORE_NO_AUTO_TEMPLATES
351#endif
bool isRemoved() const
Are axes removed?
Definition AxesMapping.h:97
IPosition posToOld(const IPosition &pos) const
Map a new position or shape to the old one.
LockType
Define the possible lock types.
Definition FileLocker.h:95
Slicer convert(const Slicer &slicer) const
Convert positions to positions in the parent object.
const LatticeRegion & region() const
Get the region used.
String: the storage and methods of handling collections of characters.
Definition String.h:225
SubLattice(Lattice< T > &lattice, const Slicer &slicer, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
void setPixelMask(const Lattice< Bool > &pixelMask, Bool mayExist)
Use the given mask as the pixelmask.
virtual LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
This function is used by the LatticeIterator class to generate an iterator of the correct type for th...
SubLattice()
The default constructor creates a SubLattice that is useless for just about everything,...
virtual void tempClose()
Close the Lattice temporarily (if it is paged to disk).
virtual Bool ok() const
Check class internals - used for debugging.
Lattice< Bool > * itsPixelMask
Definition SubLattice.h:335
virtual void flush()
Flush the data.
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask.
virtual Bool hasLock(FileLocker::LockType) const
SubLattice(MaskedLattice< T > &lattice, const LatticeRegion &region, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
SubLattice(Lattice< T > &lattice, const LatticeRegion &region, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
virtual const LatticeRegion * getRegionPtr() const
Get a pointer the region/mask object describing this sublattice.
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
SubLattice(const Lattice< T > &lattice, const Slicer &slicer, AxesSpecifier=AxesSpecifier())
Create a SubLattice from the given (Masked)Lattice and slicer.
void setRegion(const Slicer &slicer)
Set the region object using a slicer.
IPosition positionInParent(const IPosition &subLatticePosition) const
Convert the specified position in the sublattice to the corresponding position in the parent lattice.
Definition SubLattice.h:281
void andMask(Array< Bool > &buffer, Bool ref, const Array< Bool > &tmpbuf) const
And tmpbuf into buffer.
virtual Bool isPersistent() const
A SubLattice is persistent if no region is applied to the parent lattice.
const AxesMapping & getAxesMap() const
Set the axes mapping from the specification.
Definition SubLattice.h:276
SubLattice(const Lattice< T > &lattice, AxesSpecifier=AxesSpecifier())
Create a SubLattice from a Lattice.
virtual Bool isMasked() const
Is the lattice masked? It is if its parent lattice or its region is masked.
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
Bool getMaskDataSlice(Array< Bool > &buffer, const Slicer &section)
virtual IPosition shape() const
Returns the shape of the SubLattice including all degenerate axes (i.e.
void setPtr(Lattice< T > *latticePtr, MaskedLattice< T > *maskLatPtr, Bool writableIfPossible)
Set the various pointers needed to construct the object.
SubLattice(const MaskedLattice< T > &lattice, const LatticeRegion &region, AxesSpecifier=AxesSpecifier())
void setAxesMap(const AxesSpecifier &)
Set the axes mapping from the specification.
virtual T getAt(const IPosition &where) const
Get or put a single element in the lattice.
SubLattice(Lattice< T > &lattice, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
virtual Bool isPaged() const
Is the SubLattice paged to disk?
virtual Bool hasPixelMask() const
Does the SubLattice have a pixelmask?
SubLattice(const MaskedLattice< T > &lattice, AxesSpecifier=AxesSpecifier())
Create a SubLattice from a MaskedLattice.
SubLattice(MaskedLattice< T > &lattice, const Slicer &slicer, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
void setRegion(const LatticeRegion &region)
Set the region object.
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Get a section of the mask.
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
MaskedLattice< T > * itsMaskLatPtr
Definition SubLattice.h:331
virtual Bool isWritable() const
Is the SubLattice writable?
virtual MaskedLattice< T > * cloneML() const
Make a copy of the object (reference semantics).
virtual void unlock()
virtual String name(Bool stripPath=False) const
Return the name of the parent lattice.
SubLattice< T > & operator=(const SubLattice< T > &other)
Assignment (reference semantics).
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle locking of the SubLattice which is delegated to its parent.
virtual uInt advisedMaxPixels() const
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...
Bool getRegionDataSlice(Array< Bool > &buffer, const Slicer &section)
Get mask data from region and mask.
AxesMapping itsAxesMap
Definition SubLattice.h:338
AxesSpecifier itsAxesSpec
Definition SubLattice.h:337
Lattice< Bool > * itsOwnPixelMask
Definition SubLattice.h:336
virtual void reopen()
If needed, reopen a temporarily closed Lattice.
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
SubLattice(const MaskedLattice< T > &lattice, const Slicer &slicer, AxesSpecifier=AxesSpecifier())
virtual void resync()
Resynchronize the Lattice object with the lattice file.
LatticeRegion itsRegion
Definition SubLattice.h:332
SubLattice(const SubLattice< T > &other)
Copy constructor (reference semantics).
Lattice< T > * itsLatticePtr
Definition SubLattice.h:330
SubLattice(MaskedLattice< T > &lattice, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
virtual Lattice< Bool > & pixelMask()
SubLattice(const Lattice< T > &lattice, const LatticeRegion &region, AxesSpecifier=AxesSpecifier())
Create a SubLattice from the given MaskedLattice and region.
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
unsigned int uInt
Definition aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.