The classes are arranged as follows. The base class is Coordinate which defines the interface. Classes derived from it are
Other classes are Projection which is used to specify an astronomical projection for DirectionCoordinates, and LinearXform a helper class which the application programmer will not interact with.
CoordinateSystem is the class that application programmers will usually interact with. A CoordinateSystem consists of a collection of the other classes derived from Coordinate. Normally one group will be for RA/DEC, another for a Stokes axis, and another group for the spectral axis. The axes may be transposed arbitrarily, for example RA could be the first axis, and DEC the third.
Normally the CoordinateSystem being manipulated will be embedded in a PagedImage or other object. Note that the axes of the PagedImage do not necessarily map directly to the axes in the CoordinateSystem. Functionality is provided to determine this mapping.
One or more axes from the CoordinateSystem may be removed. Pixel axes and/or
world axes may be removed. You are encouraged to leave all the world axes
when you remove pixel axes.
If a world axis is removed, the corresponding pixel axis is also removed.
This means that one can be sure that a pixel axis always has a
corresponding world axis (it makes no sense otherwise). The opposite is
not necessarily true: a world axis can exist without a pixel axis.
The linear transformation and sky projection computations are carried out in an underlying library -- WCSLIB -- written by Mark Calabretta of the ATNF.
All pixels coordinates are zero relative.
Matrix<Double> xform(2,2); // 1 xform = 0.0; xform.diagonal() = 1.0; // 2 Quantum<Double> refLon(135.0, "deg"); Quantum<Double> refLat(60.0, "deg"); Quantum<Double> incLon(-1.0, "deg"); Quantum<Double> incLat(1.0, "deg"); DirectionCoordinate radec(MDirection::J2000, // 3 Projection(Projection::SIN), // 4 refLon, refLat, // 5 incLon, incLat, // 6 xform, // 7 128, 128); // 8
Although we happeend to create our DirectionCoordinate with Quanta in degrees, these have been converted to radians by the constructor. We can set the native units to degrees if we wish as follows:
Vector<String> units(2); units = "deg"; // 9 radec.setWorldAxisUnits(units); // 10The increment and reference value are updated appropriately.
Set up a couple of vectors to use the world and pixel coordinate values.
Vector<Double> world(2), pixel(2); // 11 pixel = 138.0; // 12We use 138 as an abitrary pixel position which is near the reference pixel so we can tell if the answers look foolish or not.
We can actually perform a transformation like this as follows. If it succeeds we print the value of the world coordinate.
Bool ok = radec.toWorld(world, pixel); // 13 if (!ok) { // 14 cout << "Error: " << radec.errorMessage() << endl; // 15 return 1; // 16 } // 17 cout << world << " <--- " << pixel << endl; // 18There is an overloaded "toWorld" function that produces an MDirection in case you want to, e.g., find out what the position in B1950 coordinates would be.
The reverse transformation takes place similarly:
ok = radec.toPixel(pixel, world); // 19
Suppose we have an image with a Stokes axis. It can be set up as follows:
Vector<Int> iquv(4); iquv(0) = Stokes::I; iquv(1) = Stokes::Q; // 21 iquv(2) = Stokes::U; iquv(3) = Stokes::V; // 22 StokesCoordinate stokes(iquv); // 23We create an integer array the same length as the Stokes axis, and place the corresponding Stokes enum into each element of the array. The values must be unique, e.g. there can only be one "I" plane. Besides the generic Vector<Double> toWorld/toPixel interface, you can also directly interconvert between Stokes enum and and (zero-relative) plane number:
Int plane; // 24 ok = stokes.toPixel(plane, Stokes::Q); // 25Here it will return True and set plane to 1. On the other hand, it would return False for:
ok = stokes.toPixel(plane, Stokes::XX); // 26since "XX" is not one of the Stokes enumerations we used to create this coordinate.
A Spectral ("frequency") coordinate may be created as follows:
SpectralCoordinate spectral(MFrequency::TOPO, // 27 1.4E+9, // 28 2.0E+4, // 29 0, // 30 1420.40575E+6); // 31The default frequency units of a spectral coordinate are Hz, although they may be changed to whatever is convenient. The first line (27) defines the type of frequency we have -- topocentric here. The second (28) line defines the frequency at the reference pixel, 0 (28) here. The channel increment is defined on line 29. A rest frequency of the spectral may be provided. It is useful in calculating doppler velocities. These calculations are carried out by the MFrequency and MDoppler classes of the Measures system.