00001 //# SubImage.h: A (masked) subset of an ImageInterface object 00002 //# Copyright (C) 1998,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 IMAGES_SUBIMAGE_H 00029 #define IMAGES_SUBIMAGE_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/images/Images/ImageInterface.h> 00035 #include <casacore/casa/Arrays/AxesSpecifier.h> 00036 00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00038 00039 //# Forward Declarations 00040 class IPosition; 00041 class LattRegionHolder; 00042 class Slicer; 00043 template <class T> class SubLattice; 00044 template <class T> class Array; 00045 class LatticeNavigator; 00046 template <class T> class LatticeIterInterface; 00047 class String; 00048 00049 00050 // <summary> 00051 // A (masked) subset of an ImageInterface object. 00052 // </summary> 00053 // 00054 // <use visibility=export> 00055 // 00056 // <reviewed reviewer="" date="" tests="tSubImage.cc"> 00057 // </reviewed> 00058 // 00059 // <prerequisite> 00060 // <li> <linkto class=ImageInterface>ImageInterface</linkto> 00061 // <li> <linkto class=SubLattice>SubLattice</linkto> 00062 // </prerequisite> 00063 // 00064 // <synopsis> 00065 // Class SubImage has to be used to apply a region or mask to an image. 00066 // Several functions are inherited from SubLattice and not declared 00067 // in this class. 00068 // <p> 00069 // Using an <linkto class=AxesSpecifier>AxesSpecifier</linkto> object 00070 // it is possible to remove some or all degenerate axes (i.e. axes 00071 // with length 1) to get an image with a lower dimensionality. 00072 // </synopsis> 00073 // 00074 // <example> 00075 // <srcblock> 00076 // </srcblock> 00077 // </example> 00078 // 00079 // <motivation> 00080 // </motivation> 00081 // 00082 // <todo asof="1998/02/09"> 00083 // </todo> 00084 00085 00086 template <class T> class SubImage: public ImageInterface<T> 00087 { 00088 public: 00089 // The default constructor 00090 SubImage(); 00091 00092 // Create a SubImage from a Image. 00093 // This results in a SubImage without a real mask. 00094 // <br>The "const Image" version yields a non-writable SubImage, 00095 // while for the non-const version one has to specify if the SubImage 00096 // should be writable (if the original image is non-writable, the 00097 // SubImage is always set to non-writable). 00098 // <br>If preserveAxesOrder is True, the axes order will be preserved. This 00099 // is only important in cases where pixel axes are to be dropped, if not 00100 // the axes order will be preserved. If False and pixel axes are dropped, 00101 // the order of the coordinates will be preserved, but not necessarily 00102 // the axes. 00103 // <group> 00104 SubImage (const ImageInterface<T>& image, 00105 AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False); 00106 SubImage (ImageInterface<T>& image, Bool writableIfPossible, 00107 AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False); 00108 // </group> 00109 00110 // Create a SubImage from the given Image and region. 00111 // <br>An exception is thrown if the image shape used in the region 00112 // differs from the shape of the image. 00113 // <group> 00114 SubImage (const ImageInterface<T>& image, const LattRegionHolder& region, 00115 AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False); 00116 SubImage (ImageInterface<T>& image, const LattRegionHolder& region, 00117 Bool writableIfPossible, 00118 AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False); 00119 // </group> 00120 00121 // Create a SubImage from the given Image and slicer. 00122 // The slicer can be strided. 00123 // <br>An exception is thrown if the slicer exceeds the image shape. 00124 // <group> 00125 SubImage (const ImageInterface<T>& image, const Slicer& slicer, 00126 AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False); 00127 SubImage (ImageInterface<T>& image, const Slicer& slicer, 00128 Bool writableIfPossible, 00129 AxesSpecifier=AxesSpecifier(), Bool preserveAxesOrder=False); 00130 // </group> 00131 00132 // Copy constructor (reference semantics). 00133 SubImage (const SubImage<T>& other); 00134 00135 virtual ~SubImage(); 00136 00137 // Assignment (reference semantics). 00138 SubImage<T>& operator= (const SubImage<T>& other); 00139 00140 // Make a copy of the object (reference semantics). 00141 // <group> 00142 virtual ImageInterface<T>* cloneII() const; 00143 // </group> 00144 00145 // Get the image type (returns name of derived class). 00146 virtual String imageType() const; 00147 00148 // Is the SubImage masked? 00149 // It is if its parent image or its region is masked. 00150 virtual Bool isMasked() const; 00151 00152 // Does the image object have a pixelmask? 00153 // It does if its parent has a pixelmask. 00154 virtual Bool hasPixelMask() const; 00155 00156 // Get access to the pixelmask in use (thus to the pixelmask of the parent). 00157 // An exception is thrown if the parent does not have a pixelmask. 00158 // <group> 00159 virtual const Lattice<Bool>& pixelMask() const; 00160 virtual Lattice<Bool>& pixelMask(); 00161 // </group> 00162 00163 // A SubImage is persistent if no region is applied to the parent image. 00164 // That is true if the region has the same shape as the parent image 00165 // and the region has no mask. 00166 virtual Bool isPersistent() const; 00167 00168 // Is the SubImage paged to disk? 00169 virtual Bool isPaged() const; 00170 00171 // Can the lattice data be referenced as an array section? 00172 virtual Bool canReferenceArray() const; 00173 00174 // Is the SubImage writable? 00175 virtual Bool isWritable() const; 00176 00177 // Get the region/mask object describing this subImage. 00178 virtual const LatticeRegion* getRegionPtr() const; 00179 00180 // Returns the shape of the SubImage including all degenerate axes 00181 // (i.e. axes with a length of one). 00182 virtual IPosition shape() const; 00183 00184 // Returns the number of axes in this SubImage. This includes all 00185 // degenerate axes. 00186 virtual uInt ndim() const; 00187 00188 // Returns the total number of elements in this SubImage. 00189 virtual size_t nelements() const; 00190 00191 // returns a value of "True" if this instance of Lattice and 'other' have 00192 // the same shape, otherwise returns a value of "False". 00193 virtual Bool conform (const Lattice<T>& other) const; 00194 00195 // This function returns the recommended maximum number of pixels to 00196 // include in the cursor of an iterator. 00197 virtual uInt advisedMaxPixels() const; 00198 00199 // Get access to the attribute handler (of the parent image). 00200 // If a handler keyword does not exist yet, it is created if 00201 // <src>createHandler</src> is set. 00202 // Otherwise the handler is empty and no groups can be created for it. 00203 virtual ImageAttrHandler& attrHandler (Bool createHandler=False); 00204 00205 // Get or put a single element in the lattice. 00206 // <group> 00207 virtual T getAt (const IPosition& where) const; 00208 virtual void putAt (const T& value, const IPosition& where); 00209 // </group> 00210 00211 // Function which changes the shape of the SubImage. 00212 // Throws an exception as resizing a SubImage is not possible. 00213 virtual void resize(const TiledShape& newShape); 00214 00215 // Return the name of the parent ImageInterface object. 00216 virtual String name (Bool stripPath=False) const; 00217 00218 // Check class invariants. 00219 virtual Bool ok() const; 00220 00221 // Do the actual getting of an array of values. 00222 virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section); 00223 00224 // Do the actual getting of an array of values. 00225 virtual void doPutSlice (const Array<T>& sourceBuffer, 00226 const IPosition& where, 00227 const IPosition& stride); 00228 00229 // Get a section of the mask. 00230 virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section); 00231 00232 // This function is used by the LatticeIterator class to generate an 00233 // iterator of the correct type for this Lattice. Not recommended 00234 // for general use. 00235 virtual LatticeIterInterface<T>* makeIter 00236 (const LatticeNavigator& navigator, 00237 Bool useRef) const; 00238 00239 // Get the best cursor shape. 00240 virtual IPosition doNiceCursorShape (uInt maxPixels) const; 00241 00242 // Handle the (un)locking and syncing, etc. 00243 // <group> 00244 virtual Bool lock (FileLocker::LockType, uInt nattempts); 00245 virtual void unlock(); 00246 virtual Bool hasLock (FileLocker::LockType) const; 00247 virtual void resync(); 00248 virtual void flush(); 00249 virtual void tempClose(); 00250 virtual void reopen(); 00251 // </group> 00252 00253 private: 00254 // Set the coordinates. 00255 // It removes world axes if the subimage has axes removed. 00256 // <br>If preserveAxesOrder is True and axes are dropped, it will preserve 00257 // the order of the axes as well as the order of the coordinates. 00258 void setCoords (const CoordinateSystem& coords, Bool preserveAxesOrder); 00259 void setCoords (const CoordinateSystem& coords); 00260 00261 // Set the other members to the one in itsImagePtr. 00262 void setMembers(); 00263 00264 // Set the members to the subset (in particular, the beamset). 00265 void setMembers (const Slicer& slicer); 00266 00267 // Helper 00268 void convertIPosition(Vector<Float>& x, const IPosition& pos) const; 00269 00270 00271 //# itsImagePtr points to the parent image. 00272 ImageInterface<T>* itsImagePtr; 00273 SubLattice<T>* itsSubLatPtr; 00274 00275 //# Make members of parent class known. 00276 public: 00277 using ImageInterface<T>::logger; 00278 protected: 00279 using ImageInterface<T>::setCoordsMember; 00280 }; 00281 00282 //# Declare extern templates for often used types. 00283 #ifdef AIPS_CXX11 00284 extern template class SubImage<Float>; 00285 extern template class SubImage<Complex>; 00286 #endif 00287 00288 00289 } //# NAMESPACE CASACORE - END 00290 00291 #ifndef CASACORE_NO_AUTO_TEMPLATES 00292 #include <casacore/images/Images/SubImage.tcc> 00293 #endif //# CASACORE_NO_AUTO_TEMPLATES 00294 #endif