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,
131  SubLattice (Lattice<T>& lattice, const LatticeRegion& region,
132  Bool writableIfPossible, AxesSpecifier=AxesSpecifier());
133  SubLattice (const MaskedLattice<T>& lattice, const LatticeRegion& region,
135  SubLattice (MaskedLattice<T>& lattice, const LatticeRegion& region,
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>
304  void setRegion (const LatticeRegion& region);
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
casacore::Slicer
Definition: Slicer.h:290
casacore::SubLattice::unlock
virtual void unlock()
casacore::SubLattice::positionInParent
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
casacore::IPosition
Definition: IPosition.h:120
casacore::SubLattice::reopen
virtual void reopen()
If needed, reopen a temporarily closed Lattice.
casacore::SubLattice::tempClose
virtual void tempClose()
Close the Lattice temporarily (if it is paged to disk).
casacore::SubLattice::canReferenceArray
virtual Bool canReferenceArray() const
Can the lattice data be referenced as an array section?
casacore::SubLattice::SubLattice
SubLattice(const MaskedLattice< T > &lattice, const Slicer &slicer, AxesSpecifier=AxesSpecifier())
casacore::SubLattice::setPtr
void setPtr(Lattice< T > *latticePtr, MaskedLattice< T > *maskLatPtr, Bool writableIfPossible)
Set the various pointers needed to construct the object.
casacore::MaskedLattice
Definition: MaskedLattice.h:218
casacore::SubLattice::SubLattice
SubLattice(Lattice< T > &lattice, const Slicer &slicer, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
casacore::SubLattice::flush
virtual void flush()
Flush the data.
casacore::AxesMapping::posToOld
IPosition posToOld(const IPosition &pos) const
Map a new position or shape to the old one.
casacore::SubLattice::name
virtual String name(Bool stripPath=False) const
Return the name of the parent lattice.
casacore::SubLattice::SubLattice
SubLattice(const MaskedLattice< T > &lattice, AxesSpecifier=AxesSpecifier())
Create a SubLattice from a MaskedLattice.
casacore::SubLattice
Definition: SubLattice.h:86
casacore::SubLattice::isPaged
virtual Bool isPaged() const
Is the SubLattice paged to disk?
casacore::SubLattice::SubLattice
SubLattice(const MaskedLattice< T > &lattice, const LatticeRegion &region, AxesSpecifier=AxesSpecifier())
casacore::SubLattice::~SubLattice
virtual ~SubLattice()
casacore::FileLocker::LockType
LockType
Define the possible lock types.
Definition: FileLocker.h:95
casacore::SubLattice::SubLattice
SubLattice(Lattice< T > &lattice, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
casacore::SubLattice::shape
virtual IPosition shape() const
Returns the shape of the SubLattice including all degenerate axes (i.e.
casacore::SubLattice::getRegionDataSlice
Bool getRegionDataSlice(Array< Bool > &buffer, const Slicer &section)
Get mask data from region and mask.
casacore::SubLattice::itsPixelMask
Lattice< Bool > * itsPixelMask
Definition: SubLattice.h:335
casacore::SubLattice::itsWritable
Bool itsWritable
Definition: SubLattice.h:333
casacore::SubLattice::SubLattice
SubLattice(MaskedLattice< T > &lattice, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
casacore::SubLattice::SubLattice
SubLattice(const SubLattice< T > &other)
Copy constructor (reference semantics).
casacore::SubLattice::andMask
void andMask(Array< Bool > &buffer, Bool ref, const Array< Bool > &tmpbuf) const
And tmpbuf into buffer.
casacore::LatticeRegion
Definition: LatticeRegion.h:75
casacore::SubLattice::isPersistent
virtual Bool isPersistent() const
A SubLattice is persistent if no region is applied to the parent lattice.
casacore::SubLattice::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
casacore::SubLattice::itsOwnPixelMask
Lattice< Bool > * itsOwnPixelMask
Definition: SubLattice.h:336
casacore::SubLattice::getAxesMap
const AxesMapping & getAxesMap() const
Set the axes mapping from the specification.
Definition: SubLattice.h:276
casacore::SubLattice::itsLatticePtr
Lattice< T > * itsLatticePtr
Definition: SubLattice.h:330
casacore::SubLattice::doPutSlice
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
casacore::SubLattice::lock
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle locking of the SubLattice which is delegated to its parent.
casacore::value
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
casacore::LatticeNavigator
Definition: LatticeNavigator.h:182
casacore::SubLattice::SubLattice
SubLattice(MaskedLattice< T > &lattice, const Slicer &slicer, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
casacore::SubLattice::hasLock
virtual Bool hasLock(FileLocker::LockType) const
casacore::SubLattice::getMaskDataSlice
Bool getMaskDataSlice(Array< Bool > &buffer, const Slicer &section)
casacore::SubLattice::advisedMaxPixels
virtual uInt advisedMaxPixels() const
This function returns the recommended maximum number of pixels to include in the cursor of an iterato...
casacore::SubLattice::doGetSlice
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::SubLattice::hasPixelMask
virtual Bool hasPixelMask() const
Does the SubLattice have a pixelmask?
casacore::SubLattice::SubLattice
SubLattice(MaskedLattice< T > &lattice, const LatticeRegion &region, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())
casacore::SubLattice::itsAxesMap
AxesMapping itsAxesMap
Definition: SubLattice.h:338
casacore::SubLattice::setRegion
void setRegion()
casacore::SubLattice::setAxesMap
void setAxesMap(const AxesSpecifier &)
Set the axes mapping from the specification.
casacore::SubLattice::doGetMaskSlice
virtual Bool doGetMaskSlice(Array< Bool > &buffer, const Slicer &section)
Get a section of the mask.
casacore::SubLattice::isMasked
virtual Bool isMasked() const
Is the lattice masked? It is if its parent lattice or its region is masked.
casacore::SubLattice::isWritable
virtual Bool isWritable() const
Is the SubLattice writable?
casacore::SubLattice::operator=
SubLattice< T > & operator=(const SubLattice< T > &other)
Assignment (reference semantics).
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::SubLattice::pixelMask
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask.
casacore::LatticeRegion::convert
Slicer convert(const Slicer &slicer) const
Convert positions to positions in the parent object.
casacore::AxesMapping
Definition: AxesMapping.h:88
casacore::SubLattice::SubLattice
SubLattice(const Lattice< T > &lattice, AxesSpecifier=AxesSpecifier())
Create a SubLattice from a Lattice.
casacore::SubLattice::putAt
virtual void putAt(const T &value, const IPosition &where)
casacore::SubLattice::getAt
virtual T getAt(const IPosition &where) const
Get or put a single element in the lattice.
casacore::SubLattice::SubLattice
SubLattice(const Lattice< T > &lattice, const LatticeRegion &region, AxesSpecifier=AxesSpecifier())
Create a SubLattice from the given MaskedLattice and region.
casacore::SubLattice::pixelMask
virtual Lattice< Bool > & pixelMask()
casacore::SubLattice::itsMaskLatPtr
MaskedLattice< T > * itsMaskLatPtr
Definition: SubLattice.h:331
casacore::Lattice
Definition: Lattice.h:232
casacore::SubLattice::ok
virtual Bool ok() const
Check class internals - used for debugging.
casacore::Array
template <class T, class U> class vector;
Definition: Array.h:167
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::SubLattice::itsHasLattPMask
Bool itsHasLattPMask
Definition: SubLattice.h:334
casacore::SubLattice::setRegion
void setRegion(const LatticeRegion &region)
Set the region object.
casacore::SubLattice::cloneML
virtual MaskedLattice< T > * cloneML() const
Make a copy of the object (reference semantics).
casacore::SubLattice::itsAxesSpec
AxesSpecifier itsAxesSpec
Definition: SubLattice.h:337
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::SubLattice::setRegion
void setRegion(const Slicer &slicer)
Set the region object using a slicer.
casacore::AxesSpecifier
Definition: AxesSpecifier.h:113
casacore::SubLattice::getRegionPtr
virtual const LatticeRegion * getRegionPtr() const
Get a pointer the region/mask object describing this sublattice.
casacore::SubLattice::SubLattice
SubLattice()
The default constructor creates a SubLattice that is useless for just about everything,...
casacore::SubLattice::setPixelMask
void setPixelMask(const Lattice< Bool > &pixelMask, Bool mayExist)
Use the given mask as the pixelmask.
casacore::SubLattice::resync
virtual void resync()
Resynchronize the Lattice object with the lattice file.
casacore::SubLattice::SubLattice
SubLattice(const Lattice< T > &lattice, const Slicer &slicer, AxesSpecifier=AxesSpecifier())
Create a SubLattice from the given (Masked)Lattice and slicer.
casacore::SubLattice::makeIter
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...
casacore::LatticeIterInterface
Definition: LatticeIterInterface.h:117
casacore::AxesMapping::isRemoved
Bool isRemoved() const
Are axes removed?
Definition: AxesMapping.h:109
casacore::SubLattice::itsRegion
LatticeRegion itsRegion
Definition: SubLattice.h:332
casacore::SubLattice::SubLattice
SubLattice(Lattice< T > &lattice, const LatticeRegion &region, Bool writableIfPossible, AxesSpecifier=AxesSpecifier())