casacore
LatticeRegion.h
Go to the documentation of this file.
1 //# LatticeRegion.h: An optionally strided region in a lattice
2 //# Copyright (C) 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_LATTICEREGION_H
30 #define LATTICES_LATTICEREGION_H
31 
32 
33 //# Includes
34 #include <casacore/casa/aips.h>
35 #include <casacore/lattices/Lattices/Lattice.h>
36 #include <casacore/casa/Arrays/Slicer.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 class LCRegion;
42 
43 
44 // <summary>
45 // An optionally strided region in a Lattice
46 // </summary>
47 
48 // <use visibility=local>
49 
50 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
51 // </reviewed>
52 
53 // <prerequisite>
54 // <li> <linkto class="LCRegion">LCRegion</linkto>
55 // </prerequisite>
56 
57 // <synopsis>
58 // A LatticeRegion is a lattice referencing a subset of another lattice
59 // by means of a <linkto class="Slicer">Slicer</linkto> object.
60 // <br>It is useful when only a subset of a lattice needs to be accessed.
61 // <p>
62 // When the LatticeRegion is created from a const <src>Lattice</src> object,
63 // it is not writable, thus it can only be used as an rvalue.
64 // </synopsis>
65 
66 // <example>
67 // <srcblock>
68 // </srcblock>
69 // </example>
70 
71 //# <todo asof="yyyy/mm/dd">
72 //# </todo>
73 
74 class LatticeRegion: public Lattice<Bool>
75 {
76 public:
77  // The default constructor creates a LatticeRegion that is useless for just
78  // about everything, except that it can be assigned to with the assignment
79  // operator.
81 
82  // Create from the given region.
83  // The pointer to the parent can be 0.
85 
86  // Create from the given region and take over the pointer.
87  // This means the user should not delete the region object pointed to,
88  // because it will be deleted by the LatticeRegion destructor.
89  // The pointer to the parent is set to 0.
91 
92  // Construct from the given slicer. The lattice shape has to be
93  // the lattice shape of the lattice where the region is taken from.
94  LatticeRegion (const Slicer& slicer, const IPosition& latticeShape);
95 
96  // Copy constructor (reference semantics).
97  LatticeRegion (const LatticeRegion& other);
98 
99  virtual ~LatticeRegion();
100 
101  // Assignment (reference semantics).
103 
104  // Make a copy of the object (reference semantics).
105  virtual Lattice<Bool>* clone() const;
106 
107  // Is the LatticeRegion writable?
108  virtual Bool isWritable() const;
109 
110  // Has the region a mask?
111  Bool hasMask() const;
112 
113  // Handle the (un)locking.
114  // <group>
115  virtual Bool lock (FileLocker::LockType, uInt nattempts);
116  virtual void unlock();
118  // </group>
119 
120  // Resynchronize the PagedArray object with the lattice file.
121  // This function is only useful if no read-locking is used, ie.
122  // if the table lock option is UserNoReadLocking or AutoNoReadLocking.
123  // In that cases the table system does not acquire a read-lock, thus
124  // does not synchronize itself automatically.
125  virtual void resync();
126 
127  // Flush the data (but do not unlock).
128  virtual void flush();
129 
130  // Temporarily close the lattice.
131  // It will be reopened automatically on the next access.
132  virtual void tempClose();
133 
134  // Explicitly reopen the temporarily closed lattice.
135  virtual void reopen();
136 
137  // Get the LCRegion object describing the region.
138  // Note that it does not contain strides, even if this LatticeRegion
139  // object was constructed from a Slicer with strides. In that case
140  // the region only defines the resulting shape.
141  const LCRegion& region() const;
142 
143  // Get the Slicer object describing the region.
144  // Note that it may contain strides.
145  const Slicer& slicer() const;
146 
147  // Returns the shape of the LatticeRegion including all degenerate axes
148  // (i.e. axes with a length of one).
149  virtual IPosition shape() const;
150 
151  // Returns the number of axes in this LatticeRegion. This includes all
152  // degenerate axes.
153  virtual uInt ndim() const;
154 
155  // Returns the total number of elements in this LatticeRegion.
156  virtual size_t nelements() const;
157 
158  // Check class internals - used for debugging. Should always return True
159  virtual Bool ok() const;
160 
161  // This function is used by the LatticeIterator class to generate an
162  // iterator of the correct type for this Lattice. Not recommended
163  // for general use.
165  (const LatticeNavigator& navigator,
166  Bool useRef) const;
167 
168  // Returns the maximum recommended number of pixels for a cursor.
169  // This is the number of pixels in a tile.
170  virtual uInt advisedMaxPixels() const;
171 
172  // Help the user pick a cursor for most efficient access.
173  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
174 
175  // Maximum size - not necessarily all used. In pixels.
176  virtual uInt maximumCacheSize() const;
177 
178  // Set the maximum (allowed) cache size as indicated.
179  virtual void setMaximumCacheSize (uInt howManyPixels);
180 
181  // Set the cache size as to "fit" the indicated path.
182  virtual void setCacheSizeFromPath (const IPosition& sliceShape,
183  const IPosition& windowStart,
184  const IPosition& windowLength,
185  const IPosition& axisPath);
186 
187  // Set the actual cache size for this Array to be be big enough for the
188  // indicated number of tiles. This cache is not shared with PagedArrays
189  // in other rows and is always clipped to be less than the maximum value
190  // set using the setMaximumCacheSize member function.
191  // tiles. Tiles are cached using a first in first out algorithm.
192  virtual void setCacheSizeInTiles (uInt howManyTiles);
193 
194  // Clears and frees up the caches, but the maximum allowed cache size is
195  // unchanged from when setCacheSize was called
196  virtual void clearCache();
197 
198  // Report on cache success.
199  virtual void showCacheStatistics (ostream& os) const;
200 
201  // The following "put" functions are described in detail in class
202  // <linkto class=Lattice>Lattice</linkto>.
203  // They'll throw an exception is no mask is available or if
204  // the mask is not writable.
205  // <group>
206  virtual void set (const Bool& value);
207  virtual void apply (Bool (*function)(Bool));
208  virtual void apply (Bool (*function)(const Bool&));
209  virtual void apply (const Functional<Bool,Bool>& function);
210  virtual void putAt (const Bool& value, const IPosition& where);
211  virtual void copyData (const Lattice<Bool>& from);
212  // </group>
213 
214  // Convert positions to positions in the parent object.
215  // <group>
216  Slicer convert (const Slicer& slicer) const;
217  IPosition convert (const IPosition& position) const;
218  // </group>
219 
220  // Do the actual getting of the mask.
221  virtual Bool doGetSlice (Array<Bool>& buffer, const Slicer& section);
222 
223  // Do the actual putting of the mask. Only possible if region is writable.
224  virtual void doPutSlice (const Array<Bool>& sourceBuffer,
225  const IPosition& where,
226  const IPosition& stride);
227 
228 
229 private:
233 };
234 
235 
237 {
238  return itsHasRegionMask;
239 }
240 inline const LCRegion& LatticeRegion::region() const
241 {
242  return *itsRegion;
243 }
244 inline const Slicer& LatticeRegion::slicer() const
245 {
246  return itsSlicer;
247 }
248 
249 
250 
251 } //# NAMESPACE CASACORE - END
252 
253 #endif
LockType
Define the possible lock types.
Definition: FileLocker.h:95
virtual void unlock()
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
LatticeRegion()
The default constructor creates a LatticeRegion that is useless for just about everything,...
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
virtual void doPutSlice(const Array< Bool > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual putting of the mask.
virtual size_t nelements() const
Returns the total number of elements in this LatticeRegion.
virtual void copyData(const Lattice< Bool > &from)
Copy the data from the given lattice to this one.
virtual void apply(const Functional< Bool, Bool > &function)
IPosition convert(const IPosition &position) const
LatticeRegion & operator=(const LatticeRegion &other)
Assignment (reference semantics).
virtual LatticeIterInterface< Bool > * 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...
LatticeRegion(const LatticeRegion &other)
Copy constructor (reference semantics).
LatticeRegion(const LCRegion &region)
Create from the given region.
LatticeRegion(const Slicer &slicer, const IPosition &latticeShape)
Construct from the given slicer.
Bool hasMask() const
Has the region a mask?
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle the (un)locking.
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
virtual void tempClose()
Temporarily close the lattice.
virtual void putAt(const Bool &value, const IPosition &where)
Put the value of a single element.
virtual IPosition shape() const
Returns the shape of the LatticeRegion including all degenerate axes (i.e.
virtual void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated path.
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
Slicer convert(const Slicer &slicer) const
Convert positions to positions in the parent object.
virtual void apply(Bool(*function)(Bool))
Replace every element, x, of the Lattice with the result of f(x).
virtual void flush()
Flush the data (but do not unlock).
virtual Bool hasLock(FileLocker::LockType) const
virtual void apply(Bool(*function)(const Bool &))
virtual Bool isWritable() const
Is the LatticeRegion writable?
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access.
virtual Lattice< Bool > * clone() const
Make a copy of the object (reference semantics).
virtual uInt ndim() const
Returns the number of axes in this LatticeRegion.
LatticeRegion(LCRegion *region)
Create from the given region and take over the pointer.
const Slicer & slicer() const
Get the Slicer object describing the region.
virtual Bool ok() const
Check class internals - used for debugging.
virtual void reopen()
Explicitly reopen the temporarily closed lattice.
virtual void resync()
Resynchronize the PagedArray object with the lattice file.
virtual void set(const Bool &value)
The following "put" functions are described in detail in class Lattice.
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
virtual Bool doGetSlice(Array< Bool > &buffer, const Slicer &section)
Do the actual getting of the mask.
const LCRegion & region() const
Get the LCRegion object describing the region.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
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.