00001 //# LCRegion.h: Abstract base class to define a region of interest in lattice coordinates 00002 //# Copyright (C) 1998,1999,2000,2001 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_LCREGION_H 00029 #define LATTICES_LCREGION_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/lattices/Lattices/Lattice.h> 00034 #include <casacore/casa/Arrays/IPosition.h> 00035 #include <casacore/casa/Arrays/Slicer.h> 00036 00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00038 00039 //# Forward Declarations 00040 class TableRecord; 00041 class RecordInterface; 00042 00043 00044 // <summary> 00045 // Abstract base class to define a region of interest in lattice coordinates. 00046 // </summary> 00047 00048 // <use visibility=export> 00049 00050 // <reviewed reviewer="" date="" tests=""> 00051 // </reviewed> 00052 00053 // <prerequisite> 00054 // <li> <linkto class=Slicer>Slicer</linkto> 00055 // </prerequisite> 00056 00057 // <synopsis> 00058 // The LCRegion class is the abstract base class for various types 00059 // of LCRegion's (e.g. <linkto class=LCEllipsoid>LCEllipsoid</linkto>, 00060 // <linkto class=LCBox>LCBox</linkto>). 00061 // It contains the minimal bounding box of the region and, if needed, 00062 // a mask with the same shape as the bounding box. A mask element 00063 // is true if the element is inside the box. 00064 // <p> 00065 // Each LCRegion object must be able to convert itself to and from a record. 00066 // In that way they can be made persistent (in for example a Table). 00067 // <p> 00068 // The LCRegion can be used in several Lattices and Images classes and 00069 // functions to limit the area to operate on. 00070 // </synopsis> 00071 00072 // <example> 00073 // <srcblock> 00074 // </srcblock> 00075 // </example> 00076 00077 // <motivation> 00078 // The Slicer class is too limited as a region, because it can only 00079 // describe a rectangular region. Specialized classes are needed to 00080 // describe arbitrary regions. They need a base class to combine them. 00081 // </motivation> 00082 00083 //# <todo asof="1997/11/11"> 00084 //# <li> 00085 //# </todo> 00086 00087 class LCRegion : public Lattice<Bool> 00088 { 00089 public: 00090 LCRegion(); 00091 00092 // Construct with the lattice shape only. 00093 LCRegion (const IPosition& latticeShape); 00094 00095 // Copy constructor (copy semantics). 00096 LCRegion (const LCRegion& other); 00097 00098 virtual ~LCRegion(); 00099 00100 // Equality 00101 virtual Bool operator== (const LCRegion& other) const; 00102 00103 // Non-equality. Be careful, do not use this anywhere in the derived 00104 // class structure. You must use, e.g., 00105 // <src>if (! LCRegion::operator== (...))</src> 00106 // rather than <src>if (LCRegion::operator!= (...))</src> as the 00107 // latter will invoke an infinite loop. It is ok to use when applying 00108 // to a concrete class object. 00109 Bool operator!= (const LCRegion& other) const; 00110 00111 // Make a copy of the derived object. 00112 // <group> 00113 virtual Lattice<Bool>* clone() const; 00114 virtual LCRegion* cloneRegion() const = 0; 00115 // </group> 00116 00117 // Handle deletion of the region by deleting possible tables. 00118 // The default implementation does nothing. 00119 virtual void handleDelete(); 00120 00121 // Handle renaming the region by renaming possible tables. 00122 // The default implementation does nothing. 00123 virtual void handleRename (const String& newName, Bool overwrite); 00124 00125 // Region type. Returns className() of derived class. 00126 virtual String type() const = 0; 00127 00128 // Get or set the comment. 00129 // <group> 00130 const String& comment() const; 00131 void setComment (const String& comment); 00132 // </group> 00133 00134 // Does the region have a mask? 00135 virtual Bool hasMask() const = 0; 00136 00137 // Construct another LCRegion (for e.g. another lattice) by moving 00138 // this one. It recalculates the bounding box and mask. 00139 // A positive translation value indicates "to right". 00140 // <group> 00141 LCRegion* translate (const IPosition& translateVector) const; 00142 LCRegion* translate (const IPosition& translateVector, 00143 const IPosition& newLatticeShape) const; 00144 LCRegion* translate (const Vector<Float>& translateVector) const; 00145 LCRegion* translate (const Vector<Float>& translateVector, 00146 const IPosition& newLatticeShape) const; 00147 // </group> 00148 00149 // Give the full lattice shape. 00150 const IPosition& latticeShape() const; 00151 00152 // Give the bounding box. 00153 const Slicer& boundingBox() const; 00154 00155 // Expand a slicer or position in the region to the full lattice. 00156 // This converts the positions in the region to positions 00157 // in the entire lattice. 00158 // <group> 00159 Slicer expand (const Slicer& slicer) const; 00160 IPosition expand (const IPosition& index) const; 00161 // </group> 00162 00163 // Convert the (derived) object to a record. 00164 // The record can be used to make the object persistent. 00165 // The <src>tableName</src> argument can be used by derived 00166 // classes (e.g. LCPagedMask) to put very large objects. 00167 virtual TableRecord toRecord (const String& tableName) const = 0; 00168 00169 // Convert correct object from a record. 00170 static LCRegion* fromRecord (const TableRecord&, 00171 const String& tableName); 00172 00173 // Return the dimensionality of the region. 00174 virtual uInt ndim() const; 00175 00176 // Return the shape of the region (i.e. of its bounding box). 00177 virtual IPosition shape() const; 00178 00179 // Usually the lattice (i.e. the region mask) is not writable. 00180 virtual Bool isWritable() const; 00181 00182 // Regions can usually not be put; i.e. no putSlice, etc. can be 00183 // done on their masks. 00184 // Hence LCRegion throws by default an exception for the 00185 // following functions. 00186 // <group> 00187 virtual void doPutSlice (const Array<Bool>& sourceBuffer, 00188 const IPosition& where, 00189 const IPosition& stride); 00190 virtual void set (const Bool& value); 00191 virtual void apply (Bool (*function)(Bool)); 00192 virtual void apply (Bool (*function)(const Bool&)); 00193 virtual void apply (const Functional<Bool,Bool>& function); 00194 virtual void putAt (const Bool& value, const IPosition& where); 00195 virtual void copyData (const Lattice<Bool>& from); 00196 // </group> 00197 00198 protected: 00199 // Assignment (copy semantics) is only useful for derived classes. 00200 LCRegion& operator= (const LCRegion& other); 00201 00202 // Sometimes it is inconvenient for a derived class to set the bounding 00203 // box in the constructor. So it can be set explicitly. 00204 // It fills in the possibly undefined Slicer values. 00205 // It may even be needed to set the lattice shape. 00206 // <group> 00207 void setBoundingBox (const Slicer& boundingBox); 00208 void setShapeAndBoundingBox (const IPosition& latticeShape, 00209 const Slicer& boundingBox); 00210 // </group> 00211 00212 // Do the actual translate in a derived class. 00213 virtual LCRegion* doTranslate (const Vector<Float>& translateVector, 00214 const IPosition& newLatticeShape) const = 0; 00215 00216 // Define the type and class name in the record. 00217 void defineRecordFields (RecordInterface& record, 00218 const String& className) const; 00219 00220 private: 00221 IPosition itsShape; 00222 Slicer itsBoundingBox; 00223 String itsComment; 00224 }; 00225 00226 00227 inline const Slicer& LCRegion::boundingBox() const 00228 { 00229 return itsBoundingBox; 00230 } 00231 inline const IPosition& LCRegion::latticeShape() const 00232 { 00233 return itsShape; 00234 } 00235 inline LCRegion* LCRegion::translate (const IPosition& translateVector) const 00236 { 00237 return translate (translateVector, itsShape); 00238 } 00239 inline LCRegion* LCRegion::translate (const Vector<Float>& translateVector) 00240 const 00241 { 00242 return translate (translateVector, itsShape); 00243 } 00244 inline const String& LCRegion::comment() const 00245 { 00246 return itsComment; 00247 } 00248 inline void LCRegion::setComment (const String& comment) 00249 { 00250 itsComment = comment; 00251 } 00252 00253 inline Bool LCRegion::operator!= (const LCRegion& other) const 00254 // 00255 // Watch out ! You must not, in the derived class structure, 00256 // invoke LCRegion::operator!= If you do, you will be stuck 00257 // in a time warp, as this will just fetch the 00258 // operator== of the concrete class and you start all over again. 00259 // You must use always use !LCRegion::operator==. It is ok in application 00260 // code using the concrete class to say 00261 // if (x != y) where x and y are, say, LCBoxes. 00262 { 00263 return (!operator==(other)); 00264 } 00265 00266 00267 00268 00269 } //# NAMESPACE CASACORE - END 00270 00271 #endif