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

#include <DirectionCoordinate.h>

Inheritance diagram for casa::DirectionCoordinate:

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) const
	Convert a pixel position to a world position or vice versa.
virtual Bool	toPixel (Vector< Double > &pixel, const Vector< Double > &world) const
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
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 cardinal directions (left-right, up-down).
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.
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

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

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 is 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

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

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, Projection(Projection::SIN), refLon, refLat, incLon, incLat, xform, 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 217 of file DirectionCoordinate.h.

Constructor & Destructor Documentation

casa::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.

casa::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.

casa::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)

casa::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

casa::DirectionCoordinate::DirectionCoordinate ( const DirectionCoordinate & other )

Copy constructor (copy semantics)

virtual casa::DirectionCoordinate::~DirectionCoordinate ( ) [virtual]

Destructor.

Member Function Documentation

static Vector<String> casa::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.

void casa::DirectionCoordinate::checkFormat	(	Coordinate::formatType &	format,
		Bool	absolute
	)		const `[private]`

Check formatting types.

Reimplemented from casa::Coordinate.

virtual Coordinate* casa::DirectionCoordinate::clone ( ) const [virtual]

Make a copy of the DirectionCoordinate using new.

The caller is responsible for calling delete.

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

Bool casa::DirectionCoordinate::cylindricalFix	(	Int	shapeLong,
		Int	shapeLat
	)

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

String casa::DirectionCoordinate::formatLatitude	(	String &	units,
		MVAngle &	mVA,
		Bool	absolute,
		Coordinate::formatType	form,
		Int	prec
	)		const `[private]`

virtual void casa::DirectionCoordinate::getPrecision	(	Int &	precision,
		Coordinate::formatType &	format,
		Bool	showAsAbsolute,
		Int	defPrecScientific,
		Int	defPrecFixed,
		Int	defPrecTime
	)		const `[virtual]`

void casa::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]`

virtual Coordinate* casa::DirectionCoordinate::makeFourierCoordinate	(	const Vector< Bool > &	axes,
		const Vector< Int > &	shape
	)		const `[virtual]`

void casa::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]`

virtual void casa::DirectionCoordinate::makeWorldAbsoluteRef	(	Vector< Double > &	world,
		const Vector< Double > &	refVal
	)		const `[virtual]`

virtual Bool casa::DirectionCoordinate::near	(	const Coordinate &	other,
		Double	tol = `1e-6`
	)		const `[virtual]`

Double casa::DirectionCoordinate::putLongInPiRange	(	Double	lon,
		const String &	unit
	)		const `[private]`

static DirectionCoordinate* casa::DirectionCoordinate::restore	(	const RecordInterface &	container,
		const String &	fieldName
	)		`[static]`

virtual Bool casa::DirectionCoordinate::save	(	RecordInterface &	container,
		const String &	fieldName
	)		const `[virtual]`

void casa::DirectionCoordinate::setRotationMatrix	(	RotMatrix &	rot,
		Double	lon,
		Double	lat
	)		const `[private]`

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

virtual Bool casa::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]`

Bool casa::DirectionCoordinate::toMix2	(	Vector< Double > &	out,
		const Vector< Double > &	in,
		const Vector< Double > &	minWorld,
		const Vector< Double > &	maxWorld,
		Bool	longIsWorld
	)		const `[private]`

virtual Bool casa::DirectionCoordinate::toPixel	(	Vector< Double > &	pixel,
		const Vector< Double > &	world
	)		const `[virtual]`

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

virtual Bool casa::DirectionCoordinate::toPixelMany	(	Matrix< Double > &	pixel,
		const Matrix< Double > &	world,
		Vector< Bool > &	failures
	)		const `[virtual]`

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Intended use:

Review Status

Prerequisite

Synopsis

Example

Example

Motivation

Thrown Exceptions

To Do

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

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

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