National Radio
Astronomy Observatory

1.1.3 coordsys - Tool

Operations on CoordinateSystems
Requires:

Synopsis

Description

Summary

A Coordsys tool is used to store and manipulate a Coordinate System (we will use the term ‘Coordinate System’ interchangeably with ‘Coordsys tool’). A Coordinate System is a collection of coordinates, such as a direction coordinate (E.g. RA/DEC), or a spectral coordinate (e.g. an LSRK frequency).

The main job of the Coordsys tool is to convert between absolute pixel and world (physical) coordinates. It also supports relative pixel and world coordinates (relative to reference location).

A Coordinate System is generally associated with an image (manipulated via an Image tool) but can also exist in its own right. An image is basically just a regular lattice of pixels plus a Coordinate System describing the mapping from pixel coordinate to world (or physical) coordinate.

Each coordinate is associated with a number of axes. For example, a direction coordinate has two coupled axes; a longitude and a latitude. A spectral coordinate has one axis. A linear coordinate can have an arbitrary number of axes, but they are all uncoupled. The Coordinate System actually maintains two kinds of axes; pixel axes and world axes.

As well as the coordinates, there is some extra information stored in the Coordinate System. This consists of the telescope, the epoch (date of observation), and the highly influential observer’s name. The telescope (i.e. position on earth) and epoch are important if you want to, say, change a spectral coordinate from LSRK to TOPO.

For general discussion about celestial coordinate systems, see the papers by Mark Calabretta and Eric Greisen. Background on the WCS system and relevant papers (including the papers published in

can be found here. Note that the actual system implemented originally in CASA was based on a 1996 draft of these papers. The final papers are being implemented while new version of the defining library become available.

Coordinate formatting

Many of the Coordsys tool functions use a world coordinate value as an argument. This world value can be formatted in many ways.

Some functions (e.g. toworld) have a function argument called format which takes a string. This controls the format in which the coordinate is output and hence possibly input into some other function.

Possibilities for format are :

• ’n’ - means the world coordinate is given as a numeric vector (actually doubles). The units are implicitly those returned by function units.
• ’q’ - means the world coordinate is given as a vector of quantities (value and unit) - see the quanta module. If there is only one axis (e.g. spectral coordinate), you will get a single quantum only.
• ’m’ - means the world coordinate is given as a record of measures - see the measures module.

  The record consists of fields named direction, spectral, stokes, linear, and tabular, depending upon which coordinate types are present in the Coordinate System.

  The direction field holds a direction measure.

  The spectral field holds further subfields frequency, radiovelocity, opticalvelocity, betavelocity. The frequency subfield holds a frequency measure. The radiovelocity subfield holds a doppler measure using the radio velocity definition. The opticalvelocity subfield holds a doppler measure using the optical velocity definition. The betavelocity subfield holds a doppler measure using the true or beta velocity definition.

  The stokes field just holds a string giving the Stokes type (not a real measure).

  The linear and tabular fields hold a vector of quanta (not a real measure).

• ’s’ - means the the world coordinate is given as a vector of formatted strings

You can give a combination of one or more of the allowed letters when using the format argument. The coordinate is given as a record, with possible fields ’numeric’, ’quantity’, ’measure’ and ’string’ where each of these fields is given as described above.

There are functions torel and toabs used to inter-convert between absolute and relative world and pixel coordinates. These functions have an argument isworld whereby you can specify whether the coordinate is a pixel coordinate or a world coordinate. In general, you should not need to use this argument because any coordinate variable generated by Coordsys tool functions ’knows’ whether it is absolute or relative, world or pixel. . However, you may be inputting a coordinate variable which you have generated in some other way, and then you may need this.

Stokes Coordinates

Stokes axes don’t fit very well into our Coordinate model since they are not interpolatable. The alternative to having a Stokes Coordinate is having a Stokes pixel type (like double, complex). Both have their good and bad points. We have chosen to use a Stokes Coordinate.

With the Stokes Coordinate, any absolute pixel coordinate value must be in the range of 1 to nStokes, where nStokes is the number of Stokes types in the Coordinate.

We define relative world coordinates for a Stokes axis to be the same as absolute world coordinates (it makes no sense to think of a relative value XY - XX say).

You can use the specialized functions stokes and setstokes to recover and set new Stokes values in the Stokes Coordinate.

World and Pixel axes

The Coordinate System maintains what it calls pixel and world axes. The pixel axis is associated with, say, the axes of a lattice of pixels. The world axes describe notional world axes, generally in the same order as the pixel axes. However, they may be different. Imagine that a 3-D image is collapsed along one axis. The resultant image has 2 pixel axes. However, we can maintain the world coordinate for the collapsed axis (so we know the coordinate value still). Thus we have three world axes and two pixel axes. It is also possible for the C++ programmer to reorder these pixel and world axes. However, this is strongly discouraged, and you should never actually encounter a situation where the pixel and world axes are in different orders, but you may encounter cases where the number of world and pixela axes is different.

For those of us (CASA programmers) writing robust scripts, we must account for these possibilities, although the user really shouldn’t bother. Thus, the pixel and world vectors return the pixel and world axes of the found coordinate.

The functions referencevalue, increment, units, and names return their vectors in world axis order. However, function referencepixel returns in pixel axis order (and the world vectors might have more values than the referencepixel vector).

Overview of Coordsys tool functions

• Get/set - Functions to get and set various items within the Coordinate System are
  • referencepixel - get the reference pixel
  • setreferencepixel - set the reference pixel
  • referencevalue - get the reference value
  • setreferencevalue - set the reference value
  • setreferencelocation - Set reference pixel and value to these values
  • increment - get axis increments
  • setincrement - set axis increments
  • lineartransform - get linear transform
  • setlineartransform - set linear transform
  • names - get axis names
  • setnames - set axis names
  • units - get axis units
  • setunits - set axis units
  • stokes - get Stokes values
  • setdirection - set Direction coordinate values
  • setstokes - set Stokes values
  • setspectral - set Spectral coordinate tabular values
  • settabular - set Tabular coordinate tabular values
  • projection - get direction coordinate projection
  • setprojection - set direction coordinate projection
  • referencecode - get reference codes
  • setreferencecode - set reference codes
  • restfrequency - get the spectral coordinate rest frequency
  • setrestfrequency - set the spectral coordinate rest frequency
  • epoch - get the epoch of observation
  • setepoch - set the epoch of observation
  • telescope - get the telecope of the observation
  • settelescope - set the telecope of the observation
  • observer - get observer name
  • setobserver - set observer name
• Utility - There is a range of utility services available through the functions
  • axesmap - get mapping between pixel and world axes order
  • axiscoordinatetypes - get type of coordinate for each axis
  • coordinatetype - get type of coordinates
  • copy - make a copy of this tool
  • done - destroy this tool 
  • findaxis - find specified axis (by number) in coordinate system
  • findcoordinate - find specified (by number) coordinate
  • fromrecord - set Coordinate System from a casapy record
  • id - get the fundamental identifier of this tool 
  • naxes - get number of axes
  • ncoordinates - get the number of coordinates
  • reorder - reorder coordinates
  • summary - summarize the Coordinate System
  • torecord - Convert a Coordinate SYstem to a casapy record
  • type - the type of this tool 
• Coordinate conversion
  • convert - Convert one numeric coordinate with mixed input and output formats (abs/rel/world/pixel)
  • toabs - Convert a relative coordinate to an absolute coordinate
  • topixel - Convert from absolute world coordinate to absolute pixel coordinate
  • torel - Convert an absolute coordinate to a relative coordinate
  • toworld - Convert from an absolute pixel coordinate to an absolute world coordinate
  • convertmany - Convert many numeric coordinates with mixed input and output formats (abs/rel/world/pixel)
  • toabsmany - Convert many relative coordinates to absolute coordinates
  • topixelmany - Convert many absolute world coordinates to absolute pixel coordinates
  • torelmany - Convert many absolute coordinates to relative coordinates
  • toworldmany - Convert many absolute pixel coordinates to absolute world coordinates
  • frequencytovelocity - Convert from frequency to velocity
  • frequencytofrequency - Apply a relativistic Doppler shift to a list of frequencies
  • velocitytofrequency - Convert from velocity to frequency
  • setconversiontype - Set extra reference frame conversion layer
  • conversiontype - Recover extra reference frame conversion types
• Tests -
  • coordsystest - Run test suite for Coordsys tool 

Methods

More information about CASA may be found at the CASA web page

Copyright © 2016 Associated Universities Inc., Washington, D.C.

This code is available under the terms of the GNU General Public Lincense