LatticeRegion.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1