•         advanced

NetCDF Java Library

The NetCDF-Java Library is a Java interface to NetCDF files.  It is built on the ucar.ma2 package, which is a stand-alone Java package for multidimensional arrays of primitive types.

The library is freely available and the source code is released under the GNU Lesser General Public License (LGPL).

The preferred place to ask questions, discuss problems and features and get support is in the NetCDF-Java email list, which you can subscribe to from this page. Also you might want to search or browse previous netCDF-Java support questions.

Version 2.2 (alpha)

The latest version of Java 1.6 is recommended.

The NetCDF-Java library implements a Common Data Model (CDM), a generalization of the NetCDF, OpenDAP and HDF5 data models. The library is a prototype for the NetCDF-4 project, which provides a C language API for the "data access layer" of the CDM, on top of the HDF5 file format. The NetCDF-Java library is a 100% Java framework for reading netCDF and other file formats into the CDM, as well as writing to the netCDF-3 file format. The NetCDF-Java library also implements NcML, which allows you to add metadata to CDM datasets, as well as to create virtual datasets through aggregation.

Which jar files do I need? All libraries (except toolsUI.jar) require an SLF4J library such as slf4j-jdk14.jar (14k) or nlog4j.jar (202k). We need to keep logging unbundled so your application has a choice of logging. All but the minimal library also need (at least) the JDOM library. There are a number of optional jars that you might want to use, see the README for information. The toolsUI jar has everything, use it if you arent worried about size.

Why do we designate this alpha? The stability and code quality is moderately good. However, until we implement the NetCDF-4 reader, we are not sure if the API might need some (probably minor) changes. A stable NetCDF-4 format was released April 2007, and we expect that the next stable version will incorporate this format and the APIs will be final.

Current Stable version 2.2.22 (requires Java 1.5+)

• The minimal library (MD5) just reads netcdf-3 (eventually netcdf-4) files.
• The netCDF library (MD5) implements the full CDM model.
• The netcdfUI library (MD5) includes the netCDF library plus the user interface classes for the netCDF ToolsUI application.
• The complete zip file (MD5) includes the netcdfUI library plus all other jar files you might need.
• The toolsUI.jar (MD5) is a nice fat jar containing everything in a single jar. You can run the netCDF ToolsUI application directly from it.
• The nc2.2.jar (MD5), which you can use in the IDV.
• The source code (MD5) (unzip and follow the README)
• See CHANGES for version changes.
• Try out the 2.2.22 version of ToolsUI application: launch from webstart.

• Public javadoc: This is the public interface.
• All javadoc: Javadoc for all packages and all methods except private. CAREFUL, some of this may change.

Development version 4.0 (requires Java 1.5+)

This version is ALPHA, do not rely on its API until announced as BETA.

• The minimal library (MD5) just reads netcdf-3 (eventually netcdf-4) files.
• The netCDF library (MD5) implements the full CDM model.
• The netcdfUI library (MD5) includes the netCDF library plus the user interface classes for the netCDF ToolsUI application.
• The complete zip file (MD5) includes the netcdfUI library plus all other jar files you might need.
• The toolsUI.jar (MD5) is a nice fat jar containing everything in a single jar. You can run the netCDF ToolsUI application directly from it.
• The ncIdv.jar (MD5), which you can use in the IDV (rename nc2.2.jar for now).
• The source code (MD5) (unzip and follow the README)
• See CHANGES for version changes.
• Try out the 4.0 version of ToolsUI application: launch from webstart.

• Public javadoc: This is the public interface. Downloadable jar file.
• All javadoc: Javadoc for all packages and all methods except private. Downloadable jar file. CAREFUL, some of this may change.

Last Stable version 2.2.20 for Java 1.4.2+

• The minimal library (MD5) just reads netcdf-3 (eventually netcdf-4) files.
• The netCDF library (MD5) implements the full CDM model.
• The netcdfUI library (MD5) includes the netCDF library plus the user interface classes for the netCDF ToolsUI application.
• The complete zip file (MD5) includes the netcdfUI library plus all other jar files you might need.
• The toolsUI.jar (MD5) is a nice fat jar containing everything in a single jar. You can run the netCDF ToolsUI application directly from it.
• The nc2.2.jar (MD5), which you can use in the IDV.
• The source code (MD5) (unzip and follow the README)
• See CHANGES for version changes.
• Try out the 2.2.20 library through the ToolsUI application: launch from webstart.

• Public javadoc: This is the public interface.
• All javadoc: Javadoc for all packages and all methods except private. CAREFUL, some of this may change.
• User's documentation (incomplete): doc pdf

File types

The NetCDF-Java library (version 2.2) can read the following file types and remote access protocols:

• NetCDF-3 (classic and large format)
• HDF5 (partial)
• OPeNDAP client/server protocol
• GRIB version 1 and version 2 (ongoing work on tables)
• GINI (GOES Ingest and NOAAPORT Interface ) image format
• GEMPAK gridded data (as of version 2.23)
• DMSP (Defense Meteorological Satellite Program)
• NEXRAD Radar level 2 and level 3.
• ATD's DORADE radar file format
• ADDE client/server protocol (limited)

NetCDF-Java library (version 4.0) adds

• NetCDF-4 and HDF5 (complete)
• HDF4 (complete)
• HDF-EOS and HDF5-EOS (parsing HDF-EOS metadata is ongoing)
• BUFR (limited - ongoing work)
• GTOPO 30-sec elevation dataset (USGS)
• CINRAD level II (Chinese Radar format)

Features not yet available:

• Writing to netCDF-3 is supported, but new features in the CDM, e.g. groups, structures, the long data type are not available yet.
• The feasibility of writing to the NetCDF-4 format is being evaluated. Currently, only read access is supported.
• The scientific data types interfaces are still experimental, do not rely on the APIs yet.

Related Documents:

• Tutorial
• Reference Documentation
• Common Data Model
• NetCDF Markup Language: Version 2.2 annotated schema
• NetCDF Attribute Convention for Dataset Discovery
• Using Records in NetCDF-3 files

Coordinate Systems

Working notes and documentation on coordinate system layer of the CDM

• Why we need Coordinate Systems
• Coordinate System Object Model Primer
• _Coordinate Attribute Conventions (examples) (reference)

Data Types

Working notes and documents on the scientific data type layer of the CDM

• Feature Types
• Radar Data Format
• Grid Datatype
• Unidata Observation Dataset Conventions

Software libraries used by the Netcdf-Java library:

• Apache Commons HttpClient for HTTP access, which also use commons-logging and commons-codec.
• Java-OPeNDAP library for reading OPeNDAP, which requires gnu-regexp.
• JDOM for parsing XML.
• JGoodies for UI stuff
• JPEG2000 library for decoding GRIB2 files.
• Log4J and its companion Simple Logging Facade for Java (SLF4J) for logging
• VisAD for reading ADDE
• Xerces for parsing XML (pre jdk 1.5)

Visualization Applications using the Netcdf-Java library

• Integrated Data Viewer (Unidata)
• Panoply netCDF viewer (Goddard Institude for Space Studies)
• My World GIS (Northwestern University)
• ncBrowse (EPIC/NOAA) (this uses an earlier version of the library)
• NCDC Java NEXRAD Viewer and Data Exporter

Miscellaneous Resources

• Example importing Netcdf-Java 2.2 library into MATLAB
• Port of Netcdf-Java 2.0 to .NET
• NetCDF-Java logo

This document is maintained by John Caron and was last updated on Apr 27, 2008

Contact Us   •   Site Map   •   Search   •   Terms and Conditions   •   Privacy Policy   •   Participation Policy

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