00001 //# LatticeRegion.h: An optionally strided region in a lattice 00002 //# Copyright (C) 1998,1999,2000,2003 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# 00027 //# $Id$ 00028 00029 #ifndef LATTICES_LATTICEREGION_H 00030 #define LATTICES_LATTICEREGION_H 00031 00032 00033 //# Includes 00034 #include <casacore/casa/aips.h> 00035 #include <casacore/lattices/Lattices/Lattice.h> 00036 #include <casacore/casa/Arrays/Slicer.h> 00037 00038 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00039 00040 //# Forward Declarations 00041 class LCRegion; 00042 00043 00044 // <summary> 00045 // An optionally strided region in a Lattice 00046 // </summary> 00047 00048 // <use visibility=local> 00049 00050 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos=""> 00051 // </reviewed> 00052 00053 // <prerequisite> 00054 // <li> <linkto class="LCRegion">LCRegion</linkto> 00055 // </prerequisite> 00056 00057 // <synopsis> 00058 // A LatticeRegion is a lattice referencing a subset of another lattice 00059 // by means of a <linkto class="Slicer">Slicer</linkto> object. 00060 // <br>It is useful when only a subset of a lattice needs to be accessed. 00061 // <p> 00062 // When the LatticeRegion is created from a const <src>Lattice</src> object, 00063 // it is not writable, thus it can only be used as an rvalue. 00064 // </synopsis> 00065 00066 // <example> 00067 // <srcblock> 00068 // </srcblock> 00069 // </example> 00070 00071 //# <todo asof="yyyy/mm/dd"> 00072 //# </todo> 00073 00074 class LatticeRegion: public Lattice<Bool> 00075 { 00076 public: 00077 // The default constructor creates a LatticeRegion that is useless for just 00078 // about everything, except that it can be assigned to with the assignment 00079 // operator. 00080 LatticeRegion(); 00081 00082 // Create from the given region. 00083 // The pointer to the parent can be 0. 00084 LatticeRegion (const LCRegion& region); 00085 00086 // Create from the given region and take over the pointer. 00087 // This means the user should not delete the region object pointed to, 00088 // because it will be deleted by the LatticeRegion destructor. 00089 // The pointer to the parent is set to 0. 00090 LatticeRegion (LCRegion* region); 00091 00092 // Construct from the given slicer. The lattice shape has to be 00093 // the lattice shape of the lattice where the region is taken from. 00094 LatticeRegion (const Slicer& slicer, const IPosition& latticeShape); 00095 00096 // Copy constructor (reference semantics). 00097 LatticeRegion (const LatticeRegion& other); 00098 00099 virtual ~LatticeRegion(); 00100 00101 // Assignment (reference semantics). 00102 LatticeRegion& operator= (const LatticeRegion& other); 00103 00104 // Make a copy of the object (reference semantics). 00105 virtual Lattice<Bool>* clone() const; 00106 00107 // Is the LatticeRegion writable? 00108 virtual Bool isWritable() const; 00109 00110 // Has the region a mask? 00111 Bool hasMask() const; 00112 00113 // Handle the (un)locking. 00114 // <group> 00115 virtual Bool lock (FileLocker::LockType, uInt nattempts); 00116 virtual void unlock(); 00117 virtual Bool hasLock (FileLocker::LockType) const; 00118 // </group> 00119 00120 // Resynchronize the PagedArray object with the lattice file. 00121 // This function is only useful if no read-locking is used, ie. 00122 // if the table lock option is UserNoReadLocking or AutoNoReadLocking. 00123 // In that cases the table system does not acquire a read-lock, thus 00124 // does not synchronize itself automatically. 00125 virtual void resync(); 00126 00127 // Flush the data (but do not unlock). 00128 virtual void flush(); 00129 00130 // Temporarily close the lattice. 00131 // It will be reopened automatically on the next access. 00132 virtual void tempClose(); 00133 00134 // Explicitly reopen the temporarily closed lattice. 00135 virtual void reopen(); 00136 00137 // Get the LCRegion object describing the region. 00138 // Note that it does not contain strides, even if this LatticeRegion 00139 // object was constructed from a Slicer with strides. In that case 00140 // the region only defines the resulting shape. 00141 const LCRegion& region() const; 00142 00143 // Get the Slicer object describing the region. 00144 // Note that it may contain strides. 00145 const Slicer& slicer() const; 00146 00147 // Returns the shape of the LatticeRegion including all degenerate axes 00148 // (i.e. axes with a length of one). 00149 virtual IPosition shape() const; 00150 00151 // Returns the number of axes in this LatticeRegion. This includes all 00152 // degenerate axes. 00153 virtual uInt ndim() const; 00154 00155 // Returns the total number of elements in this LatticeRegion. 00156 virtual size_t nelements() const; 00157 00158 // Check class internals - used for debugging. Should always return True 00159 virtual Bool ok() const; 00160 00161 // This function is used by the LatticeIterator class to generate an 00162 // iterator of the correct type for this Lattice. Not recommended 00163 // for general use. 00164 virtual LatticeIterInterface<Bool>* makeIter 00165 (const LatticeNavigator& navigator, 00166 Bool useRef) const; 00167 00168 // Returns the maximum recommended number of pixels for a cursor. 00169 // This is the number of pixels in a tile. 00170 virtual uInt advisedMaxPixels() const; 00171 00172 // Help the user pick a cursor for most efficient access. 00173 virtual IPosition doNiceCursorShape (uInt maxPixels) const; 00174 00175 // Maximum size - not necessarily all used. In pixels. 00176 virtual uInt maximumCacheSize() const; 00177 00178 // Set the maximum (allowed) cache size as indicated. 00179 virtual void setMaximumCacheSize (uInt howManyPixels); 00180 00181 // Set the cache size as to "fit" the indicated path. 00182 virtual void setCacheSizeFromPath (const IPosition& sliceShape, 00183 const IPosition& windowStart, 00184 const IPosition& windowLength, 00185 const IPosition& axisPath); 00186 00187 // Set the actual cache size for this Array to be be big enough for the 00188 // indicated number of tiles. This cache is not shared with PagedArrays 00189 // in other rows and is always clipped to be less than the maximum value 00190 // set using the setMaximumCacheSize member function. 00191 // tiles. Tiles are cached using a first in first out algorithm. 00192 virtual void setCacheSizeInTiles (uInt howManyTiles); 00193 00194 // Clears and frees up the caches, but the maximum allowed cache size is 00195 // unchanged from when setCacheSize was called 00196 virtual void clearCache(); 00197 00198 // Report on cache success. 00199 virtual void showCacheStatistics (ostream& os) const; 00200 00201 // The following "put" functions are described in detail in class 00202 // <linkto class=Lattice>Lattice</linkto>. 00203 // They'll throw an exception is no mask is available or if 00204 // the mask is not writable. 00205 // <group> 00206 virtual void set (const Bool& value); 00207 virtual void apply (Bool (*function)(Bool)); 00208 virtual void apply (Bool (*function)(const Bool&)); 00209 virtual void apply (const Functional<Bool,Bool>& function); 00210 virtual void putAt (const Bool& value, const IPosition& where); 00211 virtual void copyData (const Lattice<Bool>& from); 00212 // </group> 00213 00214 // Convert positions to positions in the parent object. 00215 // <group> 00216 Slicer convert (const Slicer& slicer) const; 00217 IPosition convert (const IPosition& position) const; 00218 // </group> 00219 00220 // Do the actual getting of the mask. 00221 virtual Bool doGetSlice (Array<Bool>& buffer, const Slicer& section); 00222 00223 // Do the actual putting of the mask. Only possible if region is writable. 00224 virtual void doPutSlice (const Array<Bool>& sourceBuffer, 00225 const IPosition& where, 00226 const IPosition& stride); 00227 00228 00229 private: 00230 LCRegion* itsRegion; 00231 Slicer itsSlicer; 00232 Bool itsHasRegionMask; 00233 }; 00234 00235 00236 inline Bool LatticeRegion::hasMask() const 00237 { 00238 return itsHasRegionMask; 00239 } 00240 inline const LCRegion& LatticeRegion::region() const 00241 { 00242 return *itsRegion; 00243 } 00244 inline const Slicer& LatticeRegion::slicer() const 00245 { 00246 return itsSlicer; 00247 } 00248 00249 00250 00251 } //# NAMESPACE CASACORE - END 00252 00253 #endif