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
casacore::LatticeRegion::itsRegion
LCRegion * itsRegion
Definition: LatticeRegion.h:230
casacore::Slicer
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:290
casacore::LatticeRegion::nelements
virtual size_t nelements() const
Returns the total number of elements in this LatticeRegion.
casacore::IPosition
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:120
casacore::LatticeRegion::doGetSlice
virtual Bool doGetSlice(Array< Bool > &buffer, const Slicer &section)
Do the actual getting of the mask.
casacore::LatticeRegion::flush
virtual void flush()
Flush the data (but do not unlock).
casacore::LatticeRegion::hasMask
Bool hasMask() const
Has the region a mask?
Definition: LatticeRegion.h:236
casacore::LatticeRegion::putAt
virtual void putAt(const Bool &value, const IPosition &where)
Put the value of a single element.
casacore::LatticeRegion::LatticeRegion
LatticeRegion(const LatticeRegion &other)
Copy constructor (reference semantics).
casacore::LatticeRegion::showCacheStatistics
virtual void showCacheStatistics(ostream &os) const
Report on cache success.
casacore::LatticeRegion::operator=
LatticeRegion & operator=(const LatticeRegion &other)
Assignment (reference semantics).
casacore::LatticeRegion::LatticeRegion
LatticeRegion(const Slicer &slicer, const IPosition &latticeShape)
Construct from the given slicer.
casacore::Functional
Map a domain object into a range object via operator().
Definition: Array.h:53
casacore::FileLocker::LockType
LockType
Define the possible lock types.
Definition: FileLocker.h:95
casacore::LatticeRegion::reopen
virtual void reopen()
Explicitly reopen the temporarily closed lattice.
casacore::LatticeRegion::set
virtual void set(const Bool &value)
The following "put" functions are described in detail in class Lattice.
casacore::LatticeRegion::itsHasRegionMask
Bool itsHasRegionMask
Definition: LatticeRegion.h:232
casacore::LatticeRegion
An optionally strided region in a Lattice.
Definition: LatticeRegion.h:75
casacore::LatticeRegion::apply
virtual void apply(const Functional< Bool, Bool > &function)
casacore::LatticeRegion::maximumCacheSize
virtual uInt maximumCacheSize() const
Maximum size - not necessarily all used.
casacore::LatticeRegion::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access.
casacore::LatticeRegion::LatticeRegion
LatticeRegion(const LCRegion &region)
Create from the given region.
casacore::LatticeRegion::apply
virtual void apply(Bool(*function)(const Bool &))
casacore::LatticeRegion::ndim
virtual uInt ndim() const
Returns the number of axes in this LatticeRegion.
casacore::LatticeRegion::hasLock
virtual Bool hasLock(FileLocker::LockType) const
casacore::LatticeRegion::LatticeRegion
LatticeRegion(LCRegion *region)
Create from the given region and take over the pointer.
casacore::LatticeRegion::shape
virtual IPosition shape() const
Returns the shape of the LatticeRegion including all degenerate axes (i.e.
casacore::value
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
casacore::LatticeNavigator
Abstract base class to steer lattice iterators.
Definition: LatticeNavigator.h:182
casacore::LatticeRegion::setMaximumCacheSize
virtual void setMaximumCacheSize(uInt howManyPixels)
Set the maximum (allowed) cache size as indicated.
casacore::LatticeRegion::resync
virtual void resync()
Resynchronize the PagedArray object with the lattice file.
casacore::LatticeRegion::lock
virtual Bool lock(FileLocker::LockType, uInt nattempts)
Handle the (un)locking.
casacore::LatticeRegion::itsSlicer
Slicer itsSlicer
Definition: LatticeRegion.h:231
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::LatticeRegion::convert
IPosition convert(const IPosition &position) const
casacore::LatticeRegion::~LatticeRegion
virtual ~LatticeRegion()
casacore::LatticeRegion::copyData
virtual void copyData(const Lattice< Bool > &from)
Copy the data from the given lattice to this one.
casacore::LCRegion
Abstract base class to define a region of interest in lattice coordinates.
Definition: LCRegion.h:88
casacore::LatticeRegion::makeIter
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...
casacore::LatticeRegion::setCacheSizeFromPath
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.
casacore::LatticeRegion::slicer
const Slicer & slicer() const
Get the Slicer object describing the region.
Definition: LatticeRegion.h:244
casacore::LatticeRegion::isWritable
virtual Bool isWritable() const
Is the LatticeRegion writable?
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::LatticeRegion::convert
Slicer convert(const Slicer &slicer) const
Convert positions to positions in the parent object.
casacore::LatticeRegion::unlock
virtual void unlock()
casacore::LatticeRegion::clone
virtual Lattice< Bool > * clone() const
Make a copy of the object (reference semantics).
casacore::LatticeRegion::clearCache
virtual void clearCache()
Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSiz...
casacore::Lattice
A templated, abstract base class for array-like objects.
Definition: Functional.h:37
casacore::LatticeRegion::advisedMaxPixels
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
casacore::Array< Bool >
casacore::LatticeRegion::doPutSlice
virtual void doPutSlice(const Array< Bool > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual putting of the mask.
casacore::LatticeRegion::apply
virtual void apply(Bool(*function)(Bool))
Replace every element, x, of the Lattice with the result of f(x).
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::LatticeRegion::tempClose
virtual void tempClose()
Temporarily close the lattice.
casacore::LatticeRegion::LatticeRegion
LatticeRegion()
The default constructor creates a LatticeRegion that is useless for just about everything,...
casacore::LatticeRegion::region
const LCRegion & region() const
Get the LCRegion object describing the region.
Definition: LatticeRegion.h:240
casacore::LatticeRegion::setCacheSizeInTiles
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be be big enough for the indicated number of tiles.
casacore::LatticeIterInterface
A base class for Lattice iterators.
Definition: ImageExpr.h:47
casacore::LatticeRegion::ok
virtual Bool ok() const
Check class internals - used for debugging.