00001 //# WCRegion.h: Class to define a region of interest in an image 00002 //# Copyright (C) 1998,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 IMAGES_WCREGION_H 00029 #define IMAGES_WCREGION_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/Containers/Record.h> 00034 #include <casacore/coordinates/Coordinates/CoordinateSystem.h> 00035 #include <casacore/tables/Tables/TableRecord.h> 00036 00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00038 00039 //# Forward Declarations 00040 class LCRegion; 00041 class RecordInterface; 00042 class IPosition; 00043 class String; 00044 00045 00046 // <summary> 00047 // Base class to define world coordinate regions of interest in an image. 00048 // </summary> 00049 00050 // <use visibility=export> 00051 00052 // <reviewed reviewer="" date="" tests=""> 00053 // </reviewed> 00054 // 00055 // <prerequisite> 00056 // <li> <linkto class=LCRegion>LCRegion</linkto> 00057 // </prerequisite> 00058 // 00059 // <synopsis> 00060 // WCRegion is the base class for world coordinate regions. 00061 // The axes in a WCRegion have names (e.g. RA, DEC, FREQ) and 00062 // carry sometimes an associated reference frame with it. 00063 // An WCRegion object is converted to the appropriate 00064 // <linkto class=LCRegion>LCRegion</linkto> object when they 00065 // are used to take a subset from an image. 00066 // LCRegion's are pixel based and are 00067 // used to access the correct pixels in the image. 00068 // The conversion has the following rules: 00069 // <ol> 00070 // <li> All axes of the region must be axes in the image. 00071 // <li> An image axis does not have to be an axis in the region. 00072 // Thus the image can have a higher dimensionality than the region. 00073 // If that is the case, the region is auto-extended to the image's 00074 // dimensionality by using the full range for those axes. 00075 // <li> The order of the axes in region and image do not have to 00076 // be the same. They get reordered as needed. 00077 // </ol> 00078 // </synopsis> 00079 // 00080 // <example> 00081 // <srcblock> 00082 // </srcblock> 00083 // </example> 00084 // 00085 // <motivation> 00086 // User should be able to specify their regions in world coordinates 00087 // as well as lattice coordinates. 00088 // </motivation> 00089 // 00090 //# <todo asof="1997/11/11"> 00091 //# <li> 00092 //# </todo> 00093 00094 00095 class WCRegion 00096 { 00097 public: 00098 WCRegion(); 00099 00100 // Copy constructor (copy semantics). 00101 WCRegion (const WCRegion& other); 00102 00103 // Destructor 00104 virtual ~WCRegion(); 00105 00106 // Comparison 00107 // <group> 00108 virtual Bool operator==(const WCRegion& other) const; 00109 Bool operator!=(const WCRegion& other) const; 00110 // </group> 00111 00112 // Clone a WCRegion object. 00113 virtual WCRegion* cloneRegion() const = 0; 00114 00115 // Return region type. 00116 // Just returns the class name of the derived class. 00117 virtual String type() const = 0; 00118 00119 // Get the dimensionality (i.e. the number of axes). 00120 // Note that usually all axes have a description, but in some cases 00121 // (e.g. WCLELMask) that may not be the case. 00122 // The default implementation returns the number of axes in the 00123 // axes description. 00124 virtual uInt ndim() const; 00125 00126 // Get the description of all axes. 00127 const Record& getAxesDesc() const; 00128 00129 // Get the description of the given axis. 00130 // It is a record containing some fields describing the axis. 00131 const Record& getAxisDesc (uInt axis) const; 00132 00133 // Return the axis number of the description of an axis in the full 00134 // axes description. 00135 // -1 is returned if not found. 00136 Int axisNr (const Record& desc, const Record& axesDesc) const; 00137 00138 // Are both axis descriptions equal? 00139 Bool isAxisDescEqual (const Record& desc1, const Record& desc2) const; 00140 00141 // Can the region extend itself? 00142 // By default it cannot. 00143 virtual Bool canExtend() const; 00144 00145 // Get or set the comment. 00146 // <group> 00147 const String& comment() const; 00148 void setComment (const String& comment); 00149 // </group> 00150 00151 // Convert to an LCRegion using the given new coordinate system and shape. 00152 // An exception is thrown if the region's dimensionality is more 00153 // than the length of the shape vector or if an axis in the region 00154 // is unknown in the new coordinate system.. 00155 // When less, the default implementation extends the region over the 00156 // remaining axes. 00157 // <br>If the region does not need to have coordinates (like WCLELMask) 00158 // the function has to be overridden. 00159 virtual LCRegion* toLCRegion (const CoordinateSystem& cSys, 00160 const IPosition& shape) const; 00161 00162 // Convert to an LCRegion using the given coordinate system and shape. 00163 // This function is meant for internal use by WCCompound objects. 00164 // <br>pixelAxesMap(i) is the axis in cSys and shape for region axis i. 00165 // <br>outOrder(i) is the axis in the output LCRegion for region axis i. 00166 // <br>The length of pixelAxesMap and outOrder is the dimensionality of 00167 // the output LCRegion. It can be more than the dimensionality of this 00168 // WCRegion object. In that case the region gets extended along the 00169 // latter axes. If the region cannot extend itself, this function 00170 // will create an LCExtension object to extend the region. 00171 // <br>Note that initially pixelAxisMap and outOrder are the same, 00172 // but when called for regions in compound regions they may start 00173 // to differ. 00174 LCRegion* toLCRegionAxes (const CoordinateSystem& cSys, 00175 const IPosition& shape, 00176 const IPosition& pixelAxesMap, 00177 const IPosition& outOrder) const; 00178 00179 // Convert the (derived) object to a record. 00180 // The record can be used to make the object persistent. 00181 // The <src>tableName</src> argument can be used by derived 00182 // classes (e.g. LCPagedMask) to put very large objects. 00183 virtual TableRecord toRecord(const String& tableName) const = 0; 00184 00185 // Convert correct object from a record. 00186 static WCRegion* fromRecord (const TableRecord& rec, 00187 const String& tableName); 00188 00189 // Define the type and class name in the record. 00190 void defineRecordFields (RecordInterface& record, 00191 const String& className) const; 00192 00193 protected: 00194 // Assignment (copy semantics) makes only sense for a derived class. 00195 WCRegion& operator= (const WCRegion& other); 00196 00197 // Add an axis with its description. 00198 // An exception is thrown if the axis already exists in this region. 00199 void addAxisDesc (const Record& axisDesc); 00200 00201 // Make a description of a pixel axis in the coordinate system. 00202 Record makeAxisDesc (const CoordinateSystem& cSys, uInt pixelAxis) const; 00203 00204 // Make a description of all pixel axes in the coordinate system 00205 // (in pixel axes order). 00206 Record makeAxesDesc (const CoordinateSystem& cSys) const; 00207 00208 // Convert to an LCRegion using the given coordinate system and shape. 00209 // <br>pixelAxesMap(i) is the axis in cSys and shape for region axis i. 00210 // <br>outOrder(i) is the axis in the output LCRegion for region axis i. 00211 // <br>They always have the same length. 00212 // If the region can extend itself, the length of pixelAxesMap and 00213 // outOrder can be more than the dimensionality of the region. 00214 // The latter axes in them are the extension axes. 00215 virtual LCRegion* doToLCRegion (const CoordinateSystem& cSys, 00216 const IPosition& shape, 00217 const IPosition& pixelAxesMap, 00218 const IPosition& extendAxes) const = 0; 00219 00220 // Convert relative to absolute world as needed 00221 void makeWorldAbsolute (Vector<Double>& world, 00222 const Vector<Int>& absRel, 00223 const CoordinateSystem& cSys, 00224 const IPosition& shape) const; 00225 00226 static void unitInit(); 00227 00228 void checkAxes ( 00229 const IPosition& pixelAxes, 00230 const CoordinateSystem& cSys, 00231 const Vector<String>& quantityUnits 00232 ) const; 00233 00234 static void convertPixel( 00235 Double& pixel, 00236 const Double& value, 00237 const String& unit, 00238 const Int absRel, 00239 const Double refPix, 00240 const Int shape 00241 ); 00242 private: 00243 String itsComment; 00244 Record itsAxesDesc; 00245 }; 00246 00247 00248 inline Bool WCRegion::operator!= (const WCRegion& other) const 00249 { 00250 return (!operator==(other)); 00251 } 00252 inline const String& WCRegion::comment() const 00253 { 00254 return itsComment; 00255 } 00256 inline void WCRegion::setComment (const String& comment) 00257 { 00258 itsComment = comment; 00259 } 00260 inline const Record& WCRegion::getAxesDesc() const 00261 { 00262 return itsAxesDesc; 00263 } 00264 00265 00266 00267 } //# NAMESPACE CASACORE - END 00268 00269 #endif