#include <Coordinate.h>
Inheritance diagram for casa::Coordinate:
Part of API
The Coordinate class defines the generic interface whereby a pixel position is converted to a world (sky, frequency, stokes, .\..) position and vice versa. The pixel and world coordinates are in general multi-dimensional values. In general there need not be the same number of pixel and world axes, although this will normally be the case.
The fundamental model is that a pixel is first converted into a relative physical coordinate by:
Both absolute and relative coordinates are supported. The main interface supports conversion between absolute pixel and absolute world coordinate. There are then functions to convert absolute coordinates to relative and vice versa. A relative pixel coordinate is defined according to
relative = absolute - reference
A relative world coordinate is similar, although there may be deviations from this formula (e.g. for DirectionCoordinate a cos(latitude) term is incorporated and for StokesCoordinate relative world coordinates are defined to be the same as absolute world coordinates.
Caution: All absolute pixels coordinates are zero relative.
This is a base class so there is no direct example, but see the example in Coordinates.h for use of the derived classes.
Encapsulate the common interface to coordinate conversion so that it may be used polymorphically.
Definition at line 141 of file Coordinate.h.
| virtual Type | type () const=0 |
| List the type of this Coordinate object. | |
| virtual String | showType () const=0 |
| static String | typeToString (Coordinate::Type type) |
Public Types | |
| enum | Type |
| This enum lists the types of the derived classes. More... | |
| enum | formatType |
| This enum is used for formatting world values into Strings. More... | |
Public Member Functions | |
| virtual | ~Coordinate () |
| Destructor. | |
| 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 absolute pixel/world coordinate conversion. | |
| virtual Bool | setWorldAxisUnits (const Vector< String > &units)=0 |
| Change the units. | |
| virtual Coordinate * | makeFourierCoordinate (const Vector< Bool > &axes, const Vector< Int > &shape) const |
| Find the Coordinate for when we Fourier Transform ourselves. | |
| const String & | errorMessage () const |
| If the last conversion to world or pixel coordinates resulted in an error, report that error. | |
| virtual Bool | save (RecordInterface &container, const String &fieldName) const =0 |
| Used for persistence. | |
| virtual Coordinate * | clone () const=0 |
| Make a copy of ourself. | |
| 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 The default implementation should be ok for all Coordinate types except Stokes. | |
| virtual uInt | nPixelAxes () const=0 |
| How many world/pixel axes are there in this Coordinate? While the number of world and pixel axes will generally be the same, it is not a requirement. | |
| virtual uInt | nWorldAxes () const=0 |
| virtual Bool | toWorld (Vector< Double > &world, const Vector< Double > &pixel) const=0 |
| Convert an absolute pixel position to an absolute world position or vice versa. | |
| virtual Bool | toPixel (Vector< Double > &pixel, const Vector< Double > &world) const=0 |
| 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 this coordinate. | |
| virtual void | setDefaultWorldMixRanges () |
| Vector< Double > | worldMixMin () const |
| Vector< Double > | worldMixMax () const |
| virtual Bool | toWorldMany (Matrix< Double > &world, const Matrix< Double > &pixel, Vector< Bool > &failures) const |
| Batch up a lot of transformations. | |
| virtual Bool | toPixelMany (Matrix< Double > &pixel, const Matrix< Double > &world, Vector< Bool > &failures) const |
| virtual void | makePixelRelative (Vector< Double > &pixel) const |
| Make absolute coordinates relative and vice-versa (with respect to the reference value). | |
| virtual void | makePixelAbsolute (Vector< Double > &pixel) const |
| virtual void | makeWorldRelative (Vector< Double > &world) const |
| virtual void | makeWorldAbsolute (Vector< Double > &world) const |
| virtual void | makeWorldAbsoluteRef (Vector< Double > &world, const Vector< Double > &refVal) const |
| Make absolute coordinates relative and vice versa with respect to the given reference value. | |
| virtual void | makePixelRelativeMany (Matrix< Double > &pixel) const |
| Batch up a lot of absolute/relative transformations. | |
| virtual void | makePixelAbsoluteMany (Matrix< Double > &pixel) const |
| virtual void | makeWorldRelativeMany (Matrix< Double > &world) const |
| virtual void | makeWorldAbsoluteMany (Matrix< Double > &world) const |
| virtual Vector< String > | worldAxisNames () const=0 |
| Return the requested attributed. | |
| virtual Vector< Double > | referencePixel () const=0 |
| virtual Matrix< Double > | linearTransform () const=0 |
| virtual Vector< Double > | increment () const=0 |
| virtual Vector< Double > | referenceValue () const=0 |
| virtual Vector< String > | worldAxisUnits () const=0 |
| virtual Bool | setWorldAxisNames (const Vector< String > &names)=0 |
| Set the requested attribute. | |
| virtual Bool | setReferencePixel (const Vector< Double > &refPix)=0 |
| virtual Bool | setLinearTransform (const Matrix< Double > &xform)=0 |
| virtual Bool | setIncrement (const Vector< Double > &inc)=0 |
| virtual Bool | setReferenceValue (const Vector< Double > &refval)=0 |
| virtual Bool | near (const Coordinate &other, Double tol=1.0e-6) const=0 |
| Comparison to fractional tolerance (for floating point values). | |
| virtual Bool | near (const Coordinate &other, const Vector< Int > &excludeAxes, Double tol=1.0e-6) const =0 |
| virtual void | getPrecision (Int &precision, Coordinate::formatType &format, Bool showAsAbsolute, Int defPrecScientific, Int defPrecFixed, Int defPrecTime) const |
| Provide a common interface to getting formatted representations of coordinate values. | |
| virtual String | format (String &units, Coordinate::formatType format, Double worldValue, uInt axis, Bool isAbsolute=True, Bool showAsAbsolute=True, Int precision=-1) |
| String | formatQuantity (String &units, Coordinate::formatType format, const Quantum< Double > &worldValue, uInt axis, Bool isAbsolute=True, Bool showAsAbsolute=True, Int precision=-1) |
Protected Member Functions | |
| Coordinate () | |
| Default constructor. | |
| Coordinate (const Coordinate &other) | |
| Copy constructor (copy semantics). | |
| Coordinate & | operator= (const Coordinate &other) |
| Assignment (copy semantics). | |
| void | set_error (const String &errorMsg) const |
| Set error message. | |
| Bool | find_scale_factor (String &error, Vector< Double > &factor, const Vector< String > &units, const Vector< String > &oldUnits) |
| void | fourierUnits (String &nameOut, String &unitOut, String &unitInCanon, Coordinate::Type type, Int axis, const String &unitIn, const String &nameIn) const |
| Tries to find a canonical unit for input unit (e.g. | |
| void | pcToXform (Matrix< Double > &xForm, const wcsprm &wcs) const |
| Interconvert between wcs PC cards and Matrix xForm format. | |
| void | xFormToPC (wcsprm &wcs, const Matrix< Double > &xForm) const |
| void | set_wcs (wcsprm &wcs) |
| Call wcsset on the wcs structure. | |
| Bool | toWorldWCS (Vector< Double > &world, const Vector< Double > &pixel, wcsprm &wcs) const |
| Functions to interconvert pixel<->world via wcs. | |
| Bool | toPixelWCS (Vector< Double > &pixel, const Vector< Double > &world, wcsprm &wcs) const |
| Bool | toWorldManyWCS (Matrix< Double > &world, const Matrix< Double > &pixel, Vector< Bool > &failures, wcsprm &wcs) const |
| Bool | toPixelManyWCS (Matrix< Double > &pixel, const Matrix< Double > &world, Vector< Bool > &failures, wcsprm &wcs) const |
| void | toCurrentMany (Matrix< Double > &world, const Vector< Double > &toCurrentFactors) const |
| Functions for handling conversion between the current units and the wcs units. | |
| void | fromCurrentMany (Matrix< Double > &world, const Vector< Double > &toCurrentFactors) const |
| virtual void | convertTo (Vector< Double > &world) const |
| Functions for handling conversion between the current reference frame and the native one. | |
| virtual void | convertFrom (Vector< Double > &world) const |
| void | convertToMany (Matrix< Double > &world) const |
| Functions for handling conversion between the current reference frame and the native one for many conversions. | |
| void | convertFromMany (Matrix< Double > &world) const |
Protected Attributes | |
| Vector< Double > | worldMin_p |
| toMix ranges. | |
| Vector< Double > | worldMax_p |
Private Member Functions | |
| void | checkFormat (Coordinate::formatType &format, const Bool absolute) const |
| Check format type. | |
| void | makeWorldAbsRelMany (Matrix< Double > &value, Bool toAbs) const |
| void | makePixelAbsRelMany (Matrix< Double > &value, Bool toAbs) const |
Private Attributes | |
| String | error_p |
This enum lists the types of the derived classes.
It is primarly used in the CoordinateSystem class.
Definition at line 146 of file Coordinate.h.
This enum is used for formatting world values into Strings.
Definition at line 162 of file Coordinate.h.
| virtual casa::Coordinate::~Coordinate | ( | ) | [virtual] |
Destructor.
Needs to be public so the user can delete Coordinate* objects
| casa::Coordinate::Coordinate | ( | ) | [protected] |
Default constructor.
Make an empty coordinate. Used by derived classes.
| casa::Coordinate::Coordinate | ( | const Coordinate & | other | ) | [protected] |
Copy constructor (copy semantics).
| virtual Type casa::Coordinate::type | ( | ) | const [pure virtual] |
List the type of this Coordinate object.
| virtual String casa::Coordinate::showType | ( | ) | const [pure virtual] |
| static String casa::Coordinate::typeToString | ( | Coordinate::Type | type | ) | [static] |
| virtual uInt casa::Coordinate::nPixelAxes | ( | ) | const [pure virtual] |
How many world/pixel axes are there in this Coordinate? While the number of world and pixel axes will generally be the same, it is not a requirement.
For example, in CoordinateSystem you could remove a pixel axis and leave the corresponding world axis. Also, if we ever implement a "SlicedCoordinate" class then there would be more world than pixel coordinates (the pixel coordinate would be a pixel number along the slice, whereas the world axes would continue to be RA/DEC).
| virtual uInt casa::Coordinate::nWorldAxes | ( | ) | const [pure virtual] |
| virtual Bool casa::Coordinate::toWorld | ( | Vector< Double > & | world, | |
| const Vector< Double > & | pixel | |||
| ) | const [pure virtual] |
Convert an absolute pixel position to an absolute world position or vice versa.
Returns True if the conversion succeeds, otherwise it returns False and method errorMessage contains an error message. The input vector must be of length nPixelAxes or nWorldAxes. The output vector is resized appropriately.
| virtual Bool casa::Coordinate::toPixel | ( | Vector< Double > & | pixel, | |
| const Vector< Double > & | world | |||
| ) | const [pure virtual] |
| virtual Bool casa::Coordinate::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 [virtual] |
Mixed absolute pixel/world coordinate conversion.
worldIn and worldAxes are vectors of length nWorldAxes. pixelIn and pixelAxes are of length nPixelAxes. worldAxes(i) = True specifies you have given a world value in worldIn(i) to convert to pixel. pixelAxes(i)=True specifies you have given a pixel value in pixelIn(i) to convert to world. You cannot specify the same axis via worldAxes and pixelAxes. Values in pixelIn are converted to world and put into worldOut in the appropriate world axis location. Values in worldIn are copied to worldOut. Values in worldIn are converted to pixel and put into pixelOut in the appropriate pixel axis location. Values in pixelIn are copied to pixelOut. worldMin and worldMax specify the range of the world coordinate (in the world axis units of that world axis in the CoordinateSystem) being solved for in a mixed calculation for each world axis. They are only actually needed for DirectionCoordinates and for all other Coordinates the relevant elements can be undefined. If you don't know, use -180 to 180 degrees for longitude, and -90 to 90 for latitude. Removed axes are handled (for example, a removed pixel axis with remaining corresponding world axis will correctly be converted to world using the replacement value). Returns True if the conversion succeeds, otherwise it returns False and errorMessage() contains an error message. The output vectors are resized.
Set the world min and max ranges, for use in function toMix, for a lattice of the given shape for this coordinate.
The default implementation here sets the range for pixels dangling 25% off the image. Returns False if fails with a reason in errorMessage(). setDefaultWorldMixRanges sets the range for each axis to +/-1e99 The ranges remain zero length vectors until you explicitly initialize them.
| virtual void casa::Coordinate::setDefaultWorldMixRanges | ( | ) | [virtual] |
| virtual Bool casa::Coordinate::toWorldMany | ( | Matrix< Double > & | world, | |
| const Matrix< Double > & | pixel, | |||
| Vector< Bool > & | failures | |||
| ) | const [virtual] |
Batch up a lot of transformations.
The first (most rapidly varying) axis of the matrices contain the coordinates. Returns False if any conversion failed and errorMessage() will hold a message. The failures array (True for fail, False for success) is the length of the number of conversions and holds an error status for each conversion. The default implementation is provided that works with the "single" version of toWorld and toPixel, but for maximum efficiency these should be overridden.
| virtual Bool casa::Coordinate::toPixelMany | ( | Matrix< Double > & | pixel, | |
| const Matrix< Double > & | world, | |||
| Vector< Bool > & | failures | |||
| ) | const [virtual] |
Make absolute coordinates relative and vice-versa (with respect to the reference value).
Vectors must be length nPixelAxes() or nWorldAxes() or memory access errors will occur
| virtual void casa::Coordinate::makeWorldAbsoluteRef | ( | Vector< Double > & | world, | |
| const Vector< Double > & | refVal | |||
| ) | const [virtual] |
Make absolute coordinates relative and vice versa with respect to the given reference value.
Add the other functions in this grouping as needed. Vectors must be length nPixelAxes() or nWorldAxes() or memory access errors will occur
Batch up a lot of absolute/relative transformations.
Parameters as above for toWorldMany and toPixelMany
Return the requested attributed.
Set the requested attribute.
Note that these just change the internal values, they do not cause any recomputation.
Change the units.
Adjust the increment and reference value by the ratio of the old and new units. This implies that the units must be known Unit strings, and that they must be compatible, e.g. they can't change from time to length.
A default implementation is available which does everything except set the units vector, which must be done in the derived class.
| virtual Coordinate* casa::Coordinate::makeFourierCoordinate | ( | const Vector< Bool > & | axes, | |
| const Vector< Int > & | shape | |||
| ) | const [virtual] |
Find the Coordinate for when we Fourier Transform ourselves.
This pointer must be deleted by the caller. Axes specifies which axes of the Coordinate you wish to transform. Shape specifies the shape of the image associated with all the axes of the Coordinate. Currently the output reference pixel is always shape/2.
| const String & casa::Coordinate::errorMessage | ( | ) | const [inline] |
If the last conversion to world or pixel coordinates resulted in an error, report that error.
If the last conversion succeeded, it is undefined what this will return (it might well contain the last error message).
Definition at line 558 of file Coordinate.h.
References error_p.
| virtual Bool casa::Coordinate::near | ( | const Coordinate & | other, | |
| Double | tol = 1.0e-6 | |||
| ) | const [pure virtual] |
Comparison to fractional tolerance (for floating point values).
Don't compare on specified axes in Coordinate. If the comparison returns False, errorMessage() contains a message.
| virtual Bool casa::Coordinate::near | ( | const Coordinate & | other, | |
| const Vector< Int > & | excludeAxes, | |||
| Double | tol = 1.0e-6 | |||
| ) | const [pure virtual] |
| virtual void casa::Coordinate::getPrecision | ( | Int & | precision, | |
| Coordinate::formatType & | format, | |||
| Bool | showAsAbsolute, | |||
| Int | defPrecScientific, | |||
| Int | defPrecFixed, | |||
| Int | defPrecTime | |||
| ) | const [virtual] |
Provide a common interface to getting formatted representations of coordinate values.
Different derived Coordinate types are formatted in different ways. For example, an RA/DEC DirectionCoordinate uses an HMS.SS/DMS.SS representation. A Galactic Lat/Long DirectionCoordinate uses floating format in degrees. Other derived Coordinates are formatted with scientific format or floating format. The derived class format functions provide this functionality.
You may specify the format with the format argument and a value from the enum Coordinate::formatType. If you give it the value Coordinate::DEFAULT then a sensible default is used.
A mechanism for specifying the precision number of significant digits after decimal point is provided. You can specify the precision directly when calling format if it is unambiguous how the derived Coordinate is going to be formatted. For example, a LinearCoordinate is always formatted with scientific format. However, if you are using these classes polymorphically, you don't want to have to know this and some derived Coordinates may be formatted in multiple ways (such as the DirectionCoordinate examples above). Therefore, the function getPrecision enables you to set default precisions for the different styles of formatting used variously in the base and derived classes. This function chooses the precision from these default values, according to the type of derived Coordinate that your object is and what value for format that you give (refer to the derived classes for details on this).
Some derived classes will format differently depending upon whether you want to format an absolute or offset world value input via absolute (e.g. DirectionCoordinates).
The provided worldValue must be in the native units of the Coordinate. It may be an absolute (isAbsolute=True) or relative (isAbsolute=False) value. You may choose to format the world value as absolute (showAsAbsolute=True) or relative (showAsAbsolute=False). axis specifies which axis of the Coordinate this value belongs to.
units specifies the units in which the input world value will be formatted. If units is empty, the native unit for the given axis is used.
Some derived classes will format in units different from the native unit of the Coordinate. The units of the formatted number are returned in units. If the units string is provided, the unit must be consistent with the native unit of the coordinate. The input world value will be converted to this unit.
You can also use the Quantum interface. The units of the Quantum can then be anything consistent with the Coordinate.
The default implementation here is to format only with scientific or fixed formats. If precision is negative, a the default precision is used.
| virtual String casa::Coordinate::format | ( | String & | units, | |
| Coordinate::formatType | format, | |||
| Double | worldValue, | |||
| uInt | axis, | |||
| Bool | isAbsolute = True, |
|||
| Bool | showAsAbsolute = True, |
|||
| Int | precision = -1 | |||
| ) | [virtual] |
| String casa::Coordinate::formatQuantity | ( | String & | units, | |
| Coordinate::formatType | format, | |||
| const Quantum< Double > & | worldValue, | |||
| uInt | axis, | |||
| Bool | isAbsolute = True, |
|||
| Bool | showAsAbsolute = True, |
|||
| Int | precision = -1 | |||
| ) |
| virtual Bool casa::Coordinate::save | ( | RecordInterface & | container, | |
| const String & | fieldName | |||
| ) | const [pure virtual] |
Used for persistence.
Derived classes will have similar static restore methods. It will typically only return False if fieldName has already been defined.
| virtual Coordinate* casa::Coordinate::clone | ( | ) | const [pure virtual] |
Make a copy of ourself.
This pointer has been allocated with new and must be deleted by the caller.
| virtual Bool casa::Coordinate::doNearPixel | ( | const Coordinate & | other, | |
| const Vector< Bool > & | thisAxes, | |||
| const Vector< Bool > & | otherAxes, | |||
| Double | tol = 1.0e-6 | |||
| ) | const [virtual] |
Comparison only made for specified axes in this and other Coordinate The default implementation should be ok for all Coordinate types except Stokes.
\..
| Coordinate& casa::Coordinate::operator= | ( | const Coordinate & | other | ) | [protected] |
Assignment (copy semantics).
| void casa::Coordinate::set_error | ( | const String & | errorMsg | ) | const [protected] |
Set error message.
| Bool casa::Coordinate::find_scale_factor | ( | String & | error, | |
| Vector< Double > & | factor, | |||
| const Vector< String > & | units, | |||
| const Vector< String > & | oldUnits | |||
| ) | [protected] |
| void casa::Coordinate::fourierUnits | ( | String & | nameOut, | |
| String & | unitOut, | |||
| String & | unitInCanon, | |||
| Coordinate::Type | type, | |||
| Int | axis, | |||
| const String & | unitIn, | |||
| const String & | nameIn | |||
| ) | const [protected] |
Tries to find a canonical unit for input unit (e.g.
GHz -> Hz), and tells you the output name and unit for the Fourier coordinate pairing with the canonical unit
| Bool casa::Coordinate::toWorldWCS | ( | Vector< Double > & | world, | |
| const Vector< Double > & | pixel, | |||
| wcsprm & | wcs | |||
| ) | const [protected] |
Functions to interconvert pixel<->world via wcs.
These functions are called explicitly by the to{world,Pixel} functions in the appropriate wcs-based derived classes.
| Bool casa::Coordinate::toPixelWCS | ( | Vector< Double > & | pixel, | |
| const Vector< Double > & | world, | |||
| wcsprm & | wcs | |||
| ) | const [protected] |