Loading...
Searching...
No Matches
MeasFrame.h
Go to the documentation of this file.
//# MeasFrame.h: Container for Measure frame
//# Copyright (C) 1996-2003,2007
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef MEASURES_MEASFRAME_H
#define MEASURES_MEASFRAME_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Arrays/ArrayFwd.h>
#include <casacore/casa/Arrays/Vector.h>
#include <casacore/measures/Measures/CyclicPtr.h>
#include <casacore/measures/Measures/Measure.h>
#include <casacore/casa/iosfwd.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations
class MVEpoch;
class MVPosition;
class MVDirection;
class MVRadialVelocity;
class MeasComet;
class FrameRep;
class MCFrame;
template <class Qtype> class Quantum;
// <summary> Container for Measure frame </summary>
// <use visibility=export>
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tMeasure" demos="">
// </reviewed>
// <prerequisite>
// <li> <linkto class=Measure>Measure</linkto> class
// <li> <linkto class=MeasRef>MeasRef</linkto> class
// </prerequisite>
//
// <etymology>
// From Measure and Frame
// </etymology>
//
// <synopsis>
// Measurements are made in a reference frame (epoch, position, direction,
// ...).
//
// The class is a container for the reference frame Measures (MEpoch etc).
// Since a frame will possibly be used by many different Measures, it behaves
// as a smart pointer, with reference rather than copy characteristics.
// Since it caches all its operations, it is advisable to have a 'global'
// MeasFrame across an execution, resetting (or setting) its values
// when appropriate. The frame can also contain other related information. At
// the moment the orbit of a solar system body (MeasComet) can be set.
// In future the planetary ephemeris used (e.g. DE205) and environmental
// information like refraction data will be added.
//
// A MeasFrame is constructed by setting the appropriate Measures, either in
// a constructor, or with a set(). The input to the constructors and set are
// Measures.
//
// Inside the frames automatic conversion to the most appropriate usage of
// its values is done (e.g. time to TBD time, position to astronomical
// longitude). These conversions are done only if an explicit
// Measure::Convert was used that needed information, e.g. the following
// code:
// <srcblock>
// MeasFrame frame(obser); // obser is an MPosition
// MEpoch::Convert conv(MEpoch(12345), MEpoch::Ref(MEpoch::LAST,obser));
// MEpoch last = conv();
// </srcblock>
// will set-up a state machine to convert UTC(default) to LAST in conv; the
// next call will do the actual conversion. During this conversion, the
// astronomical longitude (among others) will be needed to convert to
// local sidereal time. conv will ask (getLong()) this from the frame, which
// will calculate it (including possible other conversions) from the
// observatory's position specified in a frame. Any calculation done will be
// cached (e.g. a Nutation calculation in this case for dpsi), and used in
// subsequent conversions using the same frame.
//
// Furthermore, a frame will often be regularly updated (e.g. coordinate
// conversion for a series of times). To make use of cached information, and
// to speed up as much as possible, <src>reset...()</src> functions are
// available. These reset functions accept the same range of input parameter
// types as the <linkto class=MeasConvert>MeasConvert</linkto> () operator,
// and will keep any determined conversion machines and related information
// intact, only recalculating whatever is necessary.
//
// The actual frame calculations and interrogations are done in a separate
// <linkto class=MCFrame>MCFrame</linkto> hidden class, which attaches itself
// to MeasFrame when and if necessary (see there if you are really curious).
//
// get...() functions can return frame measures. Only when the frame has been
// attached to a calculating machine *MCFrame) are these values available.
// This attachment is done if the frame has been actively used by a
// Measure::Convert engine, or if explicitly done by the
// <src>MCFrame::make(MeasFrame &)</src> static method.
//
// Because MeasFrame uses a reference to its implementation, which can be shared
// by multiple MeasFrame instances, it is by default not thread safe
// when different MeasFrames are accessed from different threads. Moreover,
// a MeasFrame contains links to other objects which may also be shared.
// In Casacore 3.8, the referenced data entries in this class
// have been changed so they are initialized in thread-safe ways, and thread-safe
// conversions can be achieved by using the independentCopy() method. See
// the help for that function for more info.
//
// <note role=caution> An explicit (or implicit) call to MCFrame::make will
// load the whole conversion machinery (including Tables) into your
// linked module).</note>
//
// <linkto class=Aipsrc>Aipsrc keywords</linkto> can be used for additional
// (highly specialised) additional internal conversion parameters.
// </synopsis>
//
// <example>
// <srcblock>
// MEpoch my_epoch(Quantity(MeasData::MJDB1950,"d")); // an epoch
// MeasFrame frame(my_epoch); // used in a frame
// </srcblock>
// </example>
//
// <motivation>
// To separate the frame definition from the measure type
// </motivation>
//
// <todo asof="1997/04/16">
// </todo>
class MeasFrame {
public:
//# Friends
// Output a frame
friend ostream &operator<<(ostream &os, MeasFrame &mf);
// Machinery
// <group>
friend class MCFrame;
// </group>
//# Enumerations
// Enumeration for the different farme entries possible. This can be used
// to find out if a certain conversion needs the frame. It will be
// used in a registration/notify environment to enable bypassing of
// some new conversion settings.
enum FrameTypes {
EPOCH = 1,
POSITION = 2,
DIRECTION = 4,
VELOCITY = 8,
COMET = 16 };
//# Constructors
// Default constructor
MeasFrame();
// Construct frame with specified measures
// <thrown>
// <li> AipsError if a non-frame Measure
// </thrown>
// <group>
MeasFrame(const Measure &meas1);
MeasFrame(const Measure &meas1, const Measure &meas2);
MeasFrame(const Measure &meas1, const Measure &meas2,
const Measure &meas3);
// </group>
// Copy constructor (reference semantics)
MeasFrame(const MeasFrame &other);
MeasFrame(MeasFrame &&other);
// Copy assignment (reference semantics)
MeasFrame &operator=(const MeasFrame &other);
MeasFrame &operator=(MeasFrame &&other);
// Destructor
~MeasFrame();
//# Operators
// Comparisons
// <group>
Bool operator==(const MeasFrame &other) const;
Bool operator!=(const MeasFrame &other) const;
// </group>
//# General member functions
// Test if empty (i.e. no measure filled in)
Bool empty() const;
// Set frame elements
// <thrown>
// <li> AipsError if a non-frame Measure
// <li> AipsError if illegal or non-existant MeasComet given
// </thrown>
// <group>
void set(const Measure &meas1);
void set(const Measure &meas1, const Measure &meas2);
void set(const Measure &meas1, const Measure &meas2,
const Measure &meas3);
void set(const MeasComet &meas);
// </group>
// Reset a frame element and its cached derived values.
// <thrown>
// <li> AipsError if the specific Measure not yet present in frame
// </thrown>
// <group>
void resetEpoch(Double val);
void resetEpoch(const Vector<Double> &val);
void resetEpoch(const Quantum<Double> &val);
void resetEpoch(const Quantum<Vector<Double> > &val);
void resetEpoch(const MVEpoch &val);
void resetEpoch(const Measure &val);
void resetPosition(const Vector<Double> &val);
void resetPosition(const Quantum<Vector<Double> > &val);
void resetPosition(const MVPosition &val);
void resetPosition(const Measure &val);
void resetDirection(const Vector<Double> &val);
void resetDirection(const Quantum<Vector<Double> > &val);
void resetDirection(const MVDirection &val);
void resetDirection(const Measure &val);
void resetRadialVelocity(const Vector<Double> &val);
void resetRadialVelocity(const Quantum<Vector<Double> > &val);
void resetRadialVelocity(const MVRadialVelocity &val);
void resetRadialVelocity(const Measure &val);
void resetComet(const MeasComet &val);
// </group>
// Get the epoch pointer (0 if not present)
const Measure* epoch() const;
// Get the position pointer (0 if not present)
const Measure* position() const;
// Get the direction pointer (0 if not present)
const Measure* direction() const;
// Get the radial velocity pointer (0 if not present)
const Measure* radialVelocity() const;
// Get the comet pointer (0 if not present)
const MeasComet* comet() const;
// Get data from frame. Only available if appropriate measures are set,
// and the frame is in a calculating state.
// <group>
// Get TDB in days
Bool getTDB(Double &tdb) const;
// Get UT1 in days
Bool getUT1(Double &tdb) const;
// Get TT in days
Bool getTT(Double &tdb) const;
// Get the ITRF longitude (in rad)
Bool getLong(Double &tdb) const;
// Get the ITRF latitude (in rad)
Bool getLat(Double &tdb) const;
// Get the position
Bool getITRF(MVPosition &tdb) const;
// Get the geocentric position (in m)
Bool getRadius(Double &tdb) const;
// Get the geodetic latitude
Bool getLatGeo(Double &tdb) const;
// Get the LAST (in days)
Bool getLAST(Double &tdb) const;
// Get the LAST (in rad)
Bool getLASTr(Double &tdb) const;
// Get J2000 coordinates (direction cosines) and its longitude/latitude (rad)
// <group>
Bool getJ2000(MVDirection &tdb) const;
Bool getJ2000Long(Double &tdb) const;
Bool getJ2000Lat(Double &tdb) const;
// </group>
// Get B1950 coordinates (direction cosines)
// <group>
Bool getB1950(MVDirection &tdb) const;
Bool getB1950Long(Double &tdb) const;
Bool getB1950Lat(Double &tdb) const;
// </group>
// Get apparent coordinates (direction cosines)
// <group>
Bool getApp(MVDirection &tdb) const;
Bool getAppLong(Double &tdb) const;
Bool getAppLat(Double &tdb) const;
// </group>
// Get LSR radial velocity (m/s)
Bool getLSR(Double &tdb) const;
// Get the comet table reference type
Bool getCometType(uInt &tdb) const;
// Get the comet coordinates
Bool getComet(MVPosition &tdb) const;
// </group>
// Make a value copy of this MeasFrame, such that it contains no reference
// to the old MeasFrame data. This is useful for ensuring thread safety in conversions.
//
// This function is available since casacore v3.8.0.
//
// The following is an example of how a thread-safe conversion can be performed:
// <srcblock>
// void convert_example(const MDirection& shared_direction, const MeasFrame& shared_frame) {
// const MeasFrame frame = shared_frame.independentCopy();
// MDirection::Convert converter(MDirection::J2000,
// MDirection::Ref(MDirection::ITRF, frame));
// MDirection result = converter(shared_direction);
// </srcblock>
// The convert_example() function can be called from multiple threads (as long as
// they don't write to shared_direction or shared_frame), and performs a direction conversion
// from J2000 to ITRF. Any information that is shared between the threads is read-only.
MeasFrame independentCopy() const;
private:
//# Data
// Representation of MeasFrame. See the CyclicPtr class documentation for motivation.
details::CyclicPtr<FrameRep> rep;
MeasFrame(details::CyclicPtr<FrameRep> new_rep);
//# Member functions
// Create an instance of the MeasFrame class
void create();
// Fill a MeasFrame element
// <group>
void fill(const Measure *in);
void fill(const MeasComet *in);
// </group>
// Make full Epoch
void makeEpoch();
// Make full Position
void makePosition();
// Make full Direction
void makeDirection();
// Make full RadialVelocity
void makeRadialVelocity();
// Make full Comet
void makeComet();
// Throw reset error
void errorReset(const String &txt);
};
//# Global functions
// <summary> Global functions </summary>
// <group name=Output>
// Output a frame
ostream &operator<<(ostream &os, MeasFrame &mf);
// </group>
} //# NAMESPACE CASACORE - END
#endif
casacore::MCFrame
Definition MCFrame.h:87
casacore::MVDirection
Definition MVDirection.h:105
casacore::MVEpoch
Definition MVEpoch.h:87
casacore::MVPosition
Definition MVPosition.h:111
casacore::MVRadialVelocity
Definition MVRadialVelocity.h:91
casacore::MeasComet
Definition MeasComet.h:103
casacore::MeasFrame
Definition MeasFrame.h:151
casacore::MeasFrame::epoch
const Measure * epoch() const
Get the epoch pointer (0 if not present).
casacore::MeasFrame::getCometType
Bool getCometType(uInt &tdb) const
Get the comet table reference type.
casacore::MeasFrame::resetEpoch
void resetEpoch(const MVEpoch &val)
casacore::MeasFrame::getTDB
Bool getTDB(Double &tdb) const
Get data from frame.
casacore::MeasFrame::resetPosition
void resetPosition(const Quantum< Vector< Double > > &val)
casacore::MeasFrame::resetRadialVelocity
void resetRadialVelocity(const Measure &val)
casacore::MeasFrame::position
const Measure * position() const
Get the position pointer (0 if not present).
casacore::MeasFrame::MeasFrame
MeasFrame(MeasFrame &&other)
casacore::MeasFrame::resetEpoch
void resetEpoch(const Vector< Double > &val)
casacore::MeasFrame::getJ2000Long
Bool getJ2000Long(Double &tdb) const
casacore::MeasFrame::resetDirection
void resetDirection(const Measure &val)
casacore::MeasFrame::resetEpoch
void resetEpoch(const Quantum< Double > &val)
casacore::MeasFrame::resetDirection
void resetDirection(const MVDirection &val)
casacore::MeasFrame::getLat
Bool getLat(Double &tdb) const
Get the ITRF latitude (in rad).
casacore::MeasFrame::MCFrame
friend class MCFrame
Machinery.
Definition MeasFrame.h:160
casacore::MeasFrame::operator=
MeasFrame & operator=(MeasFrame &&other)
casacore::MeasFrame::MeasFrame
MeasFrame(const Measure &meas1)
Construct frame with specified measures.
casacore::MeasFrame::set
void set(const Measure &meas1, const Measure &meas2)
casacore::MeasFrame::makeEpoch
void makeEpoch()
Make full Epoch.
casacore::MeasFrame::resetEpoch
void resetEpoch(Double val)
Reset a frame element and its cached derived values.
casacore::MeasFrame::makeRadialVelocity
void makeRadialVelocity()
Make full RadialVelocity.
casacore::MeasFrame::getUT1
Bool getUT1(Double &tdb) const
Get UT1 in days.
casacore::MeasFrame::MeasFrame
MeasFrame()
Default constructor.
casacore::MeasFrame::resetRadialVelocity
void resetRadialVelocity(const MVRadialVelocity &val)
casacore::MeasFrame::resetEpoch
void resetEpoch(const Quantum< Vector< Double > > &val)
casacore::MeasFrame::getB1950
Bool getB1950(MVDirection &tdb) const
Get B1950 coordinates (direction cosines).
casacore::MeasFrame::direction
const Measure * direction() const
Get the direction pointer (0 if not present).
casacore::MeasFrame::MeasFrame
MeasFrame(details::CyclicPtr< FrameRep > new_rep)
casacore::MeasFrame::resetDirection
void resetDirection(const Vector< Double > &val)
casacore::MeasFrame::resetRadialVelocity
void resetRadialVelocity(const Vector< Double > &val)
casacore::MeasFrame::resetRadialVelocity
void resetRadialVelocity(const Quantum< Vector< Double > > &val)
casacore::MeasFrame::MeasFrame
MeasFrame(const Measure &meas1, const Measure &meas2)
casacore::MeasFrame::getTT
Bool getTT(Double &tdb) const
Get TT in days.
casacore::MeasFrame::makeComet
void makeComet()
Make full Comet.
casacore::MeasFrame::getLAST
Bool getLAST(Double &tdb) const
Get the LAST (in days).
casacore::MeasFrame::FrameTypes
FrameTypes
Enumeration for the different farme entries possible.
Definition MeasFrame.h:168
casacore::MeasFrame::POSITION
@ POSITION
Definition MeasFrame.h:170
casacore::MeasFrame::DIRECTION
@ DIRECTION
Definition MeasFrame.h:171
casacore::MeasFrame::VELOCITY
@ VELOCITY
Definition MeasFrame.h:172
casacore::MeasFrame::COMET
@ COMET
Definition MeasFrame.h:173
casacore::MeasFrame::EPOCH
@ EPOCH
Definition MeasFrame.h:169
casacore::MeasFrame::getLatGeo
Bool getLatGeo(Double &tdb) const
Get the geodetic latitude.
casacore::MeasFrame::getLong
Bool getLong(Double &tdb) const
Get the ITRF longitude (in rad).
casacore::MeasFrame::operator==
Bool operator==(const MeasFrame &other) const
Comparisons.
casacore::MeasFrame::resetEpoch
void resetEpoch(const Measure &val)
casacore::MeasFrame::makeDirection
void makeDirection()
Make full Direction.
casacore::MeasFrame::resetPosition
void resetPosition(const Vector< Double > &val)
casacore::MeasFrame::getB1950Lat
Bool getB1950Lat(Double &tdb) const
casacore::MeasFrame::errorReset
void errorReset(const String &txt)
Throw reset error.
casacore::MeasFrame::MeasFrame
MeasFrame(const Measure &meas1, const Measure &meas2, const Measure &meas3)
casacore::MeasFrame::fill
void fill(const Measure *in)
Fill a MeasFrame element.
casacore::MeasFrame::resetPosition
void resetPosition(const MVPosition &val)
casacore::MeasFrame::getJ2000Lat
Bool getJ2000Lat(Double &tdb) const
casacore::MeasFrame::set
void set(const Measure &meas1, const Measure &meas2, const Measure &meas3)
casacore::MeasFrame::getComet
Bool getComet(MVPosition &tdb) const
Get the comet coordinates.
casacore::MeasFrame::~MeasFrame
~MeasFrame()
Destructor.
casacore::MeasFrame::operator<<
friend ostream & operator<<(ostream &os, MeasFrame &mf)
Output a frame.
casacore::MeasFrame::radialVelocity
const Measure * radialVelocity() const
Get the radial velocity pointer (0 if not present).
casacore::MeasFrame::comet
const MeasComet * comet() const
Get the comet pointer (0 if not present).
casacore::MeasFrame::empty
Bool empty() const
Test if empty (i.e.
casacore::MeasFrame::getAppLat
Bool getAppLat(Double &tdb) const
casacore::MeasFrame::resetComet
void resetComet(const MeasComet &val)
casacore::MeasFrame::resetPosition
void resetPosition(const Measure &val)
casacore::MeasFrame::getJ2000
Bool getJ2000(MVDirection &tdb) const
Get J2000 coordinates (direction cosines) and its longitude/latitude (rad).
casacore::MeasFrame::set
void set(const Measure &meas1)
Set frame elements.
casacore::MeasFrame::makePosition
void makePosition()
Make full Position.
casacore::MeasFrame::operator!=
Bool operator!=(const MeasFrame &other) const
casacore::MeasFrame::MeasFrame
MeasFrame(const MeasFrame &other)
Copy constructor (reference semantics).
casacore::MeasFrame::getRadius
Bool getRadius(Double &tdb) const
Get the geocentric position (in m).
casacore::MeasFrame::fill
void fill(const MeasComet *in)
casacore::MeasFrame::getB1950Long
Bool getB1950Long(Double &tdb) const
casacore::MeasFrame::getAppLong
Bool getAppLong(Double &tdb) const
casacore::MeasFrame::set
void set(const MeasComet &meas)
casacore::MeasFrame::getITRF
Bool getITRF(MVPosition &tdb) const
Get the position.
casacore::MeasFrame::getLSR
Bool getLSR(Double &tdb) const
Get LSR radial velocity (m/s).
casacore::MeasFrame::operator=
MeasFrame & operator=(const MeasFrame &other)
Copy assignment (reference semantics).
casacore::MeasFrame::rep
details::CyclicPtr< FrameRep > rep
Representation of MeasFrame.
Definition MeasFrame.h:328
casacore::MeasFrame::independentCopy
MeasFrame independentCopy() const
Make a value copy of this MeasFrame, such that it contains no reference to the old MeasFrame data.
casacore::MeasFrame::resetDirection
void resetDirection(const Quantum< Vector< Double > > &val)
casacore::MeasFrame::getApp
Bool getApp(MVDirection &tdb) const
Get apparent coordinates (direction cosines).
casacore::MeasFrame::getLASTr
Bool getLASTr(Double &tdb) const
Get the LAST (in rad).
casacore::MeasFrame::create
void create()
Create an instance of the MeasFrame class.
casacore::Measure
Definition Measure.h:232
casacore::Quantum
Definition Quantum.h:269
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::Vector
Definition Vector.h:82
casacore::details::CyclicPtr
A smart pointer class that allows to work with complex cycles without using weak_ptrs.
Definition CyclicPtr.h:78
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::operator<<
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::Double
double Double
Definition aipstype.h:53
casacore::MeasFrame_global_functions_Output
Global functions .
Definition MeasFrame.h:357
casacore::MeasFrame_global_functions_Output::operator<<
ostream & operator<<(ostream &os, MeasFrame &mf)
Output a frame.