00001 //# ImageInfo.h: Miscellaneous information related to an image 00002 //# Copyright (C) 1998,1999,2000,2001,2002 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 //# 00027 //# $Id$ 00028 00029 #ifndef IMAGES_IMAGEINFO_H 00030 #define IMAGES_IMAGEINFO_H 00031 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/casa/Utilities/RecordTransformable.h> 00034 00035 #include <casacore/casa/Arrays/Vector.h> 00036 #include <casacore/casa/Quanta/Quantum.h> 00037 #include <casacore/casa/BasicSL/String.h> 00038 00039 #include <casacore/coordinates/Coordinates/CoordinateSystem.h> 00040 00041 #include <casacore/images/Images/ImageBeamSet.h> 00042 00043 //# Forward declarations 00044 #include <casacore/casa/iosfwd.h> 00045 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00046 00047 class LoggerHolder; 00048 00049 // <summary> 00050 // Miscellaneous information related to an image. 00051 // </summary> 00052 00053 // <use visibility=export> 00054 00055 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos=""> 00056 // </reviewed> 00057 00058 // <prerequisite> 00059 // <li> <linkto class=RecordTransformable>RecordTransformable</linkto> 00060 // </prerequisite> 00061 // 00062 // <synopsis> 00063 // This class is used to record information about an image. 00064 // At present it contains the following: 00065 // <ol> 00066 // <li> The restoring beam(s) 00067 // <li> A parameter describing what quantity the image holds. 00068 // <li> The image object name. 00069 // </ol> 00070 // 00071 // Support for per plane (eg channel) dependent beams have been added. 00072 // </synopsis> 00073 // 00074 // <example> 00075 // The interface is a simple get/set interface. Note that the "set" methods 00076 // can be chained together since each set method returns a reference to its 00077 // object (rather like cout). 00078 // <srcblock> 00079 // ImageInfo ii; 00080 // ii.setRestoringBeam(Quantity(30,"arcsec"), Quantity(10,"arcsec"), 00081 // Quantity(-18,"deg")); 00082 // ... 00083 // cout << "The restoring beam is : " << oi.restoringBeam() << endl; 00084 // </srcblock> 00085 // </example> 00086 // 00087 // <motivation> 00088 // This sort of information needed a standard place to go with a 00089 // standard interface so it could be moved out of MiscInfo. 00090 // </motivation> 00091 00092 class ImageInfo : public RecordTransformable 00093 { 00094 public: 00095 00096 // This enum defines the actual quantity being held in an image 00097 // It's really only used for descriptive information. 00098 enum ImageTypes { 00099 Undefined=0, 00100 Intensity, 00101 Beam, 00102 ColumnDensity, 00103 DepolarizationRatio, 00104 KineticTemperature, 00105 MagneticField, 00106 OpticalDepth, 00107 RotationMeasure, 00108 RotationalTemperature, 00109 SpectralIndex, 00110 Velocity, 00111 VelocityDispersion, 00112 nTypes 00113 }; 00114 00115 // Default constructor 00116 00117 ImageInfo(); 00118 00119 // Destructor 00120 ~ImageInfo(); 00121 00122 // Copy constructor (copy semantics) 00123 ImageInfo(const ImageInfo &other); 00124 00125 // Assignment (copy semantics) 00126 ImageInfo &operator=(const ImageInfo &other); 00127 00128 // Set and get the Image Type. 00129 // <group> 00130 ImageInfo::ImageTypes imageType () const; 00131 ImageInfo& setImageType(ImageTypes type); 00132 static String imageType(ImageInfo::ImageTypes type); 00133 static ImageInfo::ImageTypes imageType(String type); 00134 // </group> 00135 00136 // Set and get the Image object name 00137 // <group> 00138 String objectName () const; 00139 ImageInfo& setObjectName (const String& object); 00140 // </group> 00141 00142 // Functions to interconvert between an ImageInfo and a record. These 00143 // functions are inherited from class 00144 // <linkto class=RecordTransformable>RecordTransformable</linkto>. As new 00145 // fields get added to ImageInfo these functions should be augmented. Missing 00146 // fields should not generate an error to in fromRecord to allow for 00147 // backwards compatibility - null values should be supplied instead. 00148 // The record field names are: "restoringbeam, imagetype, objectname". 00149 // <group> 00150 virtual Bool toRecord(String& error, RecordInterface& outRecord) const; 00151 virtual Bool fromRecord(String& error, const RecordInterface& inRecord); 00152 // </group> 00153 00154 // In some circumstances it might be useful to know what the defaults for 00155 // the various values are so you can check if they have been set. 00156 // The default restoring beam is a null vector. 00157 // <group> 00158 static ImageTypes defaultImageType(); 00159 static String defaultObjectName(); 00160 static GaussianBeam defaultRestoringBeam(); 00161 // </group> 00162 00163 // Functions to interconvert between an ImageInfo and FITS keywords 00164 // (converted to a Record). Failure of <src>fromFITS</src> 00165 // should probably not be regarded as fatal as the default ImageInfo 00166 // values are viable. For each item contained 00167 // in the ImageInfo, an attempt to decode it from FITS is made. 00168 // If any of them fail, False is returned, but it attempts to decode 00169 // them all. For those that fail an error message is held in <src>error</src> 00170 // in the order restoring beam, and image type. 00171 // <src>error</src> will be returned of length 0 if the return 00172 // value is True, else it will be length 2. 00173 // <group> 00174 Bool toFITS(String & error, RecordInterface & outRecord) const; 00175 Bool fromFITS(Vector<String>& error, const RecordInterface & inRecord); 00176 // </group> 00177 00178 // This function takes an unofficial fitsValue found on the Stokes axis 00179 // and returns the appropriate ImageType. The idea is that you 00180 // detect the unofficial value, drop the Stokes axis, and store 00181 // the value as an ImageType in ImageInfo. Only values pertaining 00182 // to beam, optical depth and spectral index are handled here. All others 00183 // give back Undefined. See usage in Image FITS conversion classes. 00184 static ImageInfo::ImageTypes imageTypeFromFITS(Int fitsValue); 00185 00186 // It might be useful to know what FITS keyword names are used in to/from 00187 // FITS so we can remove them so they won't be used more than once. The 00188 // names are in lower case. 00189 static Vector<String> keywordNamesFITS(); 00190 00191 // Convert the Miriad 'btype' strings to the ImageType. Some 00192 // Miriad 'btype's are dealt with in Casacore via the Stokes 00193 // axis (fractional_polarization, polarized_intensity, position_angle) 00194 // and so these will return Undefined. 00195 static ImageInfo::ImageTypes MiriadImageType (const String& type); 00196 00197 // Set and get the beam. 00198 // Zero-based <src>channel</src> and <src>stokes</src> are 00199 // necessary and used if and only if the ImageBeamSet 00200 // has multiple beams for such an axis. If just a single beam, that beam 00201 // is returned. If no (or a null) beam, a null beam is returned. 00202 GaussianBeam restoringBeam(Int channel=-1, Int stokes=-1) const; 00203 00204 // Set the single global restoring beam. An exception will be 00205 // thrown if this object already has multiple beams. In that case, 00206 // the caller must call removeRestoringBeam() first. 00207 void setRestoringBeam(const GaussianBeam& beam); 00208 //#/// Added to build casarest with nrao-nov12 00209 void setRestoringBeam(const Quantum<Double>& major, 00210 const Quantum<Double>& minor, 00211 const Quantum<Double>& pa) 00212 { setRestoringBeam (GaussianBeam (major, minor, pa)); } 00213 00214 // Remove all beams (global or per plane) associated with this object. 00215 void removeRestoringBeam(); 00216 00217 // Get the beam set associated with this object 00218 const ImageBeamSet& getBeamSet() const; 00219 00220 // Set the beam for a specific plane. 00221 // A value of <src>channel</src> or <src>stokes</src> of less than 0 00222 // means that particular coordinate does not exist. Obviously, at least 00223 // one of these must be zero or greater. The only consistency checking 00224 // that is done is to ensure the values of <src>channel</src> and 00225 // <src>stokes</src> are consistent with the size of the beam array. 00226 // Additional consistency checks are done when this object is added via 00227 // ImageInterface<T>::setImageInfo(). 00228 // <br>This function cannot be used if no beams have been set via set(All)Beams. 00229 // <group> 00230 void setBeam(Int channel, Int stokes, const Quantity& major, 00231 const Quantity& minor, const Quantity& pa); 00232 00233 void setBeam(Int channel, Int stokes, const GaussianBeam& beam); 00234 // </group> 00235 00236 // does this object contain multiple beams? 00237 Bool hasMultipleBeams() const 00238 { return _beams.hasMultiBeam(); } 00239 00240 // does this object contain a single beam 00241 Bool hasSingleBeam() const 00242 { return _beams.hasSingleBeam(); } 00243 00244 // Does this object contain one or more beams? 00245 Bool hasBeam() const 00246 { return ! _beams.empty(); } 00247 00248 // <group> 00249 // Number of channels and stokes in per hyper-plane beam array 00250 uInt nChannels() const 00251 { return _beams.nchan(); } 00252 uInt nStokes() const 00253 { return _beams.nstokes(); } 00254 // </group> 00255 00256 // <group> 00257 // Initialize all per-plane beams to the same value 00258 void setAllBeams( 00259 const uInt nChannels, const uInt nStokes, 00260 const GaussianBeam& beam 00261 ); 00262 00263 // Set the per plane beams array directly. 00264 void setBeams(const ImageBeamSet& beams); 00265 // </group> 00266 00267 // This method is not meant for common use. New code should not use it. 00268 // Get the restoring beam from a LoggerHolder (where the history is stored) 00269 // as AIPS writes the beam in the FITS history rather than the header 00270 // keywords. If there is no beam, False is returned, and the internal 00271 // state of the object is unchanged. 00272 Bool getRestoringBeam (LoggerHolder& logger); 00273 00274 // Convert the given beam to a Record. 00275 Record beamToRecord(Int channel, Int stokes) const; 00276 00277 // Check if the beam set matches the coordinate axes sizes. 00278 void checkBeamSet (const CoordinateSystem& coords, 00279 const IPosition& shape, 00280 const String& imageName) const; 00281 00282 // Append the other beamset to this one. 00283 void appendBeams (ImageInfo& infoThat, 00284 Int axis, Bool relax, LogIO& os, 00285 const CoordinateSystem& csysThis, 00286 const CoordinateSystem& csysThat, 00287 const IPosition& shapeThis, 00288 const IPosition& shapeThat); 00289 00290 // Check if the beam shape matches the coordinates. 00291 void checkBeamShape (uInt& nchan, uInt& npol, 00292 const ImageInfo& info, 00293 const IPosition& shape, 00294 const CoordinateSystem& csys) const; 00295 00296 // Combine beam sets for the concatenation of images and replace 00297 // the beamset in this object by the result. 00298 // If channel or stokes is the concatenation axis, that beam axis 00299 // is concatenated. Otherwise it is checked if both beam sets 00300 // match and are merged. 00301 // If relax=False, an exception is thrown if mismatching. 00302 void combineBeams (const ImageInfo& infoThat, 00303 const IPosition& shapeThis, 00304 const IPosition& shapeThat, 00305 const CoordinateSystem& csysThis, 00306 const CoordinateSystem& csysThat, 00307 Int axis, 00308 Bool relax, 00309 LogIO& os); 00310 00311 // Concatenate the beam sets along the frequency axis. 00312 void concatFreqBeams (ImageBeamSet& beamsOut, 00313 const ImageInfo& infoThat, 00314 Int nchanThis, 00315 Int nchanThat, 00316 Bool relax, 00317 LogIO& os) const; 00318 00319 // Concatenate the beam sets along the stokes axis. 00320 void concatPolBeams (ImageBeamSet& beamsOut, 00321 const ImageInfo& infoThat, 00322 Int npolThis, 00323 Int npolThat, 00324 Bool relax, 00325 LogIO& os) const; 00326 00327 // Merge the beam sets and check if they match. 00328 void mergeBeams (ImageBeamSet& beamsOut, 00329 const ImageInfo& infoThat, 00330 Bool relax, 00331 LogIO& os) const; 00332 00333 // If relax=True, give a warning message if warn=True and set to False. 00334 // Otherwise give an error showing msg1 only. 00335 static void logMessage(Bool& warn, LogIO& os, Bool relax, 00336 const String& msg1, const String msg2=String()); 00337 00338 // Get the beam area in terms of pixel size of the specified 00339 // DirectionCoordinate 00340 Double getBeamAreaInPixels(Int channel, Int stokes, 00341 const DirectionCoordinate&) const; 00342 00343 static Double getBeamAreaInPixels( 00344 const GaussianBeam& beam, const DirectionCoordinate& dc 00345 ); 00346 00347 private: 00348 // Common copy ctor/assignment operator code. 00349 void copy_other(const ImageInfo &other); 00350 00351 // Set the restoring beam from the record. 00352 void _setRestoringBeam(const Record& inRecord); 00353 00354 //# Data members 00355 ImageBeamSet _beams; 00356 mutable Bool _warnBeam; //# tell if warning is already given 00357 ImageTypes itsImageType; 00358 String itsObjectName; 00359 }; 00360 00361 // <summary> Global functions </summary> 00362 // <group name=Output> 00363 // Output declaration - useful for debugging. 00364 ostream &operator<<(ostream &os, const ImageInfo &info); 00365 // </group> 00366 00367 00368 00369 } //# NAMESPACE CASACORE - END 00370 00371 #endif