Coordinate System Object Model

To understand the Coordinate System Object Model, we first review the basic NetCDF Object Model. This diagram reflects the names in the NetCDF-Java library, but is applicable to any NetCDF file, or language library:

Fig 1. NetCDF-3 Object Model

So, a netCDF Dataset (aka netCDF file) is a collection of Variables, Dimensions, and global Attributes, which can be discovered when the dataset is opened. An Attribute is a key/value pair. A Dimension is a named array length. A Variable is a container for variable Attributes, and for the data itself, which is obtained by calling the read() method. The data is a multidimensional array of primitives, of a type listed in DataType-3. The shape of the data is specified through an array of references to Dimension objects, which are always global in scope.

Coordinate Systems are additional semantics built on top of the basic Netcdf Object Model:

Fig 2. Coordinate System Object Model

So, a Variable can have zero or more Coordinate Systems. A Coordinate System consists of a list of one or more CoordinateAxis, and zero or more CoordinateTransforms. A CoordinateAxis is a subtype of Variable, and is optionally classified according to the types in AxisType. A CoordinateTransform abstractly represents a transformation between CoordinateSystems, and currently is either a Projection or a Vertical Transform.

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. This ensures that every data point in the Variable has a corresponding coordinate value for each of the CoordinateAxis in the CoordinateSystem.

Formally, a Variable is thought of as a sampled function whose domain is an index range; each CoordinateAxis is a scalar valued function on the same range; each CoordinateSystem is therefore a vector-valued function on the same range consisting of its CoordinateAxis functions. To take it one step further, when the CoordinateSystem function is invertible, the Variable can be thought of as a sampled function whose domain is the range of the Coordinate System, that is on Rn (the product space of real numbers). To be invertible, each CoordinateAxis should be invertible. For a 1-dimensional CoordinateAxis this simply means the coordinate values are strictly monotonic. For a 2 dimensional CoordinateAxis, it means that the lines connecting adjacent coordinates do not cross each other. For > 2 dimensional CoordinateAxis, it means that the surfaces connecting the adjacent coordinates do not intersect each other.

The AxisType enumerations are specific to the case of georeferencing coordinate systems. Time refers to the real date/time of the dataset. Latitude and Longitude identify standard horizontal coordinates. Height and Pressure identify the vertical coordinate. GeoX and GeoY are used in transfomations (eg projections) to Latitude, Longitude. GeoZ is used in vertical transformations to vertical Height or Pressure. RadialAzimuth, RadialElevation and RadialDistance designate polar coordinates and are used for Radial DataTypes. RunTime and Ensemble are used in forecast model output data. Often much more detailed information is required (geoid reference, projection parameters, etc), so these enumerations are quite minimal.

Current Encodings

NetCDF has long had the convention of specifying a 1-dimensional CoordinateAxis with a coordinate variable, which is a Variable with the same name as its single dimension. This is a natural and elegant way to specify a 1-dimensional CoordinateAxis, since there is an automatic association of the Coordinate Variable with any Varaible that uses its dimension. Unfortunately there are not similarly elegant ways to specify a multidimensional CoordinateAxis, and so various attribute conventions have sprung up, that typically list the CoordinateAxis variables, for exaple the CF-1.0 Convention::

  float lat(y,x);
  float lon(y,x);
  float temperature(y,x);
    temperature:coordinates="lat lon";

Note that in this example, there is no CoordinateSystem object, so the same list has to be added to each Variable, and any CoordinateTransform specifications also have to be added to each Variable. However, the common case is that all the Variables in a NetCDF file use the same Coordinate System.

The ucar.nc2.dataset layer reads various Conventions and extracts the Coordinate Systems using the CoordSysBuilder framework. We often use a set of internal attributes called the "underscore Coordinate" attributes as a way to standardize the Coordinate Systems infomation.

The AxisType enumerations are essential to getting georeferencing coordinate systems unambiguously identified. If units are also supplied for each CoordinateAxis, this information alone is often sufficient for georeferencing the data, at least in a "quick look" situation where precision is not essential.

CoordinateTransforms tend to be complex and discipline-specific. The NetCDF-Java library provides a generic framework for describing needed parameters and their values, plus a way to register third-party implementations at runtime. In addition, we support most of the projections and vertical transformations specified in the CF-1.0 Convention.

This document is maintained by John Caron and was last updated on Oct 18, 2006

				Unidata is a member of the UCAR Office of Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation.
				P.O. Box 3000 • Boulder, CO 80307-3000 USA • Tel: 303-497-8643 • Fax: 303-497-8690