[Top] [Prev]

3.13 netCDF

HDF supports the netCDF data model and interface developed at the Unidata Program Center (UPC). Like HDF, netCDF is an interface to a library of data access programs that store and retrieve data. The file format developed at the UPC to support netCDF uses XDR (eXternal Data Representation), a non-proprietary external data representation developed by Sun Microsystems for describing and encoding data. Full documentation on netCDF and the Unidata netCDF interface is available at http://www.unidata.ucar.edu/packages/netcdf/.

The netCDF data model is interchangeable with the SDS data model in so far as it is possible to use the netCDF calling interface to place an SDS into an HDF file and conversely the SDS interface will read from an XDR-based netCDF file. Because the netCDF interface has not changed and netCDF files stored in XDR format are readable, existing netCDF programs and data are still usable, although programs will need to be relinked to the new library. However, there are important conceptual differences between the HDF and the netCDF data model that must be understood to effectively use HDF in working with netCDF data objects and to understand enhancements to the interface that will be included in the future to make the two APIs much more similar.

In the HDF model, when a multidimensional SDS is created by SDcreate, HDF data objects are also created that provide information about the individual dimensions - one for each dimension. Each SDS contains within its internal structure the array data as well as pointers to these dimensions. Each dimension is stored in a structure that is in the HDF file but separate from the SDS array.

If more than one SDS have the same dimension sizes, they may share dimensions by pointing to the same dimensions. This can be done in application programs by calling SDsetdimname to assign the same dimension name to all dimensions that are shared by several SDSs. For example, suppose you make the following sequence of calls for every SDS in a file:

	dim_id = SDgetdimid(sds_id, 0);
	ret = SDsetdimname(dim_id, "Lat");
	dim_id = SDgetdimid(sds_id, 1);
	ret = SDsetdimname(dim_id, "Long");
This will create a shared dimension named "Lat" that is associated with every SDS as the first dimension and a dimension named "Long" as the second dimension.

This same result is obtained differently in netCDF. Note that a netCDF "variable" is roughly the same as an HDF SDS. The netCDF interface requires application programs to define all dimensions, using ncdimdef, before defining variables. Those defined dimensions are then used to define variables in ncvardef. Each dimension is defined by a name and a size. All variables using the same dimension will have the same dimension name and dimension size.

Although the HDF SDS interface will read from and write to existing XDR-based netCDF files, HDF cannot be used to create XDR-based netCDF files.

There is currently no support for mixing HDF data objects that are not SDSs and netCDF data objects. For example, a raster image can exist in the same HDF file as a netCDF data object, but you must use one of the HDF raster image APIs to read the image and the HDF SD or netCDF interface to read the netCDF data object. The other HDF APIs are currently being modified to allow multifile access. Closer integration with the netCDF interface will probably be delayed until the end of that project.

3.13.1 HDF Interface vs. netCDF Interface

Existing netCDF applications can be used to read HDF files and existing HDF applications can be used to read XDR-based netCDF files. To read an HDF file using a netCDF application, the application must be recompiled using the HDF library. For example, recompiling the netCDF utility ncdump with HDF creates a utility that can dump scientific data sets from both HDF and XDR-based files. To read an XDR-based file using an HDF application, the application must be relinked to the HDF library.

The current version of HDF contains several APIs that support essentially the same data model:

The first three models can create, read, and write SDSs in HDF files. Both the SD and NC interfaces can read from and write to XDR-based netCDF files, but they cannot create them. This interoperability means that a single program may contain both SD and NC function calls and thus transparently read and write scientific data sets to HDF or XDR-based files.

The SD interface is the only HDF interface capable of accessing the XDR-based netCDF file format. The DFSD interface cannot access XDR-based files and can only access SDS arrays, dimension scales, and predefined attributes. A summary of file interoperability among the three interfaces is provided in Table 3AH.

TABLE 3AH - Summary of HDF and XDR File Compatibility for the HDF and netCDF APIs

Files Created by
DFSD interface
Files Created by
SD interface
Files Written by
NC Interface

HDF
HDF
NCSA HDF Library
Unidata netCDF Library
Accessed by DFSD
Yes
Yes
Yes
No
Accessed by SD
Yes
Yes
Yes
Yes
Accessed by NC
Yes
Yes
Yes
Yes

A summary of NC function calls and their SD equivalents is presented in Table 3AI.

TABLE 3AI - NC Interface Routine Calls and their SD Equivalents

Purpose
Routine Name
SD
Equivalent
Description
C
FORTRAN-77
Operations
nccreate NCCRE SDstart Creates a file

ncopen NCOPN SDstart Opens a file

ncredef NCREDF Not Applicable

Sets open file into define mode

ncendef NCENDF Not Applicable

Leaves define mode

ncclose NCCLOS SDend Closes an open file

ncinquire NCINQ SDfileinfo Inquires about an open file

ncsync NCSNC Not Applicable

Synchronizes a file to disk

ncabort NCABOR Not Applicable

Backs out of recent definitions

ncsetfill NCSFIL Not Implemented

Sets fill mode for writes

Dimensions
ncdimdef NCDDEF SDsetdimname Creates a dimension

ncdimid NCDID SDgetdimid Returns a dimension identifier from its name

ncdiminq NCDINQ SDdiminfo Inquires about a dimension

ncdimrename NCDREN Not Implemented

Renames a dimension

Variables
ncvardef NCVDEF SDcreate Creates a variable

ncvarid NCVID SDnametoindex and SDselect Returns a variable identifier from its name

ncvarinq NCVINQ SDgetinfo Returns information about a variable

ncvarput1 NCVPT1 Not Implemented

Writes a single data value

ncvarget1 NCVGT1 Not Implemented

Reads a single data value

ncvarput NCVPT SDwritedata Writes a hyperslab of values

ncvarget NCVGT/NCVGTC SDreaddata Reads a hyperslab of values

ncvarrename NCVREN Not Implemented

Renames a variable

nctypelen NCTLEN DFKNTsize Returns the number of bytes for a data type

Attributes
ncattput NCAPT/NCAPTC SDsetattr Creates an attribute

ncattinq NCAINQ SDattrinfo Returns information about an attribute

ncattcopy NCACPY Not Implemented

Copies attribute from one file to another

ncattget NCAGT/NCAGTC SDreadattr Returns attributes values

ncattname NCANAM SDattrinfo Returns name of attribute from its number

ncattrename NCAREN Not Implemented

Renames an attribute

ncattdel NCADEL Not Implemented

Deletes an attribute



[Top] [Prev]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 05/19/99, NCSA HDF Development Group.