•         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). Version 4.1 will be released using the (MIT-style) netCDF C library license.

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.

Overview

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 aren't concerned about size.

Why do we designate this alpha? The stability and code quality is moderately good. However, until we completely 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.

Which version of Java? All active versions (2.2.22 and 4.0) require Java 5 or above. Performance and stability is improved in version 6, and so the latest version of Java 6 is recommended. NetCDF-Java version 4.1 will likely require Java 1.6. If you are stuck with Java 1.4, you can use the NetCDF-Java 2.2.20 release, but no support or bug fixes are done on that version.

Current Stable version 2.2.22 (requires Java 1.5+). Bug fixes only, no new development.

• 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.
• Transitioning to version 4.0

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 format 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 (complete)
• GTOPO 30-sec elevation dataset (USGS)
• CINRAD level II (Chinese Radar format)
• McIDAS AREA
• Universal 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:

• Frequently Asked Questions
• 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 the 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 feature type layer of the CDM

• Proposed CF Convention for Point Observation Data
• CDM Feature Types draft doc
• CDM Point Feature Types draft doc
• Complete Point Feature UML
• Feature Types (Overview)
• Grid Datatype

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
• Spring lightweight application framework
• VisAD for reading ADDE
• Xerces for parsing XML (pre jdk 1.5)

Applications using the Netcdf-Java library

• ERDDAP (Environmental Research Division Data Access Program), from National Marine Fisheries Service's Southwest Fisheries Science Center
• EDC (Environmental Data Connector) plug-in for ArcGIS
• ESSC Web Map Service for environmental data (aka Godiva2) (University of Reading (UK) E-Science Center/Jon Blower)
• Integrated Data Viewer (Unidata)
• Java NEXRAD Tools (NOAA/NCDC)
• Live Access Server from NOAA/OAR/PMEL (Pacific Marine Environmental Laboratory)
• MATLAB plug-in (USGS/Rich Signell)
• My World GIS (Northwestern University)
• ncBrowse (EPIC/NOAA) (this uses an earlier version of the library)
• Panoply netCDF viewer (NASA/Goddard Institude for Space Studies/Robert B. Schmunk)

Miscellaneous Resources

• Netcdf-Java library in MATLAB
• Port of Netcdf-Java 2.0 to .NET
• NetCDF-Java logo

This document is maintained by John Caron and was last updated on Oct 22, 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