00001 //# SubLattice.h: A subset of a Lattice or MaskedLattice 00002 //# Copyright (C) 1997,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_SUBLATTICE_H 00030 #define LATTICES_SUBLATTICE_H 00031 00032 00033 //# Includes 00034 #include <casacore/casa/aips.h> 00035 #include <casacore/lattices/Lattices/MaskedLattice.h> 00036 #include <casacore/lattices/LRegions/LatticeRegion.h> 00037 #include <casacore/casa/Arrays/AxesSpecifier.h> 00038 #include <casacore/casa/Arrays/AxesMapping.h> 00039 00040 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00041 00042 //# Forward Declarations 00043 00044 00045 // <summary> 00046 // A subset of a Lattice or MaskedLattice 00047 // </summary> 00048 00049 // <use visibility=export> 00050 00051 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos=""> 00052 // </reviewed> 00053 00054 // <prerequisite> 00055 // <li> <linkto class="Lattice">Lattice</linkto> 00056 // <li> <linkto class="LatticeRegion">LatticeRegion</linkto> 00057 // </prerequisite> 00058 00059 // <synopsis> 00060 // A SubLattice is a lattice referencing a subset of another lattice 00061 // by means of a <linkto class="Slicer">Slicer</linkto> object. 00062 // <br>It is useful when only a subset of a lattice needs to be accessed. 00063 // <p> 00064 // When the SubLattice is created from a const <src>Lattice</src> object, 00065 // it is not writable, thus it can only be used as an rvalue. 00066 // <p> 00067 // Using an <linkto class=AxesSpecifier>AxesSpecifier</linkto> object 00068 // it is possible to remove some or all degenerate axes (i.e. axes 00069 // with length 1) to get a lattice with a lower dimensionality. 00070 // </synopsis> 00071 00072 // <example> 00073 // <srcblock> 00074 // </srcblock> 00075 // </example> 00076 00077 // <templating arg=T> 00078 // <li> Any type that can be used by the Tables System can also be used by 00079 // this class. 00080 // </templating> 00081 00082 //# <todo asof="yyyy/mm/dd"> 00083 //# </todo> 00084 00085 template<class T> class SubLattice: public MaskedLattice<T> 00086 { 00087 public: 00088 // The default constructor creates a SubLattice that is useless for just 00089 // about everything, except that it can be assigned to with the assignment 00090 // operator. 00091 SubLattice(); 00092 00093 // Create a SubLattice from a Lattice. 00094 // This results in a SubLattice without a real mask. 00095 // <br>The "const Lattice" version yields a non-writable SubLattice, 00096 // while for the non-const version one has to specify if the SubLattice 00097 // should be writable (if the original lattice is non-writable, the 00098 // SubLattice is always set to non-writable). 00099 // <note>In the 2nd case the lattice could have been declared const, 00100 // but is not to indicate it can be changed. </note> 00101 // <group> 00102 SubLattice (const Lattice<T>& lattice, AxesSpecifier=AxesSpecifier()); 00103 SubLattice (Lattice<T>& lattice, Bool writableIfPossible, 00104 AxesSpecifier=AxesSpecifier()); 00105 // </group> 00106 00107 // Create a SubLattice from a MaskedLattice. 00108 // <br>The "const MaskedLattice" version yields a non-writable SubLattice, 00109 // while for the non-const version one has to specify if the SubLattice 00110 // should be writable (if the original lattice is non-writable, the 00111 // SubLattice is always set to non-writable). 00112 // <note>In the 2nd case the lattice could have been declared const, 00113 // but is not to indicate it can be changed. </note> 00114 // <group> 00115 SubLattice (const MaskedLattice<T>& lattice, AxesSpecifier=AxesSpecifier()); 00116 SubLattice (MaskedLattice<T>& lattice, Bool writableIfPossible, 00117 AxesSpecifier=AxesSpecifier()); 00118 // </group> 00119 00120 // Create a SubLattice from the given MaskedLattice and region. 00121 // Note that the region can be constructed from an 00122 // <linkto class=LCRegion>LCRegion</linkto> object or 00123 // <linkto class=Slicer>Slicer</linkto> object (with an optional stride). 00124 // <br>An exception is thrown if the lattice shape used in the region 00125 // differs from the shape of the lattice. 00126 // <note>In the 2nd and 4th case the lattice could have been declared const, 00127 // but is not to indicate it can be changed. </note> 00128 // <group> 00129 SubLattice (const Lattice<T>& lattice, const LatticeRegion& region, 00130 AxesSpecifier=AxesSpecifier()); 00131 SubLattice (Lattice<T>& lattice, const LatticeRegion& region, 00132 Bool writableIfPossible, AxesSpecifier=AxesSpecifier()); 00133 SubLattice (const MaskedLattice<T>& lattice, const LatticeRegion& region, 00134 AxesSpecifier=AxesSpecifier()); 00135 SubLattice (MaskedLattice<T>& lattice, const LatticeRegion& region, 00136 Bool writableIfPossible, AxesSpecifier=AxesSpecifier()); 00137 // </group> 00138 00139 // Create a SubLattice from the given (Masked)Lattice and slicer. 00140 // The slicer can be strided. 00141 // <br>An exception is thrown if the slicer exceeds the lattice shape. 00142 // <note>In the 2nd and 4th case the lattice could have been declared const, 00143 // but is not to indicate it can be changed. </note> 00144 // <group> 00145 SubLattice (const Lattice<T>& lattice, const Slicer& slicer, 00146 AxesSpecifier=AxesSpecifier()); 00147 SubLattice (Lattice<T>& lattice, const Slicer& slicer, 00148 Bool writableIfPossible, AxesSpecifier=AxesSpecifier()); 00149 SubLattice (const MaskedLattice<T>& lattice, const Slicer& slicer, 00150 AxesSpecifier=AxesSpecifier()); 00151 SubLattice (MaskedLattice<T>& lattice, const Slicer& slicer, 00152 Bool writableIfPossible, AxesSpecifier=AxesSpecifier()); 00153 // </group> 00154 00155 // Copy constructor (reference semantics). 00156 SubLattice (const SubLattice<T>& other); 00157 00158 virtual ~SubLattice(); 00159 00160 // Assignment (reference semantics). 00161 SubLattice<T>& operator= (const SubLattice<T>& other); 00162 00163 // Make a copy of the object (reference semantics). 00164 virtual MaskedLattice<T>* cloneML() const; 00165 00166 // Is the lattice masked? 00167 // It is if its parent lattice or its region is masked. 00168 virtual Bool isMasked() const; 00169 00170 // A SubLattice is persistent if no region is applied to the parent lattice. 00171 // That is true if the region has the same shape as the parent lattice 00172 // and the region has no mask. 00173 virtual Bool isPersistent() const; 00174 00175 // Is the SubLattice paged to disk? 00176 virtual Bool isPaged() const; 00177 00178 // Can the lattice data be referenced as an array section? 00179 virtual Bool canReferenceArray() const; 00180 00181 // Is the SubLattice writable? 00182 virtual Bool isWritable() const; 00183 00184 // Handle locking of the SubLattice which is delegated to its parent. 00185 // <br>It is strongly recommended to use class 00186 // <linkto class=LatticeLocker>LatticeLocker</linkto> to 00187 // handle lattice locking. It also contains a more detailed 00188 // explanation of the locking process. 00189 // <group> 00190 virtual Bool lock (FileLocker::LockType, uInt nattempts); 00191 virtual void unlock(); 00192 virtual Bool hasLock (FileLocker::LockType) const; 00193 // </group> 00194 00195 // Resynchronize the Lattice object with the lattice file. 00196 // This function is only useful if no read-locking is used, ie. 00197 // if the table lock option is UserNoReadLocking or AutoNoReadLocking. 00198 // In that cases the table system does not acquire a read-lock, thus 00199 // does not synchronize itself automatically. 00200 virtual void resync(); 00201 00202 // Flush the data. 00203 virtual void flush(); 00204 00205 // Close the Lattice temporarily (if it is paged to disk). 00206 // It'll be reopened automatically when needed or when 00207 // <src>reopen</src> is called explicitly. 00208 virtual void tempClose(); 00209 00210 // If needed, reopen a temporarily closed Lattice. 00211 virtual void reopen(); 00212 00213 // Does the SubLattice have a pixelmask? 00214 virtual Bool hasPixelMask() const; 00215 00216 // Get access to the pixelmask. 00217 // An exception is thrown if the SubLattice does not have a pixelmask. 00218 // <group> 00219 virtual const Lattice<Bool>& pixelMask() const; 00220 virtual Lattice<Bool>& pixelMask(); 00221 // </group> 00222 00223 // Use the given mask as the pixelmask. 00224 // If another mask was already used, the new one will be used instead. 00225 // It checks if its shape matches the shape of the sublattice. 00226 // <br>If <code>mayExist=False</code>, setting the pixelmask is only 00227 // possible if the underlying lattice does not have a pixelmask. 00228 // <br>If <code>mayExist=True</code>, the resulting pixelmask is the 00229 // AND of the given pixelmask and the pixelmask of the underlying lattice. 00230 void setPixelMask (const Lattice<Bool>& pixelMask, Bool mayExist); 00231 00232 // Get a pointer the region/mask object describing this sublattice. 00233 virtual const LatticeRegion* getRegionPtr() const; 00234 00235 // Returns the shape of the SubLattice including all degenerate axes 00236 // (i.e. axes with a length of one). 00237 virtual IPosition shape() const; 00238 00239 // Return the name of the parent lattice. 00240 virtual String name (Bool stripPath=False) const; 00241 00242 // This function returns the recommended maximum number of pixels to 00243 // include in the cursor of an iterator. 00244 virtual uInt advisedMaxPixels() const; 00245 00246 // Get or put a single element in the lattice. 00247 // <group> 00248 virtual T getAt (const IPosition& where) const; 00249 virtual void putAt (const T& value, const IPosition& where); 00250 // </group> 00251 00252 // Check class internals - used for debugging. Should always return True 00253 virtual Bool ok() const; 00254 00255 // This function is used by the LatticeIterator class to generate an 00256 // iterator of the correct type for this Lattice. Not recommended 00257 // for general use. 00258 virtual LatticeIterInterface<T>* makeIter (const LatticeNavigator& navigator, 00259 Bool useRef) const; 00260 00261 // Do the actual getting of an array of values. 00262 virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section); 00263 00264 // Do the actual getting of an array of values. 00265 virtual void doPutSlice (const Array<T>& sourceBuffer, 00266 const IPosition& where, 00267 const IPosition& stride); 00268 00269 // Get a section of the mask. 00270 virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section); 00271 00272 // Get the best cursor shape. 00273 virtual IPosition doNiceCursorShape (uInt maxPixels) const; 00274 00275 // Set the axes mapping from the specification. 00276 const AxesMapping& getAxesMap() const 00277 { return itsAxesMap; } 00278 00279 // Convert the specified position in the sublattice to the corresponding 00280 // position in the parent lattice. 00281 IPosition positionInParent(const IPosition& subLatticePosition) const 00282 { 00283 if (itsAxesMap.isRemoved()) { 00284 return itsRegion.convert (itsAxesMap.posToOld(subLatticePosition)); 00285 } else { 00286 return itsRegion.convert (subLatticePosition); 00287 } 00288 } 00289 00290 // Set the region object using a slicer. 00291 // Allows the region to be changed while keeping 00292 // the same lattice, so that new SubLattice objects do not have to be 00293 // created when one only wants to change the region of interest. Should 00294 // only be called when performance is an issue; otherwise, just create 00295 // a new SubLattice<T> object. 00296 void setRegion (const Slicer& slicer); 00297 00298 protected: 00299 // Set the region object. 00300 // It also fills in the parent pointer when the SubLattice is taken 00301 // from a MaskedLattice. 00302 // The default region is the entire lattice. 00303 // <group> 00304 void setRegion (const LatticeRegion& region); 00305 void setRegion(); 00306 // </group> 00307 00308 // Set the various pointers needed to construct the object. 00309 // One of the pointers should be zero. 00310 // It takes over the pointer and deletes the object in the destructor. 00311 void setPtr (Lattice<T>* latticePtr, 00312 MaskedLattice<T>* maskLatPtr, 00313 Bool writableIfPossible); 00314 00315 // Set the axes mapping from the specification. 00316 void setAxesMap (const AxesSpecifier&); 00317 00318 00319 private: 00320 // Get mask data from region and mask. 00321 // <group> 00322 Bool getRegionDataSlice (Array<Bool>& buffer, const Slicer& section); 00323 Bool getMaskDataSlice (Array<Bool>& buffer, const Slicer& section); 00324 // </group> 00325 00326 // And tmpbuf into buffer. If buffer is a reference, first a copy is made. 00327 void andMask (Array<Bool>& buffer, Bool ref, 00328 const Array<Bool>& tmpbuf) const; 00329 00330 Lattice<T>* itsLatticePtr; 00331 MaskedLattice<T>* itsMaskLatPtr; 00332 LatticeRegion itsRegion; 00333 Bool itsWritable; 00334 Bool itsHasLattPMask; //# has underlying lattice a pixelmask? 00335 Lattice<Bool>* itsPixelMask; //# AND of lattice and own pixelmask 00336 Lattice<Bool>* itsOwnPixelMask; //# own pixelmask 00337 AxesSpecifier itsAxesSpec; 00338 AxesMapping itsAxesMap; 00339 }; 00340 00341 //# Declare extern templates for often used types. 00342 #ifdef AIPS_CXX11 00343 extern template class SubLattice<Bool>; 00344 extern template class SubLattice<Float>; 00345 #endif 00346 00347 00348 } //# NAMESPACE CASACORE - END 00349 00350 #ifndef CASACORE_NO_AUTO_TEMPLATES 00351 #include <casacore/lattices/Lattices/SubLattice.tcc> 00352 #endif //# CASACORE_NO_AUTO_TEMPLATES 00353 #endif