 News |
FAQ
|
| Search
|
Home
|
| Getting Started | Documentation | Glish | Learn More | Programming | Contact Us |
|
| Version 1.9 Build 1488 |
|
| Package | general | |
| Module | images |
include "coordsys.g"
| coordsys | Create a default coordsys tool |
| 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 |
| convertmany | Convert many numeric mixed coordinates |
| coordinatetype | Return type of specified coordinate |
| copy | Copy this Coordsys tool |
| done | Destroy this Coordsys tool |
| epoch | Return the epoch |
| findaxis | Find specified axis in coordinate system |
| findcoordinate | Find axes of specified coordinate |
| frequencytofrequency | Convert frequency to frequency with an offset |
| frequencytovelocity | Convert frequency to velocity |
| fromrecord | Fill Coordinate System from a record |
| id | Return the fundamental identifier of this tool |
| 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 |
| replace | Replace a coordinate |
| restfrequency | Recover the rest frequency |
| setconversiontype | Set extra reference conversion layer |
| setdirection | Set direction coordinate values |
| setepoch | Set a new epoch |
| setincrement | Set the increment |
| setlineartransform | Set the linear transform |
| setnames | Set the axis names |
| setobserver | Set a new observer |
| setprojection | Set the direction coordinate projection |
| setreferencecode | Set new reference code |
| setreferencelocation | Set 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 |
| 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 |
| velocitytofrequency | Convert velocity to frequency |
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
A&A 2002, 1061-1075 and 1077-1122can be found here. Note that the actual system implemented originally in AIPS++ was based on a 1996 draft of these papers. The final papers are being implemented while new version of the defining library become available.
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 :
The record consists of fields named from from 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 an 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).
You can give any combination of the allowed letters when using the format argument. If you supply one letter the coordinate is as described above. If you supply more than one letter, 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 (uses a Glish attribute). 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.
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 (AIPS++ programmers) writing robust scripts, we must account for these possibilities, although the user really shouldn't bother. This, 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
Events
There are no events emitted or acted upon by this tool.
cs := coordsys(direction=T, linear=2) cs.summary()