casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
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: ImageInfo.h 20491 2009-01-16 08:33:56Z gervandiepen $
00028 
00029 #ifndef IMAGES_IMAGEINFO_H
00030 #define IMAGES_IMAGEINFO_H
00031 
00032 #include <casa/aips.h>
00033 #include <casa/Utilities/RecordTransformable.h>
00034 
00035 #include <casa/Arrays/Vector.h>
00036 #include <casa/Quanta/Quantum.h>
00037 #include <casa/BasicSL/String.h>
00038 
00039 #include <coordinates/Coordinates/CoordinateSystem.h>
00040 
00041 #include <images/Images/ImageBeamSet.h>
00042 
00043 //# Forward declarations
00044 #include <casa/iosfwd.h>
00045 namespace casa { //# NAMESPACE CASA - 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 beam.  Zero-based <src>channel</src>
00129     // and <src>polarization</src> are
00130     // necessary and used if and only if the ImageBeamSet
00131     // has multiple beams. If just a single beam, that beam
00132     // is returned. If no (or a null) beam, a null beam is returned.
00133     // <group>
00134     GaussianBeam restoringBeam(
00135         const Int channel=-1, const Int polarization=-1
00136     ) const;
00137 
00138     // set the single global restoring beam. An exception will be
00139     // thrown if this object already has multiple beams. In that case,
00140     // the caller must call removeRestoringBeam() first.
00141     void setRestoringBeam(const GaussianBeam& beam);
00142 
00143     // Remove all beams (global or per plane) associated with this object.
00144     void removeRestoringBeam();
00145 // </group>
00146 
00147     // This method is not meant for common use. New code should not use it.
00148     // Get the restoring beam from a LoggerHolder (where the history is stored)
00149     // as AIPS writes the beam in the FITS history rather than the header keywords.
00150     // If there is no beam,  False is returned, and the internal state of the object
00151     // is unchanged.
00152     Bool getRestoringBeam (LoggerHolder& logger);
00153 
00154     // Set and get the Image Type.
00155     // <group>
00156     ImageInfo::ImageTypes imageType () const;
00157     ImageInfo& setImageType(ImageTypes type);
00158     static String imageType(ImageInfo::ImageTypes type);
00159     static ImageInfo::ImageTypes imageType(String type);
00160 // </group>
00161 
00162 // Set and get the Image object name
00163 // <group>
00164     String objectName () const;
00165     ImageInfo& setObjectName (const String& object);
00166 // </group>
00167 
00168 // Functions to interconvert between an ImageInfo and a record. These 
00169 // functions are inherited from class
00170 // <linkto class=RecordTransformable>RecordTransformable</linkto>. As new
00171 // fields get added to ImageInfo these functions should be augmented. Missing
00172 // fields should not generate an error to in fromRecord to allow for 
00173 // backwards compatibility - null values should be supplied instead.
00174 // The record field names are: "restoringbeam, imagetype, objectname".
00175 // <group>
00176     virtual Bool toRecord(String& error, RecordInterface& outRecord) const;
00177     virtual Bool fromRecord(String& error, const RecordInterface& inRecord);
00178 // </group>
00179 
00180 // In some circumstances it might be useful to know what the defaults for
00181 // the various values are so you can check if they have been set.
00182 // The default restoring beam is a null vector.
00183 // <group>
00184 //    static GaussianBeam defaultRestoringBeam();
00185     static ImageTypes defaultImageType();
00186     static String defaultObjectName();
00187     static GaussianBeam defaultRestoringBeam();
00188 // </group>
00189 
00190 // Functions to interconvert between an ImageInfo and FITS keywords
00191 // (converted to a Record).    Failure of <src>fromFITS</src>
00192 // should probably not be regarded as fatal as the default ImageInfo
00193 // values are viable.  For each item contained
00194 // in the ImageInfo, an attempt to decode it from FITS is made.
00195 // If any of them fail, False is returned, but it attempts to decode
00196 // them all.  For those that fail an error message is held in <src>error</src> 
00197 // in the order restoring beam, and image type.
00198 // <src>error</src> will be returned of length 0 if the return 
00199 // value is True, else it will be length 2.
00200 // <group>
00201     Bool toFITS(String & error, RecordInterface & outRecord) const;
00202     Bool fromFITS(Vector<String>& error, const RecordInterface & inRecord);
00203 // </group>
00204 
00205 // This function takes an unofficial fitsValue found on the Stokes axis
00206 // and returns the appropriate ImageType.  The idea is that you 
00207 // detect the unofficial value, drop the Stokes axis, and store
00208 // the value as an ImageType in ImageInfo.  Only values pertaining
00209 // to beam, optical depth and spectral index are handled here.  All others
00210 // give back Undefined.  See usage in Image FITS conversion classes.
00211     static ImageInfo::ImageTypes imageTypeFromFITS(Int fitsValue);
00212 
00213 // It might be useful to know what FITS keyword names are used in to/from
00214 // FITS so we can remove them so they won't be used more than once. The
00215 // names are in lower case.
00216     static Vector<String> keywordNamesFITS();
00217 
00218 // Convert the Miriad 'btype' strings to the ImageType.  Some 
00219 // Miriad 'btype's are dealt with in aips++ via the Stokes
00220 // axis (fractional_polarization, polarized_intensity, position_angle)
00221 // and so these will return Undefined.
00222    static ImageInfo::ImageTypes MiriadImageType (const String& type);
00223 
00224    // get the beam set associated with this object
00225    const ImageBeamSet& getBeamSet() const;
00226 
00227     // <group>
00228     // set the beam for a specific plane. A value of <src>channel</src> or <src>stokes</src>
00229     // of less than 0 means that particular coordinate does not exist. Obviously, at least
00230     // one of these must be zero or greater. The only consistency checking that is done is
00231     // to ensure the values of <src>channel</src> and <src>stokes</src> are consistent with
00232     // the size of the beam array
00233     // Additional consistency checks are done when this object is added via
00234     // ImageInterface<T>::setImageInfo().
00235 
00236     void setBeam(
00237         const Int channel, const Int stokes, const Quantity& major,
00238         const Quantity& minor, const Quantity& pa
00239     );
00240 
00241     void setBeam(
00242         const Int channel, const Int stokes, const GaussianBeam& beam
00243     );
00244 
00245     // </group>
00246 
00247     // does this object contain multiple beams?
00248     Bool hasMultipleBeams() const;
00249 
00250     // does this object conain a single beam
00251     Bool hasSingleBeam() const;
00252 
00253     // does this object contain one or more beams?
00254     Bool hasBeam() const;
00255 
00256     // inline const Array<Vector<Quantity> >& getHyperPlaneBeams() const { return _hyperplaneBeams; }
00257 
00258     // <group>
00259     // Number of channels and polarizations in per hyper-plane beam array
00260     uInt nChannels() const;
00261     uInt nStokes() const;
00262     // </group>
00263 
00264     // <group>
00265 
00266     // initialize all per-plane beams to the same value
00267     void setAllBeams(
00268         const uInt nChannels, const uInt nPolarizations,
00269         const GaussianBeam& beam
00270     );
00271     // set the per plane beams array directly. If the dimensionality of <src>beams</src>
00272     // is 1, one <src>hasSpectral</src> or <src>hasPolarization</src> must be True and
00273     // the other False. If the dimensionality of <src>beams</src> is 2,
00274     // <src>hasSpectral</src> and <src>hasPolarization</src> are ignored.
00275     void setBeams(const ImageBeamSet& beams);
00276     // </group>
00277 
00278     Record beamToRecord(const Int channel, const Int stokes) const;
00279 
00280 private:
00281     // Vector<Quantum<Double> > itsRestoringBeam;
00282     ImageBeamSet _beams;
00283     ImageInfo::ImageTypes itsImageType;
00284     String itsObjectName;
00285    //  Array<Vector<Quantum<Double> > > _hyperplaneBeams;
00286    // uInt _nStokes, _nChannels;
00287 // Common copy ctor/assignment operator code.
00288     void copy_other(const ImageInfo &other);
00289 
00290     void _validateChannelStokes(Int& channel, Int& stokes) const;
00291 
00292     // Get the beam for hyper plane for the corresponding channel and/or stokes. If no frequency
00293     // axis, channel should be less than zero, if no polarization axis, stokes should be less
00294     // than zero.
00295     GaussianBeam _getBeam(const Int channel, const Int stokes) const;
00296 
00297     IPosition _beamPosition(
00298         const Int channel, const Int polarization
00299     ) const;
00300 
00301     // determine what the shape of the _beams array should be
00302     void _setUpBeamArray(const uInt nChan, const uInt nStokes);
00303 
00304     // convenience method for getting number of channels and polarizations
00305     // from the beam array
00306     void _getChansAndStokes(uInt& nChannels, uInt& nStokes) const;
00307 
00308     void _setRestoringBeam(const Record& inRecord);
00309 
00310     inline static String _className() {static const String c = "ImageInfo"; return c; }
00311 
00312 };
00313 
00314 // <summary> Global functions </summary>
00315 // <group name=Output>
00316 // Output declaration - useful for debugging.
00317 ostream &operator<<(ostream &os, const ImageInfo &info);
00318 // </group>
00319 
00320 
00321 
00322 } //# NAMESPACE CASA - END
00323 
00324 #endif
00325 
00326 
00327 
00328