casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TabularCoordinate.h
Go to the documentation of this file.
1 //# TabularCoordinate.h: Table lookup 1-D coordinate, with interpolation
2 //# Copyright (C) 1997,1998,1999,2000,2001,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_TABULARCOORDINATE_H
31 #define COORDINATES_TABULARCOORDINATE_H
32 
33 #include <casacore/casa/aips.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 template<class Domain, class Range> class Interpolate1D;
41 template<class T> class Quantum;
42 class LogIO;
43 
44 
45 
46 // <summary>
47 // Table lookup 1-D coordinate, with interpolation.
48 // </summary>
49 
50 // <use visibility=export>
51 
52 // <reviewed reviewer="Peter Barnes" date="1999/12/24" tests="tTabularCoordinate">
53 // </reviewed>
54 
55 // <prerequisite>
56 // <li> <linkto class=Coordinate>Coordinate</linkto>
57 // </prerequisite>
58 //
59 // <synopsis>
60 // This class is used where the world and pixel values are determined by a
61 // lookup table. For fractional pixel values, a linear interpolation is used.
62 // The values returned for, e.g., the increment, are based on
63 // the average of the whole table. At present,
64 // the values must either increase or decrease monotonically.
65 // </synopsis>
66 //
67 // <note role=caution>
68 // All pixels coordinates are zero relative.
69 // </note>
70 //
71 // <example>
72 // Let's make a non-linear TabularCoordinate and convert a pixel
73 // value to world (which will use linear interpolation)
74 // <srcblock>
75 // Vector<Double> pixelValues(3);
76 // Vector<Double> worldValues(3);
77 // pixelValues(0) = 122.0;
78 // pixelValues(1) = 300.0;
79 // pixelValues(2) = 6524.0;
80 // worldValues(0) = 1.1e6;
81 // worldValues(1) = 2.1e6;
82 // worldValues(2) = 2.2e6;
83 //
84 // String unit("km");
85 // String axisName("length");
86 //
87 // TabularCoordinate tc(pixelValues, worldValues, unit, axisName);
88 //
89 // Double world, pixel;
90 // pixel = 200.12;
91 // if (!tc.toWorld(world, pixel)) {
92 // cerr << "Error : " << tc.errorMessage() << endl;
93 // } else {
94 // cerr << "pixel, world = " << pixel << ", " << world << endl;
95 // }
96 // </srcblock>
97 // </example>
98 //
99 // <motivation>
100 // This class was motivated by the need for an irregular axis, such as a collection
101 // of frequencies. For example, the SpectralCoordinate class contains a TabularCoordinate.
102 // </motivation>
103 //
104 //
105 // <thrown>
106 // <li> AipsError
107 // </thrown>
108 //
109 // <todo asof="1997/07/12">
110 // <li> Allow interpolations other than linear.
111 // </todo>
112 
113 
115 {
116 public:
117  // Default constructor. It is equivalent to
118  // TabularCoordinate(0,1,0, "", "Tabular");
120 
121  // Create a linear TabularCoordinate where
122  // <src>world = refval + inc*(pixel-refpix)</src>
123  TabularCoordinate(Double refval, Double inc, Double refpix,
124  const String &unit, const String &axisName);
125 
126  // Create a linear TabularCoordinate with a Quantum-based interface where
127  // <src>world = refval + inc*(pixel-refpix)</src>. The units of the
128  // increment (<src>inc</src>) will be converted to
129  // those of the reference value (<src>refVal</src>) which will
130  // then serve as the units of the Coordinate.
131  TabularCoordinate(const Quantum<Double>& refval,
132  const Quantum<Double>& inc,
133  Double refpix, const String& axisName);
134 
135  // Construct a TabularCoordinate with the specified world values. The
136  // increments and related functions return the average values
137  // calculated from the first and last world values. The number of pixel
138  // and world values must be the same. Normally the pixel values will be
139  // 0,1,2,..., but this is not required.
140  //
141  // A linear interpolation/extrapolation is used for channels which are not
142  // supplied. The reference channel (pixel) is chosen to be 0. The
143  // frequencies must increase or decrease monotonically (otherwise the
144  // toPixel lookup would not be possible).
147  const String &unit, const String &axisName);
148 
149  // Construct a TabularCoordinate with the specified world values
150  // via the Quantum-based interface. All comments for the
151  // previous constructor apply
152  TabularCoordinate(const Vector<Double>& pixelValues,
153  const Quantum<Vector<Double> >& worldValues,
154  const String &axisName);
155 
156  // Copy constructor (copy semantics).
157  TabularCoordinate(const TabularCoordinate &other);
158 
159  // Assignment (copy semantics).
161 
162  // Destructor.
163  virtual ~TabularCoordinate();
164 
165  // Returns Coordinate::TABULAR.
166  virtual Coordinate::Type type() const;
167 
168  // Always returns the String "Tabular".
169  virtual String showType() const;
170 
171  // Always returns 1.
172  // <group>
173  virtual uInt nPixelAxes() const;
174  virtual uInt nWorldAxes() const;
175  // </group>
176 
177  // Convert a pixel position to a world position or vice versa. Returns True
178  // if the conversion succeeds, otherwise it returns False and method
179  // errorMessage contains an error message. The output
180  // vectors are appropriately resized.
181  // The Bool parameter in toWorld() has no effect as this coordinate does
182  // not support a conversion layer frame.
183  // <group>
184  virtual Bool toWorld(Vector<Double> &world,
185  const Vector<Double> &pixel, Bool=True) const;
186  virtual Bool toPixel(Vector<Double> &pixel,
187  const Vector<Double> &world) const;
188  Bool toWorld(Double &world, Double pixel) const;
189  Bool toPixel(Double &pixel, Double world) const;
190  // </group>
191 
192  // Batch up a lot of transformations. The first (most rapidly varying) axis
193  // of the matrices contain the coordinates. Returns False if any conversion
194  // failed and <src>errorMessage()</src> will hold a message.
195  // The <src>failures</src> array (True for fail, False for success)
196  // is the length of the number of conversions and
197  // holds an error status for each conversion.
198  // <group>
199  virtual Bool toWorldMany(Matrix<Double> &world,
200  const Matrix<Double> &pixel,
201  Vector<Bool>& failures) const;
202  virtual Bool toPixelMany(Matrix<Double>& pixel,
203  const Matrix<Double>& world,
204  Vector<Bool>& failures) const;
205  // </group>
206 
207 
208  // Make absolute coordinates relative and vice-versa (with
209  // respect to the referencfe value).
210  // Vectors must be length <src>nPixelAxes()</src> or
211  // <src>nWorldAxes()</src> or memory access errors will occur
212  // <group>
213  virtual void makePixelRelative (Vector<Double>& pixel) const {pixel -= crpix_p;};
214  virtual void makePixelAbsolute (Vector<Double>& pixel) const {pixel += crpix_p;};
215  virtual void makeWorldRelative (Vector<Double>& world) const {world -= crval_p;};
216  virtual void makeWorldAbsolute (Vector<Double>& world) const {world += crval_p;};
217  // </group>
218 
219  // Return the requested attribute.
220  // <group>
221  virtual Vector<String> worldAxisNames() const;
222  virtual Vector<Double> referencePixel() const;
223  virtual Matrix<Double> linearTransform() const;
224  virtual Vector<Double> increment() const;
225  virtual Vector<Double> referenceValue() const;
226  // </group>
227 
228  // Set the value of the requested attribute. Note that these just
229  // change the internal values, they do not cause any recomputation.
230  // <group>
231  virtual Bool setWorldAxisNames(const Vector<String> &names);
232  virtual Bool setReferencePixel(const Vector<Double> &refPix);
233  virtual Bool setLinearTransform(const Matrix<Double> &xform);
234  virtual Bool setIncrement(const Vector<Double> &inc) ;
235  virtual Bool setReferenceValue(const Vector<Double> &refval);
236  // </group>
237 
238  // Set/get the axis unit. Adjust the increment and
239  // reference value by the ratio of the old and new units.
240  // The unit must be compatible with the current units.
241  // <group>
242  virtual Bool setWorldAxisUnits(const Vector<String> &units);
243  virtual Vector<String> worldAxisUnits() const;
244  // </group>
245 
246  // Overwrite the world axis units with no compatibility
247  // checks or adjustment.
249 
250  // Get the table, i.e. the pixel and world values. The length of these
251  // Vectors will be zero if this axis is pure linear.
252  // <group>
253  Vector<Double> pixelValues() const;
254  Vector<Double> worldValues() const;
255  // </group>
256 
257  // Comparison function. Any private Double data members are compared
258  // with the specified fractional tolerance. Don't compare on the specified
259  // axes in the Coordinate. If the comparison returns False, method
260  // errorMessage() contains a message about why.
261  // <group>
262  virtual Bool near(const Coordinate& other,
263  Double tol=1e-6) const;
264  virtual Bool near(const Coordinate& other,
265  const Vector<Int>& excludeAxes,
266  Double tol=1e-6) const;
267  // </group>
268 
269  // Find the Coordinate for when we Fourier Transform ourselves. This pointer
270  // must be deleted by the caller. Axes specifies which axes of the Coordinate
271  // you wish to transform. Shape specifies the shape of the image
272  // associated with all the axes of the Coordinate. Currently the
273  // output reference pixel is always shape/2. If the pointer returned is 0,
274  // it failed with a message in <src>errorMessage</src>
275  virtual Coordinate* makeFourierCoordinate (const Vector<Bool>& axes,
276  const Vector<Int>& shape) const;
277 
278  // Save the TabularCoordinate into the supplied record using the supplied field name.
279  // The field must not exist, otherwise <src>False</src> is returned.
280  virtual Bool save(RecordInterface &container, const String &fieldName) const;
281 
282  // Recover the TabularCoordinate from a record.
283  // A null pointer means that the restoration did not succeed - probably
284  // because fieldName doesn't exist or doesn't contain a CoordinateSystem.
285  static TabularCoordinate *restore(const RecordInterface &container,
286  const String &fieldName);
287 
288  // Make a copy of the TabularCoordinate using new. The caller is responsible for calling
289  // delete.
290  virtual Coordinate *clone() const;
291 
292 private:
297 
298  // Channel_True = channel_corrections_p(Channel_average).
299  // <group>
302  // </group>
303 
304  // Common for assignment operator and destructor.
305  void clear_self();
306 
307  // Common code for copy ctor and assignment operator.
308  void copy(const TabularCoordinate &other);
309 
310  void makeNonLinearTabularCoordinate(const Vector<Double> &pixelValues,
311  const Vector<Double> &worldValues);
312 };
313 
314 } //# NAMESPACE CASACORE - END
315 
316 
317 #endif
void copy(const TabularCoordinate &other)
Common code for copy ctor and assignment operator.
virtual Vector< Double > referenceValue() const
virtual void makePixelAbsolute(Vector< Double > &pixel) const
static TabularCoordinate * restore(const RecordInterface &container, const String &fieldName)
Recover the TabularCoordinate from a record.
virtual Bool setLinearTransform(const Matrix< Double > &xform)
TabularCoordinate()
Default constructor.
virtual Bool toWorldMany(Matrix< Double > &world, const Matrix< Double > &pixel, Vector< Bool > &failures) const
Batch up a lot of transformations.
Table lookup 1-D coordinate, with interpolation.
Interpolate in one dimension.
Vector< Double > pixelValues() const
Get the table, i.e.
virtual Coordinate * clone() const
Make a copy of the TabularCoordinate using new.
virtual Coordinate::Type type() const
Returns Coordinate::TABULAR.
Vector< Double > worldValues() const
virtual Bool setReferenceValue(const Vector< Double > &refval)
virtual uInt nPixelAxes() const
Always returns 1.
ostream-like interface to creating log messages.
Definition: LogIO.h:167
virtual uInt nWorldAxes() const
virtual Bool toPixel(Vector< Double > &pixel, const Vector< Double > &world) const
TabularCoordinate & operator=(const TabularCoordinate &other)
Assignment (copy semantics).
virtual void makeWorldRelative(Vector< Double > &world) const
Bool overwriteWorldAxisUnits(const Vector< String > &units)
Overwrite the world axis units with no compatibility checks or adjustment.
virtual Bool near(const Coordinate &other, Double tol=1e-6) const
Comparison function.
virtual Bool toPixelMany(Matrix< Double > &pixel, const Matrix< Double > &world, Vector< Bool > &failures) const
virtual Vector< Double > referencePixel() const
virtual Vector< Double > increment() const
virtual Bool setIncrement(const Vector< Double > &inc)
virtual Bool save(RecordInterface &container, const String &fieldName) const
Save the TabularCoordinate into the supplied record using the supplied field name.
virtual void makePixelRelative(Vector< Double > &pixel) const
Make absolute coordinates relative and vice-versa (with respect to the referencfe value)...
virtual Bool setReferencePixel(const Vector< Double > &refPix)
void clear_self()
Common for assignment operator and destructor.
Interface for converting between world and pixel coordinates.
Definition: Coordinate.h:139
double Double
Definition: aipstype.h:55
virtual Vector< String > worldAxisNames() const
Return the requested attribute.
virtual void makeWorldAbsolute(Vector< Double > &world) const
virtual Coordinate * makeFourierCoordinate(const Vector< Bool > &axes, const Vector< Int > &shape) const
Find the Coordinate for when we Fourier Transform ourselves.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual Matrix< Double > linearTransform() const
virtual Bool setWorldAxisNames(const Vector< String > &names)
Set the value of the requested attribute.
Quantities (i.e. dimensioned values)
Definition: MeasValue.h:41
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:1987
Type
This enum lists the types of the derived classes.
Definition: Coordinate.h:144
virtual Bool toWorld(Vector< Double > &world, const Vector< Double > &pixel, Bool=True) const
Convert a pixel position to a world position or vice versa.
virtual String showType() const
Always returns the String &quot;Tabular&quot;.
const Double e
e and functions thereof:
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Interpolate1D< Double, Double > * channel_corrector_p
Channel_True = channel_corrections_p(Channel_average).
Abstract base class for Record classes.
virtual Bool setWorldAxisUnits(const Vector< String > &units)
Set/get the axis unit.
virtual ~TabularCoordinate()
Destructor.
Interpolate1D< Double, Double > * channel_corrector_rev_p
void makeNonLinearTabularCoordinate(const Vector< Double > &pixelValues, const Vector< Double > &worldValues)
const Bool True
Definition: aipstype.h:43
virtual Vector< String > worldAxisUnits() const
unsigned int uInt
Definition: aipstype.h:51