casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
SubLattice.h
Go to the documentation of this file.
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: SubLattice.h 20229 2008-01-29 15:19:06Z gervandiepen $
00028 
00029 #ifndef LATTICES_SUBLATTICE_H
00030 #define LATTICES_SUBLATTICE_H
00031 
00032 
00033 //# Includes
00034 #include <casa/aips.h>
00035 #include <lattices/Lattices/MaskedLattice.h>
00036 #include <lattices/Lattices/LatticeRegion.h>
00037 #include <casa/Arrays/AxesSpecifier.h>
00038 #include <casa/Arrays/AxesMapping.h>
00039 
00040 namespace casa { //# NAMESPACE CASA - 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   // <group>
00100   SubLattice (const Lattice<T>& lattice, AxesSpecifier=AxesSpecifier());
00101 
00102   // according to Ger, even though lattice could be declared const it is
00103   // purposefully not to indicate that the data can change.
00104   SubLattice (Lattice<T>& lattice, Bool writableIfPossible,
00105               AxesSpecifier=AxesSpecifier());
00106   // </group>
00107 
00108   // Create a SubLattice from a MaskedLattice.
00109   // <br>The "const MaskedLattice" version yields a non-writable SubLattice,
00110   // while for the non-const version one has to specify if the SubLattice
00111   // should be writable (if the original lattice is non-writable, the
00112   // SubLattice is always set to non-writable).
00113   // <group>
00114   SubLattice (const MaskedLattice<T>& lattice, AxesSpecifier=AxesSpecifier());
00115 
00116   // according to Ger, even though lattice could be declared const it is
00117   // purposefully not to indicate that the data can change.
00118   SubLattice (MaskedLattice<T>& lattice, Bool writableIfPossible,
00119               AxesSpecifier=AxesSpecifier());
00120   // </group>
00121 
00122   // Create a SubLattice from the given MaskedLattice and region.
00123   // Note that the region can be constructed from an
00124   // <linkto class=LCRegion>LCRegion</linkto> object or 
00125   // <linkto class=Slicer>Slicer</linkto> object (with an optional stride).
00126   // <br>An exception is thrown if the lattice shape used in the region
00127   // differs from the shape of the lattice.
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   // according to Ger, even though lattice could be declared const it is
00136   // purposefully not to indicate that the data can change.
00137   SubLattice (MaskedLattice<T>& lattice, const LatticeRegion& region,
00138               Bool writableIfPossible, AxesSpecifier=AxesSpecifier());
00139   // </group>
00140   
00141   // Create a SubLattice from the given (Masked)Lattice and slicer.
00142   // The slicer can be strided.
00143   // <br>An exception is thrown if the slicer exceeds the lattice shape.
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 protected:
00280   // Set the various pointer needed to construct the object.
00281   // One of the pointers should be zero.
00282   // It takes over the pointer and deletes the object in the destructor.
00283   void setPtr (Lattice<T>* latticePtr,
00284                MaskedLattice<T>* maskLatPtr,
00285                Bool writableIfPossible);
00286 
00287   // Set the region object.
00288   // It also fills in the parent pointer when the SubLattice is taken
00289   // from a MaskedLattice.
00290   // The default region is the entire lattice.
00291   // <group>
00292   void setRegion (const LatticeRegion& region);
00293   void setRegion (const Slicer& slicer);
00294   void setRegion();
00295   // </group>
00296 
00297   // Set the axes mapping from the specification.
00298   void setAxesMap (const AxesSpecifier&);
00299 
00300 
00301 private:
00302   // Get mask data from region and mask.
00303   // <group>
00304   Bool getRegionDataSlice (Array<Bool>& buffer, const Slicer& section);
00305   Bool getMaskDataSlice (Array<Bool>& buffer, const Slicer& section);
00306   // </group>
00307 
00308   // And tmpbuf into buffer. If buffer is a reference, first a copy is made.
00309   void andMask (Array<Bool>& buffer, Bool ref,
00310                 const Array<Bool>& tmpbuf) const;
00311 
00312   Lattice<T>*       itsLatticePtr;
00313   MaskedLattice<T>* itsMaskLatPtr;
00314   LatticeRegion     itsRegion;
00315   Bool              itsWritable;
00316   Bool              itsHasLattPMask;   //# has underlying lattice a pixelmask?
00317   Lattice<Bool>*    itsPixelMask;      //# AND of lattice and own pixelmask
00318   Lattice<Bool>*    itsOwnPixelMask;   //# own pixelmask
00319   AxesSpecifier     itsAxesSpec;
00320   AxesMapping       itsAxesMap;
00321 };
00322 
00323 
00324 
00325 } //# NAMESPACE CASA - END
00326 
00327 #ifndef CASACORE_NO_AUTO_TEMPLATES
00328 #include <lattices/Lattices/SubLattice.tcc>
00329 #endif //# CASACORE_NO_AUTO_TEMPLATES
00330 #endif