casacore
Loading...
Searching...
No Matches
Coordinates.h
Go to the documentation of this file.
1//# Coordinates.h : Classes to interconvert computation positions with physical
2//# Copyright (C) 1996,1997,1998,1999,2000,2001
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef COORDINATES_COORDINATES_H
29#define COORDINATES_COORDINATES_H
30
31//# Module includes
32#include <casacore/casa/aips.h>
33#include <casacore/coordinates/Coordinates/Coordinate.h>
34#include <casacore/coordinates/Coordinates/CoordinateSystem.h>
35#include <casacore/coordinates/Coordinates/DirectionCoordinate.h>
36#include <casacore/coordinates/Coordinates/LinearCoordinate.h>
37#include <casacore/coordinates/Coordinates/LinearXform.h>
38#include <casacore/coordinates/Coordinates/Projection.h>
39#include <casacore/coordinates/Coordinates/SpectralCoordinate.h>
40#include <casacore/coordinates/Coordinates/StokesCoordinate.h>
41#include <casacore/coordinates/Coordinates/TabularCoordinate.h>
42#include <casacore/coordinates/Coordinates/CoordinateUtil.h>
43
44namespace casacore { //# NAMESPACE CASACORE - BEGIN
45
46// <module>
47//
48// <summary>
49// Classes to interconvert pixel and world (physical) coordinates
50// </summary>
51
52// <prerequisite>
53// <li> Knowledge of astronomical coordinate conversions in general. Probably the
54// best documents are the papers by Mark Calabretta and Eric Greisen.
55// The initial draft from 1996 can be found at
56// http://www.atnf.csiro.au/~mcalabre. It is this draft that the
57// Coordinate classes are based upon. Since then, this paper has evolved
58// into three which can be found at the above address, and will be published in the
59// Astronomy and Astrophysics Supplement Series (probably in 2000).
60// The design has changed since the initial draft. When these papers
61// are finalized, and the IAU has ratified the new standards, WCSLIB
62// (Mark Calabretta's implementation of these conventions) will be
63// revised for the new designs. At that time, the Coordinate classes
64// may also be revised.
65// <li> Generic Casacore classes; especially those in the
66// <linkto module=Arrays>Arrays</linkto> module.
67// <li> The <linkto module=Measures>Measures</linkto> module.
68// </prerequisite>
69//
70
71// <reviewed reviewer="Peter Barnes" date="1999/12/24">
72// </reviewed>
73
74// <synopsis>
75// The primary notion is that a <linkto class=Coordinate>Coordinate</linkto>
76// can interconvert between a length "n" Vector<Double> (the
77// pixel coordinate) and a length "m" Vector<Double> (the
78// "world" coordinate). Note that "m" and "n" do not in
79// principle have to be the same (so that one can get both the RA and DEC from
80// an image slice, for example), however in practice they currently always are.
81// Each Coordinate has the full mapping from pixel to world coordinates, i.e.
82// it has a reference value, reference pixel, increments, and an arbitrary
83// transformation matrix. To go from a pixel to a world coordinate the following
84// steps are applied:
85// <ol>
86// <li> The reference pixel is subtracted from the pixel position.
87// <li> The result is multiplied by the transformation matrix.
88// <li> The result is multiplied by an increment per output axis to convert
89// it into physical coordinates.
90// <li> For some coordinate types (e.g., Direction), a non-linear function is
91// applied to this result.
92// </ol>
93//
94// The classes are arranged as follows. The base class is
95// <linkto class=Coordinate>Coordinate</linkto> which defines the
96// interface. Classes derived from it are
97// <ol>
98// <li> <linkto class=DirectionCoordinate>DirectionCoordinate</linkto>
99// <li> <linkto class=LinearCoordinate>LinearCoordinate</linkto>
100// <li> <linkto class=SpectralCoordinate>SpectralCoordinate</linkto>
101// <li> <linkto class=TabularCoordinate>TabularCoordinate</linkto>
102// <li> <linkto class=StokesCoordinate>StokesCoordinate</linkto>
103// <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
104// </ol>
105//
106// Other classes are <linkto class=Projection>Projection</linkto>
107// which is used to specify an astronomical projection for
108// DirectionCoordinates, and <linkto class=LinearXform>LinearXform</linkto>
109// a helper class which the application programmer will not interact with.
110//
111// <linkto class=CoordinateSystem>CoordinateSystem</linkto> is
112// the class that application programmers will usually interact
113// with. A CoordinateSystem consists of a collection of the other
114// classes derived from Coordinate. Normally one group will be for
115// RA/DEC, another for a Stokes axis, and another group for the spectral axis.
116// The axes may be transposed arbitrarily, for example RA could be
117// the first axis, and DEC the third.
118//
119// Normally the CoordinateSystem being manipulated will be embedded in a PagedImage
120// or other object. Note that the axes of the PagedImage do not
121// necessarily map directly to the axes in the CoordinateSystem. Functionality
122// is provided to determine this mapping.
123//
124// One or more axes from the CoordinateSystem may be removed. Pixel axes and/or
125// world axes may be removed. You are encouraged to leave all the world axes
126// when you remove pixel axes.
127// <br>
128// If a world axis is removed, the corresponding pixel axis is also removed.
129// This means that one can be sure that a pixel axis always has a
130// corresponding world axis (it makes no sense otherwise). The opposite is
131// not necessarily true: a world axis can exist without a pixel axis.
132//
133// The linear transformation and sky projection computations are carried out in an
134// underlying library -- WCSLIB -- written by Mark Calabretta of the ATNF.
135//
136// </synopsis>
137//
138//
139// <note role=caution>
140// All pixels coordinates are zero relative.
141// </note>
142//
143// <example>
144// First, let's make a DirectionCoordinate --- used to represent a direction,
145// usually an RA/DEC, but it could also be, e.g., an AZ/EL pair.
146// <srcblock>
147// Matrix<Double> xform(2,2); // 1
148// xform = 0.0; xform.diagonal() = 1.0; // 2
149// Quantum<Double> refLon(135.0, "deg");
150// Quantum<Double> refLat(60.0, "deg");
151// Quantum<Double> incLon(-1.0, "deg");
152// Quantum<Double> incLat(1.0, "deg");
153// DirectionCoordinate radec(MDirection::J2000, // 3
154// Projection(Projection::SIN), // 4
155// refLon, refLat, // 5
156// incLon, incLat, // 6
157// xform, // 7
158// 128, 128); // 8
159// </srcblock>
160// <ul>
161// <li> <i>1-2:</i>Here we set up a diagonal transformation matrix.
162// Normally this matrix should be diagonal, however if you wanted
163// to introduce a rotation or skew, you would do it through this
164// matrix.
165// <li> <i>3:</i>This defines the astronomical type of the world
166// coordinate. Most of the time it will probably be J2000
167// or B1950, but there are many other possibilities as listed
168// in the <linkto class=MDirection>MDirection</linkto> class
169// header.
170// <li> <i>4:</i>The <linkto class=Projection>Projection</linkto> class
171// defines the "geometry" that is used to map <src>xy<-->world</src>. SIN
172// is the most common projection for radio interferometers. Note that
173// SIN can optionally take parameters as defined in Calabretta and Greisen.
174// If not provided, they default to 0.0, which is the "old" SIN
175// convention.
176// <li> <i>5:</i>Set the reference position to RA=135, DEC=60 degrees.
177// Note that the native units of a DirectionCoordinate is radians.
178// <li> <i>6:</i> Set the increments to -1 degree in RA, and +1 degree
179// in DEC.
180// <li> <i>7:</i> Set the previously defined transformation matrix.
181// <li> <i>8:</i> Set the zero-relative reference pixel. Note that it does
182// not have to be incremental. At the reference pixel, the world
183// coordinate has the reference value.
184// </ul>
185//
186// Although we happeend to create our DirectionCoordinate with Quanta in degrees,
187// these have been converted to radians by the constructor. We can set the native units
188// to degrees if we wish as follows:
189// <srcblock>
190// Vector<String> units(2); units = "deg"; // 9
191// radec.setWorldAxisUnits(units); // 10
192// </srcblock>
193// The increment and reference value are updated appropriately.
194//
195// Set up a couple of vectors to use the world and pixel coordinate values.
196// <srcblock>
197// Vector<Double> world(2), pixel(2); // 11
198// pixel = 138.0; // 12
199// </srcblock>
200// We use 138 as an abitrary pixel position which is near the reference pixel
201// so we can tell if the answers look foolish or not.
202//
203// We can actually perform a transformation like this as follows. If
204// it succeeds we print the value of the world coordinate.
205// <srcblock>
206// Bool ok = radec.toWorld(world, pixel); // 13
207// if (!ok) { // 14
208// cout << "Error: " << radec.errorMessage() << endl; // 15
209// return 1; // 16
210// } // 17
211// cout << world << " <--- " << pixel << endl; // 18
212// </srcblock>
213// There is an overloaded "toWorld" function that produces an MDirection
214// in case you want to, e.g., find out what the position in B1950 coordinates
215// would be.
216//
217// The reverse transformation takes place similarly:
218// <srcblock>
219// ok = radec.toPixel(pixel, world); // 19
220// </srcblock>
221//
222// Suppose we have an image with a Stokes axis. It can be set up as follows:
223// <srcblock>
224// Vector<Int> iquv(4);
225// iquv(0) = Stokes::I; iquv(1) = Stokes::Q; // 21
226// iquv(2) = Stokes::U; iquv(3) = Stokes::V; // 22
227// StokesCoordinate stokes(iquv); // 23
228// </srcblock>
229// We create an integer array the same length as the Stokes axis, and place
230// the corresponding Stokes enum into each element of the array. The values
231// must be unique, e.g. there can only be one "I" plane.
232// Besides the generic <src>Vector<Double></src> toWorld/toPixel interface,
233// you can also directly interconvert between Stokes enum and and (zero-relative)
234// plane number:
235// <srcblock>
236// Int plane; // 24
237// ok = stokes.toPixel(plane, Stokes::Q); // 25
238// </srcblock>
239// Here it will return <src>True</src> and set plane to 1. On the other
240// hand, it would return <src>False</src> for:
241// <srcblock>
242// ok = stokes.toPixel(plane, Stokes::XX); // 26
243// </srcblock>
244// since "XX" is not one of the Stokes enumerations we used to create this
245// coordinate.
246//
247// A Spectral ("frequency") coordinate may be created as follows:
248// <srcblock>
249// SpectralCoordinate spectral(MFrequency::TOPO, // 27
250// 1.4E+9, // 28
251// 2.0E+4, // 29
252// 0, // 30
253// 1420.40575E+6); // 31
254// </srcblock>
255// The default frequency units of a spectral coordinate are Hz, although they
256// may be changed to whatever is convenient. The first line (27) defines the
257// type of frequency we have -- topocentric here. The second (28) line
258// defines the frequency at the reference pixel, 0 (28) here. The channel
259// increment is defined on line 29. A rest frequency of the spectral may
260// be provided. It is useful in calculating doppler velocities. These calculations
261// are carried out by the <linkto class=MFrequency>MFrequency</linkto> and
262// <linkto class=MDoppler>MDoppler</linkto> classes of the Measures system.
263// </example>
264//
265// <motivation>
266// The primary motivation is to provide support for converting pixel locations in an
267// image to physical ("world") positions.
268// </motivation>
269
270// <todo asof="2000/01/01">
271// <li> Add measures interfaces that handle reference frame conversions
272// <li> offset coordinates
273// </todo>
274
275// </module>
276
277
278} //# NAMESPACE CASACORE - END
279
280#endif
this file contains all the compiler specific defines
Definition mainpage.dox:28