00001 //# MaskedLattice.h: Abstract base class for array-like classes with masks 00002 //# Copyright (C) 1998,1999,2000 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 //# $Id$ 00027 00028 #ifndef LATTICES_MASKEDLATTICE_H 00029 #define LATTICES_MASKEDLATTICE_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/lattices/Lattices/Lattice.h> 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 //# Forward Declarations 00039 class LatticeRegion; 00040 00041 00042 // <summary> 00043 // A templated, abstract base class for array-like objects with masks. 00044 // </summary> 00045 00046 // <use visibility=export> 00047 00048 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="dLattice.cc"> 00049 // </reviewed> 00050 00051 // <prerequisite> 00052 // <li> <linkto class="IPosition"> IPosition </linkto> 00053 // <li> Abstract Base class Inheritance - try "Advanced C++" by James 00054 // O. Coplien, Ch. 5. 00055 // </prerequisite> 00056 00057 // <etymology> 00058 // Lattice: "A regular, periodic configuration of points, particles, 00059 // or objects, throughout an area of a space..." (American Heritage Directory) 00060 // This definition matches our own: an n-dimensional arrangement of items, 00061 // on regular orthogonal axes. 00062 // </etymology> 00063 00064 // <synopsis> 00065 // This pure abstract base class defines the operations which may be performed 00066 // on any concrete class derived from it. It has only a few non-pure virtual 00067 // member functions. 00068 // The fundamental contribution of this class, therefore, is that it 00069 // defines the operations derived classes must provide: 00070 // <ul> 00071 // <li> how to extract a "slice" (or sub-array, or subsection) from 00072 // a Lattice. 00073 // <li> how to copy a slice in. 00074 // <li> how to get and put a single element 00075 // <li> how to apply a function to all elements 00076 // <li> various shape related functions. 00077 // </ul> 00078 // <note role=tip> Lattices are always zero origined. </note> 00079 // </synopsis> 00080 00081 // <example> 00082 // Because Lattice is an abstract base class, an actual instance of this 00083 // class cannot be constructed. However the interface it defines can be used 00084 // inside a function. This is always recommended as it allows Functions 00085 // which have Lattices as arguments to work for any derived class. 00086 // 00087 // I will give a few examples here and then refer the reader to the 00088 // <linkto class="ArrayLattice">ArrayLattice</linkto> class (a memory resident 00089 // Lattice) and the <linkto class="PagedArray">PagedArray</linkto> class (a 00090 // disk based Lattice) which contain further examples with concrete 00091 // classes (rather than an abstract one). All the examples shown below are used 00092 // in the <src>dLattice.cc</src> demo program. 00093 // 00094 // <h4>Example 1:</h4> 00095 // This example calculates the mean of the Lattice. Because Lattices can be too 00096 // large to fit into physical memory it is not good enough to simply use 00097 // <src>getSlice</src> to read all the elements into an Array. Instead the 00098 // Lattice is accessed in chunks which can fit into memory (the size is 00099 // determined by the <src>maxPixels</src> and <src>niceCursorShape</src> 00100 // functions). The <src>LatticeIterator::cursor()</src> function then returns 00101 // each of these chunks as an Array and the standard Array based functions are 00102 // used to calculate the mean on each of these chunks. Functions like this one 00103 // are the recommended way to access Lattices as the 00104 // <linkto class="LatticeIterator">LatticeIterator</linkto> will correctly 00105 // setup any required caches. 00106 // 00107 // <srcblock> 00108 // Complex latMean(const Lattice<Complex>& lat) { 00109 // const uInt cursorSize = lat.advisedMaxPixels(); 00110 // const IPosition cursorShape = lat.niceCursorShape(cursorSize); 00111 // const IPosition latticeShape = lat.shape(); 00112 // Complex currentSum = 0.0f; 00113 // size_t nPixels = 0; 00114 // RO_LatticeIterator<Complex> iter(lat, 00115 // LatticeStepper(latticeShape, cursorShape)); 00116 // for (iter.reset(); !iter.atEnd(); iter++){ 00117 // currentSum += sum(iter.cursor()); 00118 // nPixels += iter.cursor().nelements(); 00119 // } 00120 // return currentSum/nPixels; 00121 // } 00122 // </srcblock> 00123 // 00124 // <h4>Example 2:</h4> 00125 // Sometimes it will be neccesary to access slices of a Lattice in a nearly 00126 // random way. Often this can be done using the subSection commands in the 00127 // <linkto class="LatticeStepper">LatticeStepper</linkto> class. But it is also 00128 // possible to use the getSlice and putSlice functions. The following example 00129 // does a two-dimensional Real to Complex Fourier transform. This example is 00130 // restricted to four-dimensional Arrays (unlike the previous example) and does 00131 // not set up any caches (caching is currently only used with PagedArrays). So 00132 // only use getSlice and putSlice when things cannot be done using 00133 // LatticeIterators. 00134 // 00135 // <srcblock> 00136 // void FFT2DReal2Complex(Lattice<Complex>& result, 00137 // const Lattice<Float>& input){ 00138 // AlwaysAssert(input.ndim() == 4, AipsError); 00139 // const IPosition shape = input.shape(); 00140 // const uInt nx = shape(0); 00141 // AlwaysAssert (nx > 1, AipsError); 00142 // const uInt ny = shape(1); 00143 // AlwaysAssert (ny > 1, AipsError); 00144 // const uInt npol = shape(2); 00145 // const uInt nchan = shape(3); 00146 // const IPosition resultShape = result.shape(); 00147 // AlwaysAssert(resultShape.nelements() == 4, AipsError); 00148 // AlwaysAssert(resultShape(3) == nchan, AipsError); 00149 // AlwaysAssert(resultShape(2) == npol, AipsError); 00150 // AlwaysAssert(resultShape(1) == ny, AipsError); 00151 // AlwaysAssert(resultShape(0) == nx/2 + 1, AipsError); 00152 // 00153 // const IPosition inputSliceShape(4,nx,ny,1,1); 00154 // const IPosition resultSliceShape(4,nx/2+1,ny,1,1); 00155 // COWPtr<Array<Float> > 00156 // inputArrPtr(new Array<Float>(inputSliceShape.nonDegenerate())); 00157 // Array<Complex> resultArray(resultSliceShape.nonDegenerate()); 00158 // FFTServer<Float, Complex> FFT2D(inputSliceShape.nonDegenerate()); 00159 // 00160 // IPosition start(4,0); 00161 // Bool isARef; 00162 // for (uInt c = 0; c < nchan; c++){ 00163 // for (uInt p = 0; p < npol; p++){ 00164 // isARef = input.getSlice(inputArrPtr, 00165 // Slicer(start,inputSliceShape), True); 00166 // FFT2D.fft(resultArray, *inputArrPtr); 00167 // result.putSlice(resultArray, start); 00168 // start(2) += 1; 00169 // } 00170 // start(2) = 0; 00171 // start(3) += 1; 00172 // } 00173 // } 00174 // </srcblock> 00175 // 00176 // <h4>Example 3:</h4> 00177 // Occasionally you may want to access a few elements of a Lattice without 00178 // all the difficulty involved in setting up Iterators or calling getSlice 00179 // and putSlice. This is demonstrated in the example below and uses the 00180 // parenthesis operator, along with the LatticeValueRef companion 00181 // class. Using these functions to access many elements of a Lattice is not 00182 // recommended as this is the slowest access method. 00183 // 00184 // In this example an ideal point spread function will be inserted into an 00185 // empty Lattice. As with the previous examples all the action occurs 00186 // inside a function because Lattice is an interface (abstract) class. 00187 // 00188 // <srcblock> 00189 // void makePsf(Lattice<Float>& psf) { 00190 // const IPosition centrePos = psf.shape()/2; 00191 // psf.set(0.0f); // this sets all the elements to zero 00192 // // As it uses a LatticeIterator it is efficient 00193 // psf(centrePos) = 1; // This sets just the centre element to one 00194 // AlwaysAssert(near(psf(centrePos), 1.0f, 1E-6), AipsError); 00195 // AlwaysAssert(near(psf(centrePos*0), 0.0f, 1E-6), AipsError); 00196 // } 00197 // </srcblock> 00198 // </example> 00199 00200 // <motivation> 00201 // Creating an abstract base class which provides a common interface between 00202 // memory and disk based arrays has a number of advantages. 00203 // <ul> 00204 // <li> It allows functions common to all arrays to be written independent 00205 // of the way the data is stored. This is illustrated in the three examples 00206 // above. 00207 // <li> It reduces the learning curve for new users who only have to become 00208 // familiar with one interface (ie. Lattice) rather than distinct interfaces 00209 // for different array types. 00210 // </ul> 00211 // </motivation> 00212 00213 //# <todo asof="1996/07/01"> 00214 //# <li> 00215 //# </todo> 00216 00217 template <class T> class MaskedLattice : public Lattice<T> 00218 { 00219 //# Make members of parent class known. 00220 public: 00221 using Lattice<T>::ndim; 00222 using Lattice<T>::shape; 00223 00224 public: 00225 // Default constructor. 00226 MaskedLattice() 00227 : itsDefRegPtr(0) {;} 00228 00229 // Copy constructor. 00230 MaskedLattice (const MaskedLattice<T>&); 00231 00232 // a virtual destructor is needed so that it will use the actual destructor 00233 // in the derived class 00234 virtual ~MaskedLattice(); 00235 00236 // Make a copy of the object (reference semantics). 00237 // <group> 00238 virtual MaskedLattice<T>* cloneML() const = 0; 00239 virtual Lattice<T>* clone() const; 00240 // </group> 00241 00242 // Has the object really a mask? 00243 // The default implementation returns True if the MaskedLattice has 00244 // a region with a mask. 00245 virtual Bool isMasked() const; 00246 00247 // Does the lattice have a pixelmask? 00248 // The default implementation returns False. 00249 virtual Bool hasPixelMask() const; 00250 00251 // Get access to the pixelmask. 00252 // An exception is thrown if the lattice does not have a pixelmask. 00253 // <group> 00254 virtual const Lattice<Bool>& pixelMask() const; 00255 virtual Lattice<Bool>& pixelMask(); 00256 // </group> 00257 00258 // Get the region used. 00259 // This is in principle the region pointed to by <src>getRegionPtr</src>. 00260 // However, if that pointer is 0, it returns a LatticeRegion for the 00261 // full image. 00262 const LatticeRegion& region() const; 00263 00264 // Get the mask or a slice from the mask. 00265 // This is the mask formed by combination of the possible pixelmask of the 00266 // lattice and the possible mask of the region taken from the lattice. 00267 // If there is no mask, it still works fine. 00268 // In that case it sizes the buffer correctly and sets it to True. 00269 // <group> 00270 Bool getMask (COWPtr<Array<Bool> >& buffer, 00271 Bool removeDegenerateAxes=False) const; 00272 Bool getMaskSlice (COWPtr<Array<Bool> >& buffer, const Slicer& section, 00273 Bool removeDegenerateAxes=False) const; 00274 Bool getMaskSlice (COWPtr<Array<Bool> >& buffer, const IPosition& start, 00275 const IPosition& shape, 00276 Bool removeDegenerateAxes=False) const; 00277 Bool getMaskSlice (COWPtr<Array<Bool> >& buffer, const IPosition& start, 00278 const IPosition& shape, const IPosition& stride, 00279 Bool removeDegenerateAxes=False) const; 00280 Bool getMask (Array<Bool>& buffer, 00281 Bool removeDegenerateAxes=False); 00282 Bool getMaskSlice (Array<Bool>& buffer, const Slicer& section, 00283 Bool removeDegenerateAxes=False); 00284 Bool getMaskSlice (Array<Bool>& buffer, const IPosition& start, 00285 const IPosition& shape, 00286 Bool removeDegenerateAxes=False); 00287 Bool getMaskSlice (Array<Bool>& buffer, const IPosition& start, 00288 const IPosition& shape, const IPosition& stride, 00289 Bool removeDegenerateAxes=False); 00290 Array<Bool> getMask (Bool removeDegenerateAxes=False) const; 00291 Array<Bool> getMaskSlice (const Slicer& section, 00292 Bool removeDegenerateAxes=False) const; 00293 Array<Bool> getMaskSlice (const IPosition& start, 00294 const IPosition& shape, 00295 Bool removeDegenerateAxes=False) const; 00296 Array<Bool> getMaskSlice (const IPosition& start, 00297 const IPosition& shape, const IPosition& stride, 00298 Bool removeDegenerateAxes=False) const; 00299 // </group> 00300 00301 // The function (in the derived classes) doing the actual work. 00302 // These functions are public, so they can be used internally in the 00303 // various Lattice classes. 00304 // <br>However, doGetMaskSlice does not call Slicer::inferShapeFromSource 00305 // to fill in possible unspecified section values. Therefore one 00306 // should normally use one of the getMask(Slice) functions. doGetMaskSlice 00307 // should be used with care and only when performance is an issue. 00308 // <br>The default implementation gets the mask from the region 00309 // and fills the buffer with True values if there is no region. 00310 virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section); 00311 00312 protected: 00313 // Assignment can only be used by derived classes. 00314 MaskedLattice<T>& operator= (const MaskedLattice<T>&); 00315 00316 // Get a pointer to the region used. 00317 // It can return 0 meaning that the MaskedLattice is the full lattice. 00318 virtual const LatticeRegion* getRegionPtr() const = 0; 00319 00320 private: 00321 mutable LatticeRegion* itsDefRegPtr; 00322 }; 00323 00324 00325 00326 } //# NAMESPACE CASACORE - END 00327 00328 #ifndef CASACORE_NO_AUTO_TEMPLATES 00329 #include <casacore/lattices/Lattices/MaskedLattice.tcc> 00330 #endif //# CASACORE_NO_AUTO_TEMPLATES 00331 #endif