casacore
Loading...
Searching...
No Matches
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
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40template<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{
122public:
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.
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.
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
253private:
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 Matrix< Double > linearTransform() const
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.
virtual Vector< Double > referenceValue() const
virtual Vector< String > worldAxisNames() const
Return the requested attribute.
virtual Vector< String > worldAxisUnits() 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).
virtual Coordinate * makeFourierCoordinate(const Vector< Bool > &axes, const Vector< Int > &shape) const
Find the Coordinate for when we Fourier Transform ourselves.
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(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 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 Bool setReferenceValue(const Vector< Double > &refval)
mutable::wcsprm wcs_p
An interface to the WCSLIB linear transformation routines.
LinearCoordinate & operator=(const LinearCoordinate &other)
Assignment (copy semantics).
Bool overwriteWorldAxisUnits(const Vector< String > &units)
Overwrite the world axis units with no compatibility checks or adjustment.
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)
static LinearCoordinate * restore(const RecordInterface &container, const String &fieldName)
Restore the LinearCoordinate from a record.
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 Vector< Double > increment() const
virtual Bool setWorldAxisUnits(const Vector< String > &units)
Set the world axis units.
virtual Vector< Double > referencePixel() const
virtual Coordinate * clone() const
Make a copy of the LinearCoordinate using new.
String: the storage and methods of handling collections of characters.
Definition String.h:225
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