## visad
Class CoordinateSystem

    java.lang.Object
      visad.CoordinateSystem

All Implemented Interfaces:
  Serializable

Direct Known Subclasses:
  CachingCoordinateSystem, CartesianProductCoordinateSystem, CMYCoordinateSystem, CylindricalCoordinateSystem, EmpiricalCoordinateSystem, FakeCoordinateSystem, FlowSphericalCoordinateSystem, GridCoordinateSystem, HSVCoordinateSystem, IdentityCoordinateSystem, InverseCoordinateSystem, LambertAzimuthalEqualArea, LambertConformalConic, LogCoordinateSystem, NavigatedCoordinateSystem, PolarCoordinateSystem, PolarStereographic, SphericalCoordinateSystem, Vis5DVerticalSystem.Vis5DVerticalCoordinateSystem, WindPolarCoordinateSystem

public abstract class CoordinateSystem
extends Object
implements Serializable

CoordinateSystem is the VisAD abstract superclass for coordinate systems for vectors in R^n for n>0. Specific coordinate systems are defined by extending this class and providing coordinate transformation logic in the toReference and fromReference methods.

CoordinateSystem objects should be immutable.

See Also:
  Serialized Form

Constructor Summary
`` `CoordinateSystem(RealTupleType reference, Unit[] units)` Constructs from the type of the reference coordinate system and units for values in this coordinate system.
`(package private)` `CoordinateSystem(RealTupleType reference, Unit[] units, boolean b)` trusted constructor for initializers (does not throw any declared Exceptions)

Method Summary
`static boolean` `canConvert(RealTupleType out, CoordinateSystem coord_out, RealTupleType in, CoordinateSystem coord_in)` Check to see if a conversion can be done between values of one RealTupleType and another given the CoordinateSystems supplied.
`abstract boolean` `equals(Object cs)` Indicates whether or not this instance is equal to an object (note must test for cs == null).
`abstract double[][]` `fromReference(double[][] value)` Convert RealTuple values from Reference coordinates; for efficiency, input and output values are passed as double[][] arrays rather than RealTuple[] arrays; the array organization is double[tuple_dimension][number_of_tuples]; can modify and return argument array.
`double[][]` `fromReference(double[][] value, Unit[] units)` Convert values in Units specified to this CoordinateSystem's Units.
`float[][]` `fromReference(float[][] value)` Convert RealTuple values from Reference coordinates; for efficiency, input and output values are passed as float[][] arrays rather than RealTuple[] arrays; the array organization is float[tuple_dimension][number_of_tuples]; can modify and return argument array.
`float[][]` `fromReference(float[][] value, Unit[] units)` Convert values in Units specified to this CoordinateSystem's Units.
`Unit[]` `getCoordinateSystemUnits()` Return the Units for this CoordinateSystem.
`int` `getDimension()` Return the number of components in the reference RealTupleType.
`RealTupleType` `getReference()` Return the reference RealTupleType for this CoordinateSystem.
`Unit[]` `getReferenceUnits()` Return the Units for this CoordinateSystem's reference RealTupleType.
`abstract double[][]` `toReference(double[][] value)` Convert RealTuple values to Reference coordinates; for efficiency, input and output values are passed as double[][] arrays rather than RealTuple[] arrays; the array organization is double[tuple_dimension][number_of_tuples]; can modify and return argument array.
`double[][]` `toReference(double[][] value, Unit[] units)` Convert values in Units specified to Reference coordinates.
`float[][]` `toReference(float[][] value)` Convert RealTuple values to Reference coordinates; for efficiency, input and output values are passed as float[][] arrays rather than RealTuple[] arrays; the array organization is float[tuple_dimension][number_of_tuples]; can modify and return argument array.
`float[][]` `toReference(float[][] value, Unit[] units)` Convert values in Units specified to Reference coordinates.
`static double[][]` `transformCoordinates(RealTupleType out, CoordinateSystem coord_out, Unit[] units_out, ErrorEstimate[] errors_out, RealTupleType in, CoordinateSystem coord_in, Unit[] units_in, ErrorEstimate[] errors_in, double[][] value)` Transforms double-valued coordinates between two `RealTupleType`s.
`static double[][]` `transformCoordinates(RealTupleType out, CoordinateSystem coord_out, Unit[] units_out, ErrorEstimate[] errors_out, RealTupleType in, CoordinateSystem coord_in, Unit[] units_in, ErrorEstimate[] errors_in, double[][] value, boolean copy)` Transforms double-valued coordinates between two `RealTupleType`s.
`static float[][]` `transformCoordinates(RealTupleType out, CoordinateSystem coord_out, Unit[] units_out, ErrorEstimate[] errors_out, RealTupleType in, CoordinateSystem coord_in, Unit[] units_in, ErrorEstimate[] errors_in, float[][] value)` Transforms float-valued coordinates between two `RealTupleType`s.
`static float[][]` `transformCoordinates(RealTupleType out, CoordinateSystem coord_out, Unit[] units_out, ErrorEstimate[] errors_out, RealTupleType in, CoordinateSystem coord_in, Unit[] units_in, ErrorEstimate[] errors_in, float[][] value, boolean copy)` Transforms float-valued coordinates between two `RealTupleType`s.
`static double[][]` `transformCoordinatesFreeUnits(RealTupleType out, CoordinateSystem coord_out, Unit[] units_out, ErrorEstimate[] errors_out, RealTupleType in, CoordinateSystem coord_in, Unit[] units_in, ErrorEstimate[] errors_in, double[][] value)` Transforms double-valued coordinates between two `RealTupleType`s.
`static float[][]` `transformCoordinatesFreeUnits(RealTupleType out, CoordinateSystem coord_out, Unit[] units_out, ErrorEstimate[] errors_out, RealTupleType in, CoordinateSystem coord_in, Unit[] units_in, ErrorEstimate[] errors_in, float[][] value)` Transforms float-valued coordinates between two `RealTupleType`s.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### CoordinateSystem

    public CoordinateSystem(RealTupleType reference,
                            Unit[] units)
                     throws VisADException

  Constructs from the type of the reference coordinate system and units for values in this coordinate system. Subclasses must supply reference type and units.

Parameters:
  `reference` - The type of the reference coordinate system. Numeric values in the reference coordinate system shall be in units of `reference.getDefaultUnits()` unless specified otherwise.
  `units` - The default units for this coordinate system. Numeric values in this coordinate system shall be in units of `units` unless specified otherwise. May be `null` or an array of `null`s.
Throws:
  `VisADException` - Couldn't create necessary VisAD object.

### CoordinateSystem

    CoordinateSystem(RealTupleType reference,
                     Unit[] units,
                     boolean b)

  trusted constructor for initializers (does not throw any declared Exceptions)

Parameters:
  `reference` - The type of the reference coordinate system. Numeric values in the reference coordinate system shall be in units of `reference.getDefaultUnits()` unless specified otherwise.
  `units` - The default units for this coordinate system. Numeric values in this coordinate system shall be in units of `units` unless specified otherwise. May be `null` or an array of `null`s.
  `b` - dummy argument for trusted constructor signature

Method Detail

### getReference

    public RealTupleType getReference()

  Return the reference RealTupleType for this CoordinateSystem.

  Returns:
    reference RealTupleType

### getDimension

    public int getDimension()

  Return the number of components in the reference RealTupleType.

  Returns:
    dimension of the reference.

### getReferenceUnits

    public Unit[] getReferenceUnits()

  Return the Units for this CoordinateSystem's reference RealTupleType. These are the units of the return values from `toReference(double[][])`.

  Returns:
    copy of the Units array used at construction.

### getCoordinateSystemUnits

    public Unit[] getCoordinateSystemUnits()

  Return the Units for this CoordinateSystem. The Units are what's expected for the input data for the `toReference(double[][])` method.

  Returns:
    copy of the Units array used at construction.

### toReference

    public abstract double[][] toReference(double[][] value)
                                    throws VisADException

  Convert RealTuple values to Reference coordinates; for efficiency, input and output values are passed as double[][] arrays rather than RealTuple[] arrays; the array organization is double[tuple_dimension][number_of_tuples]; can modify and return argument array.

  Parameters:
    `value` - array of values assumed to be in coordinateSystem units. Input array is not guaranteed to be immutable and could be used for return.
  Returns:
    array of double values in reference coordinates and Units.
  Throws:
    `VisADException` - if problem with conversion.

### fromReference

    public abstract double[][] fromReference(double[][] value)
                                      throws VisADException

  Convert RealTuple values from Reference coordinates; for efficiency, input and output values are passed as double[][] arrays rather than RealTuple[] arrays; the array organization is double[tuple_dimension][number_of_tuples]; can modify and return argument array.

  Parameters:
    `value` - array of values assumed to be in reference Units. Input array is not guaranteed to be immutable and could be used for return.
  Returns:
    array of double values in CoordinateSystem Units.
  Throws:
    `VisADException` - if problem with conversion.

### toReference

    public float[][] toReference(float[][] value)
                          throws VisADException

  Convert RealTuple values to Reference coordinates; for efficiency, input and output values are passed as float[][] arrays rather than RealTuple[] arrays; the array organization is float[tuple_dimension][number_of_tuples]; can modify and return argument array. This implementation converts the input array to doubles and calls `toReference(double[][])` and then returns that converted double array back as a float array. For efficiency, subclasses should override this implementation.

  Parameters:
    `value` - array of values assumed to be in coordinateSystem units. Input array is not guaranteed to be immutable and could be used for return.
  Returns:
    array of float values in reference coordinates and Units.
  Throws:
    `VisADException` - if problem with conversion.

### fromReference

    public float[][] fromReference(float[][] value)
                            throws VisADException

  Convert RealTuple values from Reference coordinates; for efficiency, input and output values are passed as float[][] arrays rather than RealTuple[] arrays; the array organization is float[tuple_dimension][number_of_tuples]; can modify and return argument array. This implementation converts the input array to doubles and calls `toReference(double[][])` and then returns that converted double array back as a float array. For efficiency, subclasses should override this implementation.

  Parameters:
    `value` - array of values assumed to be in reference Units. Input array is not guaranteed to be immutable and could be used for return.
  Returns:
    array of float values in this CoordinateSystem Units.
  Throws:
    `VisADException` - if problem with conversion.

### canConvert

    public static boolean canConvert(RealTupleType out,
                                     CoordinateSystem coord_out,
                                     RealTupleType in,
                                     CoordinateSystem coord_in)

  Check to see if a conversion can be done between values of one RealTupleType and another given the CoordinateSystems supplied.

  Parameters:
    `out` - The output `RealTupleType`.
    `coord_out` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `in` - The input `RealTupleType`.
    `coord_in` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
  Returns:
    true if conversion is possible.

### transformCoordinates

    public static double[][] transformCoordinates(RealTupleType out,
                                                  CoordinateSystem coord_out,
                                                  Unit[] units_out,
                                                  ErrorEstimate[] errors_out,
                                                  RealTupleType in,
                                                  CoordinateSystem coord_in,
                                                  Unit[] units_in,
                                                  ErrorEstimate[] errors_in,
                                                  double[][] value)
                                           throws VisADException

  Transforms double-valued coordinates between two `RealTupleType`s. Unit conversion is always performed even if no coordinate transformation is done.

  This implementation uses `transformCoordinatesFreeUnits(visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], double[][])` to do most of the transformation.

  If both `RealTupleType`s have a reference coordinate system, then this implementation always transforms the input domain values by first transforming them according to the input reference coordinate system and then inverse transforming them according to the output reference coordinate system -- even if the input and output `RealTupleType`s are equal.

  Parameters:
    `out` - The output `RealTupleType`.
    `coord_out` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_out` - The output units.
    `errors_out` - The output error estimates or `null`.
    `in` - The input `RealTupleType`.
    `coord_in` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_in` - The input units or `null`.
    `errors_in` - The input error estimates or `null`.
    `value` - The input coordinate values. `value[i][j]` is the `j`-th sample of the `i`-th component. The values might be modified upon return from this method.
  Returns:
    The transformed coordinate values not in the input array.
  Throws:
    `VisADException` - if a VisAD failure occurs.
    `NullPointerException` - if `units_out` is `null`.

### transformCoordinates

    public static double[][] transformCoordinates(RealTupleType out,
                                                  CoordinateSystem coord_out,
                                                  Unit[] units_out,
                                                  ErrorEstimate[] errors_out,
                                                  RealTupleType in,
                                                  CoordinateSystem coord_in,
                                                  Unit[] units_in,
                                                  ErrorEstimate[] errors_in,
                                                  double[][] value,
                                                  boolean copy)
                                           throws VisADException

  Transforms double-valued coordinates between two `RealTupleType`s. Unit conversion is always performed even if no coordinate transformation is done.

  This implementation uses `transformCoordinatesFreeUnits(visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], double[][])` to do most of the transformation.

  If both `RealTupleType`s have a reference coordinate system, then this implementation always transforms the input domain values by first transforming them according to the input reference coordinate system and then inverse transforming them according to the output reference coordinate system -- even if the input and output `RealTupleType`s are equal.

  Parameters:
    `out` - The output `RealTupleType`.
    `coord_out` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_out` - The output units.
    `errors_out` - The output error estimates or `null`.
    `in` - The input `RealTupleType`.
    `coord_in` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_in` - The input units or `null`.
    `errors_in` - The input error estimates or `null`.
    `value` - The input coordinate values. `value[i][j]` is the `j`-th sample of the `i`-th component. The values might be modified upon return from this method.
    `copy` - if false, the underlying `value` array transformations may be done in place.
  Returns:
    The transformed coordinate values not in the input array, if copy is true.
  Throws:
    `VisADException` - if a VisAD failure occurs.
    `NullPointerException` - if `units_out` is `null`.

### transformCoordinatesFreeUnits

    public static double[][] transformCoordinatesFreeUnits(RealTupleType out,
                                                           CoordinateSystem coord_out,
                                                           Unit[] units_out,
                                                           ErrorEstimate[] errors_out,
                                                           RealTupleType in,
                                                           CoordinateSystem coord_in,
                                                           Unit[] units_in,
                                                           ErrorEstimate[] errors_in,
                                                           double[][] value)
                                                    throws VisADException

  Transforms double-valued coordinates between two `RealTupleType`s. This is just like `transformCoordinates(visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], double[][])`, except that final Unit conversion to `units_out` is not done; rather, `units_out[i]` is set to the final `Unit` of `value[i]`.

  If both `RealTupleType`s have a reference coordinate system, then this implementation always transforms the input domain values by first transforming them according to the input reference coordinate system and then inverse transforming them according to the output reference coordinate system -- even if the input and output `RealTupleType`s are equal.

  Parameters:
    `out` - The output `RealTupleType`.
    `coord_out` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_out` - The output units or `null`.
    `errors_out` - The output error estimates or `null`.
    `in` - The input `RealTupleType`.
    `coord_in` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_in` - The input units or `null`.
    `errors_in` - The input error estimates or `null`.
    `value` - The input coordinate values. `value[i][j]` is the `j`-th sample of the `i`-th component.
  Returns:
    The transformed coordinate values. Possibly in the input array.
  Throws:
    `VisADException` - if a VisAD failure occurs.

### transformCoordinates

    public static float[][] transformCoordinates(RealTupleType out,
                                                 CoordinateSystem coord_out,
                                                 Unit[] units_out,
                                                 ErrorEstimate[] errors_out,
                                                 RealTupleType in,
                                                 CoordinateSystem coord_in,
                                                 Unit[] units_in,
                                                 ErrorEstimate[] errors_in,
                                                 float[][] value)
                                          throws VisADException

  Transforms float-valued coordinates between two `RealTupleType`s. Unit conversion is always performed even if no coordinate transformation is done.

  This implementation uses `transformCoordinatesFreeUnits(visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], double[][])` to do most of the transformation.

  If both `RealTupleType`s have a reference coordinate system, then this implementation always transforms the input domain values by first transforming them according to the input reference coordinate system and then inverse transforming them according to the output reference coordinate system -- even if the input and output `RealTupleType`s are equal.

  Parameters:
    `out` - The output `RealTupleType`.
    `coord_out` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_out` - The output units.
    `errors_out` - The output error estimates or `null`.
    `in` - The input `RealTupleType`.
    `coord_in` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_in` - The input units or `null`.
    `errors_in` - The input error estimates or `null`.
    `value` - The input coordinate values. `value[i][j]` is the `j`-th sample of the `i`-th component. The values might be modified upon return from this method.
  Returns:
    The transformed coordinate values not in the input array.
  Throws:
    `VisADException` - if a VisAD failure occurs.
    `NullPointerException` - if `units_out` is `null`.

### transformCoordinates

    public static float[][] transformCoordinates(RealTupleType out,
                                                 CoordinateSystem coord_out,
                                                 Unit[] units_out,
                                                 ErrorEstimate[] errors_out,
                                                 RealTupleType in,
                                                 CoordinateSystem coord_in,
                                                 Unit[] units_in,
                                                 ErrorEstimate[] errors_in,
                                                 float[][] value,
                                                 boolean copy)
                                          throws VisADException

  Transforms float-valued coordinates between two `RealTupleType`s. Unit conversion is always performed even if no coordinate transformation is done.

  This implementation uses `transformCoordinatesFreeUnits(visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], double[][])` to do most of the transformation.

  If both `RealTupleType`s have a reference coordinate system, then this implementation always transforms the input domain values by first transforming them according to the input reference coordinate system and then inverse transforming them according to the output reference coordinate system -- even if the input and output `RealTupleType`s are equal.

  Parameters:
    `out` - The output `RealTupleType`.
    `coord_out` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_out` - The output units.
    `errors_out` - The output error estimates or `null`.
    `in` - The input `RealTupleType`.
    `coord_in` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_in` - The input units or `null`.
    `errors_in` - The input error estimates or `null`.
    `value` - The input coordinate values. `value[i][j]` is the `j`-th sample of the `i`-th component. The values might be modified upon return from this method.
    `copy` - if false, the underlying `value` array transformations may be done in place.
  Returns:
    The transformed coordinate values not in the input array, if copy is true.
  Throws:
    `VisADException` - if a VisAD failure occurs.
    `NullPointerException` - if `units_out` is `null`.

### transformCoordinatesFreeUnits

    public static float[][] transformCoordinatesFreeUnits(RealTupleType out,
                                                          CoordinateSystem coord_out,
                                                          Unit[] units_out,
                                                          ErrorEstimate[] errors_out,
                                                          RealTupleType in,
                                                          CoordinateSystem coord_in,
                                                          Unit[] units_in,
                                                          ErrorEstimate[] errors_in,
                                                          float[][] value)
                                                   throws VisADException

  Transforms float-valued coordinates between two `RealTupleType`s. This is just like `transformCoordinates(visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], visad.RealTupleType, visad.CoordinateSystem, visad.Unit[], visad.ErrorEstimate[], double[][])`, except that final Unit conversion to `units_out` is not done; rather, `units_out[i]` is set to the final `Unit` of `value[i]`.

  If both `RealTupleType`s have a reference coordinate system, then this implementation always transforms the input domain values by first transforming them according to the input reference coordinate system and then inverse transforming them according to the output reference coordinate system -- even if the input and output `RealTupleType`s are equal.

  Parameters:
    `out` - The output `RealTupleType`.
    `coord_out` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_out` - The output units or `null`.
    `errors_out` - The output error estimates or `null`.
    `in` - The input `RealTupleType`.
    `coord_in` - The coordinate system transformation associated with the output `RealTupleType` or `null`.
    `units_in` - The input units or `null`.
    `errors_in` - The input error estimates or `null`.
    `value` - The input coordinate values. `value[i][j]` is the `j`-th sample of the `i`-th component.
  Returns:
    The transformed coordinate values. Possibly in the input array.
  Throws:
    `VisADException` - if a VisAD failure occurs.

### toReference

    public double[][] toReference(double[][] value,
                                  Unit[] units)
                           throws VisADException

  Convert values in Units specified to Reference coordinates. If units are non-null, they are both the Unit[] of input value, and a holder for Unit[] of output.

  Parameters:
    `value` - array of values assumed to be in the Units specified or CoordinateSystem units if null.
    `units` - Units of input values. If non-null, input values are converted to CoordinateSystem Units (if they are non-null) before calling `toReference(double[][])`.
  Returns:
    array of double values in reference coordinates and Units.
  Throws:
    `VisADException` - if problem with conversion.

### toReference

    public float[][] toReference(float[][] value,
                                 Unit[] units)
                          throws VisADException

  Convert values in Units specified to Reference coordinates. If units are non-null, they are both the Unit[] of input value, and a holder for Unit[] of output.

  Parameters:
    `value` - array of values assumed to be in the Units specified or CoordinateSystem units if null.
    `units` - Units of input values. If non-null, input values are converted to CoordinateSystem Units (if they are non-null) before calling `toReference(float[][])`.
  Returns:
    array of float values in reference coordinates and Units.
  Throws:
    `VisADException` - if problem with conversion.

### fromReference

    public double[][] fromReference(double[][] value,
                                    Unit[] units)
                             throws VisADException

  Convert values in Units specified to this CoordinateSystem's Units. If units are non-null, they are both the Unit[] of input value, and a holder for Unit[] of output.

  Parameters:
    `value` - array of values assumed to be in the Units specified or Reference units if null.
    `units` - Units of input values. If non-null, input values are converted to Reference Units (if they are non-null) before calling `fromReference(double[][])`.
  Returns:
    array of double values in CoordinateSystem Units.
  Throws:
    `VisADException` - if problem with conversion.

### fromReference

    public float[][] fromReference(float[][] value,
                                   Unit[] units)
                            throws VisADException

  Convert values in Units specified to this CoordinateSystem's Units. If units are non-null, they are both the Unit[] of input value, and a holder for Unit[] of output.

  Parameters:
    `value` - array of values assumed to be in the Units specified or Reference units if null.
    `units` - Units of input values. If non-null, input values are converted to Reference Units (if they are non-null) before calling `fromReference(float[][])`.
  Returns:
    array of float values in CoordinateSystem Units.
  Throws:
    `VisADException` - if problem with conversion.

### equals

    public abstract boolean equals(Object cs)

  Indicates whether or not this instance is equal to an object (note must test for cs == null).

  Parameters:
    `cs` - the object in question.
  Returns:
    `true` if and only if this instance equals cs.