[Top] [Prev] [Next] [Bottom]

3.12 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 API 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 API 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 for the purpose of working with netCDF data objects and to understand enhancements to the API that will be included in the future to make the two APIs much more similar.

In the HDF model, when an n-dimensional SDS is created by SDcreate, 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 dimensional data objects. Each dimensional data object 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 dimensional data objects. This can be done in application programs by calling SDsetdimname to assign the same dimension name to all dimensions that are shared by several SDS objects. 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 cause every SDS to refer to the dimensional data object named "Lat" as its first dimension and to the dimensional data object named "Long" as its 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 API 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 API 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 the mixing of HDF objects that are not SDSs and netCDF objects. For example, a raster image can exist in the same HDF file as a netCDF object, but you must use one of the HDF raster image interfaces to read the image and the HDF SD or netCDF interface to read the netCDF object. The other HDF interfaces 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.12.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 three APIs that support essentially the same data model:

The first three interfaces 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 the following table.

TABLE 3AE 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 the following table.

TABLE 3AF 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] [Next] [Bottom]

hdfhelp@ncsa.uiuc.edu
HDF User's Guide - 06/04/97, NCSA HDF Development Group.