org.geotoolkit.referencing.adapters
Class NetcdfCRS

Object
  NetcdfIdentifiedObject
      NetcdfCRS

All Implemented Interfaces:

GridGeometry, Identifier, CoordinateReferenceSystem, CoordinateSystem, IdentifiedObject, ReferenceIdentifier, ReferenceSystem

public class NetcdfCRS
extends NetcdfIdentifiedObject
implements CoordinateReferenceSystem, CoordinateSystem, GridGeometry

Wraps a NetCDF CoordinateSystem as an implementation of GeoAPI interfaces. This class implements both the GeoAPI CoordinateSystem and CoordinateReferenceSystem interfaces because the NetCDF CoordinateSystem object combines the concepts of both of them. It also implements the GridGeometry interface since NetCDF Coordinate Systems contain all information related to the image grid.

Axis order
The order of axes returned by getAxis(int) is reversed compared to the order of axes in the wrapped NetCDF coordinate system. This is because the NetCDF convention stores axes in the (time, height, latitude, longitude) order, while the Geotk referencing framework typically uses the (longitude, latitude, height, time) order.

Regular axes
While not mandatory, the Geotk Image I/O framework behaves better if the NetCDF axes are regular. Irregular axes can sometime be made regular by changing the Coordinate Reference System. The regularize() method attempts to convert some kind of CRS to other kinds of CRS (for example from geographic CRS to Mercator projection) and checks if the result is a regular grid.

Example: some NetCDF files contain data computed on a grid which was regular in the Mercator projection, but the file declare (longitude, latitude) axes for user "convenience", resulting in an irregular latitude axis. Projecting the longitudes and latitudes back to the Mercator projection gives back the regular grid.

Restrictions
Current implementation has the following restrictions:

• This class supports only axes of kind CoordinateAxis1D. Callers can verify this condition with a call to the CoordinateSystem.isProductSet() method on the wrapped NetCDF coordinate system, which shall returns true.

• At the time of writing, the NetCDF API doesn't specify the CRS datum. Consequently the current implementation assumes that all NetcdfCRS instances use the WGS84 geodetic datum.

• This class assumes that the list of NetCDF axes returned by CoordinateSystem.getCoordinateAxes() is stable during the lifetime of this NetcdfCRS instance.

Since:

3.08

Version:

3.20

Author:

Martin Desruisseaux (Geomatys)

See Also:

NetcdfImageReader

Module:

coverage/geotk-coverageio-netcdf (download)

View source code for this class

Field Summary

Fields inherited from interface ReferenceSystem

DOMAIN_OF_VALIDITY_KEY, SCOPE_KEY

Fields inherited from interface IdentifiedObject

ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY

Fields inherited from interface ReferenceIdentifier

CODESPACE_KEY, VERSION_KEY

Fields inherited from interface Identifier

AUTHORITY_KEY, CODE_KEY

Constructor Summary

protected

NetcdfCRS(CoordinateSystem netcdfCS) Creates a new NetcdfCRS object wrapping the given NetCDF coordinate system.

Method Summary

CoordinateSystem	delegate() Returns the wrapped NetCDF coordinate system.
NetcdfAxis	getAxis(int dimension) Returns the axis at the given dimension.
String	getCode() Returns the coordinate system name.
CoordinateSystem	getCoordinateSystem() Returns the coordinate system, which is this.
int	getDimension() Returns the number of dimensions.
Extent	getDomainOfValidity() Returns null since NetCDF coordinate systems don't specify their domain of validity.
GridEnvelope	getExtent() Returns the valid coordinate range of the NetCDF grid coordinates.
GridEnvelope	getGridRange() Deprecated. Renamed getExtent().
MathTransform	getGridToCRS() Returns the transform from grid coordinates to this CRS coordinates, or null if none.
MathTransform	getGridToCRS(int lowerDimension, int upperDimension) Returns the transform from grid coordinates to this CRS coordinates in the given range of dimensions.
InternationalString	getScope() Returns null since NetCDF coordinate systems don't specify their scope.
CoordinateReferenceSystem	regularize() Converts irregular axes to regular ones, if possible.
static NetcdfCRS	wrap(CoordinateSystem netcdfCS) Creates a new NetcdfCRS object wrapping the given NetCDF coordinate system.
static NetcdfCRS	wrap(CoordinateSystem netcdfCS, NetcdfDataset file, WarningProducer logger) Creates a new NetcdfCRS object, optionally using the given NetCDF file for additional information.

Methods inherited from class NetcdfIdentifiedObject

equals, getAlias, getAuthority, getCodeSpace, getIdentifiers, getName, getRemarks, getVersion, hashCode, toString, toWKT

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface IdentifiedObject

getAlias, getIdentifiers, getName, getRemarks, toWKT

Constructor Detail

NetcdfCRS

protected NetcdfCRS(CoordinateSystem netcdfCS)
             throws ClassCastException

Creates a new NetcdfCRS object wrapping the given NetCDF coordinate system. The CoordinateSystem.getCoordinateAxes() is invoked at construction time and every elements are assumed instances of CoordinateAxis1D.

Parameters:

netcdfCS - The NetCDF coordinate system to wrap.

Throws:

ClassCastException - If at least one axis is not an instance of the CoordinateAxis1D subclass.

Method Detail

wrap

public static NetcdfCRS wrap(CoordinateSystem netcdfCS)
                      throws ClassCastException

Creates a new NetcdfCRS object wrapping the given NetCDF coordinate system. The returned object may implement any of the ProjectedCRS, GeographicCRS VerticalCRS or TemporalCRS, depending on the axis types.

If the NetCDF object contains different kind of CRS, then the returned CRS will be an instance of CompoundCRS in which each component implements one of the above-cited interfaces.

If the NetCDF object contains axes of unknown type, then the returned CRS will not implement any of the above-cited interfaces.

Parameters:

netcdfCS - The NetCDF coordinate system to wrap, or null if none.

Returns:

A wrapper for the given object, or null if the argument was null.

Throws:

ClassCastException - If at least one axis is not an instance of the CoordinateAxis1D subclass.

wrap

public static NetcdfCRS wrap(CoordinateSystem netcdfCS,
                             NetcdfDataset file,
                             WarningProducer logger)
                      throws IOException,
                             ClassCastException

Creates a new NetcdfCRS object, optionally using the given NetCDF file for additional information. This method performs the same work than wrap(CoordinateSystem), except that more accurate coordinate axes may be created if a reference to the original dataset file is provided. This apply especially to CoordinateAxis1DTime.

Parameters:

netcdfCS - The NetCDF coordinate system to wrap, or null if none.

file - The originating dataset file, or null if none.

logger - An optional object where to log warnings, or null if none.

Returns:

A wrapper for the given object, or null if the netcdfCS argument was null.

Throws:

ClassCastException - If at least one axis is not an instance of the CoordinateAxis1D subclass.

IOException - If an I/O operation was needed and failed.

Since:

3.14

regularize

public CoordinateReferenceSystem regularize()

Converts irregular axes to regular ones, if possible. If this CRS contains a geographic component, and if the (longitude, latitude) axes of that component are irregular, then this method will try to project the axes to the Mercator projection and see if the result is regular. In such case, a new CRS with those regular axes is built and returned.

If this method can not improve the axes regularity, then this method returns this.

Returns:

A CRS with potentially some axes made regular, or this.

Since:

3.15

See Also:

DiscreteReferencingFactory

delegate

public CoordinateSystem delegate()

Returns the wrapped NetCDF coordinate system.

Note: The dimension of the returned NetCDF Coordinate System may be greater than the dimension of the GeoAPI CRS implemented by this object, because the NetCDF CS puts all axes in a single object while the GeoAPI CRS may splits the axes in various kind of CRS (GeographicCRS, VerticalCRS, TemporalCRS).

Specified by:

delegate in class NetcdfIdentifiedObject

Returns:

The wrapped NetCDF object on which operations are delegated.

getCode

public String getCode()

Returns the coordinate system name. The default implementation delegates to CoordinateSystem.getName().

Specified by:

getCode in interface Identifier

Specified by:

getCode in class NetcdfIdentifiedObject

See Also:

CoordinateSystem.getName()

getDimension

public int getDimension()

Returns the number of dimensions.

Specified by:

getDimension in interface CoordinateSystem

See Also:

CoordinateSystem.getRankRange()

getCoordinateSystem

public CoordinateSystem getCoordinateSystem()

Returns the coordinate system, which is this.

Specified by:

getCoordinateSystem in interface CoordinateReferenceSystem

getAxis

public NetcdfAxis getAxis(int dimension)
                   throws IndexOutOfBoundsException

Returns the axis at the given dimension. Note that the order of axes returned by this method is reversed compared to the order of axes in the NetCDF coordinate system. See the class javadoc for more information.

Specified by:

getAxis in interface CoordinateSystem

Parameters:

dimension - The zero based index of axis.

Returns:

The axis at the specified dimension.

Throws:

IndexOutOfBoundsException - if dimension is out of bounds.

See Also:

CoordinateSystem.getCoordinateAxes()

getExtent

public GridEnvelope getExtent()

Returns the valid coordinate range of the NetCDF grid coordinates. The lowest valid grid coordinate is zero.

Specified by:

getExtent in interface GridGeometry

Returns:

The valid coordinate range of a grid coverage.

Since:

3.20 (derived from 3.09)

getGridRange

@Deprecated
public GridEnvelope getGridRange()

Deprecated. Renamed getExtent().

Specified by:

getGridRange in interface GridGeometry

getGridToCRS

public MathTransform getGridToCRS()

Returns the transform from grid coordinates to this CRS coordinates, or null if none. The returned transform is often specialized in two ways:

• If the underlying NetCDF coordinate system is regular, then the returned transform implements the LinearTransform interface.
• If this CRS is regular and two-dimensional, then the returned transform is also an instance of Java2D AffineTransform.

Limitation
Current implementation can build a transform only for regular coordinate systems. A future implementation may be more general.

Specified by:

getGridToCRS in interface GridGeometry

Returns:

The transform from grid to this CRS, or null if none.

getGridToCRS

public MathTransform getGridToCRS(int lowerDimension,
                                  int upperDimension)

Returns the transform from grid coordinates to this CRS coordinates in the given range of dimensions. The returned transform is often specialized in two ways:

• If every NetCDF axes in the given range of dimensions are regular, then the returned transform implements the LinearTransform interface.
• If, in addition of the above, the range spans two dimensions (i.e. upperDimension - lowerDimension == 2), then the returned transform is also an instance of Java2D AffineTransform.

Limitation
Current implementation can build a transform only for regular axes. A future implementation may be more general.

Parameters:

lowerDimension - Index of the first dimension for which to get the transform.

upperDimension - Index after the last dimension for which to get the transform.

Returns:

The transform from grid to this CRS in the given range of dimensions, or null if none.

Throws:

IllegalArgumentException - If the given dimensions are not in the [0 … dimension] range.

getDomainOfValidity

public Extent getDomainOfValidity()

Returns null since NetCDF coordinate systems don't specify their domain of validity.

Specified by:

getDomainOfValidity in interface ReferenceSystem

getScope

public InternationalString getScope()

Returns null since NetCDF coordinate systems don't specify their scope.

Specified by:

getScope in interface ReferenceSystem