visad
Class CoordinateSystem

java.lang.Object
  visad.CoordinateSystem

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

AlbersCoordinateSystem, CachingCoordinateSystem, CartesianProductCoordinateSystem, CMYCoordinateSystem, CylindricalCoordinateSystem, EmpiricalCoordinateSystem, 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.

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

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

Throws:

VisADException - Couldn't create necessary VisAD object.

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

Overrides:

equals in class Object

Parameters:

cs - the object in question.

Returns:

true if and only if this instance equals cs.