ImageInfo.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1