Loading...
Searching...
No Matches
casacore::DirectionCoordinate Class Reference
coordinates package (libcasa_coordinates) » Coordinates_module

More...

`#include <DirectionCoordinate.h>`

## Public Member Functions

| DirectionCoordinate ()
| The default constructor creates a J2000 DirectionCoordinate with a CARtesion projection with longitude,latitude 0,0 at pixel 0,0 and an increment of +1 radian per pixel on both axes.
| DirectionCoordinate (MDirection::Types directionType, const Projection &projection, Double refLong, Double refLat, Double incLong, Double incLat, const Matrix< Double > &xform, Double refX, Double refY, Double longPole=999.0, Double latPole=999.0)
| Define the DirectionCoordinate transformation.

DirectionCoordinate (MDirection::Types directionType, const Projection &projection, const Quantum< Double > &refLong, const Quantum< Double > &refLat, const Quantum< Double > &incLong, const Quantum< Double > &incLat, const Matrix< Double > &xform, Double refX, Double refY, const Quantum< Double > &longPole=Quantum< Double >(999.0, Unit("rad")), const Quantum< Double > &latPole=Quantum< Double >(999.0, Unit("rad")))

| Create DirectionCoordinate with Quantum-based interface.
| DirectionCoordinate (MDirection::Types directionType, const ::wcsprm &wcs, Bool oneRel=True)
| Constructor from WCS structure; must hold ONLY a celestial wcs structure Specify whether the absolute pixel coordinates in the wcs structure are 0- or 1-relative.
| DirectionCoordinate (const DirectionCoordinate &other)
| Copy constructor (copy semantics).
DirectionCoordinate & | operator= (const DirectionCoordinate &other)
| Assignment (copy semantics).
virtual | ~DirectionCoordinate ()
| Destructor.
virtual Coordinate::Type | type () const
| Return Coordinate::DIRECTION.
virtual String | showType () const
| Always returns the String "Direction".
virtual uInt | nPixelAxes () const
| Always returns 2.
virtual uInt | nWorldAxes () const
void | setReferenceConversion (MDirection::Types type)
| Set extra conversion type.
void | getReferenceConversion (MDirection::Types &type) const
virtual Bool | toWorld (Vector< Double > &world, const Vector< Double > &pixel, Bool useConversionFrame=True) const
| Convert a pixel position to a world position or vice versa.
virtual Bool | toPixel (Vector< Double > &pixel, const Vector< Double > &world) const
| world values must have units equivalent to the world axis units.
virtual Bool | toMix (Vector< Double > &worldOut, Vector< Double > &pixelOut, const Vector< Double > &worldIn, const Vector< Double > &pixelIn, const Vector< Bool > &worldAxes, const Vector< Bool > &pixelAxes, const Vector< Double > &worldMin, const Vector< Double > &worldMax) const
| Mixed pixel/world coordinate conversion.
virtual Bool | setWorldMixRanges (const IPosition &shape)
| Compute and retrieve the world min and max ranges, for use in function toMix, for a lattice of the given shape (for this coordinate).
virtual void | setDefaultWorldMixRanges ()
void | setWorldMixRanges (const Vector< Bool > &which, const Vector< Double > &world)
| Non-virtual function.
Bool | toWorld (MDirection &world, const Vector< Double > &pixel) const
| A convenient way to turn the world vector into an MDirection or MVDirection for further processing in the Measures system.
Bool | toPixel (Vector< Double > &pixel, const MDirection &world) const
Bool | toWorld (MVDirection &world, const Vector< Double > &pixel) const
Bool | toPixel (Vector< Double > &pixel, const MVDirection &world) const
MVDirection | toWorld (const Vector< Double > &pixel) const
Vector< Double > | toPixel (const MVDirection &world) const
Vector< Double > | toPixel (const MDirection &world) 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 | makeWorldRelative (Vector< Double > &world) const
| Make absolute world coordinates relative and vice-versa (relative to the reference value).
virtual void | makeWorldRelative (MDirection &world) const
virtual void | makeWorldAbsolute (Vector< Double > &world) const
virtual void | makeWorldAbsolute (MDirection &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.
MDirection::Types | directionType (Bool showConversion=False) const
| Recover the requested attribute.
Projection | projection () const
virtual Vector< String > | worldAxisNames () const
| Return the requested attributed.
virtual Vector< String > | worldAxisUnits () const
virtual Vector< Double > | referenceValue () const
virtual Vector< Double > | increment () const
virtual Matrix< Double > | linearTransform () const
virtual Vector< Double > | referencePixel () const
virtual Bool | setWorldAxisNames (const Vector< String > &names)
| Set the value of the requested attribute.
virtual Bool | setReferencePixel (const Vector< Double > &refPix)
virtual Bool | setLinearTransform (const Matrix< Double > &xform)
virtual Bool | setIncrement (const Vector< Double > &inc)
virtual Bool | setReferenceValue (const Vector< Double > &refval)
virtual Bool | setWorldAxisUnits (const Vector< String > &units)
| Change the world axis units.
virtual Bool | near (const Coordinate &other, Double tol=1e-6) const
| Comparison function.
virtual Bool | near (const Coordinate &other, const Vector< Int > &excludeAxes, Double tol=1e-6) const
virtual void | getPrecision (Int &precision, Coordinate::formatType &format, Bool showAsAbsolute, Int defPrecScientific, Int defPrecFixed, Int defPrecTime) const
| Format a DirectionCoordinate coordinate world value nicely through the common format interface.
virtual String | format (String &units, Coordinate::formatType format, Double worldValue, uInt axis, Bool isAbsolute, Bool showAsAbsolute, Int precision=-1, Bool usePrecForMixed=False) const
Bool | cylindricalFix (Int shapeLong, Int shapeLat)
| Fix cylindrical coordinates to put the longitude in [-180,180] range.
virtual Coordinate * | makeFourierCoordinate (const Vector< Bool > &axes, const Vector< Int > &shape) const
| Find the Coordinate for when we Fourier Transform ourselves.
virtual Bool | save (RecordInterface &container, const String &fieldName) const
| Save the DirectionCoordinate into the supplied record using the supplied field name.
virtual Coordinate * | clone () const
| Make a copy of the DirectionCoordinate using new.
Vector< Double > | longLatPoles () const
| Fish out the ref and non-native poles (refLong, refLat, longPole, latPole) Not for general use.
Quantity | getPixelArea () const
| get the pixel area.
DirectionCoordinate | convert (Quantity &angle, MDirection::Types directionType) const
| Convert this coordinate to another reference frame by rotating it about the reference pixel so the the axes of the new reference frame are aligned along the current pixel axes.
void | setProjection (const Projection &)
| Set the projection.
void | setReferenceFrame (const MDirection::Types rf)
| Set the base (as opposed to conversion) reference frame.
Bool | hasSquarePixels () const
| Are the pixels square?
Bool | isNCP () const
| Is the projection equivalent to NCP?
Public Member Functions inherited from casacore::Coordinate
virtual | ~Coordinate ()
| Destructor.
Vector< Double > | worldMixMin () const
Vector< Double > | worldMixMax () 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 | 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
const String & | errorMessage () const
| If the last conversion to world or pixel coordinates resulted in an error, report that error.
String | formatQuantity (String &units, Coordinate::formatType format, const Quantum< Double > &worldValue, uInt axis, Bool isAbsolute=True, Bool showAsAbsolute=True, Int precision=-1)
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 and Quality...
virtual Coordinate * | rotate (const Quantum< Double > &angle) const
| return the result of rotating the coordinate clockwise through the specified angle.

## Static Public Member Functions

static Vector< String > | axisNames (MDirection::Types type, Bool FITSName=False)
| Return canonical axis names for the given MDirection type, giving FITS names if desired.
static DirectionCoordinate * | restore (const RecordInterface &container, const String &fieldName)
| Recover the DirectionCoordinate from a record.
Static Public Member Functions inherited from casacore::Coordinate
static String | typeToString (Coordinate::Type type)
static void | set_wcs (::wcsprm &wcs)
| Call wcsset on the wcs structure.
static void | init_wcs (::wcsprm &wcs, int naxis)
| Call wcsini on the wcs structure.
static void | sub_wcs (const ::wcsprm &src, int &nsub, int axes[], ::wcsprm &dst)
| Call wcssub on the src/dst pair.
static void | copy_wcs (const ::wcsprm &src, ::wcsprm &dst)
| Call wcssub on the src/dst pair with null nsub/axes.

## Private Member Functions

void | toCurrent (Vector< Double > &degrees) const
| Interconvert between the current units and wcs units (degrees).
void | fromCurrent (Vector< Double > &current) const
void | checkFormat (Coordinate::formatType &format, Bool absolute) const
| Check formatting types.
String | formatLatitude (String &units, MVAngle &mVA, Bool absolute, Coordinate::formatType form, Int prec) const
| Format a latitude.
String | formatLongitude (String &units, MVAngle &mVA, MDirection::GlobalTypes gtype, Bool absolute, Coordinate::formatType form, Int prec) const
| Format a longitude.
Bool | toMix2 (Vector< Double > &out, const Vector< Double > &in, const Vector< Double > &minWorld, const Vector< Double > &maxWorld, Bool longIsWorld) const
| Mixed pixel/world coordinate conversion.
void | initializeFactors ()
| Initialize unit conversion vectors and units.
void | makeDirectionCoordinate (MDirection::Types directionType, const Projection &proj, Double refLong, Double refLat, Double incLong, Double incLat, const Matrix< Double > &xform, Double refX, Double refY, Double longPole, Double latPole)
| Helper functions interfacing to WCS.
void | makeWCS (::wcsprm &wcs, const Matrix< Double > &xform, const Projection &proj, MDirection::Types directionType, Double refPixLong, Double refPixLat, Double refLong, Double refLat, Double incLong, Double incLat, Double longPole, Double latPole)
void | normalizePCMatrix ()
| Normalize each row of the PC matrix such that increment() will return the actual angular increment and any scale factors are removed from the PC matrix (modifies wcs_p.pc and wcs_p.cdelt and wcs_p.altlin, executes set_wcs() and hence wcsset() on the struct) See Greisen & Calabretta, A&A 395, 1061-1075 (2002), equation (4).
Double | putLongInPiRange (Double lon, const String &unit) const
void | makeConversionMachines ()
| Set up conversion machine.
virtual void | convertTo (Vector< Double > &world) const
| Convert from type_p -> conversionType_p.
virtual void | convertFrom (Vector< Double > &world) const
void | copy (const DirectionCoordinate &other)
| Copy private data.
void | setRotationMatrix ()
| Set up the offset coordinate rotation matrix.
void | setRotationMatrix (RotMatrix &rot, Double lon, Double lat) const
const Vector< Double > | toCurrentFactors () const
| Return unit conversion vector for converting to current units.

## Private Attributes

MDirection::Types | type_p
| Direction type.
MDirection::Types | conversionType_p
Projection | projection_p
| Projection parameters.
mutable::wcsprm | wcs_p
| WCS structure.
Vector< Double > | to_degrees_p
| WCS computes in degrees - use this to convert back and forth between current DirectionCoordinate units and degrees or radians.
Vector< Double > | to_radians_p
Vector< String > | names_p
| Axis names.
Vector< String > | units_p
| Current units.
RotMatrix | rot_p
| Rotation matrix used to handle relative coordinates.
MDirection::Convert * | pConversionMachineTo_p
| Conversion machines.
MDirection::Convert * | pConversionMachineFrom_p

## Additional Inherited Members

Public Types inherited from casacore::Coordinate
enum | Type { LINEAR , DIRECTION , SPECTRAL , STOKES , TABULAR , QUALITY , COORDSYS }
| This enum lists the types of the derived classes. More...
enum | formatType { DEFAULT , SCIENTIFIC , FIXED , MIXED , TIME }
| This enum is used for formatting world values into Strings. More...
Protected Member Functions inherited from casacore::Coordinate
| 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.
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
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
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
Protected Attributes inherited from casacore::Coordinate
Vector< Double > | worldMin_p
| toMix ranges.
Vector< Double > | worldMax_p

## Detailed Description

Interconvert pixel positions and directions (e.g. RA/DEC).

### Intended use:

Public interface

### Review Status

Reviewed By:
  Peter Barnes
Date Reviewed:
  1999/12/24
Test programs:
  tDirectionCoordinate

### Prerequisite

- Knowledge of astronomical coordinate conversions in general. Probably the best documents are the papers by Mark Calabretta and Eric Greisen. The initial draft from 1996 can be found at http://www.atnf.csiro.au/~mcalabre. It is this draft that the Coordinate classes are based upon. Since then, this paper has evolved into three which can be found at the above address, and will be published in the Astronomy and Astrophysics Supplement Series (probably in 2000). The design has changed since the initial draft. When these papers are finalized, and the IAU has ratified the new standards, WCSLIB (Mark Calabretta's implementation of these conventions) will be revised for the new designs. At that time, the Coordinate classes may also be revised.
- Coordinate defines the fundamental interface to coordinate conversions.
- MDirection defines the types of directions (J2000 etc.) which are defined. The measures machinery also implements "astronomical" conversions which are outside the scope of these coordinates (for example, J2000 to B1950).
- Projection defines the types of celestial projections which are available.

### Synopsis

This class implements pixel to world coordinate conversions. This class implements geometric conversions (e.g. SIN projection) via the WCS library and also provides an interface to astronomical conversions (RA/DEC <--> l,b) via the Measures module.

Caution: All absolute pixels coordinates are zero relative;

### Example

Let's make a DirectionCoordinate — used to represent a direction, usually an RA/DEC, but it could also be, e.g., an AZ/EL pair.

Matrix<Double> xform(2,2); // 1
xform = 0.0; xform.diagonal() = 1.0; // 2
DirectionCoordinate radec(MDirection::J2000, // 3
Projection(Projection::SIN), // 4
135*C::pi/180.0, 60*C::pi/180.0, // 5
-1*C::pi/180.0, 1*C::pi/180, // 6
xform, // 7
128, 128); // 8
casacore::DirectionCoordinate::DirectionCoordinate
DirectionCoordinate()
The default constructor creates a J2000 DirectionCoordinate with a CARtesion projection with longitud...
casacore::MDirection::J2000
@ J2000
Definition MDirection.h:186
casacore::Matrix
Definition Matrix.h:87
casacore::Projection
Definition Projection.h:94
casacore::Projection::SIN
@ SIN
Orthographics/synthesis.
Definition Projection.h:105
casacore::C::pi
constexpr double pi
Pi and functions thereof:
Definition Constants.h:363

- 1-2:Here we set up a diagonal transformation matrix.
  Normally this matrix should be diagonal, however if you wanted to introduce a rotation or skew, you would do it through this matrix.
- 3:This defines the astronomical type of the world coordinate. Most of the time it will probably be J2000
  or B1950, but many other possibilities are possible as listed in the MDirection class header.
- 4:The Projection class defines the "geometry" that is used to map xy<–>world. SIN is the most common projection for radio interferometers. Note that SIN can optionally take parameters as defined in Calabretta and Greisen. If not provided, they default to 0.0, which is the "old" SIN convention.
- 5:Set the reference position to RA=135, DEC=60 degrees. Note that the native units of a Direction is radians.
- 6: Set the increments to -1 degree in RA, and +1 degree in DEC.
- 7: Set the previously defined transformation matrix.
- 8: Set the zero-relative reference pixel. Note that it does not have to be incremental. At the reference pixel, the world coordinate has the reference value.

In this example it is more convenient to change the units to degrees. This can be accomplished as follows:

Vector<String> units(2); units = "deg"; // 9
radec.setWorldAxisUnits(units); // 10
casacore::Vector
Definition Vector.h:82

The increment and reference value are updated appropriately.

Set up a couple of vectors to use the world and pixel coordinate values.

Vector<Double> world(2), pixel(2); // 11
pixel = 138.0; // 12

We use 138 as an arbitrary pixel position which is near the reference pixel so we can tell if the answers look foolish or not. We can actually perform a transformation like this as follows. If it succeeds we print the value of the world coordinate.

Bool ok = radec.toWorld(world, pixel); // 13
if (!ok) { // 14
cout << "Error: " << radec.errorMessage() << endl; // 15
return 1; // 16
} // 17
cout << world << " <--- " << pixel << endl; // 18
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40

There is an overloaded "toWorld" function that produces an MDirection in case you want to, e.g., find out what the position in B1950 coordinates would be.

The reverse transformation takes place similarly:

ok = radec.toPixel(pixel, world); // 19

### Example

We could also have made the above DirectionCoordinate using the Quantum-based constructor, which is a little more elegant if you want to use degrees.

Matrix<Double> xform(2,2);
xform = 0.0; xform.diagonal() = 1.0;
Quantum<Double> refLon(135.0, "deg"); Quantum<Double> refLat(60.0, "deg"); Quantum<Double> incLon(-1.0, "deg"); Quantum<Double> incLat(1.0, "deg"); DirectionCoordinate radec(MDirection::J2000, \ilinebr<br> Projection(Projection::SIN), refLon, refLat, incLon, incLat, xform, \ilinebr<br> 128, 128);

But note that the constructor will have converted the native units of the DirectionCoordinate to radians. So the Double-based toWorld and toPixel functions will be in terms of radians. If you want the native units to be degrees, then again you can use

Vector<String> units(2); units = "deg";
radec.setWorldAxisUnits(units);

and thereafter degrees are the native units.

### Motivation

Directions in the sky are fundamental to astronomy.

### Thrown Exceptions

- AipsError

### To Do

- Nothing

Definition at line 214 of file DirectionCoordinate.h.

## Constructor & Destructor Documentation

## DirectionCoordinate() [1/5]

casacore::DirectionCoordinate::DirectionCoordinate | ( |  | ) |

The default constructor creates a J2000 DirectionCoordinate with a CARtesion projection with longitude,latitude 0,0 at pixel 0,0 and an increment of +1 radian per pixel on both axes.

Referenced by convert(), copy(), DirectionCoordinate(), operator=(), and restore().

## DirectionCoordinate() [2/5]

casacore::DirectionCoordinate::DirectionCoordinate | ( | MDirection::Types | directionType,
|  | const Projection & | projection,
|  | Double | refLong,
|  | Double | refLat,
|  | Double | incLong,
|  | Double | incLat,
|  | const Matrix< Double > & | xform,
|  | Double | refX,
|  | Double | refY,
|  | Double | longPole = 999.0,
|  | Double | latPole = 999.0 )

Define the DirectionCoordinate transformation.

refLong and refLat will normally the the RA/DEC of the pixel described by refX/refY. incLat/incLong are the increments per pixel (RA is usually negative), and the xform matrix is usually the unit diagonal matrix unless you have a rotation or some other linear transformation between the pixel and world axes.

Note that the units are radians initially. You can change it to degrees or something else with the setWorldAxisUnits method later if you want.

longPole and latPole are defined by Calabretta and Greisen (these are reference points not at the native pole). In general you can leave these out and the default values will cause them to be computed appropriately. However, when reading from FITS the LONPOLE and LATPOLE keywords are passed along here.

References directionType(), and projection().

## DirectionCoordinate() [3/5]

casacore::DirectionCoordinate::DirectionCoordinate | ( | MDirection::Types | directionType,
|  | const Projection & | projection,
|  | const Quantum< Double > & | refLong,
|  | const Quantum< Double > & | refLat,
|  | const Quantum< Double > & | incLong,
|  | const Quantum< Double > & | incLat,
|  | const Matrix< Double > & | xform,
|  | Double | refX,
|  | Double | refY,
|  | const Quantum< Double > & | longPole = Quantum< Double >(999.0, Unit("rad")),
|  | const Quantum< Double > & | latPole = Quantum< Double >(999.0, Unit("rad")) )

Create DirectionCoordinate with Quantum-based interface.

Parameters are the same as above. Regardless of the units of the quanta, the initial units of the DirectionCoordinate will be converted radians. You can change it to degrees or something else with the setWorldAxisUnits method later if you want.

longPole and latPole are defined by Calabretta and Greisen (these are reference points not at the native pole). In general you can leave these out and the default values will cause them to be computed appropriately. However, when reading from FITS the LONPOLE and LATPOLE keywords are passed along here. To get the default the 999.0 value should be used (units are irrelevant in that case)

References directionType(), and projection().

## DirectionCoordinate() [4/5]

casacore::DirectionCoordinate::DirectionCoordinate | ( | MDirection::Types | directionType,
|  | const ::wcsprm & | wcs,
|  | Bool | oneRel = True )

Constructor from WCS structure; must hold ONLY a celestial wcs structure Specify whether the absolute pixel coordinates in the wcs structure are 0- or 1-relative.

The coordinate is always constructed with 0-relative pixel coordinates

References directionType(), and casacore::True.

## DirectionCoordinate() [5/5]

casacore::DirectionCoordinate::DirectionCoordinate | ( | const DirectionCoordinate & | other | ) |

Copy constructor (copy semantics).

References DirectionCoordinate().

## ~DirectionCoordinate()

virtual casacore::DirectionCoordinate::~DirectionCoordinate | ( |  | ) |

virtual

Destructor.

## Member Function Documentation

## axisNames()

Vector< String > casacore::DirectionCoordinate::axisNames | ( | MDirection::Types | type,
|  | Bool | FITSName = False )

static

Return canonical axis names for the given MDirection type, giving FITS names if desired.

BEG think this should be in the MDirection class, but WNB disagrees. Leave it here for now.

References casacore::False, and type().

## checkFormat()

void casacore::DirectionCoordinate::checkFormat | ( | Coordinate::formatType & | format,
|  | Bool | absolute ) const

private

Check formatting types.

References format().

## clone()

virtual Coordinate * casacore::DirectionCoordinate::clone | ( |  | ) | const

virtual

Make a copy of the DirectionCoordinate using new.

The caller is responsible for calling delete.

Implements casacore::Coordinate.

References casacore::Coordinate::Coordinate().

## convert()

DirectionCoordinate casacore::DirectionCoordinate::convert | ( | Quantity & | angle,
|  | MDirection::Types | directionType ) const

Convert this coordinate to another reference frame by rotating it about the reference pixel so the the axes of the new reference frame are aligned along the current pixel axes.

The reference pixel remains the same and the conversion is exact for the reference pixel and in general becomes less accurate as distance from reference pixel increases. The latitude like and the longitude like pixel increments are preserved. Conversions which require extra information such as epoch and position are not supported. The angle parameter is the angle between the new coordinate and the pixel coordinate, measured clockwise from the positive y-axis of the new coordinate to the positive y-axis of the pixel coordinate; ie, it is the clockwise angle through which the current world coordinate would have to be rotated so that the new coordinate's axes would be parallel to the pixel axes. The accuracy of the returned angle is good to at least 7 digits.

References DirectionCoordinate(), and directionType().

## convertFrom()

virtual void casacore::DirectionCoordinate::convertFrom | ( | Vector< Double > & | world | ) | const

private virtual

Reimplemented from casacore::Coordinate.

## convertTo()

virtual void casacore::DirectionCoordinate::convertTo | ( | Vector< Double > & | world | ) | const

private virtual

Convert from type_p -> conversionType_p.

Reimplemented from casacore::Coordinate.

## copy()

void casacore::DirectionCoordinate::copy | ( | const DirectionCoordinate & | other | ) |

private

Copy private data.

References DirectionCoordinate().

## cylindricalFix()

Bool casacore::DirectionCoordinate::cylindricalFix | ( | Int | shapeLong,
|  | Int | shapeLat )

Fix cylindrical coordinates to put the longitude in [-180,180] range.

If False returned, it failed an an error is in errorMessage This fix is not done automatically internally because of the dependence on the image shape. It should be called for any foreign image (such as FITS) that is imported

## directionType()

MDirection::Types casacore::DirectionCoordinate::directionType | ( | Bool | showConversion = False | ) | const

Recover the requested attribute.

References casacore::False.

Referenced by convert(), DirectionCoordinate(), DirectionCoordinate(), DirectionCoordinate(), makeDirectionCoordinate(), and makeWCS().

## format()

virtual String casacore::DirectionCoordinate::format | ( | String & | units,
|  | Coordinate::formatType | format,
|  | Double | worldValue,
|  | uInt | axis,
|  | Bool | isAbsolute,
|  | Bool | showAsAbsolute,
|  | Int | precision = -1,
|  | Bool | usePrecForMixed = False ) const

virtual

Reimplemented from casacore::Coordinate.

References casacore::False, and format().

Referenced by checkFormat(), format(), and getPrecision().

## formatLatitude()

String casacore::DirectionCoordinate::formatLatitude | ( | String & | units,
|  | MVAngle & | mVA,
|  | Bool | absolute,
|  | Coordinate::formatType | form,
|  | Int | prec ) const

private

Format a latitude.

## formatLongitude()

String casacore::DirectionCoordinate::formatLongitude | ( | String & | units,
|  | MVAngle & | mVA,
|  | MDirection::GlobalTypes | gtype,
|  | Bool | absolute,
|  | Coordinate::formatType | form,
|  | Int | prec ) const

private

Format a longitude.

## fromCurrent()

void casacore::DirectionCoordinate::fromCurrent | ( | Vector< Double > & | current | ) | const

private

## getPixelArea()

Quantity casacore::DirectionCoordinate::getPixelArea | ( |  | ) | const

get the pixel area.

## getPrecision()

virtual void casacore::DirectionCoordinate::getPrecision | ( | Int & | precision,
|  | Coordinate::formatType & | format,
|  | Bool | showAsAbsolute,
|  | Int | defPrecScientific,
|  | Int | defPrecFixed,
|  | Int | defPrecTime ) const

virtual

Format a DirectionCoordinate coordinate world value nicely through the common format interface.

See Coordinate for basics.

Formatting types that are allowed are SCIENTIFIC, FIXED, MIXED, and TIME If you ask for format type Coordinate::DEFAULT then the selected format depends upon what the value of the enum MDirection::GlobalTypes is for this DirectionCoordinate. For example, if it is GRADEC or GHADEC you would get Coordinate::TIME style formatting (DD:MM:SS.SS), otherwise you would get Coordinate::FIXED formatting by default.

axis says which axis in this Coordinate we are formatting.
We have to know this because we may format Longitude and Latitude differently.
For Coordinate::TIME style formatting, precision refers to the places after the decimal in the SS field.

If you leave units empty, then it makes up a nice unit for you.

Reimplemented from casacore::Coordinate.

References format().

## getReferenceConversion()

void casacore::DirectionCoordinate::getReferenceConversion | ( | MDirection::Types & | type | ) | const

inline

Definition at line 318 of file DirectionCoordinate.h.

References conversionType_p, and type().

## hasSquarePixels()

Bool casacore::DirectionCoordinate::hasSquarePixels | ( |  | ) | const

Are the pixels square?

## increment()

virtual Vector< Double > casacore::DirectionCoordinate::increment | ( |  | ) | const

virtual

Implements casacore::Coordinate.

## initializeFactors()

void casacore::DirectionCoordinate::initializeFactors | ( |  | ) |

private

Initialize unit conversion vectors and units.

## isNCP()

Bool casacore::DirectionCoordinate::isNCP | ( |  | ) | const

Is the projection equivalent to NCP?

## linearTransform()

virtual Matrix< Double > casacore::DirectionCoordinate::linearTransform | ( |  | ) | const

virtual

Implements casacore::Coordinate.

## longLatPoles()

Vector< Double > casacore::DirectionCoordinate::longLatPoles | ( |  | ) | const

Fish out the ref and non-native poles (refLong, refLat, longPole, latPole) Not for general use.

Units are degrees.

## makeConversionMachines()

void casacore::DirectionCoordinate::makeConversionMachines | ( |  | ) |

private

Set up conversion machine.

## makeDirectionCoordinate()

void casacore::DirectionCoordinate::makeDirectionCoordinate | ( | MDirection::Types | directionType,
|  | const Projection & | proj,
|  | Double | refLong,
|  | Double | refLat,
|  | Double | incLong,
|  | Double | incLat,
|  | const Matrix< Double > & | xform,
|  | Double | refX,
|  | Double | refY,
|  | Double | longPole,
|  | Double | latPole )

private

Helper functions interfacing to WCS.

References directionType().

## makeFourierCoordinate()

virtual Coordinate * casacore::DirectionCoordinate::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. If the pointer returned is 0, it failed with a message in errorMessage

Reimplemented from casacore::Coordinate.

References casacore::Coordinate::Coordinate(), and casacore::shape().

## makeWCS()

void casacore::DirectionCoordinate::makeWCS | ( | ::wcsprm & | wcs,
|  | const Matrix< Double > & | xform,
|  | const Projection & | proj,
|  | MDirection::Types | directionType,
|  | Double | refPixLong,
|  | Double | refPixLat,
|  | Double | refLong,
|  | Double | refLat,
|  | Double | incLong,
|  | Double | incLat,
|  | Double | longPole,
|  | Double | latPole )

private

References directionType().

## makeWorldAbsolute() [1/2]

virtual void casacore::DirectionCoordinate::makeWorldAbsolute | ( | MDirection & | world | ) | const

virtual

## makeWorldAbsolute() [2/2]

virtual void casacore::DirectionCoordinate::makeWorldAbsolute | ( | Vector< Double > & | world | ) | const

virtual

Reimplemented from casacore::Coordinate.

## makeWorldAbsoluteRef()

virtual void casacore::DirectionCoordinate::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.

Reimplemented from casacore::Coordinate.

## makeWorldRelative() [1/2]

virtual void casacore::DirectionCoordinate::makeWorldRelative | ( | MDirection & | world | ) | const

virtual

## makeWorldRelative() [2/2]

virtual void casacore::DirectionCoordinate::makeWorldRelative | ( | Vector< Double > & | world | ) | const

virtual

Make absolute world coordinates relative and vice-versa (relative to the reference value).

Note that these functions are independent of the MDirection::Types (set either at construction or by function setReferenceConversion). The vectors must be of length nWorldAxes or memory access errors will occur

Reimplemented from casacore::Coordinate.

## near() [1/2]

virtual Bool casacore::DirectionCoordinate::near | ( | const Coordinate & | other,
|  | const Vector< Int > & | excludeAxes,
|  | Double | tol = 1e-6 ) const

virtual

Implements casacore::Coordinate.

References casacore::Coordinate::Coordinate().

## near() [2/2]

virtual Bool casacore::DirectionCoordinate::near | ( | const Coordinate & | other,
|  | Double | tol = 1e-6 ) const

virtual

Comparison function.

Any private Double data members are compared
with the specified fractional tolerance. Don't compare on the specified
axes in the Coordinate. If the comparison returns False, method errorMessage returns a message about why.

Implements casacore::Coordinate.

References casacore::Coordinate::Coordinate().

## normalizePCMatrix()

void casacore::DirectionCoordinate::normalizePCMatrix | ( |  | ) |

private

Normalize each row of the PC matrix such that increment() will return the actual angular increment and any scale factors are removed from the PC matrix (modifies wcs_p.pc and wcs_p.cdelt and wcs_p.altlin, executes set_wcs() and hence wcsset() on the struct) See Greisen & Calabretta, A&A 395, 1061-1075 (2002), equation (4).

## nPixelAxes()

virtual uInt casacore::DirectionCoordinate::nPixelAxes | ( |  | ) | const

virtual

Always returns 2.

Implements casacore::Coordinate.

## nWorldAxes()

virtual uInt casacore::DirectionCoordinate::nWorldAxes | ( |  | ) | const

virtual

Implements casacore::Coordinate.

## operator=()

DirectionCoordinate & casacore::DirectionCoordinate::operator= | ( | const DirectionCoordinate & | other | ) |

Assignment (copy semantics).

References DirectionCoordinate().

## projection()

Projection casacore::DirectionCoordinate::projection | ( |  | ) | const

Referenced by DirectionCoordinate(), and DirectionCoordinate().

## putLongInPiRange()

Double casacore::DirectionCoordinate::putLongInPiRange | ( | Double | lon,
|  | const String & | unit ) const

private

## referencePixel()

virtual Vector< Double > casacore::DirectionCoordinate::referencePixel | ( |  | ) | const

virtual

Implements casacore::Coordinate.

## referenceValue()

virtual Vector< Double > casacore::DirectionCoordinate::referenceValue | ( |  | ) | const

virtual

Implements casacore::Coordinate.

## restore()

DirectionCoordinate * casacore::DirectionCoordinate::restore | ( | const RecordInterface & | container,
|  | const String & | fieldName )

static

Recover the DirectionCoordinate from a record.

A null pointer means that the restoration did not succeed.

References DirectionCoordinate(), and casacore::RecordInterface().

## save()

virtual Bool casacore::DirectionCoordinate::save | ( | RecordInterface & | container,
|  | const String & | fieldName ) const

virtual

Save the DirectionCoordinate into the supplied record using the supplied field name.

The field must not exist, otherwise False is returned.

Implements casacore::Coordinate.

References casacore::RecordInterface().

## setDefaultWorldMixRanges()

virtual void casacore::DirectionCoordinate::setDefaultWorldMixRanges | ( |  | ) |

virtual

Reimplemented from casacore::Coordinate.

## setIncrement()

virtual Bool casacore::DirectionCoordinate::setIncrement | ( | const Vector< Double > & | inc | ) |

virtual

Implements casacore::Coordinate.

## setLinearTransform()

virtual Bool casacore::DirectionCoordinate::setLinearTransform | ( | const Matrix< Double > & | xform | ) |

virtual

Implements casacore::Coordinate.

## setProjection()

void casacore::DirectionCoordinate::setProjection | ( | const Projection & |  | ) |

Set the projection.

## setReferenceConversion()

void casacore::DirectionCoordinate::setReferenceConversion | ( | MDirection::Types | type | ) |

Set extra conversion type.

Whenever a conversion from pixel to world is done, the world value is then further converted to this MDirection::Types value. For example, your DirectionCoordinate may be defined in J2000. You can use this to get the world values out in say GALACTIC. Similarly, whenever you convert from world to pixel, the world value is assumed to be that appropriate to the conversionDirectionType. It is first converted to the MDirection::Types with which the DirectionCoordinate was constructed and from there to pixel. If you don't call this function, or you set the same type for which the DirectionCoordinate was constructed, no extra conversions occur. Some conversions will fail. These are the ones that require extra frame information (epoch, position) such as to AZEL from J2000 etc. This will be added later.

In the mixed pixel/world conversion routine toMix the implementation is only partial. See the comments for this function below.

References type().

## setReferenceFrame()

void casacore::DirectionCoordinate::setReferenceFrame | ( | const MDirection::Types | rf | ) |

Set the base (as opposed to conversion) reference frame.

## setReferencePixel()

virtual Bool casacore::DirectionCoordinate::setReferencePixel | ( | const Vector< Double > & | refPix | ) |

virtual

Implements casacore::Coordinate.

## setReferenceValue()

virtual Bool casacore::DirectionCoordinate::setReferenceValue | ( | const Vector< Double > & | refval | ) |

virtual

Implements casacore::Coordinate.

## setRotationMatrix() [1/2]

void casacore::DirectionCoordinate::setRotationMatrix | ( |  | ) |

private

Set up the offset coordinate rotation matrix.

Units of long and lat are current world units

## setRotationMatrix() [2/2]

void casacore::DirectionCoordinate::setRotationMatrix | ( | RotMatrix & | rot,
|  | Double | lon,
|  | Double | lat ) const

private

## setWorldAxisNames()

virtual Bool casacore::DirectionCoordinate::setWorldAxisNames | ( | const Vector< String > & | names | ) |

virtual

Set the value of the requested attribute.

Note that these just change the internal values, they do not cause any recomputation.

Implements casacore::Coordinate.

## setWorldAxisUnits()

virtual Bool casacore::DirectionCoordinate::setWorldAxisUnits | ( | const Vector< String > & | units | ) |

virtual

Change the world axis units.

Adjust the increment and reference value by the ratio of the old and new units. The units must be compatible with angle. The units are initially "rad" (radians).

Implements casacore::Coordinate.

## setWorldMixRanges() [1/2]

virtual Bool casacore::DirectionCoordinate::setWorldMixRanges | ( | const IPosition & | shape | ) |

virtual

Compute and retrieve the world min and max ranges, for use in function toMix, for a lattice of the given shape (for this coordinate).

Using these ranges in toMix should speed it up and help avoid ambiguity. If the shape is negative, that indicates that the shape is unknown for that axis. The default range is used for that axis. This situation arises in a CoordinateSystem for which a pixel, but not a world axis has been removed. The output vectors are resized. Returns False if fails (and then setDefaultWorldMixRanges generates the ranges) with a reason in errorMessage(). The setDefaultWorldMixRanges function just gives you [-90->90], [-180,180] (in appropriate units)

Reimplemented from casacore::Coordinate.

References casacore::shape().

## setWorldMixRanges() [2/2]

void casacore::DirectionCoordinate::setWorldMixRanges | ( | const Vector< Bool > & | which,
|  | const Vector< Double > & | world )

Non-virtual function.

When which is T, use the world value as the center for the mix world range.

## showType()

virtual String casacore::DirectionCoordinate::showType | ( |  | ) | const

virtual

Always returns the String "Direction".

Implements casacore::Coordinate.

## toCurrent()

void casacore::DirectionCoordinate::toCurrent | ( | Vector< Double > & | degrees | ) | const

private

Interconvert between the current units and wcs units (degrees).

## toCurrentFactors()

const Vector< Double > casacore::DirectionCoordinate::toCurrentFactors | ( |  | ) | const

private

Return unit conversion vector for converting to current units.

## toMix()

virtual Bool casacore::DirectionCoordinate::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 pixel/world coordinate conversion.

worldIn and worldAxes are 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. Some mixed solutions can be degenerate, whereupon you you must say which one you want. Use functions setWorldMixRanges and worldMixMin, worldMixMax to set these ranges, If you don't know, use the defaults (function setDefaultWorldMixRanges. 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.

If you actually request a pure pixel to world or world to pixel via toMix, then the functions toWorld or toPixel will be invoked directly (see above) and the extra conversion layer invoked through function setReferenceConversion will be active.
However, if you request a true mixed pixel/world conversion, the extra conversion layer is not activated (because of the nature of mixed conversions). This situation may change in the future with a partial implementation added.

Reimplemented from casacore::Coordinate.

## toMix2()

Bool casacore::DirectionCoordinate::toMix2 | ( | Vector< Double > & | out,
|  | const Vector< Double > & | in,
|  | const Vector< Double > & | minWorld,
|  | const Vector< Double > & | maxWorld,
|  | Bool | longIsWorld ) const

private

Mixed pixel/world coordinate conversion.

Vector in must be length nWorldAxes (2). Specify whether longitude (in(0)) or latitude (in(1)) is the world coordinate. It is assumed that the other value is the pixel coordinate.

## toPixel() [1/5]

Vector< Double > casacore::DirectionCoordinate::toPixel | ( | const MDirection & | world | ) | const

## toPixel() [2/5]

Vector< Double > casacore::DirectionCoordinate::toPixel | ( | const MVDirection & | world | ) | const

## toPixel() [3/5]

Bool casacore::DirectionCoordinate::toPixel | ( | Vector< Double > & | pixel,
|  | const MDirection & | world ) const

## toPixel() [4/5]

Bool casacore::DirectionCoordinate::toPixel | ( | Vector< Double > & | pixel,
|  | const MVDirection & | world ) const

## toPixel() [5/5]

virtual Bool casacore::DirectionCoordinate::toPixel | ( | Vector< Double > & | pixel,
|  | const Vector< Double > & | world ) const

virtual

world values must have units equivalent to the world axis units.

If the coordinate has a conversion layer, the world coordinates must be supplied in the conversion frame.

Implements casacore::Coordinate.

## toPixelMany()

virtual Bool casacore::DirectionCoordinate::toPixelMany | ( | Matrix< Double > & | pixel,
|  | const Matrix< Double > & | world,
|  | Vector< Bool > & | failures ) const

virtual

Reimplemented from casacore::Coordinate.

## toWorld() [1/4]

MVDirection casacore::DirectionCoordinate::toWorld | ( | const Vector< Double > & | pixel | ) | const

## toWorld() [2/4]

Bool casacore::DirectionCoordinate::toWorld | ( | MDirection & | world,
|  | const Vector< Double > & | pixel ) const

A convenient way to turn the world vector into an MDirection or MVDirection for further processing in the Measures system.

We could improve the performance of this if it would be useful. However it is expected that normally one would just call this once to get a template MDirection, and then call the vector versions.
In case of a failure, the versions with a Bool return value will return False. The other versions will throw an exception.

## toWorld() [3/4]

Bool casacore::DirectionCoordinate::toWorld | ( | MVDirection & | world,
|  | const Vector< Double > & | pixel ) const

## toWorld() [4/4]

virtual Bool casacore::DirectionCoordinate::toWorld | ( | Vector< Double > & | world,
|  | const Vector< Double > & | pixel,
|  | Bool | useConversionFrame = True ) const

virtual

Convert a pixel position to a world position or vice versa.

Returns True if the conversion succeeds, otherwise it returns False and method errorMessage returns its error message. The output vectors are appropriately resized. if useConversionFrame, if the coordinate has a conversion layer frame, it is used. Else, the native frame is used for the conversion.

Implements casacore::Coordinate.

References casacore::True.

## toWorldMany()

virtual Bool casacore::DirectionCoordinate::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 is the length of the number of conversions (True for failure, False for success)

Reimplemented from casacore::Coordinate.

## type()

virtual Coordinate::Type casacore::DirectionCoordinate::type | ( |  | ) | const

virtual

Return Coordinate::DIRECTION.

Implements casacore::Coordinate.

Referenced by axisNames(), getReferenceConversion(), and setReferenceConversion().

## worldAxisNames()

virtual Vector< String > casacore::DirectionCoordinate::worldAxisNames | ( |  | ) | const

virtual

Return the requested attributed.

Implements casacore::Coordinate.

## worldAxisUnits()

virtual Vector< String > casacore::DirectionCoordinate::worldAxisUnits | ( |  | ) | const

virtual

Implements casacore::Coordinate.

## Member Data Documentation

## conversionType_p

MDirection::Types casacore::DirectionCoordinate::conversionType_p

private

Definition at line 615 of file DirectionCoordinate.h.

Referenced by getReferenceConversion().

## names_p

Vector<String> casacore::DirectionCoordinate::names_p

private

Axis names.

Definition at line 632 of file DirectionCoordinate.h.

## pConversionMachineFrom_p

MDirection::Convert* casacore::DirectionCoordinate::pConversionMachineFrom_p

mutable private

Definition at line 644 of file DirectionCoordinate.h.

## pConversionMachineTo_p

MDirection::Convert* casacore::DirectionCoordinate::pConversionMachineTo_p

mutable private

Conversion machines.

"To" handles type_p -> conversionType_p "From" handles conversionType_p -> type_p;

Definition at line 643 of file DirectionCoordinate.h.

## projection_p

Projection casacore::DirectionCoordinate::projection_p

private

Projection parameters.

Definition at line 618 of file DirectionCoordinate.h.

## rot_p

RotMatrix casacore::DirectionCoordinate::rot_p

private

Rotation matrix used to handle relative coordinates.

Definition at line 638 of file DirectionCoordinate.h.

## to_degrees_p

Vector<Double> casacore::DirectionCoordinate::to_degrees_p

private

WCS computes in degrees - use this to convert back and forth between current DirectionCoordinate units and degrees or radians.

Definition at line 628 of file DirectionCoordinate.h.

## to_radians_p

Vector<Double> casacore::DirectionCoordinate::to_radians_p

private

Definition at line 629 of file DirectionCoordinate.h.

## type_p

MDirection::Types casacore::DirectionCoordinate::type_p

private

Direction type.

Definition at line 615 of file DirectionCoordinate.h.

## units_p

Vector<String> casacore::DirectionCoordinate::units_p

private

Current units.

Definition at line 635 of file DirectionCoordinate.h.

## wcs_p

mutable::wcsprm casacore::DirectionCoordinate::wcs_p

private

WCS structure.

This is mutable because the wcs functions that do toPixel and toWorld (which have const signature) require a non const wcs structure. so either all of these virtual functions lose their const or we use mutable...

Definition at line 624 of file DirectionCoordinate.h.

The documentation for this class was generated from the following file:

- coordinates/Coordinates/DirectionCoordinate.h