casacore
LinearCoordinate.h
Go to the documentation of this file.
1 //# LinearCoordinate.h: Assume a general linear relation between pixel and world axes.
2 //# Copyright (C) 1997,1998,1999,2000,2001,2002,2003,2004
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 
30 #ifndef COORDINATES_LINEARCOORDINATE_H
31 #define COORDINATES_LINEARCOORDINATE_H
32 
33 #include <casacore/casa/aips.h>
34 #include <casacore/coordinates/Coordinates/Coordinate.h>
35 #include <casacore/casa/Arrays/Vector.h>
36 #include <wcslib/wcs.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 template<class T> class Quantum;
41 
42 
43 // <summary>
44 // Interconvert between pixel and a linear world coordinate.
45 // </summary>
46 
47 // <use visibility=export>
48 
49 // <reviewed reviewer="Peter Barnes" date="1999/12/24" tests="tLinearCoordinate">
50 // </reviewed>
51 
52 // <prerequisite>
53 // <li> <linkto class=Coordinate>Coordinate</linkto> defines the fundamental
54 // interface to coordinate conversions.
55 // </prerequisite>
56 //
57 // <synopsis>
58 // The LinearCoordinate class ties pixel and world axes together through
59 // a general linear transformation.
60 //
61 // <srcblock>
62 // world = (cdelt * PC * (pixel - crpix)) + crval
63 // </srcblock>
64 // Where PC is an NxN matrix; pixel, crval, crpix and world are length N
65 // vectors, and cdelt is an NxN diagonal matrix, represented as a length
66 // N vector.
67 //
68 // The LinearCoordinate can contain several uncoupled axes (similar to the way
69 // in which the DirectionCoordinate contains two axes).
70 // </synopsis>
71 //
72 // <note role=caution>
73 // All pixels coordinates are zero relative.
74 // </note>
75 //
76 // <example>
77 // Let's make a LinearCoordinate with just one axis containing
78 // a coordinate describing length.
79 // <srcblock>
80 // Vector<Double> crpix(1); crpix = 0.0;
81 // Vector<Double> crval(1); crval = 100.0;
82 // Vector<Double> cdelt(1); cdelt = -10.0;
83 // Matrix<Double> pc(1,1); pc= 0; pc.diagonal() = 1.0;
84 // Vector<String> name(1); name = "length";
85 // Vector<String> units(1); units = "km";
86 //
87 // LinearCoordinate lin(names, units, crval, cdelt, pc, crpix);
88 // </srcblock>
89 //
90 // Now do a coordinate conversion
91 //
92 // <srcblock>
93 // Vector<Double> world, pixel(1);
94 // pixel = 2.0;
95 // if (!lin.toWorld(world, pixel)) {
96 // cerr << "Error : " << lin.errorMessage() << endl;
97 // } else {
98 // cerr << "pixel, world = " << pixel << world << endl;
99 // }
100 // </srcblock>
101 // The answer should of course be -20km.
102 // </example>
103 //
104 // <motivation>
105 // This class is intended for use with axes which do not have specific coordinate
106 // types. A "time" axis would be a good example.
107 // </motivation>
108 //
109 // <thrown>
110 // <li> AipsError
111 // </thrown>
112 //
113 // <todo asof="2000/01/01">
114 // <li> Allow differing numbers of world and pixel axes. Requires a change in
115 // WCS or use of a different library.
116 // </todo>
117 //
118 
119 
121 {
122 public:
123  // The default constructor makes a LinearCoordinate for which pixel
124  // and world coordinates are equal. <src>naxes</src> gives the number
125  // of axes in the Coordinate.
126  LinearCoordinate(uInt naxes = 1);
127 
128  // Construct the LinearCoordinate
130  const Vector<String> &units,
131  const Vector<Double> &refVal,
132  const Vector<Double> &inc,
133  const Matrix<Double> &pc,
134  const Vector<Double> &refPix);
135 
136  // Construct LinearCoordinate with Quantum-based interface.
137  // The units of the increment (<src>inc</src>) will be converted to
138  // those of the reference value (<src>refVal</src>) which will
139  // then serve as the units of the Coordinate.
141  const Vector<Quantum<Double> >& refVal,
142  const Vector<Quantum<Double> >& inc,
143  const Matrix<Double> &pc,
144  const Vector<Double> &refPix);
145 
146  // Constructor from WCS structure; must hold ONLY a linear wcs structure
147  // Specify whether the absolute pixel coordinates in the wcs structure
148  // are 0- or 1-relative. The coordinate is always constructed with 0-relative
149  // pixel coordinates
150  LinearCoordinate(const wcsprm& wcs, Bool oneRel=True);
151 
152  // Copy constructor (copy semantics).
154 
155  // Assignment (copy semantics).
157 
158  // Destructor.
159  virtual ~LinearCoordinate();
160 
161  // Returns Coordinate::LINEAR.
162  virtual Coordinate::Type type() const;
163 
164  // Returns the String "Linear".
165  virtual String showType() const;
166 
167  // Returns the number of pixel/world axes. The number of axes is arbitrary,
168  // however the number of world and pixel axes must at present be the same.
169  // <group>
170  virtual uInt nPixelAxes() const;
171  virtual uInt nWorldAxes() const;
172  // </group>
173 
174  // Convert a pixel position to a worl position or vice versa. Returns True
175  // if the conversion succeeds, otherwise it returns False and method
176  // errorMessage returns an error message. The output
177  // vectors are appropriately resized. The value of the Bool parameter passed
178  // to toWorld() has no effect as this type of coordinate does not support a
179  // conversion layer frame.
180  // <group>
181  virtual Bool toWorld(Vector<Double> &world,
182  const Vector<Double> &pixel, Bool=True) const;
183  virtual Bool toPixel(Vector<Double> &pixel,
184  const Vector<Double> &world) const;
185  // </group>
186 
187 
188  // Return the requested attribute
189  // <group>
192  virtual Vector<Double> increment() const;
196  // </group>
197 
198  // Set the value of the requested attributed. Note that these just
199  // change the internal values, they do not cause any recomputation.
200  // <group>
201  virtual Bool setWorldAxisNames(const Vector<String> &names);
202  virtual Bool setReferencePixel(const Vector<Double> &refPix);
204  virtual Bool setIncrement(const Vector<Double> &inc);
205  virtual Bool setReferenceValue(const Vector<Double> &refval);
206  // </group>
207 
208  // Set the world axis units. Adjust the increment and
209  // reference value by the ratio of the old and new units.
210  // The units must be compatible with the current units.
211  virtual Bool setWorldAxisUnits(const Vector<String> &units);
212 
213  // Overwrite the world axis units with no compatibility
214  // checks or adjustment.
216 
217  // Comparison function. Any private Double data members are compared
218  // with the specified fractional tolerance. Don't
219  // compare on the specified
220  // axes in the Coordinate. If the comparison returns False, method
221  // errorMessage contains a message about why.
222  // <group>
223  virtual Bool near(const Coordinate& other,
224  Double tol=1e-6) const;
225  virtual Bool near(const Coordinate& other,
226  const Vector<Int>& excludeAxes,
227  Double tol=1e-6) const;
228  // </group>
229 
230  // Find the Coordinate for when we Fourier Transform ourselves. This pointer
231  // must be deleted by the caller. Axes specifies which axes of the Coordinate
232  // you wish to transform. Shape specifies the shape of the image
233  // associated with all the axes of the Coordinate. Currently the
234  // output reference pixel is always shape/2. If the pointer returned is 0,
235  // it failed with a message in <src>errorMessage</src>
237  const Vector<Int>& shape) const;
238 
239  // Save the LinearCoordinate into the supplied record using the supplied field name.
240  // The field must not already exist, otherwise <src>False</src> is returned.
241  virtual Bool save(RecordInterface &container, const String &fieldName) const;
242 
243  // Restore the LinearCoordinate from a record.
244  // A null pointer means that the restoration did not succeed - probably
245  // because fieldName doesn't exist or doesn't contain a CoordinateSystem.
246  static LinearCoordinate *restore(const RecordInterface &container,
247  const String &fieldName);
248 
249  // Make a copy of the LinearCoordinate using new. The caller is responsible for calling
250  // delete.
251  virtual Coordinate *clone() const;
252 
253 private:
254 
255 // An interface to the WCSLIB linear transformation routines.
256  mutable ::wcsprm wcs_p;
257 
258 // Copy private data
259  void copy (const LinearCoordinate& other);
260 
261 // Make wcs structure
262  void makeWCS (wcsprm& wcs, uInt naxis, const Vector<Double>& refPix,
263  const Vector<Double>& refVal,
264  const Vector<Double>& incr,
265  const Matrix<Double>& pc,
266  const Vector<String>& units,
267  const Vector<String>& names);
268 };
269 
270 } //# NAMESPACE CASACORE - END
271 
272 
273 #endif
274 
Type
This enum lists the types of the derived classes.
Definition: Coordinate.h:144
virtual String showType() const
Returns the String "Linear".
virtual Bool setIncrement(const Vector< Double > &inc)
virtual uInt nWorldAxes() const
LinearCoordinate(const Vector< String > &names, const Vector< String > &units, const Vector< Double > &refVal, const Vector< Double > &inc, const Matrix< Double > &pc, const Vector< Double > &refPix)
Construct the LinearCoordinate.
static LinearCoordinate * restore(const RecordInterface &container, const String &fieldName)
Restore the LinearCoordinate from a record.
virtual Vector< Double > referencePixel() const
virtual Bool save(RecordInterface &container, const String &fieldName) const
Save the LinearCoordinate into the supplied record using the supplied field name.
virtual ~LinearCoordinate()
Destructor.
void makeWCS(wcsprm &wcs, uInt naxis, const Vector< Double > &refPix, const Vector< Double > &refVal, const Vector< Double > &incr, const Matrix< Double > &pc, const Vector< String > &units, const Vector< String > &names)
Make wcs structure.
LinearCoordinate(const LinearCoordinate &other)
Copy constructor (copy semantics).
LinearCoordinate(const Vector< String > &names, const Vector< Quantum< Double > > &refVal, const Vector< Quantum< Double > > &inc, const Matrix< Double > &pc, const Vector< Double > &refPix)
Construct LinearCoordinate with Quantum-based interface.
virtual uInt nPixelAxes() const
Returns the number of pixel/world axes.
virtual Bool setReferencePixel(const Vector< Double > &refPix)
LinearCoordinate & operator=(const LinearCoordinate &other)
Assignment (copy semantics).
virtual Vector< Double > referenceValue() const
virtual Vector< String > worldAxisUnits() const
LinearCoordinate(uInt naxes=1)
The default constructor makes a LinearCoordinate for which pixel and world coordinates are equal.
virtual Bool near(const Coordinate &other, Double tol=1e-6) const
Comparison function.
virtual Matrix< Double > linearTransform() const
virtual Bool toPixel(Vector< Double > &pixel, const Vector< Double > &world) const
virtual Bool near(const Coordinate &other, const Vector< Int > &excludeAxes, Double tol=1e-6) const
virtual Bool setWorldAxisNames(const Vector< String > &names)
Set the value of the requested attributed.
virtual Vector< Double > increment() const
virtual Bool setReferenceValue(const Vector< Double > &refval)
Bool overwriteWorldAxisUnits(const Vector< String > &units)
Overwrite the world axis units with no compatibility checks or adjustment.
virtual Vector< String > worldAxisNames() const
Return the requested attribute.
virtual Bool toWorld(Vector< Double > &world, const Vector< Double > &pixel, Bool=True) const
Convert a pixel position to a worl position or vice versa.
virtual Coordinate::Type type() const
Returns Coordinate::LINEAR.
virtual Bool setLinearTransform(const Matrix< Double > &pc)
virtual Coordinate * makeFourierCoordinate(const Vector< Bool > &axes, const Vector< Int > &shape) const
Find the Coordinate for when we Fourier Transform ourselves.
void copy(const LinearCoordinate &other)
Copy private data.
LinearCoordinate(const wcsprm &wcs, Bool oneRel=True)
Constructor from WCS structure; must hold ONLY a linear wcs structure Specify whether the absolute pi...
virtual Coordinate * clone() const
Make a copy of the LinearCoordinate using new.
virtual Bool setWorldAxisUnits(const Vector< String > &units)
Set the world axis units.
mutable ::wcsprm wcs_p
An interface to the WCSLIB linear transformation routines.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
const Double e
e and functions thereof:
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1987
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55