# Measures

Load this module by running

`using CasaCore.Measures`

The `Measures`

module is used to interface with the CasaCore measures system, which can be used to perform coordinate system conversions. For example, UTC time can be converted to atomic time, or a B1950 coordinates can be converted to J2000 coordinates.

At the moment there are 3 different kinds of measures available:

Epochs - representing an instance in time

Directions - representing a direction to an object on the sky

Positions - representing a location on the Earth

## Units

CasaCore.Measures depends on the Unitful package in order to specify the units associated with various quantities. The Unitful package should have automatically been installed when you ran `Pkg.add("CasaCore")`

. You can load the Unitful package by running `using Unitful`

and documentation for Unitful is also available. Unitful is a particularly elegant package for unit-checked computation because the unit checking occurs at compile-time. That is, there is no run-time overhead associated with using Unitful.

Unitful offers two ways to attach units to a quantity:

```
using Unitful: m
x = 10.0 * u"m" # using the u"..." string macro
y = 10.0 * m # using the Unitful.m object (which we have imported into our namespace)
```

The first approach using the string macro is generally preferred because it avoids polluting the namespace. Simply replace the `...`

in `u"..."`

with your desired units. For example we could obtain units of meters per second by writing `u"m/s"`

or radians per kilometer-squared by writing `u"rad/km^2"`

.

CasaCore.Measures, however, will only expect quantities with three different kinds of units: times, lengths, and angles. These are summarized below.

Unit | Expression |
---|---|

Seconds | `u"s"` |

Days | `u"d"` |

Meters | `u"m"` |

Kilometers | `u"km"` |

Degrees | `u"°"` |

Radians | `u"rad"` |

The ° character for degrees con be obtained at the Julia REPL by typing `\degree`

and then pressing `<tab>`

. The Julia plugins for Emacs and vim also provide this functionality.

UnitfulAstro extends base Unitful with additional units commonly encountered in astronomy (for instance, `pc`

and `Jy`

).

## Epochs

An epoch measure is created using the `Epoch(sys, time)`

constructor where `sys`

specifies the coordinate system and `time`

specifies the Julian date.

`CasaCore.Measures.Epoch`

— Method.`Epoch(sys, time)`

Instantiate an epoch in the given coordinate system (`sys`

).

The `time`

should be given as a modified Julian date. Additionally the Unitful package should be used to communicate the units of `time`

.

For example `time = 57365.5 * u"d"`

corresponds to a Julian date of 57365.5 days. However you can also specify the Julian date in seconds (`u"s"`

), or any other unit of time supported by Unitful.

**Coordinate Systems:**

The coordinate system is selected using the string macro `epoch"..."`

where the `...`

is replaced with one of the coordinate systems listed below.

`LAST`

- local apparent sidereal time`LMST`

- local mean sidereal time`GMST1`

- Greenwich mean sidereal time`GAST`

- Greenwich apparent sidereal time`UT1`

- UT0 (raw time from GPS measurements) corrected for polar wandering`UT2`

- UT1 corrected for variable Earth rotation`UTC`

- coordinated universal time`TAI`

- international atomic time`TDT`

- terrestrial dynamical time`TCG`

- geocentric coordinate time`TDB`

- barycentric dynamical time`TCB`

- barycentric coordinate time

**Examples:**

```
using Unitful: d
Epoch(epoch"UTC", 0.0d) # 1858-11-17T00:00:00
Epoch(epoch"UTC", 57365.5d) # 2015-12-09T12:00:00
```

## Directions

`CasaCore.Measures.Direction`

— Method.```
Direction(sys, longitude, latitude)
Direction(sys)
```

Instantiate a direction in the given coordinate system (`sys`

).

The longitude and latitude may either be a sexagesimally formatted string, or an angle where the units (degrees or radians) are specified by using the Unitful package. If the longitude and latitude coordinates are not provided, they are assumed to be zero.

**Coordinate Systems:**

The coordinate system is selected using the string macro `dir"..."`

where the `...`

is replaced with one of the coordinate systems listed below.

`J2000`

- mean equator and equinox at J2000.0 (FK5)`JMEAN`

- mean equator and equinox at frame epoch`JTRUE`

- true equator and equinox at frame epoch`APP`

- apparent geocentric position`B1950`

- mean epoch and ecliptic at B1950.0`B1950_VLA`

- mean epoch (1979.9) and ecliptic at B1950.0`BMEAN`

- mean equator and equinox at frame epoch`BTRUE`

- true equator and equinox at frame epoch`GALACTIC`

- galactic coordinates`HADEC`

- topocentric hour angle and declination`AZEL`

- topocentric azimuth and elevation (N through E)`AZELSW`

- topocentric azimuth and elevation (S through W)`AZELGEO`

- geodetic azimuth and elevation (N through E)`AZELSWGEO`

- geodetic azimuth and elevation (S through W)`JNAT`

- geocentric natural frame`ECLIPTIC`

- ecliptic for J2000 equator and equinox`MECLIPTIC`

- ecliptic for mean equator of date`TECLIPTIC`

- ecliptic for true equator of date`SUPERGAL`

- supergalactic coordinates`ITRF`

- coordinates with respect to the ITRF Earth frame`TOPO`

- apparent topocentric position`ICRS`

- international celestial reference system`MERCURY`

`VENUS`

`MARS`

`JUPITER`

`SATURN`

`URANUS`

`NEPTUNE`

`PLUTO`

`SUN`

`MOON`

**Examples:**

```
using Unitful: °, rad
Direction(dir"AZEL", 0°, 90°) # topocentric zenith
Direction(dir"ITRF", 0rad, 1rad)
Direction(dir"J2000", "12h00m", "43d21m")
Direction(dir"SUN") # the direction towards the Sun
Direction(dir"JUPITER") # the direction towards Jupiter
```

## Positions

`CasaCore.Measures.Position`

— Method.`Position(sys, elevation, longitude, latitude)`

Instantiate a position in the given coordinate system (`sys`

).

Note that depending on the coordinate system the elevation may be measured relative to the center or the surface of the Earth. In both cases the units should be given with the Unitful package. The longitude and latitude may either be a sexagesimally formatted string, or an angle where the units (degrees or radians) are specified by using the Unitful package. If the longitude and latitude coordinates are not provided, they are assumed to be zero.

**Coordinate Systems:**

The coordinate system is selected using the string macro `pos"..."`

where the `...`

is replaced with one of the coordinate systems listed below.

`ITRF`

- the International Terrestrial Reference Frame`WGS84`

- the World Geodetic System 1984

**Examples:**

```
using Unitful: m, °
Position(pos"WGS84", 5000m, "20d30m00s", "-80d00m00s")
Position(pos"WGS84", 5000m, 20.5°, -80°)
```

`CasaCore.Measures.observatory`

— Function.`observatory(name)`

Get the position of an observatory from its name.

**Examples:**

```
observatory("VLA") # the Very Large Array
observatory("ALMA") # the Atacama Large Millimeter/submillimeter Array
```

## Coordinate System Conversions

`CasaCore.Measures.ReferenceFrame`

— Type.`ReferenceFrame`

The `ReferenceFrame`

type contains information about the frame of reference to use when converting between coordinate systems. For example converting from J2000 coordinates to AZEL coordinates requires knowledge of the observer's location, and the current time. However converting between B1950 coordinates and J2000 coordinates requires no additional information about the observer's frame of reference.

Use the `set!`

function to add information to the given frame of reference.

**Example:**

```
frame = ReferenceFrame()
set!(frame, observatory("VLA")) # set the observer's position to the location of the VLA
set!(frame, Epoch(epoch"UTC", 50237.29*u"d")) # set the current UTC time
```

`CasaCore.Measures.measure`

— Function.`measure(frame, value, newsys)`

Converts the value measured in the given frame of reference into a new coordinate system.

**Arguments:**

`frame`

- an instance of the`ReferenceFrame`

type`value`

- an`Epoch`

,`Direction`

, or`Position`

that will be converted from its current coordinate system into the new one`newsys`

- the new coordinate system

Note that the reference frame must have all the required information to convert between the coordinate systems. Not all conversions require the same information!

**Examples:**

```
# Compute the azimuth and elevation of the Sun
measure(frame, Direction(dir"SUN"), dir"AZEL")
# Compute the ITRF position of the VLA
measure(frame, observatory("VLA"), pos"ITRF")
# Compute the atomic time from a UTC time
measure(frame, Epoch(epoch"UTC", 50237.29*u"d"), epoch"TAI")
```