Physical quantities within reference frame. More...

#include <Measure.h>

Inheritance diagram for casacore::Measure:

Public Types
enum	Types { N_Types, DEFAULT }
	Each derived class should have a `Types` enumeration, specifying the recognised frame types. More...

typedef void *	Convert
	Each Measure should have typedefs of the form: More...

Public Member Functions
virtual	~Measure ()
	Destructor. More...

virtual void	set (const MeasValue &dt)=0
	Each Measure should have the following set functions (with appropiate MVs and Ref): More...

virtual Bool	putValue (const Vector< Quantum< Double > > &in)=0

virtual Bool	setOffset (const Measure &in)=0
	Set the offset in the reference (False if non-matching Measure) More...

virtual Bool	areYou (const String &tp) const =0
	Check the type of derived Measure entity (e.g. More...

virtual void	assured (const String &tp) const =0
	All should have: Assert that we are the correct Measure type. More...

virtual const String &	tellMe () const =0
	Tell me your Measure type (e.g. More...

virtual String	getRefString () const =0
	Each Measure should have the following static methods to give its name (e.g. More...

virtual Bool	isModel () const
	Tell me if you are a pure model (e.g. More...

void	dummy_giveMe () const
	Each derived class should have a string-to-code translation routine for the reference type. More...

virtual Bool	setRefString (const String &in)=0
	Set the reference type to the specified String. More...

virtual const String &	getDefaultType () const =0
	Get the default reference type. More...

virtual const String *	allTypes (Int &nall, Int &nextra, const uInt *&typ) const
	Get a list of all known reference codes. More...

virtual void	checkTypes () const =0
	Check if all internal tables of types (both enum and String) are complete and correct. More...

void	dummy_getRef () const
	Each class should have a function to return its reference: More...

void	dummy_getValue () const
	Each derived class should be able to get its internal value and have: More...

virtual const Unit &	getUnit () const =0
	Get unit (only available if Measure generated from a Quantum, else "") More...

virtual const MeasValue *	getData () const =0
	Get data pointer (used by MeasConvert) More...

virtual MRBase *	getRefPtr () const =0
	Get general reference pointer. More...

virtual void	print (std::ostream &os) const =0
	Print a Measure. More...

virtual Measure *	clone () const =0
	Create a copy. More...

Static Public Member Functions
static uInt	giveMe (const String &in, Int N_name, const String tname[])
	A general string checking routine to be used in derived measures. More...

Private Member Functions
void	dummy_data () const
	Each class will have the following information: Actual data. More...

virtual void	clear ()=0
	Clear the measure. More...

Friends
std::ostream &	operator<< (std::ostream &os, const Measure &meas)
	Each derived class should have: More...

Detailed Description

Physical quantities within reference frame.

Intended use:

Public interface

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25
Test programs:: tMeasure

Prerequisite

Measures module description
Quantum dimensioned values
MeasValue internal measure values
MeasRef class to specify reference frame
MeasConvert class, doing actual conversions of a measure from one reference frame to another
Some classes if you really want to understand details:
- MeasBase class, the immediate parent of all specific Measures
- MCBase class, the base class for all specific conversion routines (like MCEpoch).
- MeasData class, containing a set of generally usable constants, and all program data necessary for conversions.
MeasTab;e class, containing the interface for external Tables (like leap-seconds, IERS data, JPL data).

Etymology

Synopsis

Measure forms the abstract base class for physical quantities within a reference frame. Examples of derived classes are:

MEpoch : a moment in time
MDirection : a direction in space
MPosition : a position on Earth
MFrequency : wave characteristics
MRadialVelocity : a space radial velocity
MDoppler : a Doppler velocity

Measure is the generic name for the more specific instances like, e.g., MEpoch, an instant in time.
A Measure has both a value (specified in some value internal to the specific Measure, in general called MVMeasure (e.g. MVEpoch)), see MeasValue for general details; and a reference type and frame specifier (see MeasRef class).
The MeasRef specifies the reference type of the value, e.g. TAI, UTC, LAST. In addition the MeasRef specifies a possible offset (e.g. the beginning of the year, or today), and, if necessary, Measures necessary for defining the absolute quantity (e.g. an MPosition on Earth for LAST), using a reference frame specifier (see MeasFrame class).
The MeasRef class is templated, but typedefs exist (and should be used) to easily specify the correct one, e.g. MEpoch::Ref.
A Measure can be converted from one reference frame to another (e.g. an MDirection can be converted from J2000 to apparent coordinates) by setting up a measure specific conversion engine (see MeasConvert class and below). From an input MeasRef frame and an output MeasRef frame it constructs a conversion functional, that can be fed values (with the () operator).
Some conversions can, in addition to the main type (like TAI), specify details to completely describe any conversion process (e.g. the type of nutation calculation) by specifying Aipsrc keyword/value pairs.

Measures can in general be constructed from a MeasRef and a value. The value can be expressed in the internally used units (e.g. MVEpoch for MEpoch, MVDirection for MDirection), or as a Quantum, i.e. a value with a dimension (e.g. (20,"km/s")) (see Quantum class). The preferred way of construction is by using the constructor:

Measure(MVmeasure, Measure::Ref)

where the reference can be omitted, defaulting to Measure::DEFAULT), or in simple cases (not needing additional frame information) be specified directly as a code (e.g. MEpoch::IAT).

The value of the Measure can be obtained by a variety of get functions, returning in general internal or Quantum values. The preferred way is a getValue(void), which returns the specific MVmeasure value, which can then be further formatted using the appropiate MVmeasure get() functions.
Special formatting (like hh:mm:ss.t, dd.mm.ss.t, yy/mm/dd etc) are catered for in conversion-type classes like MVAngle, MVTime.

Conversion (within a Measure type) from one reference frame to another is done by the MeasConvert class. The class is templated, but has typedefs Measure::Convert (e.g. MEpoch::Convert) for easy, and recommended, reference.
The basic constructors for a Measure::Convert are:

// With a default Measure included
Measure::Convert(Measure val, Measure::Ref outref);
// With only input and output reference frames given 
Mesaure::Convert(Measure::Ref inref, Measure::Ref outref);

The val is used as a model for subsequent input values into this conversion engine, including possible units; the outref specifies the output reference frame wanted. The constructor analyses the conversion wanted, and sets up a vector of routine calls to be called in sequence for the conversion. The actual conversion is done by the () operator.
To aid in using the raw measures, each class has also a Measure::MVType and Measure::MCType defined. They denote respectively the Measure Value class of the internal value, and the class with conversion routines.

Tip: In the member description a number of dummy routines are present; They are the only way I have found to get cxx2html to get the belonging text properly present;

Example

#include <casacore/measures/Measures.h>
#include <casacore/casa/Measure/MEpoch.h>
// Example is only to show what can be done, not the easiest way
// Set up a simple reference (no offset or secondary Measures). It
// indicates that times are given in MJD TAI.
MEpoch::Ref reftai(MEpoch::TAI);
// Same, but indicating MJD UTC
MEpoch::Ref refutc(MEpoch::UTC);
// Set up an MEpoch (note that no reference is given. In that case a
// default is assumed (for MEpoch UTC). MJD2000 is a provided constant
// of the MJD at 2000.0
MEpoch UTCval(Quantity(MeasData::MJD2000, "d"), reftai);
// Set up, just for fun, an epoch, UTC for B1950.0:
MEpoch val1950(Quantity(MeasData::MJDB1950, "d"));
// and use it as an offset in a reference
MEpoch::Ref ref1950(MEpoch::TAI, val1950);
// An epoch for J2000 with an offset of B1950.0 will than be
MEpoch val20_50(Quantity(MeasData::MJD2000-MeasData::MJDB1950, "d"),
ref1950);
// Set up conversion from TAI(with values in days w.r.t. B1950.0) to UTC:
MEpoch::Convert tai_to_utc(val20_50, refutc);
// And convert a value (in this case the value in val20_50, the model)
// from TAI(relative to B1950.0) to 'absolute' UTC
MEpoch result = tai_to_utc();
//   Show result
cout << "Result 1: " << result << endl;
// To convert 10 years since B1950.0
result = tai_to_utc(Quantity(10.,"a"));
cout << "Result 2: " << result << endl;
// To convert any value in years(the last used units of the model) since B1950.0
result = tai_to_utc(12.3);
cout << "Result 3: " << result << endl;

Which generates the output:

Result 1: Epoch: 51544::11:59:25.2154
Result 2: Epoch: 36934::10:09:42.1283
Result 3: Epoch: 37774::11:57:41.1085

Motivation

To be able to specify a physical entity absolutely in any reference frame; and to be able to convert from one frame to another. E.g. Local Sidereal Time to Temps Atomic International. A templated version for the MeasRef and MeasConvert was chosen to be able to check most arguments at compile time.

To Do

more Measures, e.g. MPlanet
operators on Measures (e.g. MEpoch - MEpoch == MDuration)

Definition at line 235 of file Measure.h.

Member Typedef Documentation

typedef void* casacore::Measure::Convert

Each Measure should have typedefs of the form:

typedef MeasConvert<class a_Measure, class its_MV, its_MC> Convert;

typedef MeasRef<class a_Measure> Ref;

Dummy for cxx2html

Definition at line 263 of file Measure.h.

Member Enumeration Documentation

enum casacore::Measure::Types

Each derived class should have a Types enumeration, specifying the recognised frame types.

It is formatted as:

 enum Types {
 CODE1,
 CODE2,
...,
 N_Types,       // Number of types
 SPEC1 = n,     // Possible special manipulator code
.....,
 SYNONYM1 = CODEn,  // Probable synonyms
....,
 DEFAULT = CODEm};

Dummy for cxx2html

Enumerator
N_Types
DEFAULT

Definition at line 254 of file Measure.h.

Constructor & Destructor Documentation

virtual casacore::Measure::~Measure ( )

virtual

Destructor.

Member Function Documentation

virtual const String* casacore::Measure::allTypes	(	Int &	nall,
		Int &	nextra,
		const uInt *&	typ
	)		const

virtual

Get a list of all known reference codes.

nall returns the number in list, nextra the number of specials (like planets) that should be at end of list). typ returns the list of corresponding types. All should have

static const String* allMyTypes(Int &nall, Int &nextra,

const uInt *&typ);

Reimplemented in casacore::MDirection, casacore::MFrequency, casacore::MEarthMagnetic, casacore::MRadialVelocity, casacore::Muvw, casacore::MDoppler, casacore::MEpoch, casacore::MBaseline, and casacore::MPosition.

virtual Bool casacore::Measure::areYou ( const String & tp ) const

pure virtual

Check the type of derived Measure entity (e.g.

"Epoch")

virtual void casacore::Measure::assured ( const String & tp ) const

pure virtual

All should have: Assert that we are the correct Measure type.

Thrown Exceptions

AipsError if wrong Measure type

Each Measure should have: static void assure(const Measure &in);

virtual void casacore::Measure::checkTypes ( ) const

pure virtual

Check if all internal tables of types (both enum and String) are

complete and correct.

This function is called automatically if and when necessary.

Thrown Exceptions

AipsError if a (programming) error in the types.

All should have

static void checkMyTypes();

Implemented in casacore::MDirection, casacore::MFrequency, casacore::MEarthMagnetic, casacore::MRadialVelocity, casacore::Muvw, casacore::MDoppler, casacore::MEpoch, casacore::MBaseline, and casacore::MPosition.

virtual void casacore::Measure::clear ( )

privatepure virtual

Clear the measure.

virtual Measure* casacore::Measure::clone ( ) const

pure virtual

Create a copy.

Implemented in casacore::MDirection, casacore::MFrequency, casacore::MRadialVelocity, casacore::MEarthMagnetic, casacore::Muvw, casacore::MDoppler, casacore::MEpoch, casacore::MBaseline, and casacore::MPosition.

void casacore::Measure::dummy_data ( ) const

inlineprivate

Each class will have the following information: Actual data.

MVmeasure data;

Reference frame data

MeasRef<Measure> ref;

Possible input units

Unit unit;

And maybe later (or somewhere else)

MeasErr error;

Dummy for cxx2html

Definition at line 443 of file Measure.h.

void casacore::Measure::dummy_getRef ( ) const

inline

Each class should have a function to return its reference:

Measure::Ref getRef() const;

Dummy for cxx2html

Definition at line 385 of file Measure.h.

void casacore::Measure::dummy_getValue ( ) const

inline

Each derived class should be able to get its internal value and have:

const MVmeasure &getValue() const;

To get dimensioned data, each derived class should contain the appropiate one of:

Quantity get(const Unit &unit) const;

Quantum<Vector<Double> > get(const Unit &unit) const;

Definition at line 399 of file Measure.h.

void casacore::Measure::dummy_giveMe ( ) const

inline

Each derived class should have a string-to-code translation routine for the reference type.

The routine returns False if unknown String (and a default mr), else an appropiate mr reference.

Bool giveMe(Measure::Ref &mr, const String &in);

static Bool getType(Measure::Types &tp, const String &in);

Dummy for cxx2html

Definition at line 337 of file Measure.h.

virtual const MeasValue* casacore::Measure::getData ( ) const

pure virtual

Get data pointer (used by MeasConvert)

virtual const String& casacore::Measure::getDefaultType ( ) const

pure virtual

Get the default reference type.

Implemented in casacore::MDirection, casacore::MFrequency, casacore::MEarthMagnetic, casacore::MRadialVelocity, casacore::Muvw, casacore::MDoppler, casacore::MEpoch, casacore::MBaseline, and casacore::MPosition.

virtual MRBase* casacore::Measure::getRefPtr ( ) const

pure virtual

Get general reference pointer.

virtual String casacore::Measure::getRefString ( ) const

pure virtual

Each Measure should have the following static methods to give its name (e.g.

Epoch) or reference type (e.g. UTC):

// Show the Measure type (e.g. "Direction")
static const String &showMe();
// Cast an integer to the appropriate reference type. Avaialable to provide
// a safe cast in cases where Measure type is not explicitly known.
static Measure::Types castType(uInt tp);
// Show the reference type (e.g. MEpoch::showType(MEpoch::IAT) == "TAI")
static const String &showType(uInt tp);
static const String &showType(Measure::Types tp);

Implemented in casacore::MDirection, casacore::MFrequency, casacore::MEarthMagnetic, casacore::MRadialVelocity, casacore::Muvw, casacore::MDoppler, casacore::MEpoch, casacore::MBaseline, and casacore::MPosition.

virtual const Unit& casacore::Measure::getUnit ( ) const

pure virtual

Get unit (only available if Measure generated from a Quantum, else "")

static uInt casacore::Measure::giveMe	(	const String &	in,
		Int	N_name,
		const String	tname[]
	)

static

A general string checking routine to be used in derived measures.

Its arguments are the string to be converted (in), an array of strings to check against (tname), and its length (N_name). The check is case insensitive and mini-max. A return value less than N_name indicates success.

virtual Bool casacore::Measure::isModel ( ) const

virtual

Tell me if you are a pure model (e.g.

a planet)

Reimplemented in casacore::MDirection, and casacore::MEarthMagnetic.

virtual void casacore::Measure::print ( std::ostream & os ) const

pure virtual

Print a Measure.

virtual Bool casacore::Measure::putValue ( const Vector< Quantum< Double > > & in )

pure virtual

virtual void casacore::Measure::set ( const MeasValue & dt )

pure virtual

Each Measure should have the following set functions (with appropiate MVs and Ref):

void set(const MVmeasure &dt);
void set(const Measure::Ref &rf);
void set(const MVmeasure &dt, const Measure::Ref &rf);

virtual Bool casacore::Measure::setOffset ( const Measure & in )

pure virtual

Set the offset in the reference (False if non-matching Measure)

Implemented in casacore::MDirection, casacore::MFrequency, casacore::MEarthMagnetic, casacore::MRadialVelocity, casacore::Muvw, casacore::MDoppler, casacore::MEpoch, casacore::MBaseline, and casacore::MPosition.

virtual Bool casacore::Measure::setRefString ( const String & in )

pure virtual

Set the reference type to the specified String.

False if illegal string, reference set to DEFAULT.

Implemented in casacore::MDirection, casacore::MFrequency, casacore::MEarthMagnetic, casacore::MRadialVelocity, casacore::Muvw, casacore::MDoppler, casacore::MEpoch, casacore::MBaseline, and casacore::MPosition.

virtual const String& casacore::Measure::tellMe ( ) const

pure virtual

Tell me your Measure type (e.g.

"Epoch")

Implemented in casacore::MDirection, casacore::MFrequency, casacore::MEarthMagnetic, casacore::MRadialVelocity, casacore::Muvw, casacore::MDoppler, casacore::MEpoch, casacore::MBaseline, and casacore::MPosition.

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	os,
		const Measure &	meas
	)

friend

Each derived class should have:

friend class MeasConvert<a_Measure, its_MV, its_MC>;

Output a Measure

The documentation for this class was generated from the following file:

measures/Measures/Measure.h

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Friends

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Example

Motivation

To Do

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Thrown Exceptions

Thrown Exceptions

Friends And Related Function Documentation