casacore
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 
44 namespace 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