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.

Current Stable release version 4.3 (requires Java 6)

CDM/TDS source is now hosted on GitHub, and the source jar is no longer available, and ant builds are no longer supported. To build version 4.3 from source with maven:

git clone git://github.com/Unidata/thredds.git thredds
cd thredds
mvn install

If you want to do careful JAR inclusion, see Jar Dependencies for explanation of which jars you need. Most needs can be fulfilled using the complete CDM or ToolsUI JARs:

• The complete netCDF library jar implements the full CDM model, with all dependent jars included.
• The toolsUI.jar also includes UI classes, and allows you to run the netCDF ToolsUI application directly from it with "java -Xmx1g -jar toolsUI.jar"
• The ncIDV.jar is for the IDV netcdf 4.3 branch.
• Public javadoc. This is the public interface. Future changes to the API will attempt to remain backwards compatible with this API.
• All javadoc. This is the javadoc for all packages and all methods except private. CAREFUL, much of this will change.
• Try out the 4.3 version of ToolsUI application: launch from webstart.
• Unidata public Maven repository for version 4.3 artifacts
• All source is on GitHub

File format types

The NetCDF-Java library can read these file types and remote access protocols.

Note to GRIB users:

If you are depending on the CDM/TDS to read GRIB files, you must upgrade to 4.3 AND closely examine the output of any files that you really care about. Check parameter names and everything else against the original documentation if possible, especially if there is any local parameter use. Please send us any files you suspect might be incorrectly read by the CDM library. Note that we will not backport fixes to version 4.2. Note that the variable names in 4.3 will be different from those in 4.2.

Evolving documentation for GRIB is at:

• http://www.unidata.ucar.edu/software/netcdf-java/formats/GribTables.html
• http://www.unidata.ucar.edu/software/netcdf-java/formats/GribFiles.html
  

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.
• Writing to netCDF-4 format is supported, if you have the netCDF C library loaded. As of 4.3.14, this is BETA software.
• The catalog API will be redone, however the current API will remain supported.

Related Documents:

• Frequently Asked Questions
• Tutorial
• Cookbook
• Example Basic Programs in C/C++/Fortran/Java
• Reference Documentation
• Common Data Model
• NetCDF Markup Language: annotated schema

Metadata:

• NetCDF Attribute Convention for Dataset Discovery
• NcISO: generation of ISO 19115-2 metadata from NetCDF data sources. details 

WebEx demo

• ToolsUI demo

You may need to first download the free WebEx Player.

CF Conventions

• CF Conventions Home page
• Short guide to writing files using CF 1.6 discrete sampling features Conventions
• Differences between CF and CDM
• CF Point Observation Data encoding Table
• CF/Radial RADAR/LIDAR Data Format
• CF Convention Conformance Checking
  • http://cf-pcmdi.llnl.gov/conformance/compliance-checker/
• http://htap.icg.kfa-juelich.de:50080/upload

Coordinate Systems

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

• Common Data Model (CDM) 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

• Feature Collections (draft)
• CDM implementation of CF discrete sampling features (DRAFT)
• Complete Point Feature UML
• Feature Types (Overview)
• Grid Datatype
• Using Records in NetCDF-3 files
• Adding unstructured grids to the CDM statement of work

Streaming NetCDF (Experimental)

• NetCDF Streaming Format
• CDM Remote Web Service

Software libraries used by the Netcdf-Java library:

• Apache Commons HttpClient for HTTP access
• Java-OPeNDAP library for reading OPeNDAP. (note this is branched from the opendap.org site)
• 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.

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
• ncWMS (Web Map Service for NetCDF data) and demo site (University of Reading (UK) E-Science Center/Jon Blower)
• Globally Leveraged Integrated Data Explorer for Research (aka GLIDER) (Univ. of Alabama at Huntsville)
• Integrated Data Viewer (Unidata)
• NOAA's Weather and Climate Toolkit (NOAA/NCDC)
• Live Access Server from NOAA/OAR/PMEL (Pacific Marine Environmental Laboratory)
• MATLAB toolkits
  • njTBX (Rich Signell/USGS, Sachin Bhate/Mississippi State University)
  • nctoolbox (Brian Schlining/MBARI)
• MDArray is a multi dimensional array library for JRuby similar to NumPy.
• 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)
• VERDI ( Community Modeling and Analysis System (CMAS) Center at the University of North Carolina at Chapel Hill / Argonne National Laboratory)

Miscellaneous Resources

• Talk at netCDF workshop 2012 (pptx)
• Streaming NetCDF (netCDF workshop 2011) (pptx)
• Talk at netCDF workshop 2010 (pptx)
• Talk at netCDF workshop 2009 (ppt)
• Unidata public Maven repository for version 4.3
• Unidata public GitHub repository for version 4.3
• Unidata public SVN repository for version 4.2
• NetCDF-Java logo
• BUFR Tables project (in progress)
• OPULS project (in progress)
• NCMP project (in progress)

Older versions (not supported)

Previous stable release version 4.2 (requires Java 6)

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 stable 4.2 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.

Building from source with maven

The currently supported way to build version 4.2 from source with maven:

svn co http://svn.unidata.ucar.edu/repos/thredds/branch/RB-TDS-4.2/ thredds
cd thredds
mvn install

You can also get the 4.2.28 build at http://maven.geotoolkit.org/edu/ucar/netcdf/

Last version for Java 5 (4.0.49)

• 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

Last version for Java 4.2 (2.2.20)

• 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

This document is maintained by John Caron and was last updated April 2013