casacore
StokesCoordinate.h
Go to the documentation of this file.
1 //# StokesCoordinate.h: Interconvert between pixel number and Stokes value.
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_STOKESCOORDINATE_H
31 #define COORDINATES_STOKESCOORDINATE_H
32 
33 #include <casacore/casa/aips.h>
34 #include <casacore/coordinates/Coordinates/Coordinate.h>
35 #include <casacore/measures/Measures/Stokes.h>
36 #include <casacore/casa/Containers/Block.h>
37 #include <casacore/casa/Arrays/Vector.h>
38 
39 namespace casacore { //# NAMESPACE CASACORE - BEGIN
40 
41 
42 
43 // <summary>
44 // Interconvert between pixel and Stokes value.
45 // </summary>
46 
47 // <use visibility=export>
48 
49 // <reviewed reviewer="Peter Barnes" date="1999/12/24" tests="tStokesCoordinate">
50 // </reviewed>
51 //
52 // <prerequisite>
53 // <li> <linkto class=Coordinate>Coordinate</linkto>
54 // <li> <linkto class=Stokes>Stokes</linkto>
55 // </prerequisite>
56 //
57 // <synopsis>
58 // Although not really a "coordinate", an axis where pixel numbers are used
59 // for different Stokes values is in wide use. The StokesCoordinate
60 // is a poor fit to the Coordinate polymorphic model.
61 // You will probably find that if you try to use the Coordinate
62 // classes polymorphically, that StokesCoordinate will cause you
63 // to break the polymorphism. I.e. you may have to deal with
64 // a specific StokesCoordinate)
65 //
66 // The StokesCoordinate just maintains a list (given in the constructor) of
67 // possibly non-monotonic Stokes values. The values of the list are the
68 // world values (they are values from the Stokes::StokesTypes enum).
69 // Thus world = list[pixel] where pixel is the pixel coordinate (0,1, ...)
70 //
71 // This means that concepts such as reference pixel, reference value,
72 // increment etc are meaningless for StokesCoordinate. You can recover these
73 // these attributes, but the functions to set these attributes have no effect.
74 //
75 // Note also that for the StokesCoordinate relative world coordinates are defined to be the
76 // as absolute, since there is no meaning for a relative Stokes world value (e.g.
77 // what is XX -RL ?? Relative pixel coordinates are defined.
78 //
79 // </synopsis>
80 //
81 // <note role=caution>
82 // All pixel coordinates are zero relative.
83 // </note>
84 //
85 // <example>
86 // In this example we create a StokesCoordinate housing IQUV
87 // <srcblock>
88 // Vector<Int> iquv(4);
89 // iquv(0) = Stokes::I; iquv(1) = Stokes::Q;
90 // iquv(2) = Stokes::U; iquv(3) = Stokes::V;
91 // StokesCoordinate stokes(iquv);
92 // </srcblock>
93 // </example>
94 //
95 // <motivation>
96 // It is conventional to make a pseudo-axis of Stokes parameters.
97 // Another approach is to make an image type called Stokes.
98 // </motivation>
99 //
100 // <todo asof="1997/1/14">
101 // <li> This could probably be generalized into an "enumeration axis" class.
102 // </todo>
103 //
104 
106 {
107 public:
108 
109  // The length of whichStokes is the length of the axis, and the values
110  // define which stokes are in which axis value. Often the vector will be of
111  // length 4 and will contain Stokes::I, Q, U and V, however any valid value
112  // from the stokes enum may be used. The values may not repeat however, e.g.
113  // only one axis position may contain "I".
114  explicit StokesCoordinate(const Vector<Int> &whichStokes);
115 
116  // Copy constructor (copy semantics)
118 
119  // Assignment (copy semantics)
121 
122  // Destructor.
123  virtual ~StokesCoordinate();
124 
125  // Returns Coordinates::STOKES.
126  virtual Coordinate::Type type() const;
127 
128  // Always returns the String "Stokes".
129  virtual String showType() const;
130 
131  // Always returns 1.
132  // <group>
133  virtual uInt nPixelAxes() const;
134  virtual uInt nWorldAxes() const;
135  // </group>
136 
137  // Convert a pixel to a world coordinate or vice versa. Returns True
138  // if the conversion succeeds, otherwise it returns False and method
139  // <src>errorMessage</src> returns an error message.
140  // The output vectors are appropriately resized before use.
141  // The Bool parameter in toWorld() is ignored as this coordinate does not
142  // support a conversion layer frame.
143  // <group>
144  virtual Bool toWorld(Vector<Double> &world,
145  const Vector<Double> &pixel, Bool=True) const;
146  virtual Bool toPixel(Vector<Double> &pixel,
147  const Vector<Double> &world) const;
148  // </group>
149 
150  // Interconvert between pixel and world as a Stokes type.
151  // It returns False if no conversion could be done.
152  // <group>
155  // </group>
156 
157  // Interconvert between world stored as a Double and world stored as
158  // a Stokes type. Since these functions are static, any valid
159  // Stokes type can be used. The second function returns
160  // Stokes::Undefined if world is illegal.
161  // <group>
164  // </group>
165 
166  // Make absolute coordinates relative and vice-versa.
167  // For the StokesCoordinate relative world coordinates are defined to be the
168  // same as absolute world coordinates. Relative pixels do have meaning
169  // and are implemented (rel = abs - refPix)
170  // <group>
171  virtual void makePixelRelative (Vector<Double>& pixel) const;
172  virtual void makePixelAbsolute (Vector<Double>& pixel) const;
173  virtual void makeWorldRelative (Vector<Double>& world) const;
174  virtual void makeWorldAbsolute (Vector<Double>& world) const;
175  // </group>
176 
177 
178  // Get the Stokes values (Stokes::StokesType) that we constructed
179  // with into a vector
181 
182  // Get the stokes string representations
184 
185  // Set a new vector of Stokes values (a vector of Stokes::StokesType)
186  void setStokes (const Vector<Int> &whichStokes);
187 
188  // Report the value of the requested attribute.
189  // <group>
193  virtual Vector<Double> increment() const;
195  // </group>
196 
197  // Set the value of the requested attribute. For the StokesCoordinate,
198  // these have no effect (always return True) except for setWorldAxisNames.
199  // <group>
200  virtual Bool setWorldAxisNames(const Vector<String> &names);
201  virtual Bool setReferencePixel(const Vector<Double> &refPix);
202  virtual Bool setLinearTransform(const Matrix<Double> &xform);
203  virtual Bool setIncrement(const Vector<Double> &inc) ;
204  virtual Bool setReferenceValue(const Vector<Double> &refval) ;
205  // </group>
206 
207  // The set function has no effect as the units must be empty for a StokesCoordinate
208  // Always returns True
209  // <group>
210  virtual Bool setWorldAxisUnits(const Vector<String> &units);
212  // </group>
213 
214  // Set the world min and max ranges, for use in function <src>toMix</src>,
215  // for a lattice of the given shape (for this coordinate).
216  // The implementation here gives world coordinates at the start
217  // and end of the Stokes axis.
218  // The output vectors are resized. Returns False if fails (and
219  // then <src>setDefaultWorldMixRanges</src> generates the ranges)
220  // with a reason in <src>errorMessage()</src>.
221  // The <src>setDefaultWorldMixRanges</src> function
222  // gives you [-1e99->1e99].
223  // <group>
225  virtual void setDefaultWorldMixRanges ();
226  //</group>
227 
228  // Format a StokesCoordinate world value with the common format
229  // interface (refer to the base class <linkto class=Coordinate>Coordinate</linkto>
230  // for basics.
231  //
232  // A StokesCoordinate is formatted differently from other Coordinate
233  // types. The world value is converted to the character representation
234  // as defined by the enum <src>StokesTypes</src> in the class
235  // <linkto class=Stokes>Stokes</linkto>.
236  //
237  // Thus, all other arguments to do with formatting and precision are ignored.
238  virtual String format(String& units,
240  Double worldValue,
241  uInt worldAxis,
242  Bool isAbsolute=True,
243  Bool showAsAbsolute=True,
244  Int precision = -1, Bool usePrecForMixed=False) const;
245 
246  // Comparison function. Any private Double data members are compared
247  // with the specified fractional tolerance. Don't compare on the specified
248  // axes in the Coordinate. If the comparison returns False, method
249  // errorMessage returns a message about why.
250  // <group>
251  virtual Bool near(const Coordinate& other,
252  Double tol=1e-6) const;
253  virtual Bool near(const Coordinate& other,
254  const Vector<Int>& excludeAxes,
255  Double tol=1e-6) const;
256  // </group>
257 
258  // Save the StokesCoordinate into the supplied record using the supplied field name.
259  // The field must not exist, otherwise <src>False</src> is returned.
260  virtual Bool save(RecordInterface &container,
261  const String &fieldName) const;
262 
263  // Recover the StokesCoordinate from a record.
264  // A null pointer means that the restoration did not succeed - probably
265  // because fieldName doesn't exist or doesn't contain a CoordinateSystem.
266  static StokesCoordinate* restore(const RecordInterface &container,
267  const String &fieldName);
268 
269  // Make a copy of the StokesCoordinate using new. The caller is responsible for calling
270  // delete.
271  virtual Coordinate *clone() const;
272 
273 
274  // Comparison only made for specified axes in this and other Coordinate
275  virtual Bool doNearPixel (const Coordinate& other,
276  const Vector<Bool>& thisAxes,
277  const Vector<Bool>& otherAxes,
278  Double tol=1.0e-6) const;
279 
280 private:
281 
282  Bool toWorld(Double& world, const Double pixel) const;
283  Bool toPixel(Double& pixel, const Double world) const;
284 //
286 
287  // Keep these for subimaging purposes.
292 
293  // Undefined and inaccessible
295 };
296 
297 } //# NAMESPACE CASACORE - END
298 
299 
300 #endif
301 
Type
This enum lists the types of the derived classes.
Definition: Coordinate.h:144
formatType
This enum is used for formatting world values into Strings.
Definition: Coordinate.h:162
void setStokes(const Vector< Int > &whichStokes)
Set a new vector of Stokes values (a vector of Stokes::StokesType)
virtual Bool setReferencePixel(const Vector< Double > &refPix)
virtual void makeWorldRelative(Vector< Double > &world) const
virtual uInt nPixelAxes() const
Always returns 1.
virtual Bool setWorldAxisNames(const Vector< String > &names)
Set the value of the requested attribute.
Bool toWorld(Stokes::StokesTypes &stokes, Int pixel) const
virtual String showType() const
Always returns the String "Stokes".
static StokesCoordinate * restore(const RecordInterface &container, const String &fieldName)
Recover the StokesCoordinate from a record.
virtual void setDefaultWorldMixRanges()
virtual Vector< Double > referencePixel() const
virtual Bool setWorldAxisUnits(const Vector< String > &units)
The set function has no effect as the units must be empty for a StokesCoordinate Always returns True.
virtual Vector< String > worldAxisUnits() const
virtual void makePixelAbsolute(Vector< Double > &pixel) const
StokesCoordinate()
Undefined and inaccessible.
virtual Bool setWorldMixRanges(const IPosition &shape)
Set the world min and max ranges, for use in function toMix, for a lattice of the given shape (for th...
static Stokes::StokesTypes toWorld(Double world)
virtual Vector< Double > increment() const
static Double toWorld(Stokes::StokesTypes stokes)
Interconvert between world stored as a Double and world stored as a Stokes type.
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 StokesCoordinate world value with the common format interface (refer to the base class Coord...
StokesCoordinate(const Vector< Int > &whichStokes)
The length of whichStokes is the length of the axis, and the values define which stokes are in which ...
StokesCoordinate & operator=(const StokesCoordinate &other)
Assignment (copy semantics)
Bool toPixel(Int &pixel, Stokes::StokesTypes stokes) const
Interconvert between pixel and world as a Stokes type.
Bool toPixel(Double &pixel, const Double world) const
virtual ~StokesCoordinate()
Destructor.
Vector< String > stokesStrings() const
Get the stokes string representations.
virtual Vector< Double > referenceValue() const
virtual Bool setIncrement(const Vector< Double > &inc)
virtual Bool near(const Coordinate &other, Double tol=1e-6) const
Comparison function.
virtual Vector< String > worldAxisNames() const
Report the value of the requested attribute.
virtual void makeWorldAbsolute(Vector< Double > &world) const
virtual Coordinate::Type type() const
Returns Coordinates::STOKES.
virtual Bool save(RecordInterface &container, const String &fieldName) const
Save the StokesCoordinate into the supplied record using the supplied field name.
virtual Bool toPixel(Vector< Double > &pixel, const Vector< Double > &world) const
virtual uInt nWorldAxes() const
virtual Coordinate * clone() const
Make a copy of the StokesCoordinate using new.
virtual void makePixelRelative(Vector< Double > &pixel) const
Make absolute coordinates relative and vice-versa.
StokesCoordinate(const StokesCoordinate &other)
Copy constructor (copy semantics)
virtual Bool setReferenceValue(const Vector< Double > &refval)
virtual Bool setLinearTransform(const Matrix< Double > &xform)
virtual Matrix< Double > linearTransform() const
Vector< Int > stokes() const
Get the Stokes values (Stokes::StokesType) that we constructed with into a vector.
virtual Bool doNearPixel(const Coordinate &other, const Vector< Bool > &thisAxes, const Vector< Bool > &otherAxes, Double tol=1.0e-6) const
Comparison only made for specified axes in this and other Coordinate.
virtual Bool near(const Coordinate &other, const Vector< Int > &excludeAxes, Double tol=1e-6) const
Bool toWorld(Double &world, const Double pixel) const
virtual Bool toWorld(Vector< Double > &world, const Vector< Double > &pixel, Bool=True) const
Convert a pixel to a world coordinate or vice versa.
Double crval_p
Keep these for subimaging purposes.
StokesTypes
The Stokes types are defined by this enum.
Definition: Stokes.h:66
String: the storage and methods of handling collections of characters.
Definition: String.h:225
const Double e
e and functions thereof:
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
TableExprNode shape(const TableExprNode &array)
Function operating on any scalar or array resulting in a Double array containing the shape.
Definition: ExprNode.h:1987
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55