TabularCoordinate.h

Classes

TabularCoordinate -- Table lookup 1-D coordinate, with interpolation. (full description)

class TabularCoordinate : public Coordinate

Interface

Public Members
TabularCoordinate()
TabularCoordinate(Double refval, Double inc, Double refpix, const String &unit, const String &axisName)
TabularCoordinate(const Quantum<Double>& refval, const Quantum<Double>& inc, Double refpix, const String& axisName)
TabularCoordinate(const Vector<Double> &pixelValues, const Vector<Double> &worldValues, const String &unit, const String &axisName)
TabularCoordinate(const Vector<Double>& pixelValues, const Quantum<Vector<Double> >& worldValues, const String &axisName)
TabularCoordinate(const TabularCoordinate &other)
TabularCoordinate &operator=(const TabularCoordinate &other)
virtual ~TabularCoordinate()
virtual Coordinate::Type type() const
virtual String showType() const
virtual uInt nPixelAxes() const
virtual uInt nWorldAxes() const
virtual Bool toWorld(Vector<Double> &world, const Vector<Double> &pixel) const
virtual Bool toPixel(Vector<Double> &pixel, const Vector<Double> &world) const
Bool toWorld(Double &world, Double pixel) const
Bool toPixel(Double &pixel, Double world) const
virtual Bool toWorldMany(Matrix<Double> &world, const Matrix<Double> &pixel, Vector<Bool>& failures) const
virtual Bool toPixelMany(Matrix<Double>& pixel, const Matrix<Double>& world, Vector<Bool>& failures) const
virtual void makePixelRelative (Vector<Double>& pixel) const
virtual void makePixelAbsolute (Vector<Double>& pixel) const
virtual void makeWorldRelative (Vector<Double>& world) const
virtual void makeWorldAbsolute (Vector<Double>& world) const
virtual Vector<String> worldAxisNames() const
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)
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)
virtual Vector<String> worldAxisUnits() const
Bool overwriteWorldAxisUnits(const Vector<String> &units)
Vector<Double> pixelValues() const
Vector<Double> worldValues() const
virtual Bool near(const Coordinate& other, Double tol=1e-6) const
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
virtual Bool save(RecordInterface &container, const String &fieldName) const
static TabularCoordinate *restore(const RecordInterface &container, const String &fieldName)
virtual Coordinate *clone() const
Private Members
void clear_self()
void copy(const TabularCoordinate &other)
void makeNonLinearTabularCoordinate(const Vector<Double> &pixelValues, const Vector<Double> &worldValues)

Description

Review Status

Reviewed By:
Peter Barnes
Date Reviewed:
1999/12/24
Programs:
Tests:

Prerequisite

Synopsis

This class is used where the world and pixel values are determined by a lookup table. For fractional pixel values, a linear interpolation is used. The values returned for, e.g., the increment, are based on the average of the whole table. At present, the values must either increase or decrease monotonically.

Caution All pixels coordinates are zero relative.

Example

Let's make a non-linear TabularCoordinate and convert a pixel value to world (which will use linear interpolation)
    Vector<Double> pixelValues(3); 
    Vector<Double> worldValues(3); 
    pixelValues(0) = 122.0;
    pixelValues(1) = 300.0;
    pixelValues(2) = 6524.0;
    worldValues(0) = 1.1e6;
    worldValues(1) = 2.1e6;
    worldValues(2) = 2.2e6;

    String unit("km");
    String axisName("length");

    TabularCoordinate tc(pixelValues, worldValues, unit, axisName);

    Double world, pixel;
    pixel = 200.12;
    if (!tc.toWorld(world, pixel)) {
      cerr << "Error : " << tc.errorMessage() << endl;
    } else {
      cerr << "pixel, world = " << pixel << ", " << world << endl;
    }

Motivation

This class was motivated by the need for an irregular axis, such as a collection of frequencies. For example, the SpectralCoordinate class contains a TabularCoordinate.

Thrown Exceptions

To Do

Member Description

TabularCoordinate()

Default constructor. It is equivalent to TabularCoordinate(0,1,0, "", "Tabular");

TabularCoordinate(Double refval, Double inc, Double refpix, const String &unit, const String &axisName)

Create a linear TabularCoordinate where world = refval + inc*(pixel-refpix)

TabularCoordinate(const Quantum<Double>& refval, const Quantum<Double>& inc, Double refpix, const String& axisName)

Create a linear TabularCoordinate with a Quantum-based interface where world = refval + inc*(pixel-refpix). The units of the increment (inc) will be converted to those of the reference value (refVal) which will then serve as the units of the Coordinate.

TabularCoordinate(const Vector<Double> &pixelValues, const Vector<Double> &worldValues, const String &unit, const String &axisName)

Construct a TabularCoordinate with the specified world values. The increments and related functions return the average values calculated from the first and last world values. The number of pixel and world values must be the same. Normally the pixel values will be 0,1,2,..., but this is not required.

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

TabularCoordinate(const Vector<Double>& pixelValues, const Quantum<Vector<Double> >& worldValues, const String &axisName)

Construct a TabularCoordinate with the specified world values via the Quantum-based interface. All comments for the previous constructor apply

TabularCoordinate(const TabularCoordinate &other)

Copy constructor (copy semantics).

TabularCoordinate &operator=(const TabularCoordinate &other)

Assignment (copy semantics).

virtual ~TabularCoordinate()

Destructor.

virtual Coordinate::Type type() const

Returns Coordinate::TABULAR.

virtual String showType() const

Always returns the String "Tabular".

virtual uInt nPixelAxes() const
virtual uInt nWorldAxes() const

Always returns 1.

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

Convert a pixel position to a world position or vice versa. Returns True if the conversion succeeds, otherwise it returns False and method errorMessage contains an error message. The output vectors are appropriately resized.

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

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.

virtual void makePixelRelative (Vector<Double>& pixel) const
virtual void makePixelAbsolute (Vector<Double>& pixel) const
virtual void makeWorldRelative (Vector<Double>& world) const
virtual void makeWorldAbsolute (Vector<Double>& world) const

Make absolute coordinates relative and vice-versa (with respect to the referencfe value). Vectors must be length nPixelAxes() or nWorldAxes() or memory access errors will occur

virtual Vector<String> worldAxisNames() const
virtual Vector<Double> referencePixel() const
virtual Matrix<Double> linearTransform() const
virtual Vector<Double> increment() const
virtual Vector<Double> referenceValue() const

Return the requested attribute.

virtual Bool setWorldAxisNames(const Vector<String> &names)
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)

Set the value of the requested attribute. Note that these just change the internal values, they do not cause any recomputation.

virtual Bool setWorldAxisUnits(const Vector<String> &units)
virtual Vector<String> worldAxisUnits() const

Set/get the axis unit. Adjust the increment and reference value by the ratio of the old and new units. The unit must be compatible with the current units.

Bool overwriteWorldAxisUnits(const Vector<String> &units)

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

Vector<Double> pixelValues() const
Vector<Double> worldValues() const

Get the table, i.e. the pixel and world values. The length of these Vectors will be zero if this axis is pure linear.

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

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

virtual Coordinate* makeFourierCoordinate (const Vector<Bool>& axes, const Vector<Int>& shape) const

Find the Coordinate for when we Fourier Transform ourselves. This pointer must be deleted by the caller. Axes specifies which axes of the Coordinate you wish to transform. Shape specifies the shape of the image associated with all the axes of the Coordinate. Currently the output reference pixel is always shape/2. If the pointer returned is 0, it failed with a message in errorMessage

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

Save the TabularCoordinate into the supplied record using the supplied field name. The field must not exist, otherwise False is returned.

static TabularCoordinate *restore(const RecordInterface &container, const String &fieldName)

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

virtual Coordinate *clone() const

Make a copy of the TabularCoordinate using new. The caller is responsible for calling delete.

void clear_self()

Common for assignment operator and destructor.

void copy(const TabularCoordinate &other)

Common code for copy ctor and assignment operator.

void makeNonLinearTabularCoordinate(const Vector<Double> &pixelValues, const Vector<Double> &worldValues)