Interconvert pixel and frequency values. More...

#include <SpectralCoordinate.h>

Inheritance diagram for casa::SpectralCoordinate:

Public Types
enum	SpecType { FREQ, VRAD, VOPT, BETA, WAVE, AWAV }
Public Member Functions
	SpectralCoordinate ()
	Default constructor.
	SpectralCoordinate (MFrequency::Types type, Double f0, Double inc, Double refPix, Double restFrequency=0.0)
	Create a linear frequency axis SpectralCoordinate `f0` is the frequency of the reference pixel, `inc` is the pixel increment, `refPix` is the reference pixel.
	SpectralCoordinate (MFrequency::Types type, const Quantum< Double > &f0, const Quantum< Double > &inc, Double refPix, const Quantum< Double > &restFrequency=Quantum< Double >(0.0,"Hz"))
	Create linear frequency axis SpectralCoordinate with Quantum-based interface.
	SpectralCoordinate (MFrequency::Types type, const Vector< Double > &freqs, Double restFrequency=0.0)
	Construct a SpectralCoordinate with the specified frequencies (in Hz).
	SpectralCoordinate (MFrequency::Types type, const Quantum< Vector< Double > > &freqs, const Quantum< Double > &restFrequency=Quantum< Double >(0.0,"Hz"))
	Construct a SpectralCoordinate with the specified frequencies with Quantum-based interface.
	SpectralCoordinate (MFrequency::Types freqType, MDoppler::Types velType, const Vector< Double > &velocities, const String &velUnit, Double restFrequency=0.0)
	Construct a SpectralCoordinate with the specified velocities (in km/s).
	SpectralCoordinate (MFrequency::Types freqType, const Vector< Double > &wavelengths, const String &waveUnit, Double restFrequency=0.0, Bool inAir=False)
	Construct a SpectralCoordinate with the specified wavelengths (in mm).
	SpectralCoordinate (MFrequency::Types freqType, const ::wcsprm &wcs, Bool oneRel=True)
	Construct from wcs structure.
	SpectralCoordinate (const SpectralCoordinate &other)
	Copy constructor (copy semantics).
SpectralCoordinate &	operator= (const SpectralCoordinate &other)
	Assignment (copy semantics).
virtual	~SpectralCoordinate ()
	Destructor.
virtual Coordinate::Type	type () const
	Always returns Coordinate::SPECTRAL.
virtual String	showType () const
	Always returns the String "Spectral".
virtual uInt	nPixelAxes () const
	Always returns 1.
virtual uInt	nWorldAxes () const
Bool	setReferenceConversion (MFrequency::Types type, const MEpoch &epoch, const MPosition &position, const MDirection &direction)
	Set extra conversion layer.
void	getReferenceConversion (MFrequency::Types &type, MEpoch &epoch, MPosition &position, MDirection &direction) const
virtual Bool	toWorld (Vector< Double > &world, const Vector< Double > &pixel) const
	Convert a pixel to a world coordinate or vice versa.
virtual Bool	toPixel (Vector< Double > &pixel, const Vector< Double > &world) const
Bool	toWorld (Double &world, const Double &pixel) const
Bool	toPixel (Double &pixel, const Double &world) const
Bool	toWorld (MFrequency &world, Double pixel) const
	Convert a pixel (channel number) into an MFrequency or MVFrequency and vice versa.
Bool	toPixel (Double &pixel, const MFrequency &world) const
Bool	toWorld (MVFrequency &world, Double pixel) const
Bool	toPixel (Double &pixel, const MVFrequency &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
Bool	setVelocity (const String &velUnit=String("km/s"), MDoppler::Types velType=MDoppler::RADIO)
	Set the state that is used for conversions from pixel and frequency to velocity or wavelength.
MDoppler::Types	velocityDoppler () const
String	velocityUnit () const
Bool	setWavelengthUnit (const String &waveUnit=String("mm"))
String	wavelengthUnit () const
Bool	setNativeType (const SpectralCoordinate::SpecType spcType)
SpectralCoordinate::SpecType	nativeType () const
Bool	pixelToVelocity (Quantum< Double > &velocity, Double pixel) const
	Functions to convert to velocity (uses the current active rest frequency) or wavelength.
Bool	pixelToVelocity (Double &velocity, Double pixel) const
Bool	pixelToVelocity (Vector< Double > &velocity, const Vector< Double > &pixel) const
Bool	frequencyToVelocity (Quantum< Double > &velocity, Double frequency) const
Bool	frequencyToVelocity (Quantum< Double > &velocity, const MFrequency &frequency) const
Bool	frequencyToVelocity (Quantum< Double > &velocity, const MVFrequency &frequency) const
Bool	frequencyToVelocity (Double &velocity, Double frequency) const
Bool	frequencyToVelocity (Vector< Double > &velocity, const Vector< Double > &frequency) const
Bool	frequencyToWavelength (Vector< Double > &wavelength, const Vector< Double > &frequency) const
Bool	frequencyToAirWavelength (Vector< Double > &wavelength, const Vector< Double > &frequency) const
Bool	velocityToPixel (Double &pixel, Double velocity) const
	The refractive index of air (argument can be wavelength or airwavelength) according to Greisen et al., 2006, A&A, 464, 746.
Bool	velocityToPixel (Vector< Double > &pixel, const Vector< Double > &velocity) const
Bool	velocityToFrequency (Double &frequency, Double velocity) const
Bool	velocityToFrequency (Vector< Double > &frequency, const Vector< Double > &velocity) const
Bool	wavelengthToFrequency (Vector< Double > &frequency, const Vector< Double > &wavelength) const
Bool	airWavelengthToFrequency (Vector< Double > &frequency, const Vector< Double > &wavelength) const
Double	restFrequency () const
	The SpectralCoordinate can maintain a list of rest frequencies (e.g.
const Vector< Double > &	restFrequencies () const
Bool	setRestFrequency (Double newFrequency, Bool append=False)
void	setRestFrequencies (const Vector< Double > &newFrequencies, uInt which=0, Bool append=False)
void	selectRestFrequency (uInt which)
void	selectRestFrequency (Double frequency)
String	formatRestFrequencies () const
MFrequency::Types	frequencySystem (Bool showConversion=False) const
	Retrieve/set the frequency system.
void	setFrequencySystem (MFrequency::Types type)
virtual Vector< String >	worldAxisNames () const
	Report the value of the requested attribute.
virtual Vector< Double >	referencePixel () const
virtual Matrix< Double >	linearTransform () const
virtual Vector< Double >	increment () const
virtual Vector< Double >	referenceValue () 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)
Vector< Double >	pixelValues () const
	Get the table, i.e.
Vector< Double >	worldValues () const
virtual Bool	setWorldAxisUnits (const Vector< String > &units)
	Set/get the unit.
virtual Vector< String >	worldAxisUnits () const
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 Coordinate *	makeFourierCoordinate (const Vector< Bool > &axes, const Vector< Int > &shape) const
	Find the Coordinate for when we Fourier Transform ourselves.
virtual String	format (String &unit, Coordinate::formatType format, Double worldValue, uInt worldAxis, Bool isAbsolute=True, Bool showAsAbsolute=True, Int precision=-1, Bool usePrecForFixed=False) const
	Format a SpectralCoordinate coordinate world value nicely through the common format interface.
String	formatUnit () const
	Set the default formatter unit (which is initialized to empty).
Bool	setFormatUnit (const String &unit)
void	toFITS (RecordInterface &header, uInt whichAxis, LogIO &logger, Bool oneRelative=True, Bool preferVelocity=True, Bool opticalVelDef=True, Bool preferWavelength=False, Bool airWaveDef=False) const
	Convert to FITS header record.
virtual Bool	save (RecordInterface &container, const String &fieldName) const
	Old interface.
virtual Coordinate *	clone () const
	Make a copy of the SpectralCoordinate using new.
ostream &	print (ostream &os) const
Static Public Member Functions
static SpectralCoordinate *	restore (const RecordInterface &container, const String &fieldName)
	Recover the SpectralCoordinate from a record.
static Bool	specTypetoString (String &stypeString, const SpecType &specType)
	Convert from String to spectral type and vice versa.
static Bool	stringtoSpecType (SpecType &specType, const String &stypeString)
Private Member Functions
void	checkFormat (Coordinate::formatType &format, const Bool) const
	Format checker.
void	copy (const SpectralCoordinate &other)
	Copy private data.
virtual void	convertTo (Vector< Double > &world) const
	Convert to and from conversion reference type.
virtual void	convertFrom (Vector< Double > &world) const
void	deleteVelocityMachine ()
	Deletes and sets pointer to 0.
void	deleteConversionMachines ()
	Deletes and sets pointers to 0.
Int	makeConversionMachines (MFrequency::Types type, MFrequency::Types conversionType, const MEpoch &epoch, const MPosition &position, const MDirection &direction)
	Set up pixel<->world conversion machines Returns: 3 (machines were noOPs, machines deleted) 2 (types the same, machines deleted), 1 (machines created and functioning) -1 (machines could not make trial conversion, machines deleted)
void	makeVelocityMachine (const String &velUnit, MDoppler::Types velType, const Unit &freqUnit, MFrequency::Types freqType, Double restFreq)
	Create velocity<->frequency machine.
void	toCurrent (Vector< Double > &value) const
	Interconvert between the current units and wcs units (Hz)
void	fromCurrent (Vector< Double > &value) const
const Vector< Double >	toCurrentFactors () const
	Return unit conversion vector for converting to current units.
void	updateVelocityMachine (const String &velUnit, MDoppler::Types velType)
	Update Velocity Machine.
Bool	wcsSave (RecordInterface &rec, const wcsprm &wcs, const String &fieldName) const
	Save wcs stuff into Record.
void	_setTabulatedFrequencies (const Vector< Double > &freqs)
Static Private Member Functions
static void	makeWCS (wcsprm &wcs, const String &ctype, Double refPix, Double refVal, Double inc, Double pc, Double restFreq)
	Make spectral wcs structure (items in Hz)
static SpectralCoordinate *	restoreVersion1 (const RecordInterface &container)
	Record restoration handling.
static SpectralCoordinate *	restoreVersion2 (const RecordInterface &container)
static void	restoreVelocity (SpectralCoordinate *&pSpectral, const RecordInterface &subrec)
static void	restoreRestFrequencies (SpectralCoordinate *&pSpectral, const RecordInterface &subrec, Double restFreq)
static void	restoreConversion (SpectralCoordinate *&pSpectral, const RecordInterface &subrec)
static Bool	wcsRestore (Double &crval, Double &crpix, Double &cdelt, Double &pc, String &ctype, const RecordInterface &rec)
	Restore wcs stuff from Record.
Private Attributes
std::auto_ptr< TabularCoordinate >	_tabular
mutable::wcsprm	wcs_p
Double	to_hz_p
Double	to_m_p
MFrequency::Types	type_p
MFrequency::Types	conversionType_p
Vector< Double >	restfreqs_p
uInt	restfreqIdx_p
MFrequency::Convert *	pConversionMachineTo_p
	Conversion machines; for pixel<->world conversions only.
MFrequency::Convert *	pConversionMachineFrom_p
VelocityMachine *	pVelocityMachine_p
MDoppler::Types	velType_p
String	velUnit_p
String	waveUnit_p
SpectralCoordinate::SpecType	nativeType_p
Unit	unit_p
String	axisName_p
String	formatUnit_p
MDirection	direction_p
MPosition	position_p
MEpoch	epoch_p

Detailed Description

Interconvert pixel and frequency values.

Intended use:

Public interface

Review Status

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

Prerequisite

Coordinate
MFrequency , MDoppler and VelocityMachine classes if you want radial velocities.

Synopsis

This class performs the mapping from pixel to frequency. This can be done via a Tabular lookup or via an algorithmic implementation which may be linear or non-linear. The latter is implemented via the WCS library.

Caution: All pixels coordinates are zero relative;

Example

Let us make a linear SpectralCoordinate first

      Double restfreq = 1.420405752E9;
      Double crpix = 10.0;
      Double crval = 1.4e9;
      Double cdelt = 1.0e6;
      SpectralCoordinate sc(MFrequency::TOPO, crval, cdelt, crpix, restfreq);
   
      Double world, pixel;
      pixel = 12.1;
      if (!sc.toWorld(world, pixel)) {
         cerr << "Error : " << sc.errorMessage() << endl;
      } else {
         cerr << "pixel, world = " << pixel << ", " << world << endl;
      }

Example

Now we make a non-linear SpectralCoordinate

      Vector<Double> freqs(5);
      freqs(0) = 1.4e9; freqs(1) = 1.41e9;
      freqs(2) = 1.43e9; freqs(3) = 1.44e9;
      freqs(4) = 1.47e9;
      SpectralCoordinate sc(MFrequency::LSRK, freqs, restfreq);
   
      Double world, pixel;
      world = 1.42e9;
      if (!sc.toPixel(pixel, world)) {
         cerr << "Error : " << sc.errorMessage() << endl;
      } else {
         cerr << "world, pixel = " << world << ", " << pixel << endl;
      }

Motivation

Spectral-line astronomy requires a specialized SpectralCoordinate.

To Do

Allow other than linear interpolations for frequency lookup.

Definition at line 137 of file SpectralCoordinate.h.

Member Enumeration Documentation

enum casa::SpectralCoordinate::SpecType

Enumerator:

FREQ
VRAD
VOPT
BETA
WAVE
AWAV

Definition at line 140 of file SpectralCoordinate.h.

Constructor & Destructor Documentation

casa::SpectralCoordinate::SpectralCoordinate ( )

Default constructor.

It is equivalent to doing SpectralCoordinate(MFrequency::TOPO, 0.0, 1.0, 0.0)

casa::SpectralCoordinate::SpectralCoordinate	(	MFrequency::Types	type,
		Double	f0,
		Double	inc,
		Double	refPix,
		Double	restFrequency = `0.0`
	)

Create a linear frequency axis SpectralCoordinate f0 is the frequency of the reference pixel, inc is the pixel increment, refPix is the reference pixel.

You can optionally store the rest frequency for later use in calculating radial velocities. Use 0 for restFrequency if continuum.

Frequencies and increments initially in Hz.

casa::SpectralCoordinate::SpectralCoordinate	(	MFrequency::Types	type,
		const Quantum< Double > &	f0,
		const Quantum< Double > &	inc,
		Double	refPix,
		const Quantum< Double > &	restFrequency = `Quantum< Double >(0.0,"Hz")`
	)

Create linear frequency axis SpectralCoordinate with Quantum-based interface.

Parameters are the same as above. Regardless of the units of the Quanta, the initial units of the SpectralCoordinate will be Hz. You can change it to something else with the setWorldAxisUnits method later if you want. Use 0 for restFrequency if continuum.

casa::SpectralCoordinate::SpectralCoordinate	(	MFrequency::Types	type,
		const Vector< Double > &	freqs,
		Double	restFrequency = `0.0`
	)

Construct a SpectralCoordinate with the specified frequencies (in Hz).

This axis can be nonlinear; the increments and related functions return the average values (calculated from the first and last pixel's frequencies).

A linear interpolation/extrapolation is used for pixels which are not supplied. The reference pixel is chosen to be 0. The frequencies must increase or decrease monotonically (otherwise the toPixel lookup would not be possible). Use 0 for restFrequency if continuum.

casa::SpectralCoordinate::SpectralCoordinate	(	MFrequency::Types	type,
		const Quantum< Vector< Double > > &	freqs,
		const Quantum< Double > &	restFrequency = `Quantum< Double >(0.0,"Hz")`
	)

Construct a SpectralCoordinate with the specified frequencies with Quantum-based interface.

Parameters are the same as above. Regardless of the units of the Quanta, the initial units of the SpectralCoordinate will be Hz. Use 0 for restFrequency if continuum.

casa::SpectralCoordinate::SpectralCoordinate	(	MFrequency::Types	freqType,
		MDoppler::Types	velType,
		const Vector< Double > &	velocities,
		const String &	velUnit,
		Double	restFrequency = `0.0`
	)

Construct a SpectralCoordinate with the specified velocities (in km/s).

They will be converted to Hz and the SpectralCoordinate constructed. This axis can be nonlinear; the increments and related functions return the average values (calculated from the first and last pixel's frequencies).

A linear interpolation/extrapolation is used for pixels which are not supplied. The reference pixel is chosen to be 0. The velocities must increase or decrease monotonically (otherwise the toPixel lookup would not be possible).

casa::SpectralCoordinate::SpectralCoordinate	(	MFrequency::Types	freqType,
		const Vector< Double > &	wavelengths,
		const String &	waveUnit,
		Double	restFrequency = `0.0`,
		Bool	inAir = `False`
	)

Construct a SpectralCoordinate with the specified wavelengths (in mm).

They will be converted to Hz and the SpectralCoordinate constructed. This axis can be nonlinear; the increments and related functions return the average values (calculated from the first and last pixel's frequencies). If inAir is True, the input wavelengths are assumed to be Air Wavelengths. They are converted to vacuum frequency using the refractive index which is calculated based on the mean input air wavelength.

A linear interpolation/extrapolation is used for pixels which are not supplied. The reference pixel is chosen to be 0. The wavelengths must increase or decrease monotonically (otherwise the toPixel lookup would not be possible).

casa::SpectralCoordinate::SpectralCoordinate	(	MFrequency::Types	freqType,
		const ::wcsprm &	wcs,
		Bool	oneRel = `True`
	)

Construct from wcs structure.

Must hold only a spectral 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::SpectralCoordinate::SpectralCoordinate ( const SpectralCoordinate & other )

Copy constructor (copy semantics).

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

Destructor.

Member Function Documentation

void casa::SpectralCoordinate::_setTabulatedFrequencies ( const Vector< Double > & freqs ) [private]

Bool casa::SpectralCoordinate::airWavelengthToFrequency	(	Vector< Double > &	frequency,
		const Vector< Double > &	wavelength
	)		const

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

Format checker.

Reimplemented from casa::Coordinate.

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

Make a copy of the SpectralCoordinate using new.

The caller is responsible for calling delete.

virtual String casa::SpectralCoordinate::format	(	String &	unit,
		Coordinate::formatType	format,
		Double	worldValue,
		uInt	worldAxis,
		Bool	isAbsolute = `True`,
		Bool	showAsAbsolute = `True`,
		Int	precision = `-1`,
		Bool	usePrecForFixed = `False`
	)		const `[virtual]`

Bool casa::SpectralCoordinate::frequencyToAirWavelength	(	Vector< Double > &	wavelength,
		const Vector< Double > &	frequency
	)		const

Bool casa::SpectralCoordinate::frequencyToVelocity	(	Quantum< Double > &	velocity,
		Double	frequency
	)		const

Bool casa::SpectralCoordinate::frequencyToVelocity	(	Double &	velocity,
		Double	frequency
	)		const

void casa::SpectralCoordinate::getReferenceConversion	(	MFrequency::Types &	type,
		MEpoch &	epoch,
		MPosition &	position,
		MDirection &	direction
	)		const `[inline]`

Int casa::SpectralCoordinate::makeConversionMachines	(	MFrequency::Types	type,
		MFrequency::Types	conversionType,
		const MEpoch &	epoch,
		const MPosition &	position,
		const MDirection &	direction
	)		`[private]`

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

void casa::SpectralCoordinate::makeVelocityMachine	(	const String &	velUnit,
		MDoppler::Types	velType,
		const Unit &	freqUnit,
		MFrequency::Types	freqType,
		Double	restFreq
	)		`[private]`

static void casa::SpectralCoordinate::makeWCS	(	wcsprm &	wcs,
		const String &	ctype,
		Double	refPix,
		Double	refVal,
		Double	inc,
		Double	pc,
		Double	restFreq
	)		`[static, private]`

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

Bool casa::SpectralCoordinate::pixelToVelocity	(	Quantum< Double > &	velocity,
		Double	pixel
	)		const

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

static void casa::SpectralCoordinate::restoreConversion	(	SpectralCoordinate *&	pSpectral,
		const RecordInterface &	subrec
	)		`[static, private]`

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

Bool casa::SpectralCoordinate::setReferenceConversion	(	MFrequency::Types	type,
		const MEpoch &	epoch,
		const MPosition &	position,
		const MDirection &	direction
	)

void casa::SpectralCoordinate::setRestFrequencies	(	const Vector< Double > &	newFrequencies,
		uInt	which = `0`,
		Bool	append = `False`
	)

Bool casa::SpectralCoordinate::setRestFrequency	(	Double	newFrequency,
		Bool	append = `False`
	)

Bool casa::SpectralCoordinate::setVelocity	(	const String &	velUnit = `String("km/s")`,
		MDoppler::Types	velType = `MDoppler::RADIO`
	)

static Bool casa::SpectralCoordinate::specTypetoString	(	String &	stypeString,
		const SpecType &	specType
	)		`[static]`

static Bool casa::SpectralCoordinate::stringtoSpecType	(	SpecType &	specType,
		const String &	stypeString
	)		`[static]`

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Intended use:

Review Status

Prerequisite

Synopsis

Example

Example

Motivation

To Do

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

void casa::SpectralCoordinate::toFITS	(	RecordInterface &	header,
		uInt	whichAxis,
		LogIO &	logger,
		Bool	oneRelative = `True`,
		Bool	preferVelocity = `True`,
		Bool	opticalVelDef = `True`,
		Bool	preferWavelength = `False`,
		Bool	airWaveDef = `False`
	)		const

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

Bool casa::SpectralCoordinate::toPixel	(	Double &	pixel,
		const Double &	world
	)		const

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

Bool casa::SpectralCoordinate::toWorld	(	Double &	world,
		const Double &	pixel
	)		const

Bool casa::SpectralCoordinate::toWorld	(	MFrequency &	world,
		Double	pixel
	)		const

Bool casa::SpectralCoordinate::toWorld	(	MVFrequency &	world,
		Double	pixel
	)		const

void casa::SpectralCoordinate::updateVelocityMachine	(	const String &	velUnit,
		MDoppler::Types	velType
	)		`[private]`

Bool casa::SpectralCoordinate::velocityToFrequency	(	Double &	frequency,
		Double	velocity
	)		const

Bool casa::SpectralCoordinate::wavelengthToFrequency	(	Vector< Double > &	frequency,
		const Vector< Double > &	wavelength
	)		const