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