Class ncsa.horizon.coordinates.CoordTransform
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ncsa.horizon.coordinates.CoordTransform

java.lang.Object
   |
   +----java.util.Observable
           |
           +----ncsa.horizon.coordinates.CoordTransform

public class CoordTransform
extends Observable
implements Cloneable
an object for transforming positions from one coordinate system to another.

This is an abstract class which can be sub-classed and fully implemented to create a CoordTransform object that can be attached to a CoordinateSystem object or used by itself.

Attaching a CoordTransform to a CoordinateSystemC

A CoordTransform object is most commonly used by attaching it to a CoordinateSystem via the latter's attachTransform. This causes the CoordinateSystem to automatically apply the transform everytime positions are requested from the system. When the transform is attached, it can (if necessary) adjust the parameters of the transform based on the CoordinateSystem's metadata; it can also advise the CoordinateSystem on how the latter should update its metadata to reflect the new transformation.

Two of the things an attached CoordTransform can suggest to a CoordinateSystem are what to name the transformed axes and how to print out the transformed positions. This is done by providing some suggested Strings to use as names and AxisPosFormatter objects to use as formatters. The default suggestions (if there are any) can be overriden via the setName() and setFormatter() method.

Using a CoordTransform Directly

The methods forward() and reverse() apply the transform to an array of doubles that represents a position in one of the systems (each element being the position along an axis of the system). What defines the forward transform is in general completely arbitrary and up to the specific implementations. Furthermore, the number axes in the two systems do not need to be equal. For efficiency, these methods have the option of manipulating the elements of the input position array directly and returning it, or return a new array if number of axes in the input system is different from that of the output system.

Each element in the position array given to forward(double[]) or reverse(double[]) represents a position along some coordinate system axis. When one of these methods is called, the CoordTransform applies its operation on the input array assuming that axes are in some specific order; for instance, it may assume that the first element is a longitude and the second is a latitude. (See the transform's documentation for forward(double[]) and reverse(double[]) for the assumed order.) However, one can take more control over how the transform is applied by calling forward(double[], int[]) or reverse(double[], int[]). The second argument in this case is an axis index array which gives the location in the position array of each required axis. So, using our example, if the longitude axis is actually the third element and the latitude is first element, the axis index array should be equal to {2, 0}. The position elements not listed in the axis index array are left unchanged by the transform.

In the documentation below, the terms "old" and "new" refer the to two systems relative to the direction of this transform; that is, the forward() method transforms a position in the "old" system to a position in the new system.

Implementing a CoordTransform Object

A instantiatable CoordTransform must at a minimum implement six method:

The last two return the minimum number of axes needed to apply the transform (see description below). The other four actually perform the transformation. The forward(double[]) and reverse(double[]) methods assume that the axes of the position are ordered in the default way. Most of the Horizon CoordTransform classes put the actual transforming code in the version of forward() and reverse() that take an axis index array (see previous section); the single argument versions of forward() and reverse() merely call the two-argument versions with a default axis index array.

Implementations may also wish to override one or a few of the other methods in this class that are called when the transform is attached to a CoordinateSystem. When the transform is attached, the CoordinateSystem calls the transform's init(); this allows the transform to adjust its internal parameters according to the system's metadata. (By default init() is a do-nothing method.) Next, the CoordinateSystem calls the transform's getMetadata() to update the system's metadata to reflect the new transformation. The default version of getMetadata() calls applyNamesAndFormatters() to update the axis names and formatters; thus overriding versions should call either super.getMetadata() or applyNamesAndFormatters().

Finally, implementations may wish to set some default axis names and formatters within the transform constructors. For these to be passed on to a CoordinateSystem during attachment, it is not necessary to override getMetadata(); the default version does this automatically.

Note that method that update the internal state of a CoordTransform should consider that the transform might be attached to a CoordinateSystem at the time; therefore, the methods should call hasChanged() and notifyObservers().


Variable Index

 o fwdfmtrs
suggested AxisPosFormatter objects to use with forward transformations when attached to a CoordinateSystem object; null value means use the formatter CoordinateSystem's default formatter.
 o fwdnames
suggested strings to use as axis names to use with forward transformations when attached to a CoordinateSystem object; null value means use the formatter CoordinateSystem's default formatter.
 o revfmtrs
suggested AxisPosFormatter objects to use with reverse transformations when attached to a CoordinateSystem object; null value means use the formatter CoordinateSystem's default formatter.
 o revnames
suggested strings to use as axis names to use with reverse transformations when attached to a CoordinateSystem object; null value means use the formatter CoordinateSystem's default formatter.

Constructor Index

 o CoordTransform()

Method Index

 o applyNamesAndFormatters(Metadata, boolean, int[])
update the "Axes[n].formatter" and "Axes[n].name" metadata in the given list with the assumption that the transform is being applied to a system described by the metadata list.
 o canTransform(Metadata)
return true if this transform can be logically applied to a a coordinate system with the specified Metadata.
 o canTransform(Metadata, boolean)
return true if this transform can be logically applied to a a coordinate system with the specified Metadata.
 o canTransform(Metadata, CoordTransformConstraints)
return true if this transform can be logically applied to a a coordinate system with the specified Metadata using the specified constraints.
 o clone()
create a copy of this Transform
 o determineConstraints(Metadata)
make an educated guess as to the proper way to apply this transform to a coordinate system with the specified Metadata.
 o determineConstraints(Metadata, boolean)
make an educated guess as to the proper way to apply this transform to a coordinate system with the specified Metadata.
 o forward(double[])
apply a forward tranform on an input position.
 o forward(double[], int[])
apply a forward tranform on an input position.
 o getFormatters(boolean)
return the formatter objects that will get used (when necessary) after this transform is attached to a CoordinateSystem.
 o getInNaxes()
return the minimum number of axes that the forward transform operates on.
 o getMetadata(Metadata, boolean, int[])
update the input Metadata object to reflect the changes that this tranform makes to a coordinate position.
 o getNames(boolean)
return the names that will (when necessary) identify the transformed axes after this transform is attached to a CoordinateSystem.
 o getOutNaxes()
return the minimum number of axes that results from the forward transform.
 o init(CoordinateSystem, boolean, int[])
initialize this transform according to the system it is to be applied to.
 o reverse(double[])
apply a reverse tranform on an input position.
 o reverse(double[], int[])
apply a reverse tranform on an input position
 o setFormatter(int, AxisPosFormatter, boolean)
set the formatter object(s) that get used (when necessary) while this transform is attached to a CoordinateSystem.
 o setName(int, String, boolean)
set the name that get used (when necessary) to identify an axis while this transform is attached to a CoordinateSystem.

Variables

 o fwdfmtrs
  protected Vector fwdfmtrs
suggested AxisPosFormatter objects to use with forward transformations when attached to a CoordinateSystem object; null value means use the formatter CoordinateSystem's default formatter. The formatters are not used when independent of the CoordinateSystem object, and they may not get used if this transform is not the last one in a chain.
 o revfmtrs
  protected Vector revfmtrs
suggested AxisPosFormatter objects to use with reverse transformations when attached to a CoordinateSystem object; null value means use the formatter CoordinateSystem's default formatter. The formatters are not used when independent of the CoordinateSystem object, and they may not get used if this transform is not the last one in a chain.
 o fwdnames
  protected Vector fwdnames
suggested strings to use as axis names to use with forward transformations when attached to a CoordinateSystem object; null value means use the formatter CoordinateSystem's default formatter. The names are ignored when tranform is used independent of a CoordinateSystem object, and they may not get used if this transform is not the last one in a chain.
 o revnames
  protected Vector revnames
suggested strings to use as axis names to use with reverse transformations when attached to a CoordinateSystem object; null value means use the formatter CoordinateSystem's default formatter. The names are ignored when tranform is used independent of a CoordinateSystem object, and they may not get used if this transform is not the last one in a chain.

Constructors

 o CoordTransform
  public CoordTransform()

Methods

 o forward
  public abstract double[] forward(double position[],
                                   int axisIndices[]) throws PositionBeyondDomainException, TransformUndefinedException
apply a forward tranform on an input position.
Parameters:
position - an array giving the input position to transform
axisIndices - an array containing the indices of the position array that should be used in the tranformation. The order of the indices indicate how the position should be interpreted by the transform.
 o forward
  public abstract double[] forward(double position[]) throws PositionBeyondDomainException, TransformUndefinedException
apply a forward tranform on an input position. A list of axis indices is assumed (usually { 0, ... getInNAxes()-1 }).
Parameters:
position - an array giving the input position to transform
 o reverse
  public abstract double[] reverse(double position[],
                                   int axisIndices[]) throws PositionBeyondDomainException, TransformUndefinedException
apply a reverse tranform on an input position
Parameters:
position - an array giving the input position to transform
axisIndices - an array containing the indices of the position array that should be used in the tranformation. The order of the indices indicate how the position should be interpreted by the transform.
 o reverse
  public abstract double[] reverse(double position[]) throws PositionBeyondDomainException, TransformUndefinedException
apply a reverse tranform on an input position. A list of axis indices is assumed (usually { 0, ... getOutNAxes()-1 }).
Parameters:
position - an array giving the input position to transform
 o getInNaxes
  public int getInNaxes()
return the minimum number of axes that the forward transform operates on. This value is equal to the minimum number of axes that results from the reverse transform. This value is often equal to the that returned by getOutNaxes(), but is not required to.
 o getOutNaxes
  public int getOutNaxes()
return the minimum number of axes that results from the forward transform. This value is equal to the minimum number of axes that the reverse transform operates on. This value is often equal to the that returned by getInNaxes(), but is not required to.
 o init
  public void init(CoordinateSystem csys,
                   boolean forward,
                   int axisIndices[]) throws IllegalTransformException
initialize this transform according to the system it is to be applied to. This method is usually called by a CoordinateSystem object when the transform is attached to it. By default, this method does nothing; however, sub-classers have the option of overriding this method.
Throws: IllegalTransformException
if this transform cannot initialize itself for the given system and constraints.
 o getMetadata
  public Metadata getMetadata(Metadata in,
                              boolean forward,
                              int axisIndices[])
update the input Metadata object to reflect the changes that this tranform makes to a coordinate position. In general, this method will actually edit the contents of the input Metadata when changes are necessary. By default, this method returns the input Metadata object updated with new values for the "Axis[n].formatter" metadata when available. Note therefore that subclasses that override this method should either call super.getMetadata() or applyFormatters() to properly update the formatters in the list.
Parameters:
in - the Metadata list to update
forward - if true, assume the transform is being applied in the forward direction; otherwise, assume reverse
axisIndices - the index list that describes which axes this transform will operate on; should not be null.
 o determineConstraints
  public CoordTransformConstraints determineConstraints(Metadata in)
make an educated guess as to the proper way to apply this transform to a coordinate system with the specified Metadata. By default, this method returns new CoordTransformConstraints(n) where n is the value of the "naxes" metadatum; however, sub-classers are encouraged to override this. Note that there may exist a number of ways that this transform might be logically applied to a coordinate system.
Parameters:
in - the Metadata describing the system to be transformed
Returns:
CoordTransformConstraints the resulting guess, null if the transform cannot be logically applied
 o determineConstraints
  public CoordTransformConstraints determineConstraints(Metadata in,
                                                        boolean forwards)
make an educated guess as to the proper way to apply this transform to a coordinate system with the specified Metadata. By default, this method returns new CoordTransformConstraints(n) where n is the value of the "naxes" metadatum; however, sub-classers are encouraged to override this. Note that there may exist a number of ways that this transform might be logically applied to a coordinate system.
Parameters:
in - the Metadata describing the system to be transformed
forwards - if false, the constraints determined should be for attaching the reverse of the transform
Returns:
CoordTransformConstraints the resulting guess, null if the transform cannot be logically applied
 o canTransform
  public boolean canTransform(Metadata in)
return true if this transform can be logically applied to a a coordinate system with the specified Metadata. By default, this method returns true if determineConstraints() returns a non-null value.
Parameters:
in - the Metadata describing the system to be transformed
 o canTransform
  public boolean canTransform(Metadata in,
                              boolean forwards)
return true if this transform can be logically applied to a a coordinate system with the specified Metadata. By default, this method returns true if determineConstraints() returns a non-null value.
Parameters:
in - the Metadata describing the system to be transformed
forwards - if false, return whether the reverse transform can be applied
 o canTransform
  public boolean canTransform(Metadata in,
                              CoordTransformConstraints c)
return true if this transform can be logically applied to a a coordinate system with the specified Metadata using the specified constraints. By default, this method returns false only if the CoordTransformConstraints refers to an axis index outside the range specified within the Metadata object. Sub-classers are encouraged to override this method as is appropriate (for example, it may check to make sure that there exists at least one longitude axis and one latitude axis).
 o setFormatter
  public synchronized void setFormatter(int axis,
                                        AxisPosFormatter formatter,
                                        boolean forForward)
set the formatter object(s) that get used (when necessary) while this transform is attached to a CoordinateSystem. Note that this method must be called prior to attachment in order for the CoordinateSystem to recieve the formatter.
Parameters:
axis - the axis number intended for the formatter; if <= 0, then use the formatter for all axes, taking the absolute value as the total number of axes we should expect (0 keep the same number of assumed axes).
formatter - the formatter to set
forForward - if true, the formatter should be used when this transform is attached in the forward direction; otherwise, it should only be used when attached in the reverse direction.
 o getFormatters
  public AxisPosFormatter[] getFormatters(boolean forForward)
return the formatter objects that will get used (when necessary) after this transform is attached to a CoordinateSystem.
Parameters:
forForward - if true, return the ones applicable when this transform is attached in the forward direction; otherwise, return those for the reverse direction.
Returns:
AxisPosFormatter[] the array that will be used or null if the CoordinateSystem should use whatever other formatters available to it. Null values within the array also mean use the default for that axis.
 o setName
  public synchronized void setName(int axis,
                                   String name,
                                   boolean forForward)
set the name that get used (when necessary) to identify an axis while this transform is attached to a CoordinateSystem. Note that this method must be called prior to attachment in order for the CoordinateSystem to receive the name.
Parameters:
axis - the axis number intended for the formatter; if < 1, then use the formatter for all axes
name - the name to be passed to the CoordinateSystem
forForward - if true, the formatter should be used when this transform is attached in the forward direction; otherwise, it should only be used when attached in the reverse direction.
 o getNames
  public String[] getNames(boolean forForward)
return the names that will (when necessary) identify the transformed axes after this transform is attached to a CoordinateSystem.
Parameters:
forForward - if true, return the ones applicable when this transform is attached in the forward direction; otherwise, return those for the reverse direction.
Returns:
String[] the array that will be used or null if the CoordinateSystem should use whatever other names available to it. Null values within the array also mean use the default for that axis.
 o applyNamesAndFormatters
  public synchronized void applyNamesAndFormatters(Metadata md,
                                                   boolean forward,
                                                   int axisIndices[])
update the "Axes[n].formatter" and "Axes[n].name" metadata in the given list with the assumption that the transform is being applied to a system described by the metadata list. Note that most applications need not call this method as it is usually invoked within the getMetadata() method of this class.
Parameters:
md - the metadata list to update
forward - if true, assume the transform is being applied in the forward direction; otherwise assume reverse.
axisIndices - the index list that describes which axes this transform will operate on; should not be null.
 o clone
  public synchronized Object clone()
create a copy of this Transform
Overrides:
clone in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index