casacore
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 
40 namespace 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 
85 template<class T> class SubLattice: public MaskedLattice<T>
86 {
87 public:
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 
298 protected:
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.
316  void setAxesMap (const AxesSpecifier&);
317 
318 
319 private:
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.
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 MaskedLattice< T > * cloneML() const
Make a copy of the object (reference semantics).
virtual Bool ok() const
Check class internals - used for debugging.
Lattice< Bool > * itsPixelMask
Definition: SubLattice.h:335
virtual void flush()
Flush the data.
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 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.
const AxesMapping & getAxesMap() const
Set the axes mapping from the specification.
Definition: SubLattice.h:276
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.
virtual Lattice< Bool > & pixelMask()
SubLattice(const Lattice< T > &lattice, AxesSpecifier=AxesSpecifier())
Create a SubLattice from a Lattice.
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...
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< T > & operator=(const SubLattice< T > &other)
Assignment (reference semantics).
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 const Lattice< Bool > & pixelMask() const
Get access to the pixelmask.
virtual void unlock()
virtual String name(Bool stripPath=False) const
Return the name of the parent lattice.
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).
virtual const LatticeRegion * getRegionPtr() const
Get a pointer the region/mask object describing this sublattice.
Lattice< T > * itsLatticePtr
Definition: SubLattice.h:330
SubLattice(MaskedLattice< T > &lattice, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
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.