uk.ac.starlink.ast

Class Transformer

java.lang.Object

uk.ac.starlink.ast.Transformer

Direct Known Subclasses:

Transformer1, Transformer2

public abstract class Transformer
extends Object

Defines a custom general coordinate transformation function. Objects subclassing this abstract class can be used to construct a Mapping (an IntraMap) with a user-defined transformation function.

If the IntraMaps containing this Transformer is to be read or written via a Channel, the class must be declared Serializable.

This is implemented as an abstract class (rather than an interface) so that additional `flags' along the lines of the simpFI method can be introduced in the future without breaking existing code.

Version:

$Id$

Author:

Mark Taylor (Starlink)

Constructor Summary

Constructors

Constructor and Description
Transformer()

Method Summary

Modifier and Type	Method and Description
abstract boolean	canTransformCoords(int nin, int nout) Indicates whether this Transformer is able to transform between coordinate spaces with the given dimensionalities.
abstract String	getAuthor() Names the author of this Transformer.
abstract String	getContact() Gives contact details for the author of this Transformer.
abstract String	getPurpose() Gives a brief indication of the purpose of this Transformer.
boolean	hasForward() Indicates whether this Transformer can perform a forward transformation (whether the transformation method may be invoked with forward set true).
boolean	hasInverse() Indicates whether this Transformer can perform an inverse transformation (whether the transformation method may be invoked with forward set false).
boolean	simpFI() Indicates whether a forward transformation followed by an inverse transformation may always be considered to restore the original coordinates.
boolean	simpIF() Indicates whether an inverse transformation followed by a forward transformation may always be considered to restore the original coordinates.
abstract double[][]	tranP(int npoint, int ncoord_in, double[][] in, boolean forward, int ncoord_out) Transforms points from input coordinates to output coordinates.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Transformer

public Transformer()

Method Detail

canTransformCoords

public abstract boolean canTransformCoords(int nin,
                                           int nout)

Indicates whether this Transformer is able to transform between coordinate spaces with the given dimensionalities.

Parameters:

nin - the number of coordinates of an input point

nout - the number of coordinates of an output point

Returns:

the method should return true if this Transformer's tranP method will be able to transform points with nin coordinates to points with nout coordinates, and false otherwise

hasForward

public boolean hasForward()

Indicates whether this Transformer can perform a forward transformation (whether the transformation method may be invoked with forward set true).

The default implementation returns true - subclasses should override this if the forward transformation is not available.

Returns:

whether the forward transformation is available

hasInverse

public boolean hasInverse()

Indicates whether this Transformer can perform an inverse transformation (whether the transformation method may be invoked with forward set false).

The default implementation returns true - subclasses should override this if the inverse transformation is not available.

Returns:

whether the inverse transformation is available

simpFI

public boolean simpFI()

Indicates whether a forward transformation followed by an inverse transformation may always be considered to restore the original coordinates. It is not necessary that both forward and inverse transformations have been implemented.

The default implementation returns false - subclasses should override this if such simplifications are always valid.

Returns:

whether forward followed by inverse is a unit transformation

simpIF

public boolean simpIF()

Indicates whether an inverse transformation followed by a forward transformation may always be considered to restore the original coordinates. It is not necessary that both forward and inverse transformations have been implemented.

The default implementation returns false - subclasses should override this if such simplifications are always valid.

Returns:

whether inverse followed by forward is a unit transformation

tranP

public abstract double[][] tranP(int npoint,
                                 int ncoord_in,
                                 double[][] in,
                                 boolean forward,
                                 int ncoord_out)
                          throws Exception

Transforms points from input coordinates to output coordinates. This method does the work of the Transformer, taking an array of input coordinate arrays and returning an array of output coordinate arrays.

This method will only be called with forward set true if a prior call of the hasForward method has returned true, and will only be called with forward set false if a prior call of the hasInverse has returned true.

If forward is true, then this method will only be called with values of ncoord_in, ncoord_out for which a prior call of canTransform(ncoord_in,ncoord_out) has returned true.
If forward is false, then this method will only be called with values of ncoord_in, ncoord_out for which a prior call of canTransform(ncoord_out,ncoord_in) has returned true.

Parameters:

npoint - the number of points to be transformed

ncoord_in - the number of coordinates being supplied for each input point (the dimensionality of the input space)

in - an array of ncoord_in arrays, each containing npoint elements. These give the coordinates of each point to transform.

forward - true if the forward transformation is to be used, false if its inverse transformation is to be used

ncoord_out - the number of coordinates being generated by the transformation for each output point (the dimensionality of the output space). This need not be equal to ncoord_in.

Returns:

an array of ncoord_out arrays, each containing npoint elements. These give the coordinates of the transformed points. throws Exception If an error occurs during the transformation, this method may throw an Exception. In this case the transformation will be aborted.

Throws:

Exception

getPurpose

public abstract String getPurpose()

Gives a brief indication of the purpose of this Transformer.

Returns:

a short (one-line) string describing the purpose of this transformation function

getAuthor

public abstract String getAuthor()

Names the author of this Transformer.

Returns:

a string giving the name of the author of this transformation function

getContact

public abstract String getContact()

Gives contact details for the author of this Transformer.

Returns:

a string giving contact details, for instance an e-mail or WWW address, for the author.