casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
ObsInfo.h
Go to the documentation of this file.
00001 //# ObsInfo.h: Store miscellaneous information related to an observation
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 //#
00027 //# $Id: ObsInfo.h 20739 2009-09-29 01:15:15Z Malte.Marquarding $
00028 
00029 #ifndef COORDINATES_OBSINFO_H
00030 #define COORDINATES_OBSINFO_H
00031 
00032 #include <casa/aips.h>
00033 #include <casa/Utilities/RecordTransformable.h>
00034 
00035 #include <casa/BasicSL/String.h>
00036 #include <measures/Measures/MEpoch.h>
00037 #include <measures/Measures/MPosition.h>
00038 #include <casa/Quanta/MVDirection.h>
00039 
00040 //# Forward declarations
00041 #include <casa/iosfwd.h>
00042 
00043 namespace casa { //# NAMESPACE CASA - BEGIN
00044 
00045 // <summary>
00046 // Store miscellaneous information related to an observation.
00047 // </summary>
00048 
00049 // <use visibility=export>
00050 
00051 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
00052 // </reviewed>
00053 
00054 // <prerequisite>
00055 //   <li> <linkto class=RecordTransformable>RecordTransformable</linkto>
00056 //   <li> <linkto class=MEpoch>MEpoch</linkto>
00057 // </prerequisite>
00058 //
00059 // <synopsis>
00060 // This class is used to record miscellaneous information about an observation.
00061 // At present it contains the following:
00062 // <ol>
00063 //    <li> Telescope name
00064 //    <li> Observer name
00065 //    <li> Observation date
00066 //    <li> Pointing centre (as distinct from the phase center or tangent point)
00067 // </ol>
00068 // This list can easily be extended if necessary.
00069 //
00070 // This class has functions to interconvert with a record in a "lossless"
00071 // fashion, and to also interconvert between a record that contains a list of
00072 // FITS keywords.
00073 // </synopsis>
00074 //
00075 // <example>
00076 // The interface is a simple get/set interface. Note that the "set" methods
00077 // can be chained together since each set method returns a reference to its
00078 // object (rather like cout).
00079 // <srcblock>
00080 //    ObsInfo oi;
00081 //    oi.setTelescope("VLA").setObserver("Glendenning");
00082 //    ...
00083 //    cout << "The date observed is: " << oi.obsDate() << endl;
00084 // </srcblock>
00085 // </example>
00086 //
00087 // <motivation>
00088 // Record information to allow more full measures conversion, e.g. topo->lsr
00089 // requires observatory location and time. Also record in a typesafe way
00090 // image summary information users are used to from classic AIPS.
00091 // </motivation>
00092 //
00093 // <todo asof="2000/04/20">
00094 //   <li> Nothing known
00095 // </todo>
00096 
00097 class ObsInfo : public RecordTransformable
00098 {
00099 public:
00100 
00101     // Default constructor makes an object where all the 
00102     // parameters are set to their default values (see below)
00103     ObsInfo();
00104 
00105     // Destructor
00106     ~ObsInfo();
00107 
00108     // Copy all fields from "other" to this object. Uses copy semantics.
00109     // <group>
00110     ObsInfo(const ObsInfo &other);
00111     ObsInfo &operator=(const ObsInfo &other);
00112     // </group>
00113 
00114     // Telescope identifier. If this is a "standard" telescope, you should use
00115     // the same name as is available in the Observatories method of class
00116     // <linkto class=MeasTable>MeasTable</linkto>. Defaults to "UNKNOWN".
00117     // <br>
00118     // The telescope position can be set and will be converted to ITRF.
00119     // If the telescope position has not been set explicitly, it will be
00120     // set for a standard telescope found in the MeasTable.
00121     // <group>
00122     String telescope() const;
00123     ObsInfo& setTelescope(const String &telescope);
00124     Bool isTelescopePositionSet() const
00125       { return isTelPositionSet_p; }
00126     const MPosition& telescopePosition() const
00127       { return telPosition_p; }
00128     String telescopePositionString() const;
00129     ObsInfo& setTelescopePosition(const MPosition&);
00130     // </group>
00131 
00132     // The name (or initials) of the observer. Defaults to "UNKNOWN".
00133     // <group>
00134     String observer() const;
00135     ObsInfo& setObserver(const String &observer);
00136     // </group>
00137     
00138     // When was the observation taken (start time)? This is somewhat
00139     // problematical for observations which are taken at multiple
00140     // epochs. You should use the start time of the first sample.
00141     // The default is the MEpoch default: MJD 0 UTC
00142     // <group>
00143     MEpoch obsDate() const;
00144     ObsInfo& setObsDate(const MEpoch &obsDate);
00145     // </group>
00146 
00147     // What was the pointing centre, as distinct from the phase centre ? 
00148     // This value is specified as an MVDirection.
00149     // This means it is you, the callers responsibility, to know what its reference
00150     // type is in order to turn it into an MDirection.
00151     // The default is (0,0) (or [1,0,0]).  After you have called setPointingCenter,
00152     // the function isPointingCenterInitial will return False.
00153     // <group>
00154     MVDirection pointingCenter() const;
00155     ObsInfo& setPointingCenter (const MVDirection& direction);
00156     // </group>
00157     
00158     // Because the default pointing center is a valid value (0,0), this
00159     // function is available to tell you whether the pointing center has
00160     // been set (with setPointingCenter) to some value other than its
00161     // initial (return False)
00162     Bool isPointingCenterInitial () const {return isPointingCenterInitial_p;};
00163 
00164 
00165     // Functions to interconvert between an ObsInfo and a record. These 
00166     // functions are inherited from class
00167     // <linkto class=RecordTransformable>RecordTransformable</linkto>. As new
00168     // fields get added to ObsInfo these functions should be augmented. Missing
00169     // fields should not generate an error to in fromRecord to allow for 
00170     // backwards compatibility - null values should be supplied instead.
00171     // The field names are "observer", "telescope", "obsdate", and
00172     // "pointingcenter"
00173     // <group>
00174     virtual Bool toRecord(String & error, RecordInterface & outRecord) const;
00175     virtual Bool fromRecord(String & error, const RecordInterface & inRecord);
00176     // </group>
00177 
00178     // Functions to interconvert between an ObsInfo and FITS keywords
00179     // (converted to a Record).  For the pointing center, the FITS
00180     // keywords OBSRA and OBSDEC are used.    Failure of <src>fromFITS</src>
00181     // should probably not be regarded as fatal as the default ObsInfo
00182     // values are viable.  For each item contained
00183     // in the ObsInfo, an attempt to decode it from FITS is made.
00184     // If any of them fail, False is returned, but it attempts to decode
00185     // them all.  For those that fail
00186     // an error message is held in <src>error</src> 
00187     // in the order telescope (error(0)), observer (error(1)), date
00188     // (error(2)), pointing center (error(3)).  <src>error</src> will
00189     // be returned of length 0 if the return value is True, else
00190     // it will be length 4.
00191     // <group>
00192     Bool toFITS(String & error, RecordInterface & outRecord) const;
00193     Bool fromFITS(Vector<String>& error, const RecordInterface & inRecord);
00194 
00195     // In some circumstances it might be useful to know what the defaults for
00196     // the various values are so you can check if they have been set.
00197     // <group>
00198     static String defaultTelescope();
00199     static String defaultObserver();
00200     static MEpoch defaultObsDate();
00201     static MVDirection defaultPointingCenter();
00202     // </group>
00203 
00204     // It might be useful to know what FITS keyword names are used in to/from
00205     // FITS so we can remove them so they won't be used more than once. The
00206     // names are in lower case.
00207     static Vector<String> keywordNamesFITS();
00208 
00209 private:
00210     String telescope_p;
00211     String observer_p;
00212     MEpoch obsdate_p;
00213     MPosition telPosition_p;
00214     Bool isTelPositionSet_p;
00215     MVDirection pointingCenter_p;
00216     Bool isPointingCenterInitial_p;    // True when ObsInfo contructed. 
00217                                        // False after setPointingCenter called
00218 
00219 // Common copy ctor/assignment operator code.
00220 
00221     void copy_other(const ObsInfo &other);
00222 };
00223 
00224 // <summary> Global functions </summary>
00225 // <group name=Output>
00226 // Output declaration - useful for debugging.
00227 ostream &operator<<(ostream &os, const ObsInfo &info);
00228 // </group>
00229 
00230 
00231 } //# NAMESPACE CASA - END
00232 
00233 #endif