NRAO Home > CASA > CASA Toolkit Reference Manual

1.1.3 coordsys - Tool

Operations on CoordinateSystems




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

A&A 2002, 1061-1075 and 1077-1122

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 :

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


newcoordsys Create a non-default coordsys tool
addcoordinate Add default coordinates. (For assay testing only.)
axesmap Find mapping between world and pixel axes
axiscoordinatetypes Return types of coordinates for each axis
conversiontype Get extra reference conversion layer
convert Convert a numeric mixed coordinate
convertdirection Convert the direction coordinate to the specified frame by rotating as necessary about the reference pixel so the axes line up with the cardinal directions.
convertmany Convert many numeric mixed coordinates
coordinatetype Return type of specified coordinate
copy Copy this Coordsys tool
done Destroy this Coordsys tool, restore default tool
epoch Return the epoch
findaxis Find specified axis in coordinate system
findaxisbyname Find specified axis in coordinate system.
findcoordinate Find axes of specified coordinate
frequencytofrequencyApply relativistic Doppler shift to a list of frequencies
frequencytovelocity Convert frequency to velocity
fromrecord Fill Coordinate System from a record
increment Recover the increments
lineartransform Recover the linear transform matrix
names Recover the names for each axis
naxes Recover the number of axes
ncoordinates Recover the number of coordinates in the Coordinate System
observer Return the name of the observer
projection Recover the direction coordinate projection
referencecode Return specified reference code
referencepixel Recover the reference pixel
referencevalue Recover the reference value
reorder Reorder the coordinates
transpose Transpose the axes.
replace Replace a coordinate
restfrequency Recover the rest frequency
setconversiontype Set extra reference conversion layer
getconversiontype Get extra reference conversion layer (aka conversiontype).
setdirection Set direction coordinate values
setepoch Set a new epoch
setincrement Set the increment
setlineartransformSet the linear transform
setnames Set the axis names
setobserver Set a new observer
setprojection Set the direction coordinate projection
setreferencecode Set new reference code
setreferencelocationSet reference pixel and value
setreferencepixel Set the reference pixel
setreferencevalue Set the reference value
setrestfrequency Set the rest frequency
setspectral Set tabular values for the spectral coordinate
setstokes Set the Stokes types
settabular Set tabular values for the tabular coordinate
settelescope Set a new telescope
setunits Set the axis units
stokes Recover the Stokes types
summary Summarize basic information about the Coordinate System
telescope Return the telescope
toabs Convert relative coordinate to absolute
toabsmany Convert many numeric relative coordinates to absolute
topixel Convert from absolute world to pixel coordinate
topixelmany Convert many absolute numeric world coordinates to pixel
torecord Convert Coordinate System to a record
subimage delivers a coordinate origin re-referenced for a subimage
torel Convert absolute coordinate to relative
torelmany Convert many numeric absolute coordinates to relative
toworld Convert from absolute pixel coordinate to world
toworldmany Convert many absolute pixel coordinates to numeric world
type Return the type of this tool
units Recover the units for each axis
velocitytofrequencyConvert velocity to frequency
parentname Get parent image name.
setparentname Set the parent image name (normally not needed by end-users)

    coordsys.newcoordsys - Function
    coordsys.addcoordinate - Function
    coordsys.axesmap - Function
    coordsys.axiscoordinatetypes - Function
    coordsys.conversiontype - Function
    coordsys.convert - Function
    coordsys.convertdirection - Function
    coordsys.convertmany - Function
    coordsys.coordinatetype - Function
    coordsys.copy - Function
    coordsys.done - Function
    coordsys.epoch - Function
    coordsys.findaxis - Function
    coordsys.findaxisbyname - Function
    coordsys.findcoordinate - Function
    coordsys.frequencytofrequency - Function
    coordsys.frequencytovelocity - Function
    coordsys.fromrecord - Function
    coordsys.increment - Function
    coordsys.lineartransform - Function
    coordsys.names - Function
    coordsys.naxes - Function
    coordsys.ncoordinates - Function - Function
    coordsys.projection - Function
    coordsys.referencecode - Function
    coordsys.referencepixel - Function
    coordsys.referencevalue - Function
    coordsys.reorder - Function
    coordsys.transpose - Function
    coordsys.replace - Function
    coordsys.restfrequency - Function
    coordsys.setconversiontype - Function
    coordsys.getconversiontype - Function
    coordsys.setdirection - Function
    coordsys.setepoch - Function
    coordsys.setincrement - Function
    coordsys.setlineartransform - Function
    coordsys.setnames - Function
    coordsys.setobserver - Function
    coordsys.setprojection - Function
    coordsys.setreferencecode - Function
    coordsys.setreferencelocation - Function
    coordsys.setreferencepixel - Function
    coordsys.setreferencevalue - Function
    coordsys.setrestfrequency - Function
    coordsys.setspectral - Function
    coordsys.setstokes - Function
    coordsys.settabular - Function
    coordsys.settelescope - Function
    coordsys.setunits - Function
    coordsys.stokes - Function
    coordsys.summary - Function
    coordsys.telescope - Function
    coordsys.toabs - Function
    coordsys.toabsmany - Function
    coordsys.topixel - Function
    coordsys.topixelmany - Function
    coordsys.torecord - Function
    coordsys.subimage - Function
    coordsys.torel - Function
    coordsys.torelmany - Function
    coordsys.toworld - Function
    coordsys.toworldmany - Function
    coordsys.type - Function
    coordsys.units - Function
    coordsys.velocitytofrequency - Function
    coordsys.parentname - Function
    coordsys.setparentname - Function

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

Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search