    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 `CoordinateSystem`C

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:

- double[] forward(double[] position)
- double[] forward(double[] position, int[] axisIndices)
- double[] reverse(double[] position)
- double[] reverse(double[] position, int[] axisIndices)
- int getInNaxes()
- int getOutNaxes()

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().``

##

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.
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.
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.
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.

##

CoordTransform()

##

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.
canTransform(Metadata)
  return true if this transform can be logically applied to a a coordinate system with the specified Metadata.
canTransform(Metadata, boolean)
  return true if this transform can be logically applied to a a coordinate system with the specified Metadata.
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.
clone()
  create a copy of this Transform
determineConstraints(Metadata)
  make an educated guess as to the proper way to apply this transform to a coordinate system with the specified Metadata.
determineConstraints(Metadata, boolean)
  make an educated guess as to the proper way to apply this transform to a coordinate system with the specified Metadata.
forward(double[])
  apply a forward tranform on an input position.
forward(double[], int[])
  apply a forward tranform on an input position.
getFormatters(boolean)
  return the formatter objects that will get used (when necessary) after this transform is attached to a CoordinateSystem.
getInNaxes()
  return the minimum number of axes that the forward transform operates on.
getMetadata(Metadata, boolean, int[])
  update the input Metadata object to reflect the changes that this tranform makes to a coordinate position.
getNames(boolean)
  return the names that will (when necessary) identify the transformed axes after this transform is attached to a CoordinateSystem.
getOutNaxes()
  return the minimum number of axes that results from the forward transform.
init(CoordinateSystem, boolean, int[])
  initialize this transform according to the system it is to be applied to.
reverse(double[])
  apply a reverse tranform on an input position.
reverse(double[], int[])
  apply a reverse tranform on an input position
setFormatter(int, AxisPosFormatter, boolean)
  set the formatter object(s) that get used (when necessary) while this transform is attached to a CoordinateSystem.
setName(int, String, boolean)
  set the name that get used (when necessary) to identify an axis while this transform is attached to a CoordinateSystem.

##

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.

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.

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.

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.

##

CoordTransform

      public CoordTransform()

##

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.

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

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.

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

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.

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.

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.

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.

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

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

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

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

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).

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.

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.

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.

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.

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.

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