casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | List of all members
casacore::CoordinateSystem Class Reference

Interconvert pixel and world coordinates. More...

#include <CoordinateSystem.h>

Inheritance diagram for casacore::CoordinateSystem:
casacore::Coordinate

Public Member Functions

 CoordinateSystem ()
 Default constructor. More...
 
 CoordinateSystem (const CoordinateSystem &other)
 Copying constructor (copy semantics) More...
 
CoordinateSystemoperator= (const CoordinateSystem &other)
 Assignment (copy semantics). More...
 
virtual ~CoordinateSystem ()
 Destructor. More...
 
void addCoordinate (const Coordinate &coord)
 Add another Coordinate to this CoordinateSystem. More...
 
void transpose (const Vector< Int > &newWorldOrder, const Vector< Int > &newPixelOrder)
 Transpose the CoordinateSystem so that world axis 0 is newWorldOrder(0) and so on for all the other axes. More...
 
Bool worldMap (Vector< Int > &worldAxisMap, Vector< Int > &worldAxisTranspose, Vector< Bool > &refChange, const CoordinateSystem &cSys) const
 Find the world and pixel axis mappings to the supplied CoordinateSystem from the current coordinate system. More...
 
Bool pixelMap (Vector< Int > &pixelAxisMap, Vector< Int > &pixelAxisTranspose, const CoordinateSystem &cSys) const
 
Bool removeWorldAxis (uInt axis, Double replacement)
 Remove a world or pixel axis. More...
 
Bool removePixelAxis (uInt axis, Double replacement)
 
CoordinateSystem subImage (const Vector< Float > &originShift, const Vector< Float > &incrFac, const Vector< Int > &newShape) const
 Return a CoordinateSystem appropriate for a shift of origin (the shift is subtracted from the reference pixel) and change of increment (the increments are multipled by the factor). More...
 
void subImageInSitu (const Vector< Float > &originShift, const Vector< Float > &incrFac, const Vector< Int > &newShape)
 
void restoreOriginal ()
 Untranspose and undelete all axes. More...
 
uInt nCoordinates () const
 Returns the number of Coordinates that this CoordinateSystem contains. More...
 
Vector< IntworldAxes (uInt whichCoord) const
 For a given Coordinate say where its world and pixel axes are in this CoordinateSystem. More...
 
Vector< IntpixelAxes (uInt whichCoord) const
 
Coordinate::Type type (uInt whichCoordinate) const
 Return the type of the given Coordinate. More...
 
String showType (uInt whichCoordinate) const
 Returns the type of the given Coordinate as a string. More...
 
const Coordinatecoordinate (uInt which) const
 Return the given Coordinate as a reference to the base class object. More...
 
const LinearCoordinatelinearCoordinate (uInt which) const
 Return the given Coordinate. More...
 
const DirectionCoordinatedirectionCoordinate () const
 
const DirectionCoordinatedirectionCoordinate (uInt which) const
 
const SpectralCoordinatespectralCoordinate (uInt which) const
 
const SpectralCoordinatespectralCoordinate () const
 
const StokesCoordinatestokesCoordinate () const
 
const StokesCoordinatestokesCoordinate (uInt which) const
 
const QualityCoordinatequalityCoordinate (uInt which) const
 
const TabularCoordinatetabularCoordinate (uInt which) const
 
Bool replaceCoordinate (const Coordinate &newCoordinate, uInt whichCoordinate)
 Replace one Coordinate with another. More...
 
Int findCoordinate (Coordinate::Type type, Int afterCoord=-1) const
 Find the Coordinate number that corresponds to the given type. More...
 
void findWorldAxis (Int &coordinate, Int &axisInCoordinate, uInt axisInCoordinateSystem) const
 Given an axis number (pixel or world) in the CoordinateSystem, find the corresponding coordinate number and axis in that Coordinate. More...
 
void findPixelAxis (Int &coordinate, Int &axisInCoordinate, uInt axisInCoordinateSystem) const
 
Int pixelAxisToWorldAxis (uInt pixelAxis) const
 Find the world axis for the given pixel axis in a CoordinateSystem. More...
 
Int worldAxisToPixelAxis (uInt worldAxis) const
 Find the pixel axis for the given world axis in a CoordinateSystem. More...
 
String coordRecordName (uInt which) const
 Return the name of the record field in which the coordinate is stored. More...
 
virtual Coordinate::Type type () const
 Returns Coordinate::COORDSYS More...
 
virtual String showType () const
 Always returns "System". More...
 
virtual uInt nPixelAxes () const
 Sums the number of axes in the Coordinates that the CoordinateSystem contains, allowing for removed axes. More...
 
virtual uInt nWorldAxes () 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. More...
 
virtual Vector< DoubletoWorld (const Vector< Double > &pixel) const
 This one throws an exception rather than returning False. More...
 
virtual Bool toPixel (Vector< Double > &pixel, const Vector< Double > &world) const
 
virtual Vector< DoubletoPixel (const Vector< Double > &world) const
 This one throws an exception rather than returning False. More...
 
virtual Quantity toWorldLength (const Double nPixels, const uInt pixelAxis) const
 convert a pixel "length" to a world "length" More...
 
Bool toWorld (Vector< Double > &world, const IPosition &pixel) const
 This is provided as a convenience since it is a very commonly desired operation through CoordinateSystem. More...
 
Vector< DoubletoWorld (const IPosition &pixel) 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 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. More...
 
virtual Bool setWorldMixRanges (const IPosition &shape)
 Compute and recover the world min and max ranges, for use in function toMix, for a lattice of the given shape (must be of length nPixelAxes()). More...
 
virtual void setDefaultWorldMixRanges ()
 
virtual Vector< DoubleworldMixMin () const
 
virtual Vector< DoubleworldMixMax () const
 
virtual void makePixelRelative (Vector< Double > &pixel) const
 Make absolute coordinates relative and vice-versa (relative to the reference pixel/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
 
Bool convert (Vector< Double > &coordOut, const Vector< Double > &coordin, const Vector< Bool > &absIn, const Vector< String > &unitsIn, MDoppler::Types dopplerIn, const Vector< Bool > &absOut, const Vector< String > &unitsOut, MDoppler::Types dopplerOut, Double pixInOffset=0.0, Double pixOutOffset=0.0)
 General coordinate conversion. More...
 
Bool convert (Matrix< Double > &coordOut, const Matrix< Double > &coordIn, const Vector< Bool > &absIn, const Vector< String > &unitsIn, MDoppler::Types dopplerIn, const Vector< Bool > &absOut, const Vector< String > &unitsOut, MDoppler::Types dopplerOut, Double pixInOffset=0.0, Double pixOutOffset=0.0)
 
virtual Vector< StringworldAxisNames () const
 Return the requested attribute. More...
 
virtual Vector< DoublereferencePixel () const
 
virtual Matrix< DoublelinearTransform () const
 
virtual Vector< Doubleincrement () const
 
virtual Vector< DoublereferenceValue () const
 
virtual Bool setWorldAxisNames (const Vector< String > &names)
 Set the requested attribute. More...
 
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)
 Set/get the units. More...
 
Bool setWorldAxisUnits (const Vector< String > &units, Bool throwException)
 
virtual Vector< StringworldAxisUnits () const
 
virtual Bool near (const Coordinate &other, Double tol=1e-6) const
 Comparison function. More...
 
virtual Bool near (const Coordinate &other, const Vector< Int > &excludePixelAxes, Double tol=1e-6) const
 
Bool nearPixel (const CoordinateSystem &other, Double tol=1e-6) const
 This function compares this and the other coordinate system, but ONLY for the non-removed pixel axes. More...
 
virtual String format (String &units, Coordinate::formatType format, Double worldValue, uInt worldAxis, Bool isAbsolute=True, Bool showAsAbsolute=True, Int precision=-1, Bool usePrecForMixed=False) const
 Format a world value nicely through the common format interface. More...
 
ObsInfo obsInfo () const
 Miscellaneous information related to an observation, for example the observation date. More...
 
void setObsInfo (const ObsInfo &obsinfo)
 
virtual CoordinatemakeFourierCoordinate (const Vector< Bool > &axes, const Vector< Int > &shape) const
 Find the CoordinateSystem (you can safely caste the pointer to a CoordinateSystem) for when we Fourier Transform ourselves. More...
 
virtual Bool save (RecordInterface &container, const String &fieldName) const
 Save the CoordinateSystem into the supplied record using the supplied field name. More...
 
virtual Coordinateclone () const
 Make a copy of the CoordinateSystem using new. More...
 
Bool toFITSHeader (RecordInterface &header, IPosition &shape, Bool oneRelative, Char prefix= 'c', Bool writeWCS=True, Bool preferVelocity=True, Bool opticalVelocity=True, Bool preferWavelength=False, Bool airWavelength=False) const
 Convert a CoordinateSystem to FITS, i.e. More...
 
Vector< Stringlist (LogIO &os, MDoppler::Types doppler, const IPosition &latticeShape, const IPosition &tileShape, Bool postLocally=False) const
 List all header information. More...
 
Bool hasSpectralAxis () const
 Does this coordinate system have a spectral axis? More...
 
Int spectralAxisNumber (Bool doWorld=False) const
 What number is the spectral axis? If doWorld=True, the world axis number is returned. More...
 
Int spectralCoordinateNumber () const
 what number is the spectral coordinate? Returns -1 if no spectral coordinate exists. More...
 
Bool hasPolarizationCoordinate () const
 does this coordinate system have a polarizaion/stokes coordinate? More...
 
Bool hasPolarizationAxis () const
 
Int stokesPixelNumber (const String &stokesString) const
 Given a stokes or polarization parameter, find the pixel location. More...
 
Int polarizationCoordinateNumber () const
 what is the number of the polarization/stokes coordinate? Returns -1 if no stokes coordinate exists. More...
 
Int polarizationAxisNumber (Bool doWorld=False) const
 What is the number of the polarization/stokes axis? If doWorld=True, the world axis number is returned. More...
 
Bool hasQualityAxis () const
 Does this coordinate system have a quality axis? More...
 
Int qualityAxisNumber () const
 what number is the quality axis? Returns -1 if no quality axis exists. More...
 
Int qualityCoordinateNumber () const
 what is the number of the quality coordinate? Returns -1 if no quality coordinate exists. More...
 
Int qualityPixelNumber (const String &qualityString) const
 Given a quality parameter, find the pixel location. More...
 
String qualityAtPixel (const uInt pixel) const
 
Int directionCoordinateNumber () const
 
Bool hasDirectionCoordinate () const
 
Vector< IntdirectionAxesNumbers () const
 Get the pixel axis numbers of the direction coordinate in this object. More...
 
String stokesAtPixel (const uInt pixel) const
 
Int linearCoordinateNumber () const
 
Bool hasLinearCoordinate () const
 
Vector< IntlinearAxesNumbers () const
 
Vector< IntgetWorldAxesOrder (Vector< String > &myNames, Bool requireAll, Bool allowFriendlyNames=False) const
 Get the 0 based order of the minimal match strings specified in order. More...
 
Bool isDirectionAbscissaLongitude () const
 Is the abscissa in the DirectionCoordinate the longitude axis? Throws exception if there is no DirectionCoordinate or if either of the direction pixel axes have been removed. More...
 
Bool setSpectralConversion (String &errorMsg, const String frequencySystem)
 Set Spectral conversion layer of SpectralCoordinate in CoordinateSystem so that pixel<->world go to the specified frequency system (a valid MFrequency::Types string). More...
 
void setSpectralConversion (const String frequencySystem)
 This version throws an exception rather than returning False. More...
 
Bool setRestFrequency (String &errorMsg, const Quantity &freq)
 Set rest frequency of SpectralCoordinate in CoordinateSystem. More...
 
- Public Member Functions inherited from casacore::Coordinate
virtual ~Coordinate ()
 Destructor. More...
 
Vector< DoubleworldMixMin () const
 
Vector< DoubleworldMixMax () const
 
const StringerrorMessage () 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...
 
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 Coordinaterotate (const Quantum< Double > &angle) const
 return the result of rotating the coordinate clockwise through the specified angle. More...
 

Static Public Member Functions

static CoordinateSystemrestore (const RecordInterface &container, const String &fieldName)
 Restore the CoordinateSystem from a record. More...
 
static Bool fromFITSHeader (Int &stokesFITSValue, CoordinateSystem &coordsys, RecordInterface &recHeader, const Vector< String > &header, const IPosition &shape, uInt which=0)
 Probably even if we return False we should set up the best linear coordinate that we can. 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

Bool mapOne (Vector< Int > &worldAxisMap, Vector< Int > &worldAxisTranspose, Vector< Bool > &refChange, const CoordinateSystem &cSys, const CoordinateSystem &cSys2, const uInt coord, const uInt coord2) const
 Helper functions to group common code. More...
 
void copy (const CoordinateSystem &other)
 
void clear ()
 
Bool checkAxesInThisCoordinate (const Vector< Bool > &axes, uInt which) const
 
void cleanUpSpecCoord (PtrBlock< SpectralCoordinate * > &in, PtrBlock< SpectralCoordinate * > &out)
 Delete some pointer blocks. More...
 
void deleteTemps (const uInt which)
 Delete temporary maps. More...
 
void makeWorldAbsRelMany (Matrix< Double > &value, Bool toAbs) const
 Many abs/rel conversions. More...
 
void makePixelAbsRelMany (Matrix< Double > &value, Bool toAbs) const
 
StokesCoordinate stokesSubImage (const StokesCoordinate &sc, Int originShift, Int pixincFac, Int newShape) const
 Do subImage for Stokes. More...
 
QualityCoordinate qualitySubImage (const QualityCoordinate &qc, Int originShift, Int pixincFac, Int newShape) const
 Do subImage for Quality. More...
 
CoordinateSystem stripRemovedAxes (const CoordinateSystem &cSys) const
 Strip out coordinates with all world and pixel axes removed. More...
 
void listDirectionSystem (LogIO &os) const
 All these functions are in support of the list function. More...
 
void listFrequencySystem (LogIO &os, MDoppler::Types velocityType) const
 
void listPointingCenter (LogIO &os) const
 
void getFieldWidths (LogIO &os, uInt &widthAxis, uInt &widthCoordType, uInt &widthCoordNumber, uInt &widthName, uInt &widthProj, uInt &widthShape, uInt &widthTile, uInt &widthRefValue, uInt &widthRefPixel, uInt &widthInc, uInt &widthUnits, Int &precRefValSci, Int &precRefValFloat, Int &precRefValRADEC, Int &precRefPixFloat, Int &precIncSci, String &nameAxis, String &nameCoordType, String &nameCoordNumber, String &nameName, String &nameProj, String &nameShape, String &nameTile, String &nameRefValue, String &nameRefPixel, String &nameInc, String &nameUnits, MDoppler::Types velocityType, const IPosition &latticeShape, const IPosition &tileShape) const
 
void listHeader (LogIO &os, Coordinate *pc, uInt &widthAxis, uInt &widthCoordType, uInt &widthCoordNumber, uInt &widthName, uInt &widthProj, uInt &widthShape, uInt &widthTile, uInt &widthRefValue, uInt &widthRefPixel, uInt &widthInc, uInt &widthUnits, Bool findWidths, Int coordinate, Int axisInCoordinate, Int pixelAxis, Int precRefValSci, Int precRefValFloat, Int precRefValRADEC, Int precRefPixFloat, Int precIncSci, const IPosition &latticeShape, const IPosition &tileShape) const
 
void listVelocity (LogIO &os, Coordinate *pc, uInt widthAxis, uInt widthCoordType, uInt widthCoordNumber, uInt &widthName, uInt widthProj, uInt widthShape, uInt widthTile, uInt &widthRefValue, uInt widthRefPixel, uInt &widthInc, uInt &widthUnits, Bool findWidths, Int axisInCoordinate, Int pixelAxis, MDoppler::Types velocityType, Int precRefValSci, Int precRefValFloat, Int precRefValRADEC, Int precRefPixFloat, Int precIncSci) const
 
void clearFlags (LogIO &os) const
 
Bool velocityIncrement (Double &velocityInc, SpectralCoordinate &sc, MDoppler::Types velocityType, const String &velUnits) const
 
void _downcase (Vector< String > &vec) const
 

Static Private Member Functions

static void _initFriendlyAxisMap ()
 

Private Attributes

PtrBlock< Coordinate * > coordinates_p
 Where we store copies of the coordinates we are created with. More...
 
PtrBlock< Block< Int > * > world_maps_p
 For coordinate[i] axis[j], world_maps_p[i][j], if >=0 gives the location in the input vector that maps to this coord/axis, <0 means that the axis has been removed world_tmp_p[i] a temporary vector length coord[i]->nworldAxes() replacement_values_p[i][j] value to use for this axis if removed. More...
 
PtrBlock< Vector< Double > * > world_tmps_p
 
PtrBlock< Vector< Double > * > world_replacement_values_p
 
PtrBlock< Block< Int > * > pixel_maps_p
 Same meanings as for the world*'s above. More...
 
PtrBlock< Vector< Double > * > pixel_tmps_p
 
PtrBlock< Vector< Double > * > pixel_replacement_values_p
 
PtrBlock< Vector< Bool > * > worldAxes_tmps_p
 These temporaries all needed for the toMix function. More...
 
PtrBlock< Vector< Bool > * > pixelAxes_tmps_p
 
PtrBlock< Vector< Double > * > worldOut_tmps_p
 
PtrBlock< Vector< Double > * > pixelOut_tmps_p
 
PtrBlock< Vector< Double > * > worldMin_tmps_p
 
PtrBlock< Vector< Double > * > worldMax_tmps_p
 
ObsInfo obsinfo_p
 Miscellaneous information about the observation associated with this Coordinate System. More...
 

Static Private Attributes

static const String _class
 
static Mutex _mapInitMutex
 
static std::map< String, String_friendlyAxisMap
 

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...
 
Coordinateoperator= (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< DoubleworldMin_p
 toMix ranges. More...
 
Vector< DoubleworldMax_p
 

Detailed Description

Interconvert pixel and world coordinates.

Intended use:

Public interface

Review Status

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

Prerequisite

Synopsis

CoordinateSystem is the normal interface to coordinate systems, typically attached to an ImageInterface, however the coordinate system can be manipulated on its own. CoordinateSystem is in turn composed from various classes derived from the base class Coordinate.

The fundamental operations available to the user of a CoordinateSystem are:

  1. Transform a world (physical) coordinate to a pixel coordinate or vice versa via the methods toWorld and toPixel.
  2. Compose a CoordinateSystem from one or more independent groups, typically the sky-plane transformation will be one group, and the spectral axis will be another group. Each group consists of a linear transformation (in FITS terms, apply CRPIX, PC, CDELT) to turn the pixel coordinates into relative world coordinates, followed by a (possibly) nonlinear projection to world coordinates (i.e. apply CTYPE and CRVAL), typically a sky projection or a frequency to velocity conversion. Note that an arbitrary rotation or linear transformation can be applied by changing the matrix.
  3. Transpose the world and/or pixel axes.
  4. One or more pixel or world axes may be removed. You are encouraged to leave all the world axes if you remove a pixel axis. Removing a world axis also removes the corresponding pixel axis.
  5. Calculate the CoordinateSystem that results from a subimage operation.

Note that all the knowledge to do with removing and transposing axes is maintained by the CoordinateSystem. The individual Coordinates, of which it is made, know nothing about this.

Although the CoordinateSystem exists in the absence of an image, the usual place you will find one is attached to an object derived from ImageInterface such as PagedImage. When you do so, the physical (or pixel) axes in the image map one to one with the pixel axes contained in the CoordinateSystem. It cannot be any other way as when you create a PagedImage, it is checked that there are equal numbers of image and CoordinateSystem pixel axes. It is up to the creator of the PagedImage to make sure that they are in the correct order.

However, the CoordinateSystem may have more world axes than pixel axes because it is possible to remove a pixel axis but not its associated world axis (for example for a moment image). Now, if you use the CoordinateSystem functions referencePixel and referenceValue, you will find the vector of reference values will have more values than the vector of reference pixels, if a pixel axis has been removed but not the world axis. You must use the ancilliary functions provided to find out what is where.

Let's consider an example where a CoordinateSystem consisted of a DirectionCoordinate and a SpectralCoordinate. Let us say that the first two pixel axes of the image associate (roughly of course because lines of constant RA and DEC are not parallel with the pixel coordinates) with the DirectionCoordinate (RA and DEC say) and the third pixel axis is the SpectralCoordinate. Now imagine we collapse the image along the second pixel axis (roughly, the DEC axis). For the output image, we remove the second pixel axis from the CoordinateSystem, but leave the world axis intact. This enables us to still be able to make coordinate conversions for the first (roughly RA) pixel axis. Thus, CoordinateSystem::referenceValue would return a Vector of length 3 (for RA, DEC and spectral), but CoordinateSystem::referencePixel would return a vector length 2 (for RA and spectral).

Now this CoordinateSystem has two Coordinates, a DirectionCoordinate and a SpectralCoordinate, and let us state that that is the order in which they exist in the CoordinateSystem (you can change them about if you wish); they are coordinates number 0 and 1. The DirectionCoordinate has two axes (RA and DEC) and the SpectralCoordinate has one axis. Only the CoordinateSystem knows about removed axes, the DirectionCoordinate itself is ignorant that it has been bisected. If you want to find out what axis in the Coordinate system is where, you can use the functions findPixelAxis or findWorldAxis.

If we asked the former to find pixel axis 0, it would tell us that the Coordinate number was 0 (the DirectionCoordinate) and that the axis in that coordinate was 0 (the first axis in a DirectionCoordinate is always longitude, the second always latitude). If we asked it to find pixel axis 1, it would tell us that the coordinate number was 1 (the SpectralCoordinate) and that the axis in that coordinate was 0 (there is only one axis in a SpectralCoordinate). If we asked for pixelAxis 2 that would generate an error because our squashed image only has 2 pixel axes.

Now, if we asked findWorldAxis similar questions, it would tell us that worldAxis 0 in the CoordinateSystem can be found in coordinate 0 (the DirectionCoordinate) in axis 0 of that DirectionCoordinate. Similarly, worldAxis 1 in the CoordinateSystem (which has not been removed) is in coordinate 0 (the DirectionCoordinate) in axis 1 of that Finally, worldAxis 2 in the CoordinateSystem is in coordinate 1 (the SpectralCoordinate) in axis 0 of that SpectralCoordinate.

Other handy functions are pixelAxes and worldAxes. These list the pixel and world axes in the CoordinateSystem for the specified coordinate. Thus, if we asked pixelAxes to find the pixel axes for coordinate 0 (the DirectionCoordinate) in the CoordinateSystem it would return a vector [0, -1] indicating the second axis of the DirectionCoordinate has been removed. However, the worldAxes function would return [0,1] as no world axis has been removed. Similarly, if operated on coordinate 1 (the SpectralCoordinate), pixelAxes would return [1] and worldAxes would return [2].

Because you can transpose the CoordinateSystem about, you should NEVER ASSUME ANYTHING except that the pixel axes of the CoordinateSystem map to the pixel axes of the image when you first construct the image.

SpectralCoordinate and DirectionCoordinate both have a (non-virtual) function called setReferenceConversion. This enables an extra conversion layer so that conversion between pixel and world can go to a reference frame other than the construction reference. When you use the function convert, these layers are active, but ONLY if the requested conversion is purely between pixel and world. For a SpectralCoordinate this must always be true (only has one axis) but for the DirectionCoordinate you might request a mixed pixel/world conversion. In this case, the extra conversion layer is ill-defined and not active (for the DirectionCoordinate part of it).


Caution: All pixels coordinates are zero relative;

Example

See the example in Coordinates.h and tCoordinateSystem.cc

Motivation

Coordinate systems for images.

Thrown Exceptions

To Do

Definition at line 217 of file CoordinateSystem.h.

Constructor & Destructor Documentation

casacore::CoordinateSystem::CoordinateSystem ( )

Default constructor.

This is an empty CoordinateSystem.

casacore::CoordinateSystem::CoordinateSystem ( const CoordinateSystem other)

Copying constructor (copy semantics)

virtual casacore::CoordinateSystem::~CoordinateSystem ( )
virtual

Destructor.

Member Function Documentation

void casacore::CoordinateSystem::_downcase ( Vector< String > &  vec) const
inlineprivate

Definition at line 987 of file CoordinateSystem.h.

References casacore::downcase(), and casacore::ArrayBase::size().

static void casacore::CoordinateSystem::_initFriendlyAxisMap ( )
staticprivate
void casacore::CoordinateSystem::addCoordinate ( const Coordinate coord)

Add another Coordinate to this CoordinateSystem.

This addition is done by copying, so that if coord changes the change is NOT reflected in the CoordinateSystem.

Referenced by casa::DisplayCoordinateSystem::addCoordinate().

Bool casacore::CoordinateSystem::checkAxesInThisCoordinate ( const Vector< Bool > &  axes,
uInt  which 
) const
private
void casacore::CoordinateSystem::cleanUpSpecCoord ( PtrBlock< SpectralCoordinate * > &  in,
PtrBlock< SpectralCoordinate * > &  out 
)
private

Delete some pointer blocks.

void casacore::CoordinateSystem::clear ( )
private
void casacore::CoordinateSystem::clearFlags ( LogIO os) const
private
virtual Coordinate* casacore::CoordinateSystem::clone ( ) const
virtual

Make a copy of the CoordinateSystem using new.

The caller is responsible for calling delete.

Implements casacore::Coordinate.

Bool casacore::CoordinateSystem::convert ( Vector< Double > &  coordOut,
const Vector< Double > &  coordin,
const Vector< Bool > &  absIn,
const Vector< String > &  unitsIn,
MDoppler::Types  dopplerIn,
const Vector< Bool > &  absOut,
const Vector< String > &  unitsOut,
MDoppler::Types  dopplerOut,
Double  pixInOffset = 0.0,
Double  pixOutOffset = 0.0 
)

General coordinate conversion.

Only works if no axes have been removed and no axis reordering has occurred. That is pixel axes and world axes are the same.

Specify the input coordinate values, input units, whether value is absolute (or relative). For output specify units and abs/rel. Units may be 'pix' and velocity consistent units (e.g. m/s). Specify doppler types if velocities involved. The pixel offsets allow for the input and output pixel coordinates to be something other than 0-rel. If your pixel coordinates are 1-rel input and output, set the offsets to -1 and 1

The Matrix interface lets you do many conversions efficiently. Use Matrix(nAxes, nConversions) and Matrix.column()=coordinate or Matrix(axis, iConversion) to get the order right.

These functions invoke toMix so make sure you call setWorldMixRanges first to set up the world ranges.

Bool casacore::CoordinateSystem::convert ( Matrix< Double > &  coordOut,
const Matrix< Double > &  coordIn,
const Vector< Bool > &  absIn,
const Vector< String > &  unitsIn,
MDoppler::Types  dopplerIn,
const Vector< Bool > &  absOut,
const Vector< String > &  unitsOut,
MDoppler::Types  dopplerOut,
Double  pixInOffset = 0.0,
Double  pixOutOffset = 0.0 
)
const Coordinate& casacore::CoordinateSystem::coordinate ( uInt  which) const

Return the given Coordinate as a reference to the base class object.

Referenced by casa::DisplayCoordinateSystem::coordinate().

String casacore::CoordinateSystem::coordRecordName ( uInt  which) const

Return the name of the record field in which the coordinate is stored.

void casacore::CoordinateSystem::copy ( const CoordinateSystem other)
private
void casacore::CoordinateSystem::deleteTemps ( const uInt  which)
private

Delete temporary maps.

Vector<Int> casacore::CoordinateSystem::directionAxesNumbers ( ) const

Get the pixel axis numbers of the direction coordinate in this object.

The order of the returned axis numbers is always longitude axis first, latitude axis second.

const DirectionCoordinate& casacore::CoordinateSystem::directionCoordinate ( ) const
const DirectionCoordinate& casacore::CoordinateSystem::directionCoordinate ( uInt  which) const
Int casacore::CoordinateSystem::directionCoordinateNumber ( ) const
Int casacore::CoordinateSystem::findCoordinate ( Coordinate::Type  type,
Int  afterCoord = -1 
) const

Find the Coordinate number that corresponds to the given type.

Since there might be more than one Coordinate of a given type you can call this multiple times setting afterCoord to the last value found. Returns -1 if a Coordinate of the desired type is not found.

Referenced by casa::DisplayCoordinateSystem::findCoordinate().

void casacore::CoordinateSystem::findPixelAxis ( Int coordinate,
Int axisInCoordinate,
uInt  axisInCoordinateSystem 
) const
void casacore::CoordinateSystem::findWorldAxis ( Int coordinate,
Int axisInCoordinate,
uInt  axisInCoordinateSystem 
) const

Given an axis number (pixel or world) in the CoordinateSystem, find the corresponding coordinate number and axis in that Coordinate.

The returned values are set to -1 if the axis does not exist.

Referenced by casa::DisplayCoordinateSystem::findWorldAxis().

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

Format a world value nicely through the common format interface.

See Coordinate for basics.

You specify a world value and its corresponding world axis in the CoordinateSystem.

For the specified worldAxis, the coordinate number in the CoordinateSystem is found and the actual derived Coordinate class object for that number is created. The arguments to the formatting function are then passed on to the formatter for that Coordinate. So refer to the other derived Coordinate classes for specifics on the formatting.

Reimplemented from casacore::Coordinate.

static Bool casacore::CoordinateSystem::fromFITSHeader ( Int stokesFITSValue,
CoordinateSystem coordsys,
RecordInterface recHeader,
const Vector< String > &  header,
const IPosition shape,
uInt  which = 0 
)
static

Probably even if we return False we should set up the best linear coordinate that we can.

Use oneRelative=True to convert one-relative FITS pixel coordinates to zero-relative Casacore coordinates. On output, stokesFITSValue holds the FITS value of any unofficial Stokes (beam, optical depth, spectral index) for the last unofficial value accessed (-1 if none). The idea is that if the Stokes axis is of length one and holds an unofficial value, you should drop the STokes axis and convert that value to ImageInfo::ImageTypes with ImageInfo::imageTypeFromFITSValue. If on input, stokesFITSValue is positive, then a warning is issued if any unofficial values are encountered. Otherwise no warning is issued.

void casacore::CoordinateSystem::getFieldWidths ( LogIO os,
uInt widthAxis,
uInt widthCoordType,
uInt widthCoordNumber,
uInt widthName,
uInt widthProj,
uInt widthShape,
uInt widthTile,
uInt widthRefValue,
uInt widthRefPixel,
uInt widthInc,
uInt widthUnits,
Int precRefValSci,
Int precRefValFloat,
Int precRefValRADEC,
Int precRefPixFloat,
Int precIncSci,
String nameAxis,
String nameCoordType,
String nameCoordNumber,
String nameName,
String nameProj,
String nameShape,
String nameTile,
String nameRefValue,
String nameRefPixel,
String nameInc,
String nameUnits,
MDoppler::Types  velocityType,
const IPosition latticeShape,
const IPosition tileShape 
) const
private
Vector<Int> casacore::CoordinateSystem::getWorldAxesOrder ( Vector< String > &  myNames,
Bool  requireAll,
Bool  allowFriendlyNames = False 
) const

Get the 0 based order of the minimal match strings specified in order.

If requireAll is True, checks are done to ensure that all axes in the coordinate system are uniquely specified in order. If allowFriendlyNames is True, the following (fully specified) strings will match the specified axes: "spectral" matches both "frequency" and "velocity". "ra" matches "right ascension".

Bool casacore::CoordinateSystem::hasDirectionCoordinate ( ) const
Bool casacore::CoordinateSystem::hasLinearCoordinate ( ) const
Bool casacore::CoordinateSystem::hasPolarizationAxis ( ) const
inline

Definition at line 791 of file CoordinateSystem.h.

References hasPolarizationCoordinate().

Bool casacore::CoordinateSystem::hasPolarizationCoordinate ( ) const

does this coordinate system have a polarizaion/stokes coordinate?

Referenced by hasPolarizationAxis(), and casa::DisplayCoordinateSystem::hasPolarizationCoordinate().

Bool casacore::CoordinateSystem::hasQualityAxis ( ) const

Does this coordinate system have a quality axis?

Bool casacore::CoordinateSystem::hasSpectralAxis ( ) const

Does this coordinate system have a spectral axis?

Referenced by casa::DisplayCoordinateSystem::hasSpectralAxis().

virtual Vector<Double> casacore::CoordinateSystem::increment ( ) const
virtual
Bool casacore::CoordinateSystem::isDirectionAbscissaLongitude ( ) const

Is the abscissa in the DirectionCoordinate the longitude axis? Throws exception if there is no DirectionCoordinate or if either of the direction pixel axes have been removed.

For a normal direction coordinate, this will return True.

Referenced by casa::DisplayCoordinateSystem::isDirectionAbscissaLongitude().

Vector<Int> casacore::CoordinateSystem::linearAxesNumbers ( ) const
const LinearCoordinate& casacore::CoordinateSystem::linearCoordinate ( uInt  which) const

Return the given Coordinate.

Throws an exception if retrieved as the wrong type. The versions which take no parameters will return the first (or in most cases only) coordinate of the requested type. If no such coordinate exists, an exception is thrown.

Referenced by casa::DisplayCoordinateSystem::linearCoordinate().

Int casacore::CoordinateSystem::linearCoordinateNumber ( ) const
virtual Matrix<Double> casacore::CoordinateSystem::linearTransform ( ) const
virtual

Implements casacore::Coordinate.

Vector<String> casacore::CoordinateSystem::list ( LogIO os,
MDoppler::Types  doppler,
const IPosition latticeShape,
const IPosition tileShape,
Bool  postLocally = False 
) const

List all header information.

By default, the reference values and pixel increments are converted to a "nice" unit before formatting (e.g. RA is shown as HH:MM:SS.S). For spectral axes, both frequency and velocity information is listed. You can specify what velocity definition you want with velocityType If you wish, you can specify two shapes; a lattice and tile shape (perhaps an image from which the CoordinateSystem came) If you give (both of) these, they are included in the listing. If you pass in zero length IPositions then they are not included in the listing. If postlocally=True the formatted summary lines are written locally only to the sink, and then returned by the return value vector.

void casacore::CoordinateSystem::listDirectionSystem ( LogIO os) const
private

All these functions are in support of the list function.

void casacore::CoordinateSystem::listFrequencySystem ( LogIO os,
MDoppler::Types  velocityType 
) const
private
void casacore::CoordinateSystem::listHeader ( LogIO os,
Coordinate pc,
uInt widthAxis,
uInt widthCoordType,
uInt widthCoordNumber,
uInt widthName,
uInt widthProj,
uInt widthShape,
uInt widthTile,
uInt widthRefValue,
uInt widthRefPixel,
uInt widthInc,
uInt widthUnits,
Bool  findWidths,
Int  coordinate,
Int  axisInCoordinate,
Int  pixelAxis,
Int  precRefValSci,
Int  precRefValFloat,
Int  precRefValRADEC,
Int  precRefPixFloat,
Int  precIncSci,
const IPosition latticeShape,
const IPosition tileShape 
) const
private
void casacore::CoordinateSystem::listPointingCenter ( LogIO os) const
private
void casacore::CoordinateSystem::listVelocity ( LogIO os,
Coordinate pc,
uInt  widthAxis,
uInt  widthCoordType,
uInt  widthCoordNumber,
uInt widthName,
uInt  widthProj,
uInt  widthShape,
uInt  widthTile,
uInt widthRefValue,
uInt  widthRefPixel,
uInt widthInc,
uInt widthUnits,
Bool  findWidths,
Int  axisInCoordinate,
Int  pixelAxis,
MDoppler::Types  velocityType,
Int  precRefValSci,
Int  precRefValFloat,
Int  precRefValRADEC,
Int  precRefPixFloat,
Int  precIncSci 
) const
private
virtual Coordinate* casacore::CoordinateSystem::makeFourierCoordinate ( const Vector< Bool > &  axes,
const Vector< Int > &  shape 
) const
virtual

Find the CoordinateSystem (you can safely caste the pointer to a CoordinateSystem) for when we Fourier Transform ourselves.

This pointer must be deleted by the caller. Axes specifies which pixel axes of the Coordinate System you wish to transform. Shape specifies the shape of the image associated with all the axes of the CoordinateSystem. Currently you have no control over the reference pixel, it is always shape/2.

Reimplemented from casacore::Coordinate.

virtual void casacore::CoordinateSystem::makePixelAbsolute ( Vector< Double > &  pixel) const
virtual

Reimplemented from casacore::Coordinate.

virtual void casacore::CoordinateSystem::makePixelAbsoluteMany ( Matrix< Double > &  pixel) const
virtual

Reimplemented from casacore::Coordinate.

void casacore::CoordinateSystem::makePixelAbsRelMany ( Matrix< Double > &  value,
Bool  toAbs 
) const
private
virtual void casacore::CoordinateSystem::makePixelRelative ( Vector< Double > &  pixel) const
virtual

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

The vectors must be of length nPixelAxes() or nWorldAxes()

Reimplemented from casacore::Coordinate.

virtual void casacore::CoordinateSystem::makePixelRelativeMany ( Matrix< Double > &  pixel) const
virtual

Batch up a lot of absolute/relative transformations.

Parameters as above for toWorldMany and toPixelMany

Reimplemented from casacore::Coordinate.

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

Reimplemented from casacore::Coordinate.

virtual void casacore::CoordinateSystem::makeWorldAbsoluteMany ( Matrix< Double > &  world) const
virtual

Reimplemented from casacore::Coordinate.

virtual void casacore::CoordinateSystem::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. The vectors must be of length nPixelAxes() or nWorldAxes()

Reimplemented from casacore::Coordinate.

void casacore::CoordinateSystem::makeWorldAbsRelMany ( Matrix< Double > &  value,
Bool  toAbs 
) const
private

Many abs/rel conversions.

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

Reimplemented from casacore::Coordinate.

virtual void casacore::CoordinateSystem::makeWorldRelativeMany ( Matrix< Double > &  world) const
virtual

Reimplemented from casacore::Coordinate.

Bool casacore::CoordinateSystem::mapOne ( Vector< Int > &  worldAxisMap,
Vector< Int > &  worldAxisTranspose,
Vector< Bool > &  refChange,
const CoordinateSystem cSys,
const CoordinateSystem cSys2,
const uInt  coord,
const uInt  coord2 
) const
private

Helper functions to group common code.

uInt casacore::CoordinateSystem::nCoordinates ( ) const

Returns the number of Coordinates that this CoordinateSystem contains.

The order might be unrelated to the axis order through the results of transposing and removing axes.

Referenced by casa::DisplayCoordinateSystem::nCoordinates().

virtual Bool casacore::CoordinateSystem::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 pixel axes in the CoordinateSystem. If the comparison returns False, errorMessage() contains a message about why.

Implements casacore::Coordinate.

Referenced by casa::DisplayCoordinateSystem::near().

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

Implements casacore::Coordinate.

Bool casacore::CoordinateSystem::nearPixel ( const CoordinateSystem other,
Double  tol = 1e-6 
) const

This function compares this and the other coordinate system, but ONLY for the non-removed pixel axes.

It is less strict than near, which, for example, insists the number of coordinates is the same in each CS

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

Sums the number of axes in the Coordinates that the CoordinateSystem contains, allowing for removed axes.

Implements casacore::Coordinate.

Referenced by casa::DisplayCoordinateSystem::nPixelAxes().

virtual uInt casacore::CoordinateSystem::nWorldAxes ( ) const
virtual
ObsInfo casacore::CoordinateSystem::obsInfo ( ) const

Miscellaneous information related to an observation, for example the observation date.

Referenced by casa::DisplayCoordinateSystem::obsInfo().

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

Assignment (copy semantics).

Vector<Int> casacore::CoordinateSystem::pixelAxes ( uInt  whichCoord) const
Int casacore::CoordinateSystem::pixelAxisToWorldAxis ( uInt  pixelAxis) const

Find the world axis for the given pixel axis in a CoordinateSystem.

Returns -1 if the world axis is unavailable (e.g. if it has been removed).

Referenced by casa::DisplayCoordinateSystem::pixelAxisToWorldAxis().

Bool casacore::CoordinateSystem::pixelMap ( Vector< Int > &  pixelAxisMap,
Vector< Int > &  pixelAxisTranspose,
const CoordinateSystem cSys 
) const
Int casacore::CoordinateSystem::polarizationAxisNumber ( Bool  doWorld = False) const

What is the number of the polarization/stokes axis? If doWorld=True, the world axis number is returned.

Otherwise, the pixel axis number is returned. Returns -1 if the stokes axis (world c.q. pixel) does not exist.

Referenced by casa::DisplayCoordinateSystem::polarizationAxisNumber().

Int casacore::CoordinateSystem::polarizationCoordinateNumber ( ) const

what is the number of the polarization/stokes coordinate? Returns -1 if no stokes coordinate exists.

String casacore::CoordinateSystem::qualityAtPixel ( const uInt  pixel) const
Int casacore::CoordinateSystem::qualityAxisNumber ( ) const

what number is the quality axis? Returns -1 if no quality axis exists.

Referenced by casa::DisplayCoordinateSystem::qualityAxisNumber().

const QualityCoordinate& casacore::CoordinateSystem::qualityCoordinate ( uInt  which) const
Int casacore::CoordinateSystem::qualityCoordinateNumber ( ) const

what is the number of the quality coordinate? Returns -1 if no quality coordinate exists.

Int casacore::CoordinateSystem::qualityPixelNumber ( const String qualityString) const

Given a quality parameter, find the pixel location.

Note the client is responsible for any boundedness checks (eg finite number of quality in an image).

QualityCoordinate casacore::CoordinateSystem::qualitySubImage ( const QualityCoordinate qc,
Int  originShift,
Int  pixincFac,
Int  newShape 
) const
private

Do subImage for Quality.

virtual Vector<Double> casacore::CoordinateSystem::referencePixel ( ) const
virtual
virtual Vector<Double> casacore::CoordinateSystem::referenceValue ( ) const
virtual
Bool casacore::CoordinateSystem::removePixelAxis ( uInt  axis,
Double  replacement 
)
Bool casacore::CoordinateSystem::removeWorldAxis ( uInt  axis,
Double  replacement 
)

Remove a world or pixel axis.

When its value is required for forward or backwards transformations, use replacement
When a world axis is removed, the corresponding pixel axis is removed too, because it makes no sense having a pixel axis without world coordinates.
Removing a pixel axis without removing the corresponding world axis is, however, possible and meaningful. It can be used when e.g. a frequency plane is taken from a cube. The plane has 2 pixel axes, but the 3rd world axis can still describe the frequency coordinate. See also the functions in CoordinateUtil for removing lists of pixel/world axes (tricky because they shift down)

False is returned (an error in errorMessage() will be set) if the axis is illegal, else returns True.

Referenced by casa::DisplayCoordinateSystem::removeWorldAxis().

Bool casacore::CoordinateSystem::replaceCoordinate ( const Coordinate newCoordinate,
uInt  whichCoordinate 
)

Replace one Coordinate with another.

The mapping of the coordinate axes to the CoordinateSystem axes is unchanged, therefore the number of world and pixel axes must not be changed. You can, somewhat dangerously, change the type of the coordinate however. For example, replace a SpectralCoordinate with a 1-D Linearcoordinate. It is dangerous because the world replacement values (see removeWorldAxis) have to be scaled. The algorithm tries to find a scale factor between the old and new units and applies it to the replacement values. If it can't find a scale factor (non-conformant units) then the reference value is used for any world replacement values. If the latter occurs, it returns False, else True is returned.

Referenced by casa::DisplayCoordinateSystem::replaceCoordinate().

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

Restore the CoordinateSystem from a record.

The fieldName can be empty, in which case the CoordinateSystem is restored directly from the Record, rather than a subrecord of it. A null pointer means that the restoration did not succeed - probably because fieldName doesn't exist or doesn't contain a CoordinateSystem.

Referenced by casa::CubePartitionMixin< T >::get_params().

void casacore::CoordinateSystem::restoreOriginal ( )

Untranspose and undelete all axes.

Does not undo the effects of subimaging.

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

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

The field must not exist, otherwise False is returned. If the CoordinateSystem is empty False is also returned. If False is returned, errorMessage() contains a message about why.

Implements casacore::Coordinate.

Referenced by casa::DisplayCoordinateSystem::save().

virtual void casacore::CoordinateSystem::setDefaultWorldMixRanges ( )
virtual

Reimplemented from casacore::Coordinate.

virtual Bool casacore::CoordinateSystem::setIncrement ( const Vector< Double > &  inc)
virtual
virtual Bool casacore::CoordinateSystem::setLinearTransform ( const Matrix< Double > &  xform)
virtual

Implements casacore::Coordinate.

void casacore::CoordinateSystem::setObsInfo ( const ObsInfo obsinfo)
virtual Bool casacore::CoordinateSystem::setReferencePixel ( const Vector< Double > &  refPix)
virtual
virtual Bool casacore::CoordinateSystem::setReferenceValue ( const Vector< Double > &  refval)
virtual
Bool casacore::CoordinateSystem::setRestFrequency ( String errorMsg,
const Quantity freq 
)

Set rest frequency of SpectralCoordinate in CoordinateSystem.

Unit must be consistent with Hz or m. Returns False if invalid inputs (and CS not changed) and an error message.

Referenced by casa::DisplayCoordinateSystem::setRestFrequency().

Bool casacore::CoordinateSystem::setSpectralConversion ( String errorMsg,
const String  frequencySystem 
)

Set Spectral conversion layer of SpectralCoordinate in CoordinateSystem so that pixel<->world go to the specified frequency system (a valid MFrequency::Types string).

Returns False if frequency system invalid or if no DirectionCoordinate or if cant get Date/Epoch.

Referenced by casa::DisplayCoordinateSystem::setSpectralConversion().

void casacore::CoordinateSystem::setSpectralConversion ( const String  frequencySystem)

This version throws an exception rather than returning False.

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

Set the requested attribute.

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

Implements casacore::Coordinate.

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

Set/get the units.

Adjust the increment and reference value by the ratio of the old and new units. This implies that the units must be known Unit strings, and that they must be compatible, e.g. they can't change from time to length. If throwException=True, throw an exception rather than returning False on failure.

Implements casacore::Coordinate.

Bool casacore::CoordinateSystem::setWorldAxisUnits ( const Vector< String > &  units,
Bool  throwException 
)
virtual Bool casacore::CoordinateSystem::setWorldMixRanges ( const IPosition shape)
virtual

Compute and recover the world min and max ranges, for use in function toMix, for a lattice of the given shape (must be of length nPixelAxes()).

Removed pixel axes (with remaining world axes are handled). With the retrieval functions, the output vectors are resized. They return False if they fail (and then setDefaultWorldMixRanges generates the ranges) with a reason in errorMessage(). The setDefaultWorldMixRanges function gives you a useful default range if you don't know the shape. The only Coordinate type for which these ranges are actually used in toMix is DirectionCoordinate (because its coupled). For the rest the functionality is provided but never used by toMix.

Reimplemented from casacore::Coordinate.

Referenced by casa::DisplayCoordinateSystem::setWorldMixRanges().

String casacore::CoordinateSystem::showType ( uInt  whichCoordinate) const

Returns the type of the given Coordinate as a string.

Referenced by casa::DisplayCoordinateSystem::showType().

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

Always returns "System".

Implements casacore::Coordinate.

Int casacore::CoordinateSystem::spectralAxisNumber ( Bool  doWorld = False) const

What number is the spectral axis? If doWorld=True, the world axis number is returned.

Otherwise, the pixel axis number is returned. Returns -1 if the spectral axis (world c.q. pixel) does not exist.

Referenced by casa::DisplayCoordinateSystem::spectralAxisNumber().

const SpectralCoordinate& casacore::CoordinateSystem::spectralCoordinate ( uInt  which) const
const SpectralCoordinate& casacore::CoordinateSystem::spectralCoordinate ( ) const
Int casacore::CoordinateSystem::spectralCoordinateNumber ( ) const

what number is the spectral coordinate? Returns -1 if no spectral coordinate exists.

String casacore::CoordinateSystem::stokesAtPixel ( const uInt  pixel) const
const StokesCoordinate& casacore::CoordinateSystem::stokesCoordinate ( ) const
const StokesCoordinate& casacore::CoordinateSystem::stokesCoordinate ( uInt  which) const
Int casacore::CoordinateSystem::stokesPixelNumber ( const String stokesString) const

Given a stokes or polarization parameter, find the pixel location.

Note the client is responsible for any boundedness checks (eg finite number of stokes in an image).

StokesCoordinate casacore::CoordinateSystem::stokesSubImage ( const StokesCoordinate sc,
Int  originShift,
Int  pixincFac,
Int  newShape 
) const
private

Do subImage for Stokes.

CoordinateSystem casacore::CoordinateSystem::stripRemovedAxes ( const CoordinateSystem cSys) const
private

Strip out coordinates with all world and pixel axes removed.

CoordinateSystem casacore::CoordinateSystem::subImage ( const Vector< Float > &  originShift,
const Vector< Float > &  incrFac,
const Vector< Int > &  newShape 
) const

Return a CoordinateSystem appropriate for a shift of origin (the shift is subtracted from the reference pixel) and change of increment (the increments are multipled by the factor).

Both vectors should be of length nPixelAxes().

The newShape vector is only needed for the StokesCoordinate, if any. If this vector is of length zero, the new StokesCoordinate is formed from all of the available input Stokes after application of the shift and increment factor. Otherwise, the new Stokes axis length is equal to that specified after appliction of the shift and increment and excess values discarded. In addition, for any StokesCoordinate, the shift and factor must be integer. So Int(value+0.5) is taken before they are used.

void casacore::CoordinateSystem::subImageInSitu ( const Vector< Float > &  originShift,
const Vector< Float > &  incrFac,
const Vector< Int > &  newShape 
)
const TabularCoordinate& casacore::CoordinateSystem::tabularCoordinate ( uInt  which) const
Bool casacore::CoordinateSystem::toFITSHeader ( RecordInterface header,
IPosition shape,
Bool  oneRelative,
Char  prefix = 'c',
Bool  writeWCS = True,
Bool  preferVelocity = True,
Bool  opticalVelocity = True,
Bool  preferWavelength = False,
Bool  airWavelength = False 
) const

Convert a CoordinateSystem to FITS, i.e.

fill in ctype etc. In the record the keywords are vectors, it is expected that the actual FITS code will split them into scalars and upcase the names. Returns False if one of the keywords is already taken.

If writeWCS is True, attempt to write the WCS convention (Greisen and Calabretta "Representation of celestial coordinates in FITS"). Use oneRelative=True to convert zero-relative pixel coordinates to one-relative FITS coordinates.

prefix gives the prefix for the FITS keywords. E.g., if prefix="c" then crval, cdelt etc. if prefix="d" then drval, ddelt etc.

virtual Bool casacore::CoordinateSystem::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. Vectors worldMin and worldMax specify the range of the world coordinate (in the world axis units of that world axis in the coordinate system) being solved for in a mixed calculation for each world axis. They are only actually used for DirectionCoordinates and for all other coordinates the relevant elements are ignored. Functions setWorldMixRanges, worldMixMin, worldMixMax can be used to compute and recover the world ranges. If you don't know the values, use functions setDefaultWorldMixRanges, worldMixMin, worldMixMax. 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.

Reimplemented from casacore::Coordinate.

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

Implements casacore::Coordinate.

virtual Vector<Double> casacore::CoordinateSystem::toPixel ( const Vector< Double > &  world) const
virtual

This one throws an exception rather than returning False.

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

Reimplemented from casacore::Coordinate.

virtual Bool casacore::CoordinateSystem::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 errorMessage() contains an error message. The input vector must be of length nPixelAxes or nWorldAxes. The output vector is resized appropriately. if useConversionFrame, if the coordinate has a conversion layer frame (such as can be present in spectral and direction coordinates), it is used. Else, the native frame is used for the conversion.

Implements casacore::Coordinate.

Referenced by casa::MomentCalcBase< T >::getMomentCoord().

virtual Vector<Double> casacore::CoordinateSystem::toWorld ( const Vector< Double > &  pixel) const
virtual

This one throws an exception rather than returning False.

After all, that's what exceptions are for.

Bool casacore::CoordinateSystem::toWorld ( Vector< Double > &  world,
const IPosition pixel 
) const

This is provided as a convenience since it is a very commonly desired operation through CoordinateSystem.

The output vector is resized.

Vector<Double> casacore::CoordinateSystem::toWorld ( const IPosition pixel) const
virtual Quantity casacore::CoordinateSystem::toWorldLength ( const Double  nPixels,
const uInt  pixelAxis 
) const
virtual

convert a pixel "length" to a world "length"

virtual Bool casacore::CoordinateSystem::toWorldMany ( Matrix< Double > &  world,
const Matrix< Double > &  pixel,
Vector< Bool > &  failures 
) const
virtual

Batch up a lot of transformations.

The first (most rapidly varying) axis of the matrices contain the coordinates. Returns False if any conversion failed and errorMessage() will hold a message. The failures array (True for fail, False for success) is the length of the number of conversions and holds an error status for each conversion.

Reimplemented from casacore::Coordinate.

void casacore::CoordinateSystem::transpose ( const Vector< Int > &  newWorldOrder,
const Vector< Int > &  newPixelOrder 
)

Transpose the CoordinateSystem so that world axis 0 is newWorldOrder(0) and so on for all the other axes.

newPixelOrder works similarly. Normally you will give the same transformation vector for both the world and pixel transformations, however this is not required.

Coordinate::Type casacore::CoordinateSystem::type ( uInt  whichCoordinate) const

Return the type of the given Coordinate.

Referenced by casa::DisplayCoordinateSystem::type().

virtual Coordinate::Type casacore::CoordinateSystem::type ( ) const
virtual
Bool casacore::CoordinateSystem::velocityIncrement ( Double velocityInc,
SpectralCoordinate sc,
MDoppler::Types  velocityType,
const String velUnits 
) const
private
Vector<Int> casacore::CoordinateSystem::worldAxes ( uInt  whichCoord) const

For a given Coordinate say where its world and pixel axes are in this CoordinateSystem.

The position in the returned Vector is its axis number in the Coordinate, and its value is the axis number in the CoordinateSystem. If the value is less than zero the axis has been removed from this CoordinateSystem.

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

Return the requested attribute.

Implements casacore::Coordinate.

Int casacore::CoordinateSystem::worldAxisToPixelAxis ( uInt  worldAxis) const

Find the pixel axis for the given world axis in a CoordinateSystem.

Returns -1 if the pixel axis is unavailable (e.g. if it has been removed).

Referenced by casa::DisplayCoordinateSystem::worldAxisToPixelAxis().

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

Implements casacore::Coordinate.

Bool casacore::CoordinateSystem::worldMap ( Vector< Int > &  worldAxisMap,
Vector< Int > &  worldAxisTranspose,
Vector< Bool > &  refChange,
const CoordinateSystem cSys 
) const

Find the world and pixel axis mappings to the supplied CoordinateSystem from the current coordinate system.

False is returned if either the supplied or current coordinate system, has no world axes (and a message recoverable with function errorMessage indicating why). Otherwise True is returned. worldAxisMap(i) is the location of world axis i (from the supplied CoordinateSystem, cSys, in the current CoordinateSystem. worldAxisTranspose(i) is the location of world axis i (from the current CoordinateSystem) in the supplied CoordinateSystem, cSys. The output vectors are resized appropriately by this function. A value of -1 in either vector means that the axis could not be found in the other CoordinateSystem. The vector refChange says if the types are the same, is there a reference type change (e.g. TOPO versus LSR for the SpectralCoordinate, or J2000 versus GALACTIC for DirectionCoordinate). Thus if refChange(i) is True, it means world axis i in the current CoordinateSystem was matched, but has a different reference type to that of the supplied CoordinateSystem.

virtual Vector<Double> casacore::CoordinateSystem::worldMixMax ( ) const
virtual
virtual Vector<Double> casacore::CoordinateSystem::worldMixMin ( ) const
virtual

Member Data Documentation

const String casacore::CoordinateSystem::_class
staticprivate

Definition at line 905 of file CoordinateSystem.h.

std::map<String, String> casacore::CoordinateSystem::_friendlyAxisMap
staticprivate

Definition at line 907 of file CoordinateSystem.h.

Mutex casacore::CoordinateSystem::_mapInitMutex
staticprivate

Definition at line 906 of file CoordinateSystem.h.

PtrBlock<Coordinate *> casacore::CoordinateSystem::coordinates_p
private

Where we store copies of the coordinates we are created with.

Definition at line 876 of file CoordinateSystem.h.

ObsInfo casacore::CoordinateSystem::obsinfo_p
private

Miscellaneous information about the observation associated with this Coordinate System.

Definition at line 903 of file CoordinateSystem.h.

PtrBlock<Block<Int> *> casacore::CoordinateSystem::pixel_maps_p
private

Same meanings as for the world*'s above.

Definition at line 889 of file CoordinateSystem.h.

PtrBlock<Vector<Double> *> casacore::CoordinateSystem::pixel_replacement_values_p
private

Definition at line 891 of file CoordinateSystem.h.

PtrBlock<Vector<Double> *> casacore::CoordinateSystem::pixel_tmps_p
private

Definition at line 890 of file CoordinateSystem.h.

PtrBlock<Vector<Bool> *> casacore::CoordinateSystem::pixelAxes_tmps_p
private

Definition at line 895 of file CoordinateSystem.h.

PtrBlock<Vector<Double> *> casacore::CoordinateSystem::pixelOut_tmps_p
private

Definition at line 897 of file CoordinateSystem.h.

PtrBlock<Block<Int> *> casacore::CoordinateSystem::world_maps_p
private

For coordinate[i] axis[j], world_maps_p[i][j], if >=0 gives the location in the input vector that maps to this coord/axis, <0 means that the axis has been removed world_tmp_p[i] a temporary vector length coord[i]->nworldAxes() replacement_values_p[i][j] value to use for this axis if removed.

Definition at line 884 of file CoordinateSystem.h.

PtrBlock<Vector<Double> *> casacore::CoordinateSystem::world_replacement_values_p
private

Definition at line 886 of file CoordinateSystem.h.

PtrBlock<Vector<Double> *> casacore::CoordinateSystem::world_tmps_p
private

Definition at line 885 of file CoordinateSystem.h.

PtrBlock<Vector<Bool> *> casacore::CoordinateSystem::worldAxes_tmps_p
private

These temporaries all needed for the toMix function.

Definition at line 894 of file CoordinateSystem.h.

PtrBlock<Vector<Double> *> casacore::CoordinateSystem::worldMax_tmps_p
private

Definition at line 899 of file CoordinateSystem.h.

PtrBlock<Vector<Double> *> casacore::CoordinateSystem::worldMin_tmps_p
private

Definition at line 898 of file CoordinateSystem.h.

PtrBlock<Vector<Double> *> casacore::CoordinateSystem::worldOut_tmps_p
private

Definition at line 896 of file CoordinateSystem.h.


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