Interconvert between pixel and a linear world coordinate. More...

#include <LinearCoordinate.h>

Inheritance diagram for casacore::LinearCoordinate:

Public Member Functions
	LinearCoordinate (uInt naxes=1)
	The default constructor makes a LinearCoordinate for which pixel and world coordinates are equal. More...

	LinearCoordinate (const Vector< String > &names, const Vector< String > &units, const Vector< Double > &refVal, const Vector< Double > &inc, const Matrix< Double > &pc, const Vector< Double > &refPix)
	Construct the LinearCoordinate. More...

	LinearCoordinate (const Vector< String > &names, const Vector< Quantum< Double > > &refVal, const Vector< Quantum< Double > > &inc, const Matrix< Double > &pc, const Vector< Double > &refPix)
	Construct LinearCoordinate with Quantum-based interface. More...

	LinearCoordinate (const wcsprm &wcs, Bool oneRel=True)
	Constructor from WCS structure; must hold ONLY a linear wcs structure Specify whether the absolute pixel coordinates in the wcs structure are 0- or 1-relative. More...

	LinearCoordinate (const LinearCoordinate &other)
	Copy constructor (copy semantics). More...

LinearCoordinate &	operator= (const LinearCoordinate &other)
	Assignment (copy semantics). More...

virtual	~LinearCoordinate ()
	Destructor. More...

virtual Coordinate::Type	type () const
	Returns Coordinate::LINEAR. More...

virtual String	showType () const
	Returns the String "Linear". More...

virtual uInt	nPixelAxes () const
	Returns the number of pixel/world axes. More...

virtual uInt	nWorldAxes () const

virtual Bool	toWorld (Vector< Double > &world, const Vector< Double > &pixel, Bool=True) const
	Convert a pixel position to a worl position or vice versa. More...

virtual Bool	toPixel (Vector< Double > &pixel, const Vector< Double > &world) const

virtual Vector< String >	worldAxisNames () const
	Return the requested attribute. More...

virtual Vector< Double >	referenceValue () const

virtual Vector< Double >	increment () const

virtual Matrix< Double >	linearTransform () const

virtual Vector< Double >	referencePixel () const

virtual Vector< String >	worldAxisUnits () const

virtual Bool	setWorldAxisNames (const Vector< String > &names)
	Set the value of the requested attributed. More...

virtual Bool	setReferencePixel (const Vector< Double > &refPix)

virtual Bool	setLinearTransform (const Matrix< Double > &pc)

virtual Bool	setIncrement (const Vector< Double > &inc)

virtual Bool	setReferenceValue (const Vector< Double > &refval)

virtual Bool	setWorldAxisUnits (const Vector< String > &units)
	Set the world axis units. More...

Bool	overwriteWorldAxisUnits (const Vector< String > &units)
	Overwrite the world axis units with no compatibility checks or adjustment. More...

virtual Bool	near (const Coordinate &other, Double tol=1e-6) const
	Comparison function. More...

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

virtual Coordinate *	makeFourierCoordinate (const Vector< Bool > &axes, const Vector< Int > &shape) const
	Find the Coordinate for when we Fourier Transform ourselves. More...

virtual Bool	save (RecordInterface &container, const String &fieldName) const
	Save the LinearCoordinate into the supplied record using the supplied field name. More...

virtual Coordinate *	clone () const
	Make a copy of the LinearCoordinate using new. More...

Public Member Functions inherited from casacore::Coordinate
virtual	~Coordinate ()
	Destructor. More...

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. More...

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. More...

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. More...

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). More...

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. More...

virtual void	makePixelRelativeMany (Matrix< Double > &pixel) const
	Batch up a lot of absolute/relative transformations. More...

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. More...

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. More...

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

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... More...

virtual Coordinate *	rotate (const Quantum< Double > &angle) const
	return the result of rotating the coordinate clockwise through the specified angle. More...

Static Public Member Functions
static LinearCoordinate *	restore (const RecordInterface &container, const String &fieldName)
	Restore the LinearCoordinate from a record. More...

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. More...

static void	init_wcs (::wcsprm &wcs, int naxis)
	Call wcsini on the wcs structure. More...

static void	sub_wcs (const ::wcsprm &src, int &nsub, int axes[],::wcsprm &dst)
	Call wcssub on the src/dst pair. More...

static void	copy_wcs (const ::wcsprm &src,::wcsprm &dst)
	Call wcssub on the src/dst pair with null nsub/axes. More...

Private Member Functions
void	copy (const LinearCoordinate &other)
	Copy private data. More...

void	makeWCS (wcsprm &wcs, uInt naxis, const Vector< Double > &refPix, const Vector< Double > &refVal, const Vector< Double > &incr, const Matrix< Double > &pc, const Vector< String > &units, const Vector< String > &names)
	Make wcs structure. More...

Private Attributes
mutable::wcsprm	wcs_p
	An interface to the WCSLIB linear transformation routines. More...

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. More...

	Coordinate (const Coordinate &other)
	Copy constructor (copy semantics) More...

Coordinate &	operator= (const Coordinate &other)
	Assignment (copy semantics) More...

void	set_error (const String &errorMsg) const
	Set error message. More...

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. More...

Bool	toWorldWCS (Vector< Double > &world, const Vector< Double > &pixel, wcsprm &wcs) const
	Functions to interconvert pixel<->world via wcs. More...

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. More...

void	fromCurrentMany (Matrix< Double > &world, const Vector< Double > &toCurrentFactors) const

virtual void	convertTo (Vector< Double > &) const
	Functions for handling conversion between the current reference frame and the native one. More...

virtual void	convertFrom (Vector< Double > &) const

void	convertToMany (Matrix< Double > &world) const
	Functions for handling conversion between the current reference frame and the native one for many conversions. More...

void	convertFromMany (Matrix< Double > &world) const

void	pcToXform (Matrix< Double > &xForm, const wcsprm &wcs) const
	Interconvert between wcs PC cards and Matrix xForm format. More...

void	xFormToPC (wcsprm &wcs, const Matrix< Double > &xForm) const

Protected Attributes inherited from casacore::Coordinate
Vector< Double >	worldMin_p
	toMix ranges. More...

Vector< Double >	worldMax_p

Detailed Description

Interconvert between pixel and a linear world coordinate.

Intended use:

Public interface

Review Status

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

Prerequisite

Coordinate defines the fundamental interface to coordinate conversions.

Synopsis

The LinearCoordinate class ties pixel and world axes together through a general linear transformation.

world = (cdelt * PC * (pixel - crpix)) + crval

Where PC is an NxN matrix; pixel, crval, crpix and world are length N vectors, and cdelt is an NxN diagonal matrix, represented as a length N vector.

The LinearCoordinate can contain several uncoupled axes (similar to the way in which the DirectionCoordinate contains two axes).

Caution: All pixels coordinates are zero relative;

Example

Let's make a LinearCoordinate with just one axis containing a coordinate describing length.

Vector<Double> crpix(1); crpix = 0.0;
Vector<Double> crval(1); crval = 100.0;
Vector<Double> cdelt(1); cdelt = -10.0;
Matrix<Double> pc(1,1); pc= 0; pc.diagonal() = 1.0;
Vector<String> name(1);  name = "length";
Vector<String> units(1); units = "km";
LinearCoordinate lin(names, units, crval, cdelt, pc, crpix);

Now do a coordinate conversion

Vector<Double> world, pixel(1);
pixel = 2.0;
if (!lin.toWorld(world, pixel)) {
cerr << "Error : " << lin.errorMessage() << endl;
} else {
cerr << "pixel, world = " << pixel << world << endl;
}

The answer should of course be -20km.

Motivation

This class is intended for use with axes which do not have specific coordinate types. A "time" axis would be a good example.

Thrown Exceptions

AipsError

To Do

Allow differing numbers of world and pixel axes. Requires a change in WCS or use of a different library.

Definition at line 120 of file LinearCoordinate.h.

Constructor & Destructor Documentation

casacore::LinearCoordinate::LinearCoordinate ( uInt naxes = 1 )

The default constructor makes a LinearCoordinate for which pixel and world coordinates are equal.

naxes gives the number of axes in the Coordinate.

casacore::LinearCoordinate::LinearCoordinate	(	const Vector< String > &	names,
		const Vector< String > &	units,
		const Vector< Double > &	refVal,
		const Vector< Double > &	inc,
		const Matrix< Double > &	pc,
		const Vector< Double > &	refPix
	)

Construct the LinearCoordinate.

casacore::LinearCoordinate::LinearCoordinate	(	const Vector< String > &	names,
		const Vector< Quantum< Double > > &	refVal,
		const Vector< Quantum< Double > > &	inc,
		const Matrix< Double > &	pc,
		const Vector< Double > &	refPix
	)

Construct LinearCoordinate with Quantum-based interface.

The units of the increment (inc) will be converted to those of the reference value (refVal) which will then serve as the units of the Coordinate.

casacore::LinearCoordinate::LinearCoordinate	(	const wcsprm &	wcs,
		Bool	oneRel = `True`
	)

Constructor from WCS structure; must hold ONLY a linear 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

casacore::LinearCoordinate::LinearCoordinate ( const LinearCoordinate & other )

Copy constructor (copy semantics).

virtual casacore::LinearCoordinate::~LinearCoordinate ( )

virtual

Destructor.

Member Function Documentation

virtual Coordinate* casacore::LinearCoordinate::clone ( ) const

virtual

Make a copy of the LinearCoordinate using new.

The caller is responsible for calling delete.

Implements casacore::Coordinate.

void casacore::LinearCoordinate::copy ( const LinearCoordinate & other )

private

Copy private data.

virtual Vector<Double> casacore::LinearCoordinate::increment ( ) const

virtual

Implements casacore::Coordinate.

virtual Matrix<Double> casacore::LinearCoordinate::linearTransform ( ) const

virtual

Implements casacore::Coordinate.

virtual Coordinate* casacore::LinearCoordinate::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.

void casacore::LinearCoordinate::makeWCS	(	wcsprm &	wcs,
		uInt	naxis,
		const Vector< Double > &	refPix,
		const Vector< Double > &	refVal,
		const Vector< Double > &	incr,
		const Matrix< Double > &	pc,
		const Vector< String > &	units,
		const Vector< String > &	names
	)

private

Make wcs structure.

virtual Bool casacore::LinearCoordinate::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 contains a message about why.

Implements casacore::Coordinate.

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

virtual

Implements casacore::Coordinate.

virtual uInt casacore::LinearCoordinate::nPixelAxes ( ) const

virtual

Returns the number of pixel/world axes.

The number of axes is arbitrary, however the number of world and pixel axes must at present be the same.

Implements casacore::Coordinate.

virtual uInt casacore::LinearCoordinate::nWorldAxes ( ) const

virtual

Implements casacore::Coordinate.

LinearCoordinate& casacore::LinearCoordinate::operator= ( const LinearCoordinate & other )

Assignment (copy semantics).

Bool casacore::LinearCoordinate::overwriteWorldAxisUnits ( const Vector< String > & units )

Overwrite the world axis units with no compatibility checks or adjustment.

virtual Vector<Double> casacore::LinearCoordinate::referencePixel ( ) const

virtual

Implements casacore::Coordinate.

virtual Vector<Double> casacore::LinearCoordinate::referenceValue ( ) const

virtual

Implements casacore::Coordinate.

static LinearCoordinate* casacore::LinearCoordinate::restore	(	const RecordInterface &	container,
		const String &	fieldName
	)

static

Restore the LinearCoordinate from a record.

A null pointer means that the restoration did not succeed - probably because fieldName doesn't exist or doesn't contain a CoordinateSystem.

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

virtual

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

The field must not already exist, otherwise False is returned.

Implements casacore::Coordinate.

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

virtual

Implements casacore::Coordinate.

virtual Bool casacore::LinearCoordinate::setLinearTransform ( const Matrix< Double > & pc )

virtual

Implements casacore::Coordinate.

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

virtual

Implements casacore::Coordinate.

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

virtual

Implements casacore::Coordinate.

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

virtual

Set the value of the requested attributed.

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

Implements casacore::Coordinate.

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

virtual

Set 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 the current units.

Implements casacore::Coordinate.

virtual String casacore::LinearCoordinate::showType ( ) const

virtual

Returns the String "Linear".

Implements casacore::Coordinate.

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

virtual

Implements casacore::Coordinate.

virtual Bool casacore::LinearCoordinate::toWorld	(	Vector< Double > &	world,
		const Vector< Double > &	pixel,
		Bool	= `True`
	)		const

virtual

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

Returns True if the conversion succeeds, otherwise it returns False and method errorMessage returns an error message. The output vectors are appropriately resized. The value of the Bool parameter passed to toWorld() has no effect as this type of coordinate does not support a conversion layer frame.

Implements casacore::Coordinate.

virtual Coordinate::Type casacore::LinearCoordinate::type ( ) const

virtual

Returns Coordinate::LINEAR.

Implements casacore::Coordinate.

virtual Vector<String> casacore::LinearCoordinate::worldAxisNames ( ) const

virtual

Return the requested attribute.

Implements casacore::Coordinate.

virtual Vector<String> casacore::LinearCoordinate::worldAxisUnits ( ) const

virtual

Implements casacore::Coordinate.