casacore
CoordinateSystem.h
Go to the documentation of this file.
1 //# CoordinateSystem.h: Interconvert pixel and image coordinates.
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_COORDINATESYSTEM_H
31 #define COORDINATES_COORDINATESYSTEM_H
32 
33 #include <casacore/casa/aips.h>
34 #include <casacore/coordinates/Coordinates/Coordinate.h>
35 #include <casacore/measures/Measures/MDirection.h>
36 #include <casacore/measures/Measures/MFrequency.h>
37 #include <casacore/coordinates/Coordinates/ObsInfo.h>
38 #include <casacore/casa/Containers/Block.h>
39 #include <casacore/measures/Measures/MDoppler.h>
40 
41 namespace casacore { //# NAMESPACE CASACORE - BEGIN
42 
43 template<class T> class Matrix;
44 class DirectionCoordinate;
45 class LinearCoordinate;
46 class SpectralCoordinate;
47 class StokesCoordinate;
48 class QualityCoordinate;
49 class TabularCoordinate;
50 class IPosition;
51 class LogIO;
52 
53 
54 // <summary>
55 // Interconvert pixel and world coordinates.
56 // </summary>
57 
58 // <use visibility=export>
59 
60 // <reviewed reviewer="Peter Barnes" date="1999/12/24" tests="tCoordinateSystem">
61 // </reviewed>
62 //
63 // <prerequisite>
64 // <li> <linkto class=Coordinate>Coordinate</linkto>
65 // </prerequisite>
66 
67 // <synopsis>
68 // CoordinateSystem is the normal interface to coordinate systems,
69 // typically attached to an
70 // <linkto class=ImageInterface>ImageInterface</linkto>, however the
71 // coordinate system can be manipulated on its own. CoordinateSystem
72 // is in turn composed from various classes derived from the base class
73 // <linkto class=Coordinate>Coordinate</linkto>.
74 // <p>
75 // The fundamental operations available to the user of a
76 // CoordinateSystem are:
77 // <ol>
78 // <li> Transform a world (physical) coordinate to a pixel coordinate
79 // or vice versa via the methods toWorld and toPixel.
80 // <li> Compose a CoordinateSystem from one or more independent groups,
81 // typically the sky-plane transformation will be one group, and the
82 // spectral axis will be another group. Each group consists of a linear
83 // transformation (in FITS terms, apply <src>CRPIX, PC, CDELT</src>)
84 // to turn the pixel coordinates into relative world coordinates,
85 // followed by a (possibly) nonlinear projection to world coordinates
86 // (i.e. apply <src>CTYPE and CRVAL</src>), typically a sky projection
87 // or a frequency to velocity conversion. Note that an arbitrary rotation
88 // or linear transformation can be applied by changing the
89 // matrix.
90 // <li> Transpose the world and/or pixel axes.
91 // <li> One or more pixel or world axes may be removed. You are encouraged to
92 // leave all the world axes if you remove a pixel axis.
93 // Removing a world axis also removes the corresponding pixel axis.
94 // <li> Calculate the CoordinateSystem that results from a subimage
95 // operation.
96 // </ol>
97 //
98 // Note that all the knowledge to do with removing and transposing axes is
99 // maintained by the CoordinateSystem. The individual Coordinates, of which it
100 // is made, know nothing about this.
101 // <p>
102 // Although the CoordinateSystem exists in the absence of an image, the usual
103 // place you will find one is attached to an object derived from ImageInterface
104 // such as PagedImage. When you do so, the physical (or pixel) axes in the image
105 // map one to one with the pixel axes contained in the CoordinateSystem.
106 // It cannot be any other way as when you create a PagedImage, it is checked
107 // that there are equal numbers of image and CoordinateSystem pixel axes.
108 // It is up to the creator of the PagedImage to make sure that they are
109 // in the correct order.
110 // <p>
111 // However, the CoordinateSystem may have more world axes than pixel axes
112 // because it is possible to remove a pixel axis but not its associated
113 // world axis (for example for a moment image). Now, if you use
114 // the CoordinateSystem functions
115 // referencePixel and referenceValue, you will find the vector of reference
116 // values will have more values than the vector of reference pixels,
117 // if a pixel axis has been removed but not the world axis. You
118 // must use the ancilliary functions provided
119 // to find out what is where.
120 // <p>
121 // Let's consider an example where a CoordinateSystem consisted of
122 // a DirectionCoordinate and a SpectralCoordinate. Let us say that
123 // the first two pixel axes of the image associate (roughly of course
124 // because lines of constant RA and DEC are not parallel with
125 // the pixel coordinates) with the DirectionCoordinate (RA and DEC say)
126 // and the third pixel axis is the SpectralCoordinate.
127 // Now imagine we collapse the image along the second pixel axis (roughly,
128 // the DEC axis). For the output image, we remove the second pixel axis
129 // from the CoordinateSystem, but leave the world axis intact. This enables
130 // us to still be able to make coordinate conversions for the first (roughly RA)
131 // pixel axis. Thus, CoordinateSystem::referenceValue would return a Vector of
132 // length 3 (for RA, DEC and spectral), but CoordinateSystem::referencePixel
133 // would return a vector length 2 (for RA and spectral).
134 // <p>
135 // Now this CoordinateSystem has two Coordinates, a DirectionCoordinate and
136 // a SpectralCoordinate, and let us state that that is the order in which
137 // they exist in the CoordinateSystem (you can change them about if you wish);
138 // they are coordinates number 0 and 1. The DirectionCoordinate has two axes
139 // (RA and DEC) and the SpectralCoordinate has one axis. Only the
140 // CoordinateSystem knows about removed axes, the DirectionCoordinate
141 // itself is ignorant that it has been bisected. If you want to find
142 // out what axis in the Coordinate system is where, you can use
143 // the functions findPixelAxis or findWorldAxis.
144 //
145 // If we asked the former to find pixel axis 0, it would tell us that the
146 // Coordinate number was 0 (the DirectionCoordinate) and that the axis in
147 // that coordinate was 0 (the first axis in a DirectionCoordinate
148 // is always longitude, the second always latitude). If we asked it to find
149 // pixel axis 1, it would tell us that the coordinate number was 1
150 // (the SpectralCoordinate) and that the axis in that coordinate was 0
151 // (there is only one axis in a SpectralCoordinate). If we asked for
152 // pixelAxis 2 that would generate an error because our squashed image
153 // only has 2 pixel axes.
154 //
155 // Now, if we asked findWorldAxis similar questions,
156 // it would tell us that worldAxis 0 in the CoordinateSystem can be found in
157 // coordinate 0 (the DirectionCoordinate) in axis 0 of that DirectionCoordinate.
158 // Similarly, worldAxis 1 in the CoordinateSystem (which has not been removed)
159 // is in coordinate 0 (the DirectionCoordinate) in axis 1 of that
160 // Finally, worldAxis 2 in the CoordinateSystem is in coordinate 1
161 // (the SpectralCoordinate) in axis 0 of that SpectralCoordinate.
162 // <p>
163 // Other handy functions are pixelAxes and worldAxes.
164 // These list the pixel and world axes in
165 // the CoordinateSystem for the specified coordinate. Thus, if we asked
166 // pixelAxes to find the pixel axes for coordinate 0 (the DirectionCoordinate)
167 // in the CoordinateSystem it would return a vector [0, -1] indicating
168 // the second axis of the DirectionCoordinate has been removed. However,
169 // the worldAxes function would return [0,1] as no world axis has been removed.
170 // Similarly, if operated on coordinate 1 (the SpectralCoordinate), pixelAxes
171 // would return [1] and worldAxes would return [2].
172 //
173 // Because you can transpose the CoordinateSystem about, you should NEVER ASSUME
174 // ANYTHING except that the pixel axes of the CoordinateSystem map to the pixel
175 // axes of the image when you first construct the image.
176 //
177 // <p>
178 // SpectralCoordinate and DirectionCoordinate both have a (non-virtual) function
179 // called <src>setReferenceConversion</src>. This enables an extra conversion
180 // layer so that conversion between pixel and world can go to a reference frame
181 // other than the construction reference. When you use the function
182 // <src>convert</src>, these layers are active, but ONLY if the
183 // requested conversion is purely between pixel and world. For
184 // a SpectralCoordinate this must always be true (only has one axis)
185 // but for the DirectionCoordinate you might request a mixed
186 // pixel/world conversion. In this case, the extra conversion layer
187 // is ill-defined and not active (for the DirectionCoordinate part of it).
188 // </synopsis>
189 
190 // <note role=caution>
191 // All pixels coordinates are zero relative.
192 // </note>
193 
194 // <example>
195 // See the example in <linkto module=Coordinates>Coordinates.h</linkto>
196 // and tCoordinateSystem.cc
197 // </example>
198 
199 // <motivation>
200 // Coordinate systems for images.
201 // </motivation>
202 //
203 // <thrown>
204 // <li> AipsError
205 // </thrown>
206 //
207 // <todo asof="1997/01/13">
208 // <li> Undelete individual removed axes.
209 // <li> Non-integral pixel shifts/decimations in subimage operations?
210 // <li> Copy-on-write for efficiency?
211 // <li> Check if the classes are thread safe in general
212 // </todo>
213 //
214 
215 
217 {
218 public:
219  // Default constructor. This is an empty CoordinateSystem.
221 
222  // Copying constructor (copy semantics)
223  CoordinateSystem(const CoordinateSystem &other);
224 
225  // Assignment (copy semantics).
227 
228  // Destructor
229  virtual ~CoordinateSystem();
230 
231  // Add another Coordinate to this CoordinateSystem. This addition is done
232  // by copying, so that if coord changes the change is NOT
233  // reflected in the CoordinateSystem.
234  void addCoordinate(const Coordinate &coord);
235 
236  // Transpose the CoordinateSystem so that world axis 0 is
237  // newWorldOrder(0) and so on for all the other axes.
238  // newPixelOrder works similarly. Normally you will give the
239  // same transformation vector for both the world and pixel transformations,
240  // however this is not required.
241  void transpose(const Vector<Int> &newWorldOrder,
242  const Vector<Int> &newPixelOrder);
243 
244  // Find the world and pixel axis mappings to the supplied CoordinateSystem
245  // from the current coordinate system. <src>False</src> is
246  // returned if either the supplied or current coordinate system,
247  // has no world axes (and a message recoverable with function
248  // errorMessage indicating why). Otherwise <src>True</src> is returned.
249  // worldAxisMap(i) is the location of world axis <src>i</src> (from the
250  // supplied CoordinateSystem, cSys, in the current CoordinateSystem.
251  // worldAxisTranspose(i) is the location of world axis
252  // <src>i</src> (from the current CoordinateSystem) in the supplied
253  // CoordinateSystem, cSys. The output vectors
254  // are resized appropriately by this function. A value of -1
255  // in either vector means that the axis could not be found in the other
256  // CoordinateSystem. The vector <src>refChange</src> says
257  // if the types are the same, is there a reference type change
258  // (e.g. TOPO versus LSR for the SpectralCoordinate,
259  // or J2000 versus GALACTIC for DirectionCoordinate). Thus
260  // if refChange(i) is True, it means world axis i in the
261  // current CoordinateSystem was matched, but has a different
262  // reference type to that of the supplied CoordinateSystem.
263  // <group>
264  Bool worldMap (Vector<Int>& worldAxisMap,
265  Vector<Int>& worldAxisTranspose,
266  Vector<Bool>& refChange,
267  const CoordinateSystem& cSys) const;
268  Bool pixelMap (Vector<Int>& pixelAxisMap,
269  Vector<Int>& pixelAxisTranspose,
270  const CoordinateSystem& cSys) const;
271  // </group>
272 
273  // Remove a world or pixel axis. When its value is required for forward or
274  // backwards transformations, use <src>replacement</src>
275  // <br>
276  // When a world axis is removed, the corresponding pixel axis is removed
277  // too, because it makes no sense having a pixel axis without world
278  // coordinates.
279  // <br>
280  // Removing a pixel axis without removing the corresponding world axis
281  // is, however, possible and meaningful. It can be used when e.g. a
282  // frequency plane is taken from a cube. The plane has 2 pixel axes, but
283  // the 3rd world axis can still describe the frequency coordinate.
284  // See also the functions in <linkto class=CoordinateUtil>CoordinateUtil</linkto>
285  // for removing lists of pixel/world axes (tricky because they shift down)
286  //
287  // False is returned (an error in <src>errorMessage()</src> will be set)
288  // if the axis is illegal, else returns True.
289  // <group>
290  Bool removeWorldAxis(uInt axis, Double replacement);
291  Bool removePixelAxis(uInt axis, Double replacement);
292  // </group>
293 
294  // Return a CoordinateSystem appropriate for a shift of origin
295  // (the shift is subtracted from the reference pixel)
296  // and change of increment (the increments are multipled
297  // by the factor). Both vectors should be of length nPixelAxes().
298  //
299  // The newShape vector is only needed for the StokesCoordinate,
300  // if any. If this vector is of length zero, the new StokesCoordinate
301  // is formed from all of the available input Stokes after application
302  // of the shift and increment factor. Otherwise,
303  // the new Stokes axis length is equal to that specified after
304  // appliction of the shift and increment and excess values
305  // discarded. In addition, for any StokesCoordinate, the
306  // shift and factor must be integer. So <src>Int(value+0.5)</src>
307  // is taken before they are used.
308  // <group>
309  CoordinateSystem subImage(const Vector<Float> &originShift,
310  const Vector<Float> &incrFac,
311  const Vector<Int>& newShape) const;
312  void subImageInSitu (const Vector<Float> &originShift,
313  const Vector<Float> &incrFac,
314  const Vector<Int>& newShape);
315  // </group>
316 
317  // Untranspose and undelete all axes. Does not undo the effects of
318  // subimaging.
319  void restoreOriginal();
320 
321  // Returns the number of Coordinates that this CoordinateSystem contains.
322  // The order might be unrelated to the axis order through the results of
323  // transposing and removing axes.
324  uInt nCoordinates() const;
325 
326  // For a given Coordinate say where its world and pixel axes are in
327  // this CoordinateSystem. The position in the returned Vector is its
328  // axis number in the Coordinate, and its value is the axis
329  // number in the CoordinateSystem. If the value is less than zero the axis
330  // has been removed from this CoordinateSystem.
331  // <group>
332  Vector<Int> worldAxes(uInt whichCoord) const;
333  Vector<Int> pixelAxes(uInt whichCoord) const;
334  // </group>
335 
336  // Return the type of the given Coordinate.
337  Coordinate::Type type(uInt whichCoordinate) const;
338 
339  // Returns the type of the given Coordinate as a string.
340  String showType(uInt whichCoordinate) const;
341 
342  // Return the given Coordinate as a reference to the base
343  // class object.
344  const Coordinate& coordinate(uInt which) const;
345 
346  // Return the given Coordinate.
347  // Throws an exception if retrieved as the wrong type.
348  // The versions which take no parameters will return the
349  // first (or in most cases only) coordinate of the requested type.
350  // If no such coordinate exists, an exception is thrown.
351  // <group>
352  const LinearCoordinate &linearCoordinate(uInt which) const;
354  const DirectionCoordinate &directionCoordinate(uInt which) const;
355 
356  const SpectralCoordinate &spectralCoordinate(uInt which) const;
357  const SpectralCoordinate &spectralCoordinate() const;
358  const StokesCoordinate &stokesCoordinate() const;
359 
360  const StokesCoordinate &stokesCoordinate(uInt which) const;
361  const QualityCoordinate &qualityCoordinate(uInt which) const;
362  const TabularCoordinate &tabularCoordinate(uInt which) const;
363  // </group>
364 
365  // Replace one Coordinate with another. The mapping of the coordinate axes
366  // to the CoordinateSystem axes is unchanged, therefore the number of world
367  // and pixel axes must not be changed. You can, somewhat dangerously,
368  // change the type of the coordinate however. For example, replace a
369  // SpectralCoordinate with a 1-D Linearcoordinate. It is dangerous because
370  // the world replacement values (see removeWorldAxis) have to be scaled.
371  // The algorithm tries to find a scale factor between the old and new
372  // units and applies it to the replacement values. If it can't find
373  // a scale factor (non-conformant units) then the reference value is
374  // used for any world replacement values. If the latter occurs,
375  // it returns False, else True is returned.
376  Bool replaceCoordinate(const Coordinate &newCoordinate, uInt whichCoordinate);
377 
378  // Find the Coordinate number that corresponds to the given type.
379  // Since there might be more than one Coordinate of a given type you
380  // can call this multiple times setting <src>afterCoord</src> to
381  // the last value found. Returns -1 if a Coordinate of the desired
382  // type is not found.
383  Int findCoordinate(Coordinate::Type type, Int afterCoord = -1) const;
384 
385  // Given an axis number (pixel or world) in the CoordinateSystem,
386  // find the corresponding coordinate number and axis in that Coordinate.
387  // The returned values are set to -1 if the axis does not exist.
388  // <group>
389  void findWorldAxis(Int &coordinate, Int &axisInCoordinate,
390  uInt axisInCoordinateSystem) const;
391  void findPixelAxis(Int &coordinate, Int &axisInCoordinate,
392  uInt axisInCoordinateSystem) const;
393  // </group>
394 
395  // Find the world axis for the given pixel axis in a CoordinateSystem.
396  // Returns -1 if the world axis is unavailable (e.g. if it has been
397  // removed).
398  Int pixelAxisToWorldAxis(uInt pixelAxis) const;
399 
400  // Find the pixel axis for the given world axis in a CoordinateSystem.
401  // Returns -1 if the pixel axis is unavailable (e.g. if it has been
402  // removed).
403  Int worldAxisToPixelAxis(uInt worldAxis) const;
404 
405  // Return the name of the record field in which the coordinate is stored.
406  String coordRecordName(uInt which) const;
407 
408  // Returns <src>Coordinate::COORDSYS</src>
409  virtual Coordinate::Type type() const;
410 
411  // Always returns "System"
412  virtual String showType() const;
413 
414  // Sums the number of axes in the Coordinates that the CoordinateSystem
415  // contains, allowing for removed axes.
416  // <group>
417  virtual uInt nPixelAxes() const;
418  virtual uInt nWorldAxes() const;
419  // </group>
420 
421 
422  // Convert a pixel position to a world position or vice versa. Returns True
423  // if the conversion succeeds, otherwise it returns <src>False</src> and
424  // <src>errorMessage()</src> contains an error message.
425  // The input vector must be of length <src>nPixelAxes</src> or
426  // <src>nWorldAxes</src>. The output vector is resized appropriately.
427  // if <src>useConversionFrame</src>, if the coordinate has a conversion layer frame
428  // (such as can be present in spectral and direction coordinates), it
429  // is used. Else, the native frame is used for the conversion.
430  // <group>
431  virtual Bool toWorld(Vector<Double> &world,
432  const Vector<Double> &pixel, Bool useConversionFrame=True) const;
433  // This one throws an exception rather than returning False. After all, that's
434  // what exceptions are for.
435  virtual Vector<Double> toWorld(const Vector<Double> &pixel) const;
436  virtual Bool toPixel(Vector<Double> &pixel,
437  const Vector<Double> &world) const;
438  // This one throws an exception rather than returning False.
439  virtual Vector<Double> toPixel(const Vector<Double> &world) const;
440  // </group>
441 
442  // convert a pixel "length" to a world "length"
443  virtual Quantity toWorldLength(
444  const Double nPixels,
445  const uInt pixelAxis
446  ) const;
447 
448  // This is provided as a convenience since it is a very commonly desired
449  // operation through CoordinateSystem. The output vector is resized.
450  Bool toWorld(Vector<Double> &world, const IPosition &pixel) const;
451  Vector<Double> toWorld(const IPosition& pixel) const;
452 
453  // Batch up a lot of transformations. The first (most rapidly varying) axis
454  // of the matrices contain the coordinates. Returns False if any conversion
455  // failed and <src>errorMessage()</src> will hold a message.
456  // The <src>failures</src> array (True for fail, False for success)
457  // is the length of the number of conversions and
458  // holds an error status for each conversion.
459  // <group>
460  virtual Bool toWorldMany(Matrix<Double>& world,
461  const Matrix<Double>& pixel,
462  Vector<Bool>& failures) const;
463  virtual Bool toPixelMany(Matrix<Double>& pixel,
464  const Matrix<Double>& world,
465  Vector<Bool>& failures) const;
466  // </group>
467 
468 
469  // Mixed pixel/world coordinate conversion.
470  // <src>worldIn</src> and <src>worldAxes</src> are of length n<src>worldAxes</src>.
471  // <src>pixelIn</src> and <src>pixelAxes</src> are of length nPixelAxes.
472  // <src>worldAxes(i)=True</src> specifies you have given a world
473  // value in <src>worldIn(i)</src> to convert to pixel.
474  // <src>pixelAxes(i)=True</src> specifies you have given a pixel
475  // value in <src>pixelIn(i)</src> to convert to world.
476  // You cannot specify the same axis via <src>worldAxes</src>
477  // and pixelAxes.
478  // Values in <src>pixelIn</src> are converted to world and
479  // put into <src>worldOut</src> in the appropriate world axis
480  // location. Values in <src>worldIn</src> are copied to
481  // <src>worldOut</src>.
482  // Values in <src>worldIn</src> are converted to pixel and
483  // put into <src>pixelOut</src> in the appropriate pixel axis
484  // location. Values in <src>pixelIn</src> are copied to
485  // <src>pixelOut</src>. Vectors
486  // <src>worldMin</src> and <src>worldMax</src> specify the range of the world
487  // coordinate (in the world axis units of that world axis
488  // in the coordinate system) being solved for in a mixed calculation
489  // for each world axis. They are only actually used for DirectionCoordinates
490  // and for all other coordinates the relevant elements are ignored.
491  // Functions <src>setWorldMixRanges, worldMixMin, worldMixMax</src> can be
492  // used to compute and recover the world ranges. If you don't know
493  // the values, use functions <src>setDefaultWorldMixRanges, worldMixMin, worldMixMax</src>.
494  // Removed axes are handled (for example, a removed pixel
495  // axis with remaining corresponding world axis will
496  // correctly be converted to world using the replacement
497  // value).
498  // Returns True if the conversion succeeds, otherwise it returns <src>False</src> and
499  // <src>errorMessage()</src> contains an error message. The output vectors
500  // are resized.
501  virtual Bool toMix(Vector<Double>& worldOut,
502  Vector<Double>& pixelOut,
503  const Vector<Double>& worldIn,
504  const Vector<Double>& pixelIn,
505  const Vector<Bool>& worldAxes,
506  const Vector<Bool>& pixelAxes,
507  const Vector<Double>& worldMin,
508  const Vector<Double>& worldMax) const;
509 
510  // Compute and recover the world min and max ranges, for use in function <src>toMix</src>,
511  // for a lattice of the given shape (must be of length <src>nPixelAxes()</src>).
512  // Removed pixel axes (with remaining world axes are handled). With
513  // the retrieval functions, the output vectors are resized. They return
514  // False if they fail (and then <src>setDefaultWorldMixRanges</src> generates the ranges)
515  // with a reason in <src>errorMessage()</src>.
516  // The <src>setDefaultWorldMixRanges</src> function
517  // gives you a useful default range if you don't know the shape.
518  // The only Coordinate type for which these ranges are actually
519  // used in <src>toMix</src> is DirectionCoordinate (because its coupled). For
520  // the rest the functionality is provided but never used
521  // by toMix.
522  //<group>
523  virtual Bool setWorldMixRanges (const IPosition& shape);
524  virtual void setDefaultWorldMixRanges ();
525  virtual Vector<Double> worldMixMin () const;
526  virtual Vector<Double> worldMixMax () const;
527  //</group>
528 
529  // Make absolute coordinates relative and vice-versa (relative
530  // to the reference pixel/value). The vectors must be of length
531  // <src>nPixelAxes()</src> or <src>nWorldAxes()</src>
532  //<group>
533  virtual void makePixelRelative (Vector<Double>& pixel) const;
534  virtual void makePixelAbsolute (Vector<Double>& pixel) const;
535  virtual void makeWorldRelative (Vector<Double>& world) const;
536  virtual void makeWorldAbsolute (Vector<Double>& world) const;
537  //</group>
538 
539  // Make absolute coordinates relative and vice versa with respect
540  // to the given reference value. Add the other functions in this grouping
541  // as needed. The vectors must be of length
542  // <src>nPixelAxes()</src> or <src>nWorldAxes()</src>
543  //<group>
544  virtual void makeWorldAbsoluteRef (Vector<Double>& world,
545  const Vector<Double>& refVal) const;
546  //</group>
547 
548  // Batch up a lot of absolute/relative transformations.
549  // Parameters as above for
550  // <src>toWorldMany</src> and <src>toPixelMany</src>
551  // <group>
552  virtual void makePixelRelativeMany (Matrix<Double>& pixel) const;
553  virtual void makePixelAbsoluteMany (Matrix<Double>& pixel) const;
554  virtual void makeWorldRelativeMany (Matrix<Double>& world) const;
555  virtual void makeWorldAbsoluteMany (Matrix<Double>& world) const;
556  // </group>
557 
558 
559  // General coordinate conversion. Only works if no axes
560  // have been removed and no axis reordering has occurred.
561  // That is pixel axes and world axes are the same.
562  //
563  // Specify the input coordinate values, input units,
564  // whether value is absolute (or relative). For output
565  // specify units and abs/rel. Units may be 'pix' and velocity consistent
566  // units (e.g. m/s). Specify doppler types if velocities
567  // involved. The pixel offsets allow for the input
568  // and output pixel coordinates to be something other than 0-rel.
569  // If your pixel coordinates are 1-rel input and output, set the
570  // offsets to -1 and 1
571  //
572  // The Matrix interface lets you do many conversions efficiently.
573  // Use <src>Matrix(nAxes, nConversions) </src> and
574  // <src>Matrix.column()=coordinate</src> or
575  // <src>Matrix(axis, iConversion)</src> to get the order right.
576  //
577  // These functions invoke <src>toMix</src>
578  // so make sure you call <src>setWorldMixRanges</src>
579  // first to set up the world ranges.
580  // <group>
581  Bool convert (Vector<Double>& coordOut,
582  const Vector<Double>& coordin,
583  const Vector<Bool>& absIn,
584  const Vector<String>& unitsIn,
585  MDoppler::Types dopplerIn,
586  const Vector<Bool>& absOut,
587  const Vector<String>& unitsOut,
588  MDoppler::Types dopplerOut,
589  Double pixInOffset = 0.0,
590  Double pixOutOffset = 0.0);
591  Bool convert (Matrix<Double>& coordOut,
592  const Matrix<Double>& coordIn,
593  const Vector<Bool>& absIn,
594  const Vector<String>& unitsIn,
595  MDoppler::Types dopplerIn,
596  const Vector<Bool>& absOut,
597  const Vector<String>& unitsOut,
598  MDoppler::Types dopplerOut,
599  Double pixInOffset = 0.0,
600  Double pixOutOffset = 0.0);
601  // </group>
602 
603  // Return the requested attribute.
604  // <group>
605  virtual Vector<String> worldAxisNames() const;
606  virtual Vector<Double> referencePixel() const;
607  virtual Matrix<Double> linearTransform() const;
608  virtual Vector<Double> increment() const;
609  virtual Vector<Double> referenceValue() const;
610  // </group>
611 
612  // Set the requested attribute. Note that these just
613  // change the internal values, they do not cause any recomputation.
614  // <group>
615  virtual Bool setWorldAxisNames(const Vector<String> &names);
616  virtual Bool setReferencePixel(const Vector<Double> &refPix);
617  virtual Bool setLinearTransform(const Matrix<Double> &xform);
618  virtual Bool setIncrement(const Vector<Double> &inc);
619  virtual Bool setReferenceValue(const Vector<Double> &refval);
620  // </group>
621 
622  // Set/get the units. Adjust the increment and
623  // reference value by the ratio of the old and new units. This implies that
624  // the units must be known <linkto class=Unit>Unit</linkto> strings, and
625  // that they must be compatible, e.g. they can't change from time to
626  // length. If <src>throwException=True</src>, throw an exception rather than
627  // returning False on failure.
628  // <group>
629  virtual Bool setWorldAxisUnits(const Vector<String> &units);
631  Bool throwException);
632  virtual Vector<String> worldAxisUnits() const;
633  // </group>
634 
635  // Comparison function. Any private Double data members are compared
636  // with the specified fractional tolerance. Don't compare on the specified
637  // pixel axes in the CoordinateSystem. If the comparison returns
638  // <src>False</src>, errorMessage() contains a message about why.
639  // <group>
640  virtual Bool near(const Coordinate& other, Double tol=1e-6) const;
641  virtual Bool near(const Coordinate& other,
642  const Vector<Int>& excludePixelAxes,
643  Double tol=1e-6) const;
644  // </group>
645 
646  // This function compares this and the other coordinate system,
647  // but ONLY for the non-removed pixel axes. It is less strict
648  // than near, which, for example, insists the number of coordinates
649  // is the same in each CS
650  Bool nearPixel (const CoordinateSystem& other, Double tol=1e-6) const;
651 
652 
653  // Format a world value nicely through the
654  // common format interface. See <linkto class=Coordinate>Coordinate</linkto>
655  // for basics.
656  //
657  // You specify a world value and its corresponding world axis in
658  // the CoordinateSystem.
659  //
660  // For the specified worldAxis, the coordinate
661  // number in the CoordinateSystem is found and the actual derived Coordinate
662  // class object for that number is created. The arguments to the formatting
663  // function are then passed on to the formatter for that Coordinate. So
664  // refer to the other derived Coordinate classes for specifics on the
665  // formatting.
666  virtual String format(
667  String& units,
669  Double worldValue,
670  uInt worldAxis,
671  Bool isAbsolute=True,
672  Bool showAsAbsolute=True,
673  Int precision=-1, Bool usePrecForMixed=False
674  ) const;
675 
676  // Miscellaneous information related to an observation, for example the
677  // observation date.
678  // <group>
679  ObsInfo obsInfo() const;
680  void setObsInfo(const ObsInfo &obsinfo);
681  // </group>
682 
683  // Find the CoordinateSystem (you can safely caste the pointer to a CoordinateSystem)
684  // for when we Fourier Transform ourselves. This pointer
685  // must be deleted by the caller. Axes specifies which pixel axes of the Coordinate
686  // System you wish to transform. Shape specifies the shape of the image
687  // associated with all the axes of the CoordinateSystem. Currently you have
688  // no control over the reference pixel, it is always shape/2.
689  virtual Coordinate* makeFourierCoordinate (const Vector<Bool>& axes,
690  const Vector<Int>& shape) const;
691 
692 
693  // Save the CoordinateSystem into the supplied record using the supplied field name.
694  // The field must not exist, otherwise <src>False</src> is returned.
695  // If the CoordinateSystem is empty <src>False</src> is also returned.
696  // If <src>False</src> is returned, errorMessage() contains a message about why.
697  virtual Bool save(RecordInterface &container,
698  const String &fieldName) const;
699 
700  // Restore the CoordinateSystem from a record. The <src>fieldName</src>
701  // can be empty, in which case the CoordinateSystem is restored
702  // directly from the Record, rather than a subrecord of it.
703  // A null pointer means that the restoration did not succeed - probably
704  // because fieldName doesn't exist or doesn't contain a CoordinateSystem.
705  static CoordinateSystem *restore(const RecordInterface &container,
706  const String &fieldName);
707 
708  // Make a copy of the CoordinateSystem using new. The caller is responsible for calling
709  // delete.
710  virtual Coordinate* clone() const;
711 
712  // Convert a CoordinateSystem to FITS, i.e. fill in ctype etc. In the record
713  // the keywords are vectors, it is expected that the actual FITS code will
714  // split them into scalars and upcase the names. Returns False if one of the
715  // keywords is already taken.
716  //
717  // If writeWCS is True, attempt to write the WCS convention (Greisen and
718  // Calabretta "Representation of celestial coordinates in FITS").
719  // Use <src>oneRelative=True</src> to convert zero-relative pixel coordinates to
720  // one-relative FITS coordinates.
721  //
722  // prefix gives the prefix for the FITS keywords. E.g.,
723  // if prefix="c" then crval, cdelt etc.
724  // if prefix="d" then drval, ddelt etc.
725  //# Much of the work in to/from fits should be moved to the individual
726  //# classes.
728  IPosition &shape,
729  Bool oneRelative,
730  Char prefix = 'c', Bool writeWCS=True,
731  Bool preferVelocity=True,
732  Bool opticalVelocity=True,
733  Bool preferWavelength=False,
734  Bool airWavelength=False) const;
735 
736  // Probably even if we return False we should set up the best linear
737  // coordinate that we can.
738  // Use oneRelative=True to convert one-relative FITS pixel coordinates to
739  // zero-relative Casacore coordinates.
740  // On output, <src>stokesFITSValue</src>
741  // holds the FITS value of any unofficial Stokes (beam, optical depth,
742  // spectral index) for the last unofficial value accessed (-1 if none).
743  // The idea is that if the Stokes axis is of length one and holds an
744  // unofficial value, you should drop the STokes axis and convert that
745  // value to <src>ImageInfo::ImageTypes</src> with
746  // <src>ImageInfo::imageTypeFromFITSValue</src>.
747  // If on input, <src>stokesFITSValue</src> is positive, then a warning
748  // is issued if any unofficial values are encountered.
749  // Otherwise no warning is issued.
750  //# cf comment in toFITS.
751  static Bool fromFITSHeader(Int& stokesFITSValue,
752  CoordinateSystem &coordsys,
753  RecordInterface& recHeader,
754  const Vector<String>& header,
755  const IPosition& shape,
756  uInt which=0);
757 
758 // List all header information. By default, the reference
759 // values and pixel increments are converted to a "nice" unit before
760 // formatting (e.g. RA is shown as HH:MM:SS.S).
761 // For spectral axes, both frequency and velocity information is listed. You
762 // can specify what velocity definition you want with <src>velocityType</src>
763 // If you wish, you can specify two shapes; a lattice and tile shape
764 // (perhaps an image from which the CoordinateSystem came)
765 // If you give (both of) these, they are included in the listing. If you pass
766 // in zero length <src>IPositions</src> then they are not included in
767 // the listing. If <src>postlocally=True</src> the formatted summary lines
768 // are written locally only to the sink, and then returned by the return value
769 // vector.
771  const IPosition& latticeShape,
772  const IPosition& tileShape, Bool postLocally=False) const;
773 
774  // Does this coordinate system have a spectral axis?
775  Bool hasSpectralAxis() const;
776 
777  // What number is the spectral axis?
778  // If doWorld=True, the world axis number is returned.
779  // Otherwise, the pixel axis number is returned.
780  // Returns -1 if the spectral axis (world c.q. pixel) does not exist.
781  Int spectralAxisNumber(Bool doWorld=False) const;
782 
783  // what number is the spectral coordinate?
784  // Returns -1 if no spectral coordinate exists.
786 
787 
788  // does this coordinate system have a polarizaion/stokes coordinate?
791  { return hasPolarizationCoordinate(); }
792 
793  // Given a stokes or polarization parameter, find the pixel location.
794  // Note the client is responsible for any boundedness checks
795  // (eg finite number of stokes in an image).
796  Int stokesPixelNumber(const String& stokesString) const;
797 
798  // what is the number of the polarization/stokes coordinate?
799  // Returns -1 if no stokes coordinate exists.
801 
802  // What is the number of the polarization/stokes axis?
803  // If doWorld=True, the world axis number is returned.
804  // Otherwise, the pixel axis number is returned.
805  // Returns -1 if the stokes axis (world c.q. pixel) does not exist.
806  Int polarizationAxisNumber(Bool doWorld=False) const;
807 
808  // Does this coordinate system have a quality axis?
809  Bool hasQualityAxis() const;
810 
811  // what number is the quality axis? Returns -1 if no quality axis exists.
812  Int qualityAxisNumber() const;
813 
814  // what is the number of the quality coordinate?
815  // Returns -1 if no quality coordinate exists.
817 
818  // Given a quality parameter, find the pixel location.
819  // Note the client is responsible for any boundedness checks
820  // (eg finite number of quality in an image).
821  Int qualityPixelNumber(const String& qualityString) const;
822 
823  String qualityAtPixel(const uInt pixel) const;
824 
826 
828 
829  // Get the pixel axis numbers of the direction coordinate in this object.
830  // The order of the returned axis numbers is always longitude axis first,
831  // latitude axis second.
833 
834  String stokesAtPixel(const uInt pixel) const;
835 
836  Int linearCoordinateNumber() const;
837 
838  Bool hasLinearCoordinate() const;
839 
841 
842  // Get the 0 based order of the minimal match strings specified in <src>order</src>.
843  // If <src>requireAll</src> is True, checks are done to ensure that all axes in
844  // the coordinate system are uniquely specified in <src>order</src>.
845  // If <src>allowFriendlyNames</src> is True, the following (fully specified) strings
846  // will match the specified axes:
847  // "spectral" matches both "frequency" and "velocity".
848  // "ra" matches "right ascension".
849  Vector<Int> getWorldAxesOrder(Vector<String>& myNames, Bool requireAll,
850  Bool allowFriendlyNames=False) const;
851 
852  // Is the abscissa in the DirectionCoordinate the longitude axis?
853  // Throws exception if there is no DirectionCoordinate or if either of
854  // the direction pixel axes have been removed.
855  // For a normal direction coordinate, this will return True.
857 
858  // Set Spectral conversion layer of SpectralCoordinate in CoordinateSystem
859  // so that pixel<->world go to the specified frequency system (a valid
860  // MFrequency::Types string). Returns False if frequency system invalid
861  // or if no DirectionCoordinate or if cant get Date/Epoch.
862  // <group>
863  Bool setSpectralConversion (String& errorMsg, const String frequencySystem);
864  // This version throws an exception rather than returning False.
865  void setSpectralConversion (const String frequencySystem);
866  //</group>
867 
868  // Set rest frequency of SpectralCoordinate in CoordinateSystem.
869  // Unit must be consistent with Hz or m.
870  // Returns False if invalid inputs (and CS not changed) and an error message.
871  Bool setRestFrequency (String& errorMsg, const Quantity& freq);
872 
873 private:
874  // Where we store copies of the coordinates we are created with.
876 
877  // For coordinate[i] axis[j],
878  // world_maps_p[i][j], if >=0 gives the location in the
879  // input vector that maps to this coord/axis,
880  // <0 means that the axis has been removed
881  // world_tmp_p[i] a temporary vector length coord[i]->nworldAxes()
882  // replacement_values_p[i][j] value to use for this axis if removed
886 
887  // Same meanings as for the world*'s above.
891 
892  // These temporaries all needed for the toMix function
899 
900  // Miscellaneous information about the observation associated with this
901  // Coordinate System.
903 
904  const static String _class;
906  static map<String, String> _friendlyAxisMap;
907 
908  static void _initFriendlyAxisMap();
909 
910  // Helper functions to group common code.
911  Bool mapOne(Vector<Int>& worldAxisMap,
912  Vector<Int>& worldAxisTranspose,
913  Vector<Bool>& refChange,
914  const CoordinateSystem& cSys,
915  const CoordinateSystem& cSys2,
916  const uInt coord, const uInt coord2) const;
917 
918  void copy(const CoordinateSystem &other);
919  void clear();
920  Bool checkAxesInThisCoordinate(const Vector<Bool>& axes, uInt which) const;
921 
922  // Delete some pointer blocks
925 
926  // Delete temporary maps
927  void deleteTemps (const uInt which);
928 
929  // Many abs/rel conversions
930  // <group>
931  void makeWorldAbsRelMany (Matrix<Double>& value, Bool toAbs) const;
932  void makePixelAbsRelMany (Matrix<Double>& value, Bool toAbs) const;
933  // </group>
934 
935  // Do subImage for Stokes
936  StokesCoordinate stokesSubImage(const StokesCoordinate& sc, Int originShift, Int pixincFac,
937  Int newShape) const;
938 
939  // Do subImage for Quality
940  QualityCoordinate qualitySubImage(const QualityCoordinate& qc, Int originShift, Int pixincFac,
941  Int newShape) const;
942 
943  // Strip out coordinates with all world and pixel axes removed
945 
946  // All these functions are in support of the <src>list</src> function
947  // <group>
948  void listDirectionSystem(LogIO& os) const;
949  void listFrequencySystem(LogIO& os, MDoppler::Types velocityType) const;
950  void listPointingCenter (LogIO& os) const;
951  void getFieldWidths (LogIO& os, uInt& widthAxis, uInt& widthCoordType,
952  uInt& widthCoordNumber, uInt& widthName,
953  uInt& widthProj, uInt& widthShape,
954  uInt& widthTile, uInt& widthRefValue,
955  uInt& widthRefPixel, uInt& widthInc,
956  uInt& widthUnits, Int& precRefValSci,
957  Int& precRefValFloat, Int& precRefValRADEC,
958  Int& precRefPixFloat, Int& precIncSci, String& nameAxis,
959  String& nameCoordType, String& nameCoordNumber, String& nameName, String& nameProj,
960  String& nameShape, String& nameTile,
961  String& nameRefValue, String& nameRefPixel,
962  String& nameInc, String& nameUnits,
963  MDoppler::Types velocityType,
964  const IPosition& latticeShape, const IPosition& tileShape) const;
965 
966  void listHeader (LogIO& os, Coordinate* pc, uInt& widthAxis, uInt& widthCoordType, uInt& widthCoordNumber,
967  uInt& widthName, uInt& widthProj,
968  uInt& widthShape, uInt& widthTile, uInt& widthRefValue,
969  uInt& widthRefPixel, uInt& widthInc, uInt& widthUnits,
970  Bool findWidths, Int coordinate, Int axisInCoordinate, Int pixelAxis,
971  Int precRefValSci, Int precRefValFloat, Int precRefValRADEC, Int precRefPixFloat,
972  Int precIncSci, const IPosition& latticeShape, const IPosition& tileShape) const;
973  void listVelocity (LogIO& os, Coordinate* pc, uInt widthAxis,
974  uInt widthCoordType, uInt widthCoordNumber,
975  uInt& widthName, uInt widthProj,
976  uInt widthShape, uInt widthTile, uInt& widthRefValue,
977  uInt widthRefPixel, uInt& widthInc, uInt& widthUnits,
978  Bool findWidths, Int axisInCoordinate, Int pixelAxis,
979  MDoppler::Types velocityType, Int precRefValSci, Int precRefValFloat,
980  Int precRefValRADEC, Int precRefPixFloat, Int precIncSci) const;
981  void clearFlags (LogIO& os) const;
983  MDoppler::Types velocityType, const String& velUnits) const;
984  // </group>
985 
986  void _downcase(Vector<String>& vec) const
987  { for (uInt i=0; i<vec.size(); ++i) vec[i].downcase(); }
988 
989 };
990 
991 } //# NAMESPACE CASACORE - END
992 
993 #endif
994 
String coordRecordName(uInt which) const
Return the name of the record field in which the coordinate is stored.
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
virtual uInt nWorldAxes() const
Int qualityPixelNumber(const String &qualityString) const
Given a quality parameter, find the pixel location.
virtual Bool near(const Coordinate &other, Double tol=1e-6) const
Comparison function.
const LinearCoordinate & linearCoordinate(uInt which) const
Return the given Coordinate.
const QualityCoordinate & qualityCoordinate(uInt which) const
int Int
Definition: aipstype.h:47
Int qualityAxisNumber() const
what number is the quality axis? Returns -1 if no quality axis exists.
virtual Vector< Double > referencePixel() const
Bool worldMap(Vector< Int > &worldAxisMap, Vector< Int > &worldAxisTranspose, Vector< Bool > &refChange, const CoordinateSystem &cSys) const
Find the world and pixel axis mappings to the supplied CoordinateSystem from the current coordinate s...
CoordinateSystem()
Default constructor.
Vector< Int > directionAxesNumbers() const
Get the pixel axis numbers of the direction coordinate in this object.
virtual ~CoordinateSystem()
Destructor.
virtual Vector< Double > referenceValue() const
PtrBlock< Vector< Double > * > worldOut_tmps_p
TableExprNode downcase(const TableExprNode &node)
Definition: ExprNode.h:1530
CoordinateSystem & operator=(const CoordinateSystem &other)
Assignment (copy semantics).
virtual Coordinate * clone() const
Make a copy of the CoordinateSystem using new.
const TabularCoordinate & tabularCoordinate(uInt which) const
PtrBlock< Vector< Double > * > world_replacement_values_p
Bool hasSpectralAxis() const
Does this coordinate system have a spectral axis?
const StokesCoordinate & stokesCoordinate() const
Int polarizationAxisNumber(Bool doWorld=False) const
What is the number of the polarization/stokes axis? If doWorld=True, the world axis number is returne...
void findWorldAxis(Int &coordinate, Int &axisInCoordinate, uInt axisInCoordinateSystem) const
Given an axis number (pixel or world) in the CoordinateSystem, find the corresponding coordinate numb...
Bool toFITSHeader(RecordInterface &header, IPosition &shape, Bool oneRelative, Char prefix= 'c', Bool writeWCS=True, Bool preferVelocity=True, Bool opticalVelocity=True, Bool preferWavelength=False, Bool airWavelength=False) const
Convert a CoordinateSystem to FITS, i.e.
static CoordinateSystem * restore(const RecordInterface &container, const String &fieldName)
Restore the CoordinateSystem from a record.
String qualityAtPixel(const uInt pixel) const
Table lookup 1-D coordinate, with interpolation.
virtual Bool toPixelMany(Matrix< Double > &pixel, const Matrix< Double > &world, Vector< Bool > &failures) const
virtual Vector< String > worldAxisNames() const
Return the requested attribute.
virtual Vector< Double > worldMixMin() const
const SpectralCoordinate & spectralCoordinate() const
void makeWorldAbsRelMany(Matrix< Double > &value, Bool toAbs) const
Many abs/rel conversions.
CoordinateSystem subImage(const Vector< Float > &originShift, const Vector< Float > &incrFac, const Vector< Int > &newShape) const
Return a CoordinateSystem appropriate for a shift of origin (the shift is subtracted from the referen...
ObsInfo obsInfo() const
Miscellaneous information related to an observation, for example the observation date.
Bool pixelMap(Vector< Int > &pixelAxisMap, Vector< Int > &pixelAxisTranspose, const CoordinateSystem &cSys) const
PtrBlock< Vector< Double > * > pixel_tmps_p
Interconvert between pixel and a linear world coordinate.
Int spectralAxisNumber(Bool doWorld=False) const
What number is the spectral axis? If doWorld=True, the world axis number is returned.
char Char
Definition: aipstype.h:43
virtual Bool setReferenceValue(const Vector< Double > &refval)
const DirectionCoordinate & directionCoordinate() const
void findPixelAxis(Int &coordinate, Int &axisInCoordinate, uInt axisInCoordinateSystem) const
Interconvert between pixel and Quality value.
ostream-like interface to creating log messages.
Definition: LogIO.h:167
void deleteTemps(const uInt which)
Delete temporary maps.
static const String _class
virtual Coordinate::Type type() const
Returns Coordinate::COORDSYS
Int spectralCoordinateNumber() const
what number is the spectral coordinate? Returns -1 if no spectral coordinate exists.
PtrBlock< Vector< Double > * > world_tmps_p
PtrBlock< Vector< Bool > * > pixelAxes_tmps_p
virtual Bool toMix(Vector< Double > &worldOut, Vector< Double > &pixelOut, const Vector< Double > &worldIn, const Vector< Double > &pixelIn, const Vector< Bool > &worldAxes, const Vector< Bool > &pixelAxes, const Vector< Double > &worldMin, const Vector< Double > &worldMax) const
Mixed pixel/world coordinate conversion.
virtual String format(String &units, Coordinate::formatType format, Double worldValue, uInt worldAxis, Bool isAbsolute=True, Bool showAsAbsolute=True, Int precision=-1, Bool usePrecForMixed=False) const
Format a world value nicely through the common format interface.
formatType
This enum is used for formatting world values into Strings.
Definition: Coordinate.h:162
virtual String showType() const
Always returns "System".
virtual uInt nPixelAxes() const
Sums the number of axes in the Coordinates that the CoordinateSystem contains, allowing for removed a...
QualityCoordinate qualitySubImage(const QualityCoordinate &qc, Int originShift, Int pixincFac, Int newShape) const
Do subImage for Quality.
Store miscellaneous information related to an observation.
Definition: ObsInfo.h:97
void listFrequencySystem(LogIO &os, MDoppler::Types velocityType) const
virtual void makePixelRelativeMany(Matrix< Double > &pixel) const
Batch up a lot of absolute/relative transformations.
Bool setRestFrequency(String &errorMsg, const Quantity &freq)
Set rest frequency of SpectralCoordinate in CoordinateSystem.
String stokesAtPixel(const uInt pixel) const
Int polarizationCoordinateNumber() const
what is the number of the polarization/stokes coordinate? Returns -1 if no stokes coordinate exists...
virtual Bool save(RecordInterface &container, const String &fieldName) const
Save the CoordinateSystem into the supplied record using the supplied field name. ...
Int linearCoordinateNumber() const
virtual void makePixelRelative(Vector< Double > &pixel) const
Make absolute coordinates relative and vice-versa (relative to the reference pixel/value).
virtual Vector< Double > increment() const
virtual void makeWorldAbsoluteRef(Vector< Double > &world, const Vector< Double > &refVal) const
Make absolute coordinates relative and vice versa with respect to the given reference value...
virtual void makeWorldRelativeMany(Matrix< Double > &world) const
void copy(const CoordinateSystem &other)
virtual Bool setWorldAxisNames(const Vector< String > &names)
Set the requested attribute.
virtual Bool toPixel(Vector< Double > &pixel, const Vector< Double > &world) const
Interconvert pixel positions and directions (e.g. RA/DEC).
Interface for converting between world and pixel coordinates.
Definition: Coordinate.h:139
Bool hasDirectionCoordinate() const
void setObsInfo(const ObsInfo &obsinfo)
virtual void makeWorldAbsolute(Vector< Double > &world) const
Bool nearPixel(const CoordinateSystem &other, Double tol=1e-6) const
This function compares this and the other coordinate system, but ONLY for the non-removed pixel axes...
uInt nCoordinates() const
Returns the number of Coordinates that this CoordinateSystem contains.
double Double
Definition: aipstype.h:52
Int qualityCoordinateNumber() const
what is the number of the quality coordinate? Returns -1 if no quality coordinate exists...
Bool hasQualityAxis() const
Does this coordinate system have a quality axis?
virtual Bool setReferencePixel(const Vector< Double > &refPix)
void listHeader(LogIO &os, Coordinate *pc, uInt &widthAxis, uInt &widthCoordType, uInt &widthCoordNumber, uInt &widthName, uInt &widthProj, uInt &widthShape, uInt &widthTile, uInt &widthRefValue, uInt &widthRefPixel, uInt &widthInc, uInt &widthUnits, Bool findWidths, Int coordinate, Int axisInCoordinate, Int pixelAxis, Int precRefValSci, Int precRefValFloat, Int precRefValRADEC, Int precRefPixFloat, Int precIncSci, const IPosition &latticeShape, const IPosition &tileShape) const
void listDirectionSystem(LogIO &os) const
All these functions are in support of the list function.
Bool checkAxesInThisCoordinate(const Vector< Bool > &axes, uInt which) const
Bool isDirectionAbscissaLongitude() const
Is the abscissa in the DirectionCoordinate the longitude axis? Throws exception if there is no Direct...
void getFieldWidths(LogIO &os, uInt &widthAxis, uInt &widthCoordType, uInt &widthCoordNumber, uInt &widthName, uInt &widthProj, uInt &widthShape, uInt &widthTile, uInt &widthRefValue, uInt &widthRefPixel, uInt &widthInc, uInt &widthUnits, Int &precRefValSci, Int &precRefValFloat, Int &precRefValRADEC, Int &precRefPixFloat, Int &precIncSci, String &nameAxis, String &nameCoordType, String &nameCoordNumber, String &nameName, String &nameProj, String &nameShape, String &nameTile, String &nameRefValue, String &nameRefPixel, String &nameInc, String &nameUnits, MDoppler::Types velocityType, const IPosition &latticeShape, const IPosition &tileShape) const
const Coordinate & coordinate(uInt which) const
Return the given Coordinate as a reference to the base class object.
PtrBlock< Vector< Double > * > pixelOut_tmps_p
void transpose(const Vector< Int > &newWorldOrder, const Vector< Int > &newPixelOrder)
Transpose the CoordinateSystem so that world axis 0 is newWorldOrder(0) and so on for all the other a...
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
Vector< String > list(LogIO &os, MDoppler::Types doppler, const IPosition &latticeShape, const IPosition &tileShape, Bool postLocally=False) const
List all header information.
static map< String, String > _friendlyAxisMap
void restoreOriginal()
Untranspose and undelete all axes.
Types
Types of known MDopplers Warning: The order defines the order in the translation matrix FromTo in th...
Definition: MDoppler.h:149
Bool removeWorldAxis(uInt axis, Double replacement)
Remove a world or pixel axis.
Int findCoordinate(Coordinate::Type type, Int afterCoord=-1) const
Find the Coordinate number that corresponds to the given type.
const Bool False
Definition: aipstype.h:41
PtrBlock< Vector< Double > * > worldMax_tmps_p
Bool velocityIncrement(Double &velocityInc, SpectralCoordinate &sc, MDoppler::Types velocityType, const String &velUnits) const
A drop-in replacement for Block<T*>.
Definition: Block.h:861
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape...
Definition: ExprNode.h:2015
virtual Matrix< Double > linearTransform() const
Type
This enum lists the types of the derived classes.
Definition: Coordinate.h:144
void _downcase(Vector< String > &vec) const
StokesCoordinate stokesSubImage(const StokesCoordinate &sc, Int originShift, Int pixincFac, Int newShape) const
Do subImage for Stokes.
Wrapper around a pthreads mutex.
Definition: Mutex.h:49
Interconvert pixel and frequency values.
Int directionCoordinateNumber() const
PtrBlock< Block< Int > * > pixel_maps_p
Same meanings as for the world*&#39;s above.
virtual Bool toWorldMany(Matrix< Double > &world, const Matrix< Double > &pixel, Vector< Bool > &failures) const
Batch up a lot of transformations.
PtrBlock< Vector< Bool > * > worldAxes_tmps_p
These temporaries all needed for the toMix function.
Vector< Int > linearAxesNumbers() const
void addCoordinate(const Coordinate &coord)
Add another Coordinate to this CoordinateSystem.
Bool removePixelAxis(uInt axis, Double replacement)
virtual Vector< Double > worldMixMax() const
Bool mapOne(Vector< Int > &worldAxisMap, Vector< Int > &worldAxisTranspose, Vector< Bool > &refChange, const CoordinateSystem &cSys, const CoordinateSystem &cSys2, const uInt coord, const uInt coord2) const
Helper functions to group common code.
virtual void makeWorldAbsoluteMany(Matrix< Double > &world) const
const Double e
e and functions thereof:
CoordinateSystem stripRemovedAxes(const CoordinateSystem &cSys) const
Strip out coordinates with all world and pixel axes removed.
Interconvert between pixel and Stokes value.
Vector< Int > pixelAxes(uInt whichCoord) const
virtual Bool setLinearTransform(const Matrix< Double > &xform)
virtual Coordinate * makeFourierCoordinate(const Vector< Bool > &axes, const Vector< Int > &shape) const
Find the CoordinateSystem (you can safely caste the pointer to a CoordinateSystem) for when we Fourie...
void clearFlags(LogIO &os) const
virtual Bool toWorld(Vector< Double > &world, const Vector< Double > &pixel, Bool useConversionFrame=True) const
Convert a pixel position to a world position or vice versa.
PtrBlock< Vector< Double > * > worldMin_tmps_p
Vector< Int > getWorldAxesOrder(Vector< String > &myNames, Bool requireAll, Bool allowFriendlyNames=False) const
Get the 0 based order of the minimal match strings specified in order.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void subImageInSitu(const Vector< Float > &originShift, const Vector< Float > &incrFac, const Vector< Int > &newShape)
PtrBlock< Vector< Double > * > pixel_replacement_values_p
virtual void makePixelAbsolute(Vector< Double > &pixel) const
void makePixelAbsRelMany(Matrix< Double > &value, Bool toAbs) const
static void _initFriendlyAxisMap()
static Bool fromFITSHeader(Int &stokesFITSValue, CoordinateSystem &coordsys, RecordInterface &recHeader, const Vector< String > &header, const IPosition &shape, uInt which=0)
Probably even if we return False we should set up the best linear coordinate that we can...
void cleanUpSpecCoord(PtrBlock< SpectralCoordinate * > &in, PtrBlock< SpectralCoordinate * > &out)
Delete some pointer blocks.
size_t size() const
Definition: ArrayBase.h:101
Bool replaceCoordinate(const Coordinate &newCoordinate, uInt whichCoordinate)
Replace one Coordinate with another.
virtual Bool setWorldAxisUnits(const Vector< String > &units)
Set/get the units.
Abstract base class for Record classes.
void listPointingCenter(LogIO &os) const
PtrBlock< Block< Int > * > world_maps_p
For coordinate[i] axis[j], world_maps_p[i][j], if >=0 gives the location in the input vector that map...
PtrBlock< Coordinate * > coordinates_p
Where we store copies of the coordinates we are created with.
virtual Bool setIncrement(const Vector< Double > &inc)
virtual void setDefaultWorldMixRanges()
Int worldAxisToPixelAxis(uInt worldAxis) const
Find the pixel axis for the given world axis in a CoordinateSystem.
virtual Quantity toWorldLength(const Double nPixels, const uInt pixelAxis) const
convert a pixel "length" to a world "length"
ObsInfo obsinfo_p
Miscellaneous information about the observation associated with this Coordinate System.
const Bool True
Definition: aipstype.h:40
Bool setSpectralConversion(String &errorMsg, const String frequencySystem)
Set Spectral conversion layer of SpectralCoordinate in CoordinateSystem so that pixel<->world go to t...
this file contains all the compiler specific defines
Definition: mainpage.dox:28
virtual void makePixelAbsoluteMany(Matrix< Double > &pixel) const
Int pixelAxisToWorldAxis(uInt pixelAxis) const
Find the world axis for the given pixel axis in a CoordinateSystem.
Interconvert pixel and world coordinates.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
Vector< Int > worldAxes(uInt whichCoord) const
For a given Coordinate say where its world and pixel axes are in this CoordinateSystem.
Int stokesPixelNumber(const String &stokesString) const
Given a stokes or polarization parameter, find the pixel location.
void listVelocity(LogIO &os, Coordinate *pc, uInt widthAxis, uInt widthCoordType, uInt widthCoordNumber, uInt &widthName, uInt widthProj, uInt widthShape, uInt widthTile, uInt &widthRefValue, uInt widthRefPixel, uInt &widthInc, uInt &widthUnits, Bool findWidths, Int axisInCoordinate, Int pixelAxis, MDoppler::Types velocityType, Int precRefValSci, Int precRefValFloat, Int precRefValRADEC, Int precRefPixFloat, Int precIncSci) const
unsigned int uInt
Definition: aipstype.h:48
virtual Vector< String > worldAxisUnits() const
virtual void makeWorldRelative(Vector< Double > &world) const
Bool hasLinearCoordinate() const
virtual Bool setWorldMixRanges(const IPosition &shape)
Compute and recover the world min and max ranges, for use in function toMix, for a lattice of the giv...
Bool convert(Vector< Double > &coordOut, const Vector< Double > &coordin, const Vector< Bool > &absIn, const Vector< String > &unitsIn, MDoppler::Types dopplerIn, const Vector< Bool > &absOut, const Vector< String > &unitsOut, MDoppler::Types dopplerOut, Double pixInOffset=0.0, Double pixOutOffset=0.0)
General coordinate conversion.
Bool hasPolarizationCoordinate() const
does this coordinate system have a polarizaion/stokes coordinate?