Module Measures

Changes made in the current development cycle can be found in the changelog.

Description (classes)

a module for coordinates

Prerequisite

Etymology

The name Measure derives from physical measurements, i.e. values with units and possibly a reference frame attached.

Synopsis

The Measure model deals with measures (i.e. quantities with a reference frame). Measures are handled in the Measure section (see Measure.h).

Includes

Including the measures/Measures.h will take care of all includes necessary for the handling of Units and Quantities, and the general Measure interface. For the use of individual Measures, the appropiate include files should be added. E.g. to be able to handle Directions, the following includes could be given:
	#include <measures/Measures.h>
	#include <measures/Measures/MDirection.h>
An inclusion of the appropiate measure file, will also take care of the connected measure value (in this case MVDirection). However, if only the value suffices, it can be included on its own (from the Quanta directory).
When doing actual conversions (see MeasConvert later on), by using the explicit Measure::Convert types, the description of the actual conversions (called MCmeasure, e.g. MCEpoch.h) should be included as well; in adition to general MeasConvert.h.

Measures

Measures are physical quantities within a certain reference frame. Examples are the Hour-angle and Declination of a source at a certain time and observatory; an Ra/Dec for a certain mean epoch; an apparent frequency at a certain time given in eV; a local sidereal time at an observatory.
Measures can be converted from one reference frame to another (and this possibility is its main reason for existence). A simple B1950-J2000 coordinate conversion example:

  cout <<       		// output
				// the conversion of a B1950 direction
	MDirection::Convert( MDirection( Quantity( 20, "deg"),
				         Quantity(-10, "deg"),
					 MDirection::Ref( MDirection::B1950)),
				// to J2000
			     MDirection::Ref( MDirection::J2000)) () 
				// where the constructor sets up a conversion
				// engine, and the operator() converts
		<< endl;
or converting an UTC to a local apparent sidereal time:
  // Set up the model for the input (default reference is UTC)
	MEpoch model (	Quantity(0., "d"));
  // Set up the frame with the observatory position
	MPosition obs(	MVPosition(	Quantity( 10, "m"),
					Quantity( -6, "deg"),
					Quantity( 50, "deg")),
			MPosition::Ref(MPosition::WGS84));
	Measframe frame( obs);
  // Set up the output reference
	MEpoch::Ref outref(	MEpoch::LAST,
				frame);
  // Set up conversion
	MEpoch::Convert	toLST(	model,
				outref);
  // Output a series of sidereal times (formatted in ddd::hh:mm:ss)
	for (Double d = 12345; d<12346; d += 0.1) {
	  cout << "Converted from UTC to LAST: " <<
		d <<  " : " <<
		toLST(d).getValue() << endl;
	};

The examples show the use of the 5 major classes involved in Measures:

   Base         Example               Description
  ------       ---------             -------------
  Measure      MEpoch          has a value and a  reference
  MeasValue    MVEpoch         value
  MeasRef      MEpoch::Ref     contains type, frame, offset
  MeasFrame    MeasFrame       contains Measures describing frame
  MeasConvert  MEpoch::Convert contains conversion information and engine

Each type of Measure has its own distinct class. Each is (weakly) derived from the Measure base class, and its name starts with an M. Examples are:

Others are being, or could be, considered.
TipThe current set can be deduced from the class list at the end of the html version of this module description.

The main role of the Measure (and related) classes is to be able to convert an observed (or to be calculated) physical entity from one reference frame to another, e.g. a J2000 coordinate to galactic coordinates, or an TAI time to a local sidereal time (LAST). Simple unit conversions (e.g. an angle from mrad to deg), or calculations with values with attached units, are sufficiently catered for by the Quanta module classes.

Each measure has a value (MeasValue) and a reference (MeasRef).
The values are in general measure specific, weakly derived from MeasValue, and named with an initial MV. Examples are:

MeasValue and the MV classes can be found in the Quanta module. In addition some other value classes, not directly used in measures, are available. Examples: References are measure specific. Each specific reference class is called Measure::Ref (e.g. MEpoch::Ref). It specifies the full reference frame of the specific measure, i.e. its type, an optional frame of measures (a MeasFrame, consisting of say a time and position), and an optional offset. It has at least a reference code (e.g. MDirection::B1950, MEpoch::LAST), with defaults for each measure (i.e. MDirection::J2000, MEpoch::UTC) if none specified.
In addition the reference can contain a reference frame (MeasFrame) to specify from when and/or where the measure was obtained or calculated.
A third optional element of the reference is an offset measure, which indicates the offset (e.g. a sidereal date) that has to be added to the value referenced before it is used.
Examples of some measures are:
	// An instance of time expressed in days (MJD) in UTC
	MEpoch date(MVEpoch(Quantity(50237.29, "d")),
		    MEpoch::Ref(MEpoch::UTC));
	// which could also be expressed as:
	MEpoch date(Quantity(50237.29, "d"),
		    MEpoch::UTC);
	// or using the default reference type:
	MEpoch date(Quantity(50237.29, "d"));
	// or as a time with an offset to a specific date:
	MEpoch date(Quantity(12.3, "h"),		// time
		    MEpoch::Ref(MEpoch::UTC,		// reference with
		    		MEpoch(Quantity(50237, "d"))));  // offset
	// A position of a telescope
	MPosition pos(MVPosition(Quantity(25, "m"),	// height
				 Quantity(20, "deg"),	// East longitude
				 Quantity(53, "deg")),	// lattitude
		      MPosition::WGS84);		// reference type
	// Use this position in a frame
	MeasFrame frame(pos);
	// Specify an LAST (in MGSD) observed at this position:
	MEpoch last(Quantity(51000.234, "d"),		// time and date
		    MEpoch::Ref(MEpoch::LAST,		// indicate LAST
				frame));		// and where observed
	// Maybe we know the MJD of the observed sidereal time,
	// but not its sidereal date. We could then specify it as an
	// offset to the beginning of the sidereal day in progress at
	// specified UTC
	MEpoch last(Quantity(13.45, "h"),		// time
		    MEpoch::Ref(MEpoch::LAST,		// indicate LAST
				frame,			// where observed
				MEpoch(51234,		// MJD of today
				       MEpoch::Ref(MEpoch::TAI + MEpoch::RAZE)));
	// where the RAZE indicates that the value will be truncated after
	// conversion. In this case it will be converted to LAST to be able
	// to add it as an offset to the specified LAST
	//
	// A direction (in RA/Dec) could be:
	MDirection coord(MVDirection(Quantity(54, "deg"),	// RA
				     Quantity(2034, "'")),	// DEC arcmin
			 MDirection::Ref(MDirection::J2000));	// J2000 type
	// If it were apparent coordinates, the time when observed should
	// have been known. We could just add it to the frame defined above,
	// and use it:
	frame.set(date);				// add time to frame
	MDirection acoord(MVDirection(Quantity(54, "deg"),	// RA
				      Quantity(2034, "'")),	// DEC
			  MDirection::Ref(MDirection::APP,	// apparent type
					  frame));		// and when
	// If it was given in HA/Dec, the position should have been known
	// as well, but it is already in the frame, hence we could say:
	MDirection acoord(MVDirection(Quantity(54, "deg"),	// HA
				      Quantity(2034, "'")),	// DEC
			  MDirection::Ref(MDirection::HADEC,	// type
					  frame));		// when/where
TipIn the above examples in general explicit MV values have been used to specified the measure's value. In many cases (depending on the actual measure) it can be omitted, and the data can be given directly to the measure constructor. See the constructors for the individual measures for details.
If the reference is simple (i.e. no frame and/or offset) the Measure::Ref can be omitted, and only the code has to be specified.
A MeasFrame is a container for specifying Measures needed to describe the circumstances under which the measure was observed (or for which it has to be calculated). E.g. the position on Earth (an MPosition) is necessary for sidereal time and coordinates like HA/Dec and Az/El; the time (MEpoch) is necessary for non-standard coordinates (apparent, mean, HA/Dec etc); the coordinates (MDirection) for radial velocities; etc.
Although quite often the value has to be in a specific format (e.g. TBD for precession calculations; astronomical longitude for the LAST), the frame values can be given in any known reference format: conversion to the appropiate type will be done automatically if and when necessary.
Frames (and references) are never copied, but act always as containers with shallow copying only (i.e. copied frames will point to identical instances, and changes made in one copy will be visible in all others. This means, e.g., that in the following:
	MeasFrame frame1(MEpoch(50236.12));
	MeasFrame frame2(frame1);
the two frames will be identical, and a change to one means a change to the other. Furthermore, only the information needed for a specific calculation will be used (and calculated). This means that one frame can be used specifying all of e.g. the position (which will probably stay the same for a series of calculations) and time; with the time being set() (if also the reference of the epoch changes) or resetEpoch() (if only the value changes, but the reference and its frame stay the same). A change in the frame will influence automatically any calculation (e.g. conversion to LAST) of which it is part.

The value of a measure (in MV format) can be obtained with the getValue() member function. The value in a variety of formats and units can be obtained with a (specific Measure dependent) series of get() members of both the MV-value and the Measure.

Measures in themselves are not really necessary for proper data reduction and the like. Its real value is the ability to transform a Measure from one reference type (and frame, offset) to another.
Conversion of a measure of a certain kind from one reference to another is done with the aid of special, measure specific, MeasConvert classes. Each conversion class is called Measure::Convert (e.g. MDirection::Convert). A conversion generates from an input reference (or an input measure) and an output reference a conversion functional, that can be used to convert specific values.
Example:

  cout <<       		// output
				// the conversion of a B1950 direction
	MDirection::Convert( MDirection( Quantity( 20, "deg"),
				         Quantity(-10, "deg"),
					 MDirection::Ref( MDirection::B1950)),
				// to J2000
			     MDirection::Ref( MDirection::J2000)) () 
				// where the constructor sets up a conversion
				// engine, and the operator() converts
		<< endl;
The same could have been done by only setting up the conversion engine, and not specifing the default value to be converted in the Convert constructor by:
  cout <<       		// output
				// the conversion of a B1950 direction
      MDirection::Convert(MDirection::Ref( MDirection::B1950),
				// to J2000
			    MDirection::Ref( MDirection::J2000))
				// and use conversion on value
				 (MVDirection( Quantity( 20, "deg"),
					       Quantity(-10, "deg")))
				// where the operator() converts
		<< endl;
Specifying the conversion engine separately, it can be re-used for other values:
	MDirection::Convert conv(MDirection::Ref( MDirection::B1950),
				 MDirection::Ref( MDirection::J2000));
	// We have some coordinates from somewhere, say coord(0:N-1):
	for (Int i=0; i<N; i++) {
	   cout << "B1950: " << coord(i) << "= J2000: " <<
		                conv(coord(i)) << endl;
      };
A larger example. Say you have the J2000 coordinates for a source (RA=11 deg, DEC= -30 deg), and you want to observe it on May 17, 1996 (MJD=50220) at 8:18 UTC in a place with a Longitude of 150 deg (latitude of 20 deg) at 1000 m high, you could get the apparent RA,DEC, and the LAST at that time (you could also go straight to HA/DEC or so) with (I write the example longer than necessary to indicate the steps, and with explicit reference to MV values):
 // The observatory position. Note that the reference is geodetic position 
	MPosition myobs(MVPosition ( Quantity(1, "km") ,
				     Quantity(150, "deg"),
				     Quantity(20, "deg")),
				     MPosition::WGS84);
 // The time I want to observe (note that it could be specified in many
 // other ways)
	MEpoch obstime(MVEpoch(MVTime(1996, 5, 17, (8+18./60.)/24.)), 
	               MEpoch::UTC);
 // The frame specification for when and where to observe
	MeasFrame frame(myobs, obstime);
 // The reference for a sidereal time (note the frame could be empty and 
 // filled at the actual conversion time)
	MEpoch::Ref sidref( MEpoch::LAST, frame);
 // The reference for apparent coordinates:
	MDirection::Ref appref( MDirection::APP, frame);
 // The conversion engine for my time to LAST
	MEpoch::Convert tosid(obstime, sidref);
 // The conversion to sidereal time of obstime
	MEpoch sidtime = tosid();
 // Conversion of UTC 10.8 h 
	sidtime = tosid(MVEpoch(MVTime(1996, 5, 17, 10.8/24.))); 
 // Show me some time
	cout << "LAST for UTC = 11:00: " <<
		tosid(MVEpoch( MVTime( 1996, 5, 17, 11, 0))) << endl;
 // An offset reference (note the RAZE will keep only the integer part of
 // the day for the conversion result)
	MEpoch::Ref offtime(obstime.getValue(), MEpoch::UTC+MEpoch::RAZE);
 // The reference for a sidereal with respect to a specified offset (note
 // that it is automatically calculated into correct units)
	MEpoch::Ref sidoffref(MEpoch::LAST, frame, offtime);
 // Show the offset result
	cout << "LAST today: " <<
		MEpoch::Convert(11., sidoffref)() << endl;
 // Coordinate conversion from J2000
	cout << "Apparent coordinates: " <<
		MDirection::Convert ( MDirection(Quantum(11,"deg"),
                                               Quantum(-30, "deg")),
	                              MDirection::Ref( MDirection::APP,
	                                               frame))() << endl;
 // Handier to have the conversion engine available
	MDirection::Convert cvt( MDirection(Quantum(11,"deg"),
                                          Quantum(-30, "deg")),
	                         MDirection::Ref( MDirection::APP,
	                                          frame));
 // Set another frame time (note it is now sidereal, not UTC. The
 // frame will automatically convert it (using the frame again for
 // position) to TDB for precession etc calculations).
	frame.set(sidtime);
 // And look what same position is at this new time
	cout << "Next position: " << cvt() << endl;

Some conversions need maybe some fine tuning (e.g. what is the acceptable interval for Nutation linear interpolation: could be different from the default interval; some time calculations will want to use the predicted IERS values rather than the actual determined; some Nutation will maybe use the IERS updates, some maybe the JPL DE databases).
The AipsrcValue class can be used to specify very specific parameters that are used to steer the conversion process beyond what is possible with just a list of measure reference types (that list is already long for some cases). Values, switches can be set() (and removed) to change the default behaviour of the conversions. In general the user will only need to use the details in very specific cases. The details that can be used are described in the classes that provide calculations (e.g. Nutation), and in the aipsrc-data reference manual entry.

Some details about the different classes follows. In the examples often a specific measure value (e.g. MVEpoch, the MeasValue for MEpoch), or a specific measure (e.g. MDirection, a direction in space) is used. This is only to visualise the use, any other measure could have been used.

MeasValue

The MeasValue class derivatives are all named MVmeasure, e.g. MVFrequency, and represent the internal representation of the specific measure class. Details can be found in the Quanta module.

Measure

The Measure class derivatives are all called MMeasure. MDirection (a celestial direction), MPosition (a position on Earth), MFrequency (characteristics of electro-magnetic wave), MEpoch (an instance in time), MDoppler, MRadialVelocity MBaseline, Muvw, MEarthMagnetic, .
A measure has a value (kept in internal units in MVmeasure format) and a definition of the reference frame (MeasRef) of the value. The reference is optional, and will default to Measure::DEFAULT.
All measures have a set of standard constructors:
	M();			// some default, e.g. pole directoon, time ==0)
 	M(MV, MeasRef);
	M(Quantity, MeasRef);
	M(Quantum<Vector<Double> >, MeasRef);
	M(Vector<Quantity>, MeasRef);
But also some special ones (e.g. two Quantities for MDirection to specify two angles) depending on type. The MeasRef can be omitted (will then be defaulted to Measure::DEFAULT, e.g. MEpoch::DEFAULT); can be specified as a full reference as a Measure::Ref (e.g. MDirection::Ref) type; or as a simple reference as Measure::TYPE (e.g. MDirection::J2000).
The individual elements of a Measure (i.e the MV value and the reference) can be overwritten (or set) with the set() methods.
get() methods (in general get(unit) to return the internal value in some specified unit as a Quantum; and methods like getAngle() for e.g. MDirection) enable the user to obtain the value of the measure.
A String tellMe() will tell the type of Measure; a void assured(String) and Bool areYou(String) will check the type; while a String showType(Measure::TYPE) will return the string value of a reference type code (e.g. J2000).

Recall that a Measure is a value with a reference specified. The MeasConvert engines enable you to convert it into another Measure, with a different reference (e.g. from J2000 to AZEL). The different get() methods (either directly, or indirectly using additional MV get() functions, or Quantum conversion methods, can convert the internal value into a value (or values) with user preferred units.
For reasons of speed (and safety) the allowed reference types for each Measure are enumerated in each measure class. The different reference types for MDirection are, for example:

    		MDirection::J2000,
		MDirection::JMEAN,
		MDirection::JTRUE,
		MDirection::APP,
		MDirection::B1950,
		MDirection::BMEAN,
		MDirection::BTRUE,
		MDirection::GALACTIC,
		MDirection::HADEC,
		MDirection::AZEL,
		MDirection::DEFAULT = MDirection::J2000
The MEpoch has a special reference type (MEpoch::RAZE) that can only be used in conjuncion with another reference type (e.g. MEpoch::UT1+MEpoch::RAZE). The meaning is: if a measure with such a reference type is converted to another reference type (say MEpoch::LAST) the resultant (sidereal time) instance will be razed to an integer number of days; hence providing an easy way to specify sidereal times offset with the beginning of the current sidereal day.
To aid with external data, a Bool giveMe(String, uInt) will give the correct reference type to be used given the String type. Note that the uInt, rather than the corresponding enum is used, due to templating restrictions in some compilers.
The correct reference (MeasRef) and conversion (MeasConvert) class for each Measure (a frequency cannot be converted into an epoch) are templated, and have specified (and to be used) typedefs: Measure::Ref and Measure::Convert (e.g. MEpoch::Ref, MEpoch::Convert). In addition, Measure::MVType and Measure::MCType are defined for all measures.

Measure errors

In the current implementation, no errors are attached to a Measure. In the original design errors were foreseen, but up till now they have been left out.
The addition of errors is in principle an easy process. They could be attached to either a Measure (as an additial MV value), or the MV's could be expanded to include errors (my preferred option at the moment). An MV being converted will then automatically have its error converted as well.
Before implementing, however, I think it would be worthwhile to look at the whole area of error handling. The easiest way would be to introduce for each of the defined aips++ standard values a corresponding E class (EDouble, EInt, EComplex, EuInt etc), and have all mathematical and logical operators that are defined for the standard classes be defined for the E-classes as well. It would then be easy to introduce errors everywhere.

MeasFrame

A MeasFrame is a container with the instance of time (an MEpoch) and/or the position (an MPosition) for a measure reference. (Other Measures, like MDirection and MRadialVelocity are sometimes needed as well). MeasFrames are never actually copied, but only referred to (shallow copy) , so they can be used for all different types of measure reference. They are only necessary, but then essential, if the reference type does not fully specify the frame (like e.g. MDirection::J2000, or MEpoch::TAI do). Examples are the position necessary to go to MEpoch::LAST, the epoch necessary to go to MDirection::APP, the epoch and position necessary to reference an MDirection::AZEL.
A MeasFrame can be constructed empty (and used in references, as long as it is filled properly at the time of an actual conversion), or with one or Measures already defined with: MeasFrame frame(a_Measure, ...). It can be filled, or re-filled, with set(a_measure,....).
The conversion routines use different values of the frame values given (e.g. the precession and nutation will need the epoch in TDB time, the hour-angle constructor local apparent sidereal time, which needs the astronomical longitude etc.). For that reason the specification of an epoch or position in either the constructor or the set() will create conversion engines for conversion of the input measure to all appropiate values that can be asked by the conversion routines. Note that the actual conversion is only done when that value is requested (and is then saved for later use). It is, therefore, safe and probably good practice to have one frame in a certain conversion environment, filled with as much info as is needed at that stage.
To aid and speed up, resetEpoch() and resetPosition() methods are available. As arguments they accept the corresponding MV or a variety of Double and Quantum arguments to reset the value of the corresponding frame measure only. In that case the conversion engine won't be redesigned, leading to fast recalculation when necessary, since e.g. nutation values could be re-used.
In an observing environment you could hence setup a proper frame with the Observatory position, and an observing day offset (see MeasRef) time; and do resetEpoch() to update the time if and when necessary.

MeasRef

A MeasRef is a measure specific container (and its class reference is Measure::Ref, e.g. MFrequency::Ref) with the measure reference type (e.g. MEpoch::UTC), an optional (but in some cases necessary) MeasFrame (e.g. to specify where the sidereal time was determined), and, just for convenience, an optional offset (e.g. the MJD for which the time specified in the MEpoch referenced is valid). Note that if no frame or offset is necessary, the Measure::TYPE can be used everywhere where a Measure::Ref is needed.
A MeasRef is never copied (all copying and so is done by referencing). This means, for example, that if a specific MeasRef is part of the MEpoch definition for an epoch that is part of a MeasFrame, and you chnage that MeasRef, the change will automatically occur wherever that MeasRef is used (as e.g. in the frame). In most cases that is the expected response, but you should be aware of it, and not re-use a MeasRef for a completely different purpose.
A simple example:
 	MEpoch mytime(MVEpoch(50236.5), MEpoch::UTC);
 // this will define a time in UTC on MJD 50236, 12 hours. The MVEpoch
 // explicit conversion could be left out for most compilers, but some
 // have trouble with automatic conversions.
 // Another way of doing it would be to use Quantities, which have
 // explicit constructors for all measures:
	MEpoch mytime(Quantity(50236.5, "d"));
A slighty more involved example, written out a bit:
 // Specify the location of the observatory (10m high, at given longitude
 // and latitude as geodetic position)
	MPosition obs( 	MVPosition( 	Quantity( 10, "m"),
					Quantity( -6, "deg"),
					Quantity( 52, "deg")),
			MPosition::WGS84);
 // If the current time is MJD50236, 12.3 h UTC, it could be specified as:
	MEpoch tim(	MVEpoch(	Quantity( 50236, "d"),
					Quantity( 12.3, "h")));
 // Note the default reference
 // For this example we will also specify it as:
	MEpoch offtim(tim); 
	offtim.set(MEpoch::DEFAULT+MEpoch::RAZE);
 // These two could define a frame
	MeasFrame frame(tim, obs);
 // Or maybe as (since observatory will stay put)
	MeasFrame frame1(obs);
 // and later addition of some time and its reference frame
	frame1.set(tim);
 // with a change to another time value at a later stage with
	frame1.resetEpoch(	MVEpoch(	Quantity( 50236, "d"),
					Quantity( 13, "h")));
 // At this time we observe a sidereal time of 2.3 h. The actual instance
 // of time needs a sidereal date to specify, but we are too lazy to
 // look it up, hence we specify that this time has an offset, equal to
 // the sidereal time at offtim (which with the RAZE addition will be
 // converted to an integral number of days in whatever time it is
 // converted to)
	MEpoch mylast(	MVEpoch(	Quantity( 2.3, "h")),
			MEpoch::Ref(	MEpoch::LAST,
					frame,
					offtim));
 // Which specifies that we have a Local apparent sidereal time of 2.3 h
 // at the position specified by obs in the frame, at an offset offtim.
 // Note that the offset is given in UTC (and RAZE). Any conversion of
 // this mylast value to any other reference type, will always auto start
 // with a conversion of the offset to the current type (i.e LAST (with
 // the RAZE taking the integer part only)), and adding it to the value
 // given. Note that if an output reference has an offset, the resulting
 // value will be corrected for the specified offset as well.
The reference type can be set with a set() function, and set() functions for the offset and frame will be present as well.
A Bool empty() checks if the reference is empty; get() functions provide the information in the reference; and a String showMe() will return the type of measure (e.g. "Epoch") the MeasRef can be used for.

MeasConvert

The MeasConvert class converts Measures from one reference type and frame to another. It gathers all relevant information and analyses it to have fast multiple conversions. The MeasConvert classes are Measure specific, and should be used with the class names Measure::Convert (e.g. MFrequency::Convert ). The () operator will do the actual conversion; constructors and set() methods will only fill the information necessary to do the conversion. MeasConvert is a non-copying container.
To set up the conversion engine, the MeasConvert object has to know the input data reference (remember the MeasRef contains information about the type, the possible reference frame and a possible offset), and an output reference. Using these references it will communicate with the appropiate Measure class to set up a series of routines that have to be executed in order to attain the goal. (Note that if the input and output reference both define a frame, but different ones, e.g. because you want to convert a sidereal time at one place to a sidereal time at another place, the conversion machinery will always first go to the proper default (UTC in this case), and then go to the goal).
The actual conversion need a value to be converted, and it also can use a default Unit, so that if your frequencies are in nm, you can once specify that they are nm, and then simply convert a Double.
This means that the optimal constructor for a MeasConvert is:
 // The first argument will give the input reference, and, if a Quantum is
 // used to make the Measure, the default units for inputs to the conversion.
 // It acts as a 'model' for subsequent input to be converted.
 // () operator
	Measure::Convert(	Measure(Quantum), 
 // the second argument gives the output reference
				Measure::Ref);
The actual constructors present include ones with the first argument only an input reference, rather than a full Measure. However, in all cases an empty or partial one can be constructed, with set() functions filling in the rest. The conversion engine is only (re-)setup if at least an input and output reference can be found.
After setting up the conversion engine, the () operator can be used with a variety of values to return a converted Measure. Possibilities are:
	()		// convert the value as specified in the 'model'
	(Double)	// convert the value first to appropiate units (if they
			// were implicit in 'model' or explicitly set), and
			// then convert
	(Vector<Double>)// as Double
	(Quantity)	// convert the full value, including its own units
	(Quantum<Vector<Double> >) // as Quantity
	(MeasValue)	// convert the specified appropiate MV
	(Measure)	// set up a new conversion chain, using the value as
			// 'model', and the old output reference,
			//  and then convert
	(Measure, Measure::Ref) // set up a new conversion chain for the
			// 'model' given and the output reference given
	(Measure::Ref)	// set up a new conversion chain using the old 'model'
			// and the output reference given, and convert the
			// existing model value
A simple example to output the J2000 coordinates for a B1950 input (RA=20 deg, DEC=-10 deg):
  cout << 	
	MDirection::Convert( MDirection( Quantity( 20, "deg")
			   		 Quantity(-10, "deg"),
			     		 MDirection::Ref( MDirection::B1950)),
			     MDirection::Ref( MDirection::J2000)) () << endl;
In this example everything is done in one go (the () at the end does the conversion). Another example, to have a UTC to LAST converter:
 // Set up the model for the input (default reference is UTC)
	MEpoch model (	Quantity(0., "d"));
 // Set up the frame with the observatory position
	MPosition obs(	MVPosition(	Quantity( 10, "m"),
					Quantity( -6, "deg"),
					Quantity( 50, "deg")),
			MPosition::Ref(MPosition::WGS84));
	Measframe frame( obs);
 // set up the output reference
	MEpoch::Ref outref(	MEpoch::LAST,
				frame);
 // Set up conversion
	MEpoch::Convert	toLST(	model,
				outref);
 // Output a series of sidereal times (formatted in ddd::hh:mm:ss)
	for (Double d = 12345; d<12346; d += 0.1) {
	  cout << "Converted from UTC to LAST: " <<
		d <<
		toLST(d).getValue() << endl;
	};

For specific purposes it would be very easy to set up a series of simple classes, that would do standard conversions.

MeasData, MeasTable, MeasBase, other help classes

A series of help classes are present to aid in the conversion, especially caching information. They are of no direct use for the end user (except maybe a few constants in MeasData).
The classes are:

Motivation

The Measures module originated to be able to convert ccordinates between different reference frames.

To Do

Example

See the individual measures for appropiate examples.

Classes

Aberration -- Aberration class and calculations (full description)
EarthField -- EarthField class model calculations (full description)
EarthMagneticMachine -- Calculates magnetic field in a direction (full description)
IAU_SOFA -- Global Fortran function wraps (full description)
MBaseline -- A Measure: Baseline on Earth (full description)
MCBase -- Base for specific measure conversions (full description)
MCBaseline -- MBaseline conversion routines (full description)
MCDirection -- MDirection conversion routines (full description)
MCDoppler -- MDoppler conversion routines (full description)
MCEarthMagnetic -- MEarthMagnetic conversion routines (full description)
MCEpoch -- MEpoch conversion routines (full description)
MCFrame -- Measure frame calculations proxy (full description)
MCFrequency -- MFrequency conversion routines (full description)
MCPosition -- MPosition conversion routines (full description)
MCRadialVelocity -- MRadialVelocity conversion routines (full description)
MConvertBase -- Conversion of Measures Base (full description)
MCuvw -- Muvw conversion routines (full description)
MDirection -- A Measure: astronomical direction (full description)
MDoppler -- A Measure: Doppler shift (full description)
MEarthMagnetic -- A Measure: Magnetic field on Earth (full description)
MEpoch -- A Measure: instant in time (full description)
MFrequency -- A Measure: wave characteristics (full description)
MPosition -- A Measure: position on Earth (full description)
MRBase -- Base for Reference frame for physical measures (full description)
MRadialVelocity -- A Measure: radial velocity (full description)
MeasBase -- Base class for all measures (full description)
MeasComet -- Position for comets and other solar system bodies (full description)
MeasConvert -- Conversion of Measures (full description)
MeasData -- MeasData provides Measure computing data (full description)
MeasFrame -- Container for Measure frame (full description)
MeasFrameInterface -- Global functions (full description)
MeasIERS -- Interface to IERS tables (full description)
MeasJPL -- Interface to JPL DE tables (full description)
MeasMath -- Measure conversion aid routines (full description)
MeasRef -- Reference frame for physical measures (full description)
MeasTable -- MeasTable provides Measure computing database data (full description)
Measure -- Physical quantities within reference frame (full description)
MeasureHolder -- A holder for Measures to enable record conversions (full description)
MeasuresProxy -- (full description)
Muvw -- A Measure: uvw on Earth (full description)
Nutation -- Nutation class and calculations (full description)
Output -- Global functions (full description)
Output -- Global functions (full description)
Output -- Global functions (full description)
Output -- Global functions (full description)
ParAngleMachine -- Converts a direction into parallactic angle (full description)
Precession -- Precession class and calculations (full description)
SofaTest -- Wrapping of IAU SOFA Fortran routines and test class (full description)
SolarPos -- Solar position class and calculations (full description)
Stokes -- Stokes parameter definitions for interface to table data. (full description)
UVWMachine -- Converts UVW coordinates between coordinate systems (full description)
VelocityMachine -- Converts between velocities and frequencies (full description)