casacore
Loading...
Searching...
No Matches
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
39namespace 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{
107public:
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.
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);
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>
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
280private:
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
simple 1-D array
Definition Block.h:200
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)
static StokesCoordinate * restore(const RecordInterface &container, const String &fieldName)
Recover the StokesCoordinate from a record.
virtual Bool setReferencePixel(const Vector< Double > &refPix)
virtual void makeWorldRelative(Vector< Double > &world) const
virtual Coordinate * clone() const
Make a copy of the StokesCoordinate using new.
virtual uInt nPixelAxes() const
Always returns 1.
virtual Bool setWorldAxisNames(const Vector< String > &names)
Set the value of the requested attribute.
virtual Matrix< Double > linearTransform() const
Bool toWorld(Stokes::StokesTypes &stokes, Int pixel) const
virtual String showType() const
Always returns the String "Stokes".
Vector< Int > stokes() const
Get the Stokes values (Stokes::StokesType) that we constructed with into a vector.
virtual void setDefaultWorldMixRanges()
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.
Vector< String > stokesStrings() const
Get the stokes string representations.
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...
virtual Vector< Double > increment() const
static Stokes::StokesTypes toWorld(Double world)
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 ...
Bool toPixel(Int &pixel, Stokes::StokesTypes stokes) const
Interconvert between pixel and world as a Stokes type.
virtual Vector< Double > referenceValue() const
Bool toPixel(Double &pixel, const Double world) const
virtual ~StokesCoordinate()
Destructor.
virtual Bool setIncrement(const Vector< Double > &inc)
virtual Vector< Double > referencePixel() const
virtual Bool near(const Coordinate &other, Double tol=1e-6) const
Comparison function.
virtual Vector< String > worldAxisUnits() const
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 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 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
StokesCoordinate & operator=(const StokesCoordinate &other)
Assignment (copy semantics)
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
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