ucar.nc2.dataset
Class CoordinateSystem

java.lang.Object
  extended by ucar.nc2.dataset.CoordinateSystem

public class CoordinateSystem
extends java.lang.Object

A CoordinateSystem specifies the coordinates of a Variable's values. Mathmatically it is a vector function F from index space to Sn:

  F(i,j,k,...) -> (S1, S2, ...Sn)
  where i,j,k are integers, and S is the set of reals (R) or Strings.
 
The components of F are just its coordinate axes:
  F = (A1, A2, ...An)
    A1(i,j,k,...) -> S1
    A2(i,j,k,...) -> S1
    An(i,j,k,...) -> Sn
 
Concretely, a CoordinateSystem is a set of coordinate axes, and an optional set of coordinate transforms. The domain rank of F is the number of dimensions it is a function of. The range rank is the number of coordinate axes.

An important class of CoordinateSystems are georeferencing Coordinate Systems, that locate a Variable's values in space and time. A CoordinateSystem that has a Lat and Lon axis, or a GeoX and GeoY axis and a Projection CoordinateTransform will have isGeoReferencing() true. A CoordinateSystem that has a Height, Pressure, or GeoZ axis will have hasVerticalAxis() true.

Further CoordinateSystems specialization is done by "data type specific" clasess such as ucar.nc2.dt.grid.GridCoordSys.

Author:
caron
See Also:
Coordinate System Object Model

Constructor Summary
CoordinateSystem(NetcdfDataset ds, java.util.Collection<CoordinateAxis> axes, java.util.Collection<CoordinateTransform> coordTrans)
          Constructor.
 
Method Summary
 void addCoordinateTransform(CoordinateTransform ct)
          add a CoordinateTransform
 void addCoordinateTransforms(java.util.Collection<CoordinateTransform> ct)
          add a Collection of CoordinateTransform
 boolean containsAxes(java.util.List<CoordinateAxis> wantAxes)
          Do we have all the axes in the list?
 boolean containsAxis(java.lang.String axisName)
          Do we have the named axis?
 boolean containsAxisType(AxisType wantAxisType)
          Do we have an axes of the given type?
 boolean containsAxisTypes(java.util.List<AxisType> wantAxes)
          Do we have all the axes types in the list?
 boolean containsDomain(java.util.List<Dimension> wantDimensions)
          Do we have all the dimensions in the list?
 boolean equals(java.lang.Object oo)
          Instances which have same name are equal.
 CoordinateAxis findAxis(AxisType type)
          Find the CoordinateAxis that has the given AxisType.
 CoordinateAxis getAzimuthAxis()
          get the CoordinateAxis with AxisType.RadialAzimuth, or null if none.
 java.util.List<CoordinateAxis> getCoordinateAxes()
          get the List of CoordinateAxis objects
 java.util.List<CoordinateTransform> getCoordinateTransforms()
          get the List of CoordinateTransform objects
 java.util.List<Dimension> getDomain()
          List of Dimensions that constitute the domain.
 CoordinateAxis getElevationAxis()
          get the CoordinateAxis with AxisType.RadialElevation, or null if none.
 CoordinateAxis getHeightAxis()
          get the CoordinateAxis with AxisType.Height, or null if none.
 CoordinateAxis getLatAxis()
          get the CoordinateAxis with AxisType.Lat, or null if none.
 CoordinateAxis getLonAxis()
          get the CoordinateAxis with AxisType.Lon, or null if none.
 java.lang.String getName()
          get the name of the Coordinate System
 NetcdfDataset getNetcdfDataset()
          Get the underlying NetcdfDataset
 CoordinateAxis getPressureAxis()
          get the CoordinateAxis with AxisType.Pressure, or null if none.
 ProjectionImpl getProjection()
          Get the Projection for this coordinate system.
 ProjectionCT getProjectionCT()
          Find the first ProjectionCT from the list of CoordinateTransforms.
 CoordinateAxis getRadialAxis()
          get the CoordinateAxis with AxisType.RadialDistance, or null if none.
 int getRankDomain()
          Get the domain rank of the coordinate system = number of dimensions it is a function of.
 int getRankRange()
          Get the range rank of the coordinate system = number of coordinate axes.
 CoordinateAxis getTaxis()
          get the CoordinateAxis with AxisType.Time, or null if none.
 CoordinateAxis getXaxis()
          get the CoordinateAxis with AxisType.GeoX, or null if none.
 CoordinateAxis getYaxis()
          get the CoordinateAxis with AxisType.GeoY, or null if none.
 CoordinateAxis getZaxis()
          get the CoordinateAxis with AxisType.GeoZ, or null if none.
 int hashCode()
          Override Object.hashCode() to implement equals.
 boolean hasTimeAxis()
          true if has Time axis
 boolean hasVerticalAxis()
          true if has Height, Pressure, or GeoZ axis
 boolean isComplete(VariableIF v)
          Check if this Coordinate System is complete, ie if all its dimensions are also used by the Variable.
 boolean isCoordinateSystemFor(VariableIF v)
          Check if this Coordinate System can be used for the given variable.
 boolean isGeoReferencing()
          true if isGeoXY or isLatLon
 boolean isGeoXY()
          true if it has X and Y CoordinateAxis, and a CoordTransform Projection
 boolean isImplicit()
          Implicit Coordinate System are constructed based on which Coordinate Variables exist for the Dimensions of the Variable.
 boolean isLatLon()
          true if it has Lat and Lon CoordinateAxis
 boolean isProductSet()
          true if all axes are CoordinateAxis1D
 boolean isRadial()
          true if it has radial distance and azimuth CoordinateAxis
 boolean isRegular()
          true if all axes are CoordinateAxis1D and are regular
static boolean isSubset(java.util.List<Dimension> subset, java.util.List<Dimension> set)
          Test if all the Dimensions in subset are in set
static java.util.List<Dimension> makeDomain(Variable[] axes)
           
static java.lang.String makeName(java.util.List<CoordinateAxis> axes)
          Create standard name from list of axes.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CoordinateSystem

public CoordinateSystem(NetcdfDataset ds,
                        java.util.Collection<CoordinateAxis> axes,
                        java.util.Collection<CoordinateTransform> coordTrans)
Constructor.

Parameters:
ds - the containing dataset
axes - Collection of type CoordinateAxis, must be at least one.
coordTrans - Collection of type CoordinateTransform, may be empty or null.
Method Detail

makeName

public static java.lang.String makeName(java.util.List<CoordinateAxis> axes)
Create standard name from list of axes. Sort the axes first

Parameters:
axes - list of CoordinateAxis
Returns:
CoordinateSystem name, created from axes names

addCoordinateTransform

public void addCoordinateTransform(CoordinateTransform ct)
add a CoordinateTransform

Parameters:
ct - add this CoordinateTransform

addCoordinateTransforms

public void addCoordinateTransforms(java.util.Collection<CoordinateTransform> ct)
add a Collection of CoordinateTransform

Parameters:
ct - add all CoordinateTransform in this collection

getCoordinateAxes

public java.util.List<CoordinateAxis> getCoordinateAxes()
get the List of CoordinateAxis objects

Returns:
the List of CoordinateAxis objects

getCoordinateTransforms

public java.util.List<CoordinateTransform> getCoordinateTransforms()
get the List of CoordinateTransform objects

Returns:
the List of CoordinateTransform objects

getName

public java.lang.String getName()
get the name of the Coordinate System

Returns:
the name of the Coordinate System

getNetcdfDataset

public NetcdfDataset getNetcdfDataset()
Get the underlying NetcdfDataset

Returns:
the underlying NetcdfDataset.

getDomain

public java.util.List<Dimension> getDomain()
List of Dimensions that constitute the domain.

Returns:
the List of Dimensions that constitute the domain.

getRankDomain

public int getRankDomain()
Get the domain rank of the coordinate system = number of dimensions it is a function of.

Returns:
domain.size()

getRankRange

public int getRankRange()
Get the range rank of the coordinate system = number of coordinate axes.

Returns:
coordAxes.size()

findAxis

public CoordinateAxis findAxis(AxisType type)
Find the CoordinateAxis that has the given AxisType. If more than one, return the one with lesser rank.

Parameters:
type - look for this axisType
Returns:
CoordinateAxis of the given AxisType, else null.

getXaxis

public CoordinateAxis getXaxis()
get the CoordinateAxis with AxisType.GeoX, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.GeoX, or null if none

getYaxis

public CoordinateAxis getYaxis()
get the CoordinateAxis with AxisType.GeoY, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.GeoY, or null if none

getZaxis

public CoordinateAxis getZaxis()
get the CoordinateAxis with AxisType.GeoZ, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.GeoZ, or null if none

getTaxis

public CoordinateAxis getTaxis()
get the CoordinateAxis with AxisType.Time, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.Time, or null if none

getLatAxis

public CoordinateAxis getLatAxis()
get the CoordinateAxis with AxisType.Lat, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.Lat, or null if none

getLonAxis

public CoordinateAxis getLonAxis()
get the CoordinateAxis with AxisType.Lon, or null if none. if more than one, choose one with smallest rank *

Returns:
axis of type AxisType.Lon, or null if none

getHeightAxis

public CoordinateAxis getHeightAxis()
get the CoordinateAxis with AxisType.Height, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.Height, or null if none

getPressureAxis

public CoordinateAxis getPressureAxis()
get the CoordinateAxis with AxisType.Pressure, or null if none. if more than one, choose one with smallest rank.

Returns:
axis of type AxisType.Pressure, or null if none

getAzimuthAxis

public CoordinateAxis getAzimuthAxis()
get the CoordinateAxis with AxisType.RadialAzimuth, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.RadialAzimuth, or null if none

getRadialAxis

public CoordinateAxis getRadialAxis()
get the CoordinateAxis with AxisType.RadialDistance, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.RadialDistance, or null if none

getElevationAxis

public CoordinateAxis getElevationAxis()
get the CoordinateAxis with AxisType.RadialElevation, or null if none. if more than one, choose one with smallest rank

Returns:
axis of type AxisType.RadialElevation, or null if none

getProjectionCT

public ProjectionCT getProjectionCT()
Find the first ProjectionCT from the list of CoordinateTransforms.

Returns:
ProjectionCT or null if none.

getProjection

public ProjectionImpl getProjection()
Get the Projection for this coordinate system. If isLatLon(), then returns a LatLonProjection. Otherwise, extracts the projection from any ProjectionCT CoordinateTransform.

Returns:
ProjectionImpl or null if none.

isGeoXY

public boolean isGeoXY()
true if it has X and Y CoordinateAxis, and a CoordTransform Projection

Returns:
true if it has X and Y CoordinateAxis, and a CoordTransform Projection

isLatLon

public boolean isLatLon()
true if it has Lat and Lon CoordinateAxis

Returns:
true if it has Lat and Lon CoordinateAxis

isRadial

public boolean isRadial()
true if it has radial distance and azimuth CoordinateAxis

Returns:
true if it has radial distance and azimuth CoordinateAxis

isGeoReferencing

public boolean isGeoReferencing()
true if isGeoXY or isLatLon

Returns:
true if isGeoXY or isLatLon

isProductSet

public boolean isProductSet()
true if all axes are CoordinateAxis1D

Returns:
true if all axes are CoordinateAxis1D

isRegular

public boolean isRegular()
true if all axes are CoordinateAxis1D and are regular

Returns:
true if all axes are CoordinateAxis1D and are regular

isComplete

public boolean isComplete(VariableIF v)
Check if this Coordinate System is complete, ie if all its dimensions are also used by the Variable.

Parameters:
v - check for this variable
Returns:
true if all dimensions in V (including parents) are in the domain of this coordinate system.

isCoordinateSystemFor

public boolean isCoordinateSystemFor(VariableIF v)
Check if this Coordinate System can be used for the given variable. A CoordinateAxis can only be part of a Variable's CoordinateSystem if the CoordinateAxis' set of Dimensions is a subset of the Variable's set of Dimensions. So, a CoordinateSystem' set of Dimensions must be a subset of the Variable's set of Dimensions.

Parameters:
v - check for this variable
Returns:
true if all dimensions in the domain of this coordinate system are in V (including parents).

isSubset

public static boolean isSubset(java.util.List<Dimension> subset,
                               java.util.List<Dimension> set)
Test if all the Dimensions in subset are in set

Parameters:
subset - is this a subset
set - of this?
Returns:
true if all the Dimensions in subset are in set

makeDomain

public static java.util.List<Dimension> makeDomain(Variable[] axes)

isImplicit

public boolean isImplicit()
Implicit Coordinate System are constructed based on which Coordinate Variables exist for the Dimensions of the Variable. This is in contrast to a Coordinate System that is explicitly specified in the file.

Returns:
true if this coordinate system was constructed implicitly.

hasVerticalAxis

public boolean hasVerticalAxis()
true if has Height, Pressure, or GeoZ axis

Returns:
true if has a vertical axis

hasTimeAxis

public boolean hasTimeAxis()
true if has Time axis

Returns:
true if has Time axis

containsAxes

public boolean containsAxes(java.util.List<CoordinateAxis> wantAxes)
Do we have all the axes in the list?

Parameters:
wantAxes - List of CoordinateAxis
Returns:
true if all in our list.

containsAxis

public boolean containsAxis(java.lang.String axisName)
Do we have the named axis?

Parameters:
axisName - (full) name of axis
Returns:
true if we have an axis of that name

containsDomain

public boolean containsDomain(java.util.List<Dimension> wantDimensions)
Do we have all the dimensions in the list?

Parameters:
wantDimensions - List of Dimensions
Returns:
true if all in our list.

containsAxisTypes

public boolean containsAxisTypes(java.util.List<AxisType> wantAxes)
Do we have all the axes types in the list?

Parameters:
wantAxes - List of AxisType
Returns:
true if all in our list.

containsAxisType

public boolean containsAxisType(AxisType wantAxisType)
Do we have an axes of the given type?

Parameters:
wantAxisType - want this AxisType
Returns:
true if we have at least one axis of that type.

equals

public boolean equals(java.lang.Object oo)
Instances which have same name are equal.

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Override Object.hashCode() to implement equals.

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object