•         advanced

NetCDF Java Library

The NetCDF-Java Library is a Java interface to NetCDF files, as well as to many other types of scientific data formats. 

The library is freely available and the source code is released under the (MIT-style) netCDF C library license. Previous versions use 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.

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? See Jar Dependencies for explanation of which library you want.

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 4.0 (requires Java 1.5)

See Jar Dependencies for explanation of which library you want:

• The unbundled netCDF library (MD5) allows you to choose which other jars you need.
• The complete netCDF library (MD5) implements the full CDM model, with all dependent jars included.
• The complete zip file (MD5) includes all the jar files you might need.
• The toolsUI.jar (MD5) allows you to run the netCDF ToolsUI application directly from it.
• The ncIdv.jar (MD5) which you can use in the IDV
• The minimal library (MD5) just reads netcdf-3 files.
• The unbundled GUI.jar (MD5) for GUI applications that want to choose which other jars are needed
• 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, downloadable jar file. This is the public interface. Future changes to the API will remain backwards compatible with this API.
• All javadoc, downloadable jar file. This is the javadoc for all packages and all methods except private. CAREFUL, some of this may change.
• Transitioning to version 4.0
• Maven repository

Development version 4.1 (requires Java 1.6)

• The unbundled netCDF library (MD5) allows you to choose which other jars you need.
• The complete netCDF library (MD5) implements the full CDM model, with all dependent jars included.
• The complete zip file (MD5) includes all the jar files you might need.
• The toolsUI.jar (MD5) allows you to run the netCDF ToolsUI application directly from it.
• The ncIdv.jar (MD5) which you can use in the IDV
• The minimal library (MD5) just reads netcdf-3 files.
• The unbundled GUI.jar (MD5) for GUI applications that want to choose which other jars are needed
• The source code (MD5) (unzip and follow the README)
• See CHANGES for version changes.
• Try out the 4.1 version of ToolsUI application: launch from webstart.

• Public javadoc, downloadable jar file. This is the public interface. Future changes to the API will remain backwards compatible with this API.
• All javadoc, downloadable jar file. This is the javadoc for all packages and all methods except private. CAREFUL, some of this may change.

Previous stable version 2.2 (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.

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 can read these file types and remote access protocols.

Caveats and not-so-stable APIs:

• Writing to netCDF-3 format is supported, but new features in the CDM, e.g. groups, structures, long data types are not yet supported.
• The feasibility of writing to the NetCDF-4 format is being evaluated. Currently, only read access is supported.
• The catalog API will be redone, however the current API will remain supported.

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

WebEx demo

• ToolsUI demo

You may need to first download the free WebEx Player.

Coordinate Systems

Working notes and documentation on the coordinate system layer of the CDM

• CDM Data Model and Coordinate Systems
• Why we need Coordinate Systems
• _Coordinate Attribute Conventions (examples) (reference)

Feature Types

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

• Proposed CF Convention for Point Observation Data
• Unidata Observation Dataset Conventions (deprecated)
• CDM Feature Types draft doc
• CDM Point Feature Types draft doc
• Complete Point Feature UML
• Feature Types (Overview)
• Grid Datatype
• Experimental CDM Remote web service

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.
• JDOM for parsing XML.
• JGoodies for UI stuff
• JPEG2000 library for decoding GRIB2 files.
• Simple Logging Facade for Java (SLF4J) for logging
• Spring lightweight application framework. Used in ToolsUI application.
• VisAD for reading McIDAS AREA files.
• Xerces for parsing XML (pre jdk 1.5)

Applications using the Netcdf-Java library (partial list):

• 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 toolkits
  • njTBX (Rich Signell/USGS, Sachin Bhate/Mississippi State University)
  • NCDATASET (Brian Schlining/MBARI)
• 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

• Talk at netCDF workshop 2009 (ppt)
• Maven repository
• Port of Netcdf-Java 2.0 to .NET
• NetCDF-Java logo

This document is maintained by John Caron and was last updated on August 26, 2009

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

Unidata is a member of the UCAR Community 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