Cube.h

Go to the documentation of this file.
00001 //# Cube.h: A 3-D Specialization of the Array Class
00002 //# Copyright (C) 1993,1994,1995,1996,1999,2000,2001,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 //# $Id$
00027 
00028 #ifndef CASA_CUBE_H
00029 #define CASA_CUBE_H
00030 
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/casa/Arrays/Array.h>
00035 
00036 namespace casacore { //#Begin casa namespace
00037 
00038 //# Forward Declarations
00039 template<class T> class Matrix;
00040 
00041 
00042 // <summary> A 3-D Specialization of the Array class </summary>
00043 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
00044 // </reviewed>
00045 //
00046 // Cube objects are three-dimensional specializations (e.g., more convenient
00047 // and efficient indexing) of the general Array class. You might also want
00048 // to look at the Array documentation to see inherited functionality.
00049 //
00050 // Generally the member functions of Array are also available in
00051 // Cube versions which take a pair of integers where the array 
00052 // needs an IPosition. Since the Cube
00053 // is three-dimensional, the IPositions are overkill, although you may
00054 // use those versions if you want to.
00055 // <srcblock>
00056 // Cube<Int> ci(100,100,100);   // Shape is 100x100
00057 // ci.resize(50,50,50);         // Shape now 50x50
00058 // </srcblock>
00059 //
00060 // Slices may be taken with the Slice class. To take a slice, one "indexes" 
00061 // with one Slice(start, length, inc) for each axis, where end and inc 
00062 // are optional. Additionally, there is an xyPlane()
00063 // member function which return a Matrix which corresponds to some plane:
00064 // <srcblock>
00065 // Cube<Float> cube(10,20,30);
00066 // for(uInt i=0; i < 30; i++) {
00067 //    cube.xyPlane(i) = i;   // Set every 10x20 plane to its "height"
00068 // }
00069 // </srcblock>
00070 //
00071 // Element-by-element arithmetic and logical operations are available (in
00072 // aips/ArrayMath.h and aips/ArrayLogical.h).
00073 //
00074 // As with the Arrays, if the preprocessor symbol AIPS_DEBUG is
00075 // defined at compile time invariants will be checked on entry to most
00076 // member functions. Additionally, if AIPS_ARRAY_INDEX_CHECK is defined
00077 // index operations will be bounds-checked. Neither of these should
00078 // be defined for production code.
00079 
00080 template<class T> class Cube : public Array<T>
00081 {
00082 public:
00083 
00084     // A Cube of length zero in each dimension; zero origin.
00085     Cube();
00086 
00087     // A l1xl2xl3 sized cube.
00088     Cube(size_t l1, size_t l2, size_t l3);
00089 
00090     // A l1xl2xl3 sized cube.
00091     Cube(size_t l1, size_t l2, size_t l3, ArrayInitPolicy initPolicy);
00092 
00093     // A l1xl2xl3 sized cube.
00094     // Fill it with the initial value.
00095     Cube(size_t l1, size_t l2, size_t l3, const T &initialValue);
00096 
00097     // A Cube where the shape ("len") is defined with IPositions.
00098     Cube(const IPosition &len);
00099 
00100     // A Cube where the shape ("len") is defined with IPositions.
00101     Cube(const IPosition &len, ArrayInitPolicy initPolicy);
00102 
00103     // A Cube where the shape ("len") is defined with IPositions.
00104     // Fill it with the initial value.
00105     Cube(const IPosition &len, const T &initialValue);
00106 
00107     // The copy constructor uses reference semantics.
00108     Cube(const Cube<T> &);
00109 
00110     // Construct a cube by reference from "other". "other must have
00111     // ndim() of 3 or less. The warning which applies to the copy constructor
00112     // is also valid here.
00113     Cube(const Array<T> &);
00114 
00115     // Create an Cube of a given shape from a pointer.
00116     Cube(const IPosition &shape, T *storage, StorageInitPolicy policy = COPY);
00117     // Create an Cube of a given shape from a pointer.
00118     Cube(const IPosition &shape, T *storage, StorageInitPolicy policy, AbstractAllocator<T> const &allocator);
00119     // Create an  Cube of a given shape from a pointer. Because the pointer
00120     // is const, a copy is always made.
00121     Cube(const IPosition &shape, const T *storage);
00122 
00123     // Define a destructor, otherwise the (SUN) compiler makes a static one.
00124     virtual ~Cube();
00125 
00126     // Assign the other array (which must be dimension 3) to this cube.
00127     // If the shapes mismatch, this array is resized.
00128     virtual void assign (const Array<T>& other);
00129 
00130     // Make this cube a reference to other. Other must be of dimensionality
00131     // 3 or less.
00132     virtual void reference(const Array<T> &other);
00133 
00134     // Resize to the given shape.
00135     // Resize without argument is equal to resize(0,0,0).
00136     // <group>
00137     using Array<T>::resize;
00138     void resize(size_t nx, size_t ny, size_t nz, Bool copyValues=False) {
00139         Cube<T>::resize(nx, ny, nz, copyValues, Array<T>::defaultArrayInitPolicy());
00140     }
00141     void resize(size_t nx, size_t ny, size_t nz, Bool copyValues, ArrayInitPolicy policy);
00142     virtual void resize();
00143     virtual void resize(const IPosition &newShape, Bool copyValues, ArrayInitPolicy policy);
00144     // </group>
00145 
00146     // Copy the values from other to this cube. If this cube has zero
00147     // elements then it will resize to be the same shape as other; otherwise
00148     // other must conform to this.
00149     // Note that the assign function can be used to assign a
00150     // non-conforming cube.
00151     // <group>
00152     Cube<T> &operator=(const Cube<T> &other);
00153     virtual Array<T> &operator=(const Array<T> &other);
00154     // </group>
00155 
00156     // Copy val into every element of this cube; i.e. behaves as if
00157     // val were a constant conformant cube.
00158     Array<T> &operator=(const T &val)
00159       { return Array<T>::operator=(val); }
00160 
00161     // Copy to this those values in marray whose corresponding elements
00162     // in marray's mask are True.
00163     Cube<T> &operator= (const MaskedArray<T> &marray)
00164       { Array<T> (*this) = marray; return *this; }
00165 
00166 
00167     // Single-pixel addressing. If AIPS_ARRAY_INDEX_CHECK is defined,
00168     // bounds checking is performed.
00169     // <group>
00170     T &operator()(const IPosition &i)
00171       { return Array<T>::operator()(i); }
00172     const T &operator()(const IPosition &i) const 
00173       { return Array<T>::operator()(i); }
00174 
00175     T &operator()(size_t i1, size_t i2, size_t i3)
00176       {
00177 #if defined(AIPS_ARRAY_INDEX_CHECK)
00178         this->validateIndex(i1, i2, i3);   // Throws an exception on failure
00179 #endif
00180         return this->begin_p[i1*xinc_p + i2*yinc_p + i3*zinc_p];
00181       }
00182 
00183     const T &operator()(size_t i1, size_t i2, size_t i3) const
00184       {
00185 #if defined(AIPS_ARRAY_INDEX_CHECK)
00186         this->validateIndex(i1, i2, i3);   // Throws an exception on failure
00187 #endif
00188         return this->begin_p[i1*xinc_p + i2*yinc_p + i3*zinc_p];
00189       }
00190 
00191   //# Have function at (temporarily) to check if test on contiguous is
00192   //# indeed slower than always using multiplication in operator()
00193     T &at(size_t i1, size_t i2, size_t i3)
00194       {
00195 #if defined(AIPS_ARRAY_INDEX_CHECK)
00196         this->validateIndex(i1, i2, i3);   // Throws an exception on failure
00197 #endif
00198         return this->contiguous_p ? this->begin_p[i1 + i2*yinc_p + i3*zinc_p] :
00199                               this->begin_p[i1*xinc_p + i2*yinc_p + i3*zinc_p];
00200       }
00201 
00202     const T &at(size_t i1, size_t i2, size_t i3) const
00203       {
00204 #if defined(AIPS_ARRAY_INDEX_CHECK)
00205         this->validateIndex(i1, i2, i3);   // Throws an exception on failure
00206 #endif
00207         return this->contiguous_p ? this->begin_p[i1 + i2*yinc_p + i3*zinc_p] :
00208                               this->begin_p[i1*xinc_p + i2*yinc_p + i3*zinc_p];
00209       }
00210     // </group>
00211 
00212     // Take a slice of this cube. Slices are always indexed starting
00213     // at zero. This uses reference semantics, i.e. changing a value
00214     // in the slice changes the original.
00215     // <srcblock>
00216     // Cube<Double> vd(100,100,100);
00217     // //...
00218     // vd(Slice(0,10),Slice(10,10,Slice(0,10))) = -1.0; // sub-cube set to -1.0
00219     // </srcblock>
00220     // <group>
00221     Cube<T> operator()(const Slice &sliceX, const Slice &sliceY,
00222                        const Slice &sliceZ);
00223     const Cube<T> operator()(const Slice &sliceX, const Slice &sliceY,
00224                              const Slice &sliceZ) const;
00225     // </group>
00226 
00227     // Slice using IPositions. Required to be defined, otherwise the base
00228     // class versions are hidden.
00229     // <group>
00230     Array<T> operator()(const IPosition &blc, const IPosition &trc,
00231                         const IPosition &incr)
00232       { return Array<T>::operator()(blc,trc,incr); }
00233     const Array<T> operator()(const IPosition &blc, const IPosition &trc,
00234                               const IPosition &incr) const
00235       { return Array<T>::operator()(blc,trc,incr); }
00236     Array<T> operator()(const IPosition &blc, const IPosition &trc)
00237       { return Array<T>::operator()(blc,trc); }
00238     const Array<T> operator()(const IPosition &blc, const IPosition &trc) const
00239       { return Array<T>::operator()(blc,trc); }
00240     Array<T> operator()(const Slicer& slicer)
00241       { return Array<T>::operator()(slicer); }
00242     const Array<T> operator()(const Slicer& slicer) const
00243       { return Array<T>::operator()(slicer); }
00244     // </group>
00245 
00246 
00247     // The array is masked by the input LogicalArray.
00248     // This mask must conform to the array.
00249     // <group>
00250 
00251     // Return a MaskedArray.
00252     const MaskedArray<T> operator() (const LogicalArray &mask) const
00253       { return Array<T>::operator() (mask); }
00254 
00255     // Return a MaskedArray.
00256     MaskedArray<T> operator() (const LogicalArray &mask)
00257       { return Array<T>::operator() (mask); }
00258 
00259     // </group>
00260 
00261 
00262     // The array is masked by the input MaskedLogicalArray.
00263     // The mask is effectively the AND of the internal LogicalArray
00264     // and the internal mask of the MaskedLogicalArray.
00265     // The MaskedLogicalArray must conform to the array.
00266     // <group>
00267 
00268     // Return a MaskedArray.
00269     const MaskedArray<T> operator() (const MaskedLogicalArray &mask) const
00270       { return Array<T>::operator() (mask); }
00271 
00272     // Return a MaskedArray.
00273     MaskedArray<T> operator() (const MaskedLogicalArray &mask)
00274       { return Array<T>::operator() (mask); }
00275 
00276     // </group>
00277 
00278 
00279     // Extract a plane as a matrix referencing the original data.
00280     // Of course you could also use a Matrix
00281     // iterator on the cube.
00282     // <group>
00283     Matrix<T> xyPlane(size_t zplane); 
00284     const  Matrix<T> xyPlane(size_t zplane) const; 
00285     Matrix<T> xzPlane(size_t yplane); 
00286     const  Matrix<T> xzPlane(size_t yplane) const; 
00287     Matrix<T> yzPlane(size_t xplane); 
00288     const  Matrix<T> yzPlane(size_t xplane) const; 
00289     // </group>
00290 
00291     // The length of each axis of the cube.
00292     const IPosition &shape() const
00293       { return this->length_p; }
00294     void shape(Int &s1, Int &s2, Int &s3) const
00295       { s1 = this->length_p(0); s2=this->length_p(1); s3=this->length_p(2); }
00296 
00297     // The number of rows in the Cube, i.e. the length of the first axis.
00298     size_t nrow() const
00299       { return this->length_p(0); }
00300 
00301     // The number of columns in the Cube, i.e. the length of the 2nd axis.
00302     size_t ncolumn() const
00303       { return this->length_p(1); }
00304 
00305     // The number of planes in the Cube, i.e. the length of the 3rd axis.
00306     size_t nplane() const
00307       { return this->length_p(2); }
00308 
00309     // Checks that the cube is consistent (invariants check out).
00310     virtual Bool ok() const;
00311 
00312 protected:
00313     virtual void preTakeStorage(const IPosition &shape);
00314     virtual void postTakeStorage();
00315     // Remove the degenerate axes from other and store result in this cube.
00316     // An exception is thrown if removing degenerate axes does not result
00317     // in a cube.
00318     virtual void doNonDegenerate(const Array<T> &other,
00319                                  const IPosition &ignoreAxes);
00320 
00321 private:
00322     // Cached constants to improve indexing.
00323     size_t xinc_p, yinc_p, zinc_p;
00324     // Helper fn to calculate the indexing constants.
00325     void makeIndexingConstants();
00326 };
00327 
00328 } //#End casa namespace
00329 #ifndef CASACORE_NO_AUTO_TEMPLATES
00330 #include <casacore/casa/Arrays/Cube.tcc>
00331 #endif //# CASACORE_NO_AUTO_TEMPLATES
00332 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1