casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
LinearXform.h
Go to the documentation of this file.
1 //# LinearXform.h: Perform a linear transform between input and output vectors
2 //# Copyright (C) 1997-2003
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 //#
27 //# $Id$
28 
29 #ifndef COORDINATES_LINEARXFORM_H
30 #define COORDINATES_LINEARXFORM_H
31 
32 #include <casacore/casa/aips.h>
33 #include <wcslib/lin.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 template<class T> class Vector;
38 template<class T> class Matrix;
39 class String;
40 
41 // <summary>
42 // Perform a linear transform between input and output vectors
43 // </summary>
44 
45 // <use visibility=local>
46 
47 // <reviewed reviewer="Peter Barnes" date="1999/12/24" tests="tLinearXform">
48 // </reviewed>
49 
50 // <prerequisite>
51 // <li> General knowledge of Casacore Arrays
52 // <li> Knowledge of FITS terminology in coordinate transformations
53 // </prerequisite>
54 //
55 // <synopsis>
56 // This class represents the common linear part of a FITS coordinate
57 // transformation. In particular it does the following:
58 // <srcblock>
59 // world = cdelt * PC * (pixel - crpix)
60 // </srcblock>
61 // Where PC is an NxN matrix; pixel, crpix (reference pixel) and world are
62 // length N vectors; and cdelt (increment) is an NxN diagonal matrix,
63 // represented as a length N vector.
64 //
65 // Normally this class isn't used directly, rather it is used indirectly through
66 // a class like <linkto class=LinearCoordinate>LinearCoordinate</linkto>.
67 //
68 // The actual computations are performed by WCSLIB, written by Mark Calabretta
69 // of the ATNF.
70 // </synopsis>
71 //
72 // <example>
73 // Let's make a LinearXform housing two axes with a unit
74 // diagonal PC matrix and convert from pixel to world
75 //
76 // <srcblock>
77 // Vector<Double> crpix(2), cdelt(2);
78 // crpix(0) = 10.0; crpix(1) = 20.0;
79 // cdelt(0) = 1.0; cdelt(1) = -1.0;
80 // LinearXform lxf(crpix, cdelt);
81 //
82 // String errMsg;
83 // Vector<Double> world, pixel(2);
84 // pixel = 10.0;
85 // Bool ok = lxf.reverse(world, pixel, errMsg);
86 // if (ok) {
87 // cerr << "pixel, world = " << pixel << world << endl;
88 // } else {
89 // cerr << "Error : " << errMsg << endl;
90 // }
91 // </srcblock>
92 // The answer should be a world vector with values 0 and -10.
93 // </example>
94 //
95 // <motivation>
96 // Factor out the common linear part of coordinate transformations.
97 // </motivation>
98 //
99 // <thrown>
100 // <li> AipsError
101 // </thrown>
102 //
103 // <todo asof="1997/01/13">
104 // <li> Allow different numbers of pixel and world axes.
105 // </todo>
106 //
107 
108 
110 {
111 public:
112  // Construct with specified number of axes. The reference pixel is
113  // assumed to be 0, and the increment is assumed to be unity, and the
114  // PC matrix is assumed to be diagonal.
115  LinearXform(uInt naxis=1);
116 
117  // Construct the linear transformation from the supplied reference pixel
118  // and increment. The PC matrix is the unit matrix.
119  // <src>crpix</src> and <src>cdelt</src> must have the same number
120  // of elements.
122 
123  // Construct a linear transformation, supplying all of the reference pixel,
124  // increment and PC matrix.
125  // The vectors must be of the same length ("n") and the number of rows and
126  // columns in the matrix must also be n.
127  LinearXform(const Vector<Double> &crpix, const Vector<Double> &cdelt,
128  const Matrix<Double> &pc);
129 
130  // Copy constructor (copy sematics)
131  LinearXform(const LinearXform &other);
132 
133  // Assignment (copy sematics)
134  LinearXform &operator=(const LinearXform &other);
135 
136  // Destructor
137  ~LinearXform();
138 
139  // Returns the number of world axes, which for this class is also the
140  // number of pixel axes.
141  uInt nWorldAxes() const;
142 
143  // Convert world coordinates to pixel coordinates (forward), or pixel
144  // coordinates to world (reverse). If the conversion works True is returned,
145  // otherwise False is returned and errorMsg is set. The output vectors
146  // are resized appropriately.
147  // <group>
148  Bool forward(Vector<Double> &pixel, const Vector<Double> &world,
149  String &errorMsg) const;
150  Bool reverse(Vector<Double> &world, const Vector<Double> &pixel,
151  String &errorMsg) const;
152  // </group>
153 
154  // Retrieve the value of crpix, cdelt, and pc.
155  // <group>
156  Vector<Double> crpix() const;
157  Vector<Double> cdelt() const;
158  Matrix<Double> pc() const;
159  // </group>
160 
161  // Set the value of crpix, cdelt, and pc. Note that since you can only
162  // set one of them, you cannot change the dimensionality of the transform
163  // using these functions. Instead use assignment on a temporary, i.e.:
164  // <src> linxform = LinearXform (crpix,crval,pc); </src>
165  // <group>
166  void crpix(const Vector<Double> &newvals);
167  void cdelt(const Vector<Double> &newvals);
168  void pc(const Matrix<Double> &newvals);
169  // </group>
170 
171  // Invert the LinearXform ready for use in a Fourier Transformed Coordinate.
172  // It is the callers responsibility to delete the pointer. If it fails
173  // the pointer is 0 and an error message is provided
174  LinearXform* fourierInvert (String& errMsg, const Vector<Bool>& axes,
175  const Vector<Double>& crpix,
176  const Vector<Double>& scale) const;
177 
178  // Comparison function. Any private Double data members are compared
179  // with the specified fractional tolerance. You can specify axes to
180  // exclude from the comparison if you wish.
181  // <group>
182  Bool near(const LinearXform& other,
183  Double tol=1e-6) const;
184  Bool near(const LinearXform& other,
185  const Vector<Int>& excludeAxes,
186  Double tol=1e-6) const;
187  // </group>
188 
189 private:
190  // A WCSLIB C-structure.
191  mutable linprm linprm_p;
192 
194  void set_linprm();
195 };
196 
197 } //# NAMESPACE CASACORE - END
198 
199 #endif
std::vector< double > Vector
Definition: ds9context.h:24
Bool reverse(Vector< Double > &world, const Vector< Double > &pixel, String &errorMsg) const
Vector< Double > crpix() const
Retrieve the value of crpix, cdelt, and pc.
Matrix< Double > pc() const
Perform a linear transform between input and output vectors.
Definition: LinearXform.h:109
~LinearXform()
Destructor.
Vector< Double > cdelt() const
double Double
Definition: aipstype.h:55
LinearXform(uInt naxis=1)
Construct with specified number of axes.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
uInt nWorldAxes() const
Returns the number of world axes, which for this class is also the number of pixel axes...
Bool forward(Vector< Double > &pixel, const Vector< Double > &world, String &errorMsg) const
Convert world coordinates to pixel coordinates (forward), or pixel coordinates to world (reverse)...
linprm linprm_p
A WCSLIB C-structure.
Definition: LinearXform.h:191
LinearXform & operator=(const LinearXform &other)
Assignment (copy sematics)
const Double e
e and functions thereof:
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Bool near(const LinearXform &other, Double tol=1e-6) const
Comparison function.
LinearXform * fourierInvert(String &errMsg, const Vector< Bool > &axes, const Vector< Double > &crpix, const Vector< Double > &scale) const
Invert the LinearXform ready for use in a Fourier Transformed Coordinate.
unsigned int uInt
Definition: aipstype.h:51
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42