NetCDF: Network Common Data Form

This format is supported for read and write access. This page only describes
the raster support (you can find documentation for the
vector side)
NetCDF is an interface for
array-oriented data access and is used for representing scientific data.

The fill value metadata or missing_value backward compatibility is preserved
as NODATA value when available.

NOTE: Implemented as gdal/frmts/netcdf/netcdfdataset.cpp.

Multiple Image Handling (Subdatasets)

Network Command Data Form is a container for several different arrays most
used for storing scientific dataset. One NetCDF file may
contain several datasets. They may differ in size, number of dimensions and
may represent data for different regions.

If the file contains only one NetCDF array which appears to be an image,
it may be accessed directly, but if the file contains multiple images it may
be necessary to import the file via a two step process.

The first step is to get a report of the components images (dataset) in the
file using gdalinfo, and then to import the desired images using
gdal_translate. The gdalinfo utility lists all multidimensional subdatasets
from the input NetCDF file.

The name of individual images are assigned to the SUBDATASET_n_NAME
metadata item. The description for each image is found in the
SUBDATASET_n_DESC metadata item. For NetCDF images will follow this format:
NETCDF:filename:variable_name

where filename is the name of the input file, and
variable_name is the dataset selected within the file.

On the second step you provide this name for gdalinfo to get information
about the dataset or
gdal_translate to read dataset.

gdalinfo displays the number of bands into this subdataset.
There are metadata attached to each band.
In this example, the metadata informs us
that each band correspond to an array of monthly sea surface temperature
from January 2001. There are 24 months of data in this subdataset.
You may also use gdal_translate for reading the subdataset.

Note that you should provide exactly the contents of the line marked
SUBDATASET_n_NAME to GDAL, including the NETCDF: prefix.

The NETCDF prefix must be first. It triggers the subdataset NetCDF driver.
This driver is intended only for importing remote sensing and geospatial
datasets in form of raster images. If you want explore all data contained in
NetCDF file you should use another tools.

Dimension

The NetCDF driver assume that data follows the CF-1 convention from
UNIDATA
The dimensions inside the NetCDF file use the following rules: (Z,Y,X).
If there are more than 3
dimensions, the driver will merge them into bands. For example if you have
an 4 dimension arrays of the type (P, T, Y, X). The driver will multiply the
last 2 dimensions (P*T). The driver will display the bands in the following
order. It will first increment T and then P. Metadata
will be displayed on each band with its corresponding T and P values.

Georeference

There is no universal way of storing georeferencing in NetCDF files.
The driver first tries to follow the CF-1 Convention from UNIDATA looking for
the Metadata named "grid_mapping".
If "grid_mapping" is not present, the driver will try to find an
lat/lon grid array to set geotransform array. The NetCDF driver verifies
that the Lat/Lon array is equally space.

If those 2 methods fail, NetCDF driver will try to read the following
metadata directly and set up georeferencing.

spatial_ref (Well Known Text)

GeoTransform (GeoTransform array)

or,

Northernmost_Northing

Southernmost_Northing

Easternmost_Easting

Westernmost_Easting

Open options

The following open options are available:

HONOUR_VALID_RANGE=YES/NO: (GDAL > 2.2) Whether to set to nodata pixel values
outside of the validity range indicated by valid_min, valid_max or valid_range
attributes. Default is YES.

Creation Issues

This driver supports creation of NetCDF file following the CF-1 convention.
You may create set of 2D datasets. Each variable array is named
Band1, Band2, ... BandN.

Each band will have metadata tied to it giving a short description of
the data it contains.

Creation Options

FORMAT=[NC/NC2/NC4/NC4C]: Set the NetCDF file format to use, NC is the default. NC2 is normally supported by recent NetCDF installations, but NC4 and NC4C are available if NetCDF was compiled with NetCDF-4 (and HDF5) support.

COMPRESS=[NONE/DEFLATE]: Set the compression to use. DEFLATE is only available if NetCDF has been compiled with NetCDF-4 support. NC4C format is the default if DEFLATE compression is used.

ZLEVEL=[1-9]: Set the level of compression when using DEFLATE compression. A value of 9 is best, and 1 is least compression. The default is 1, which offers the best time/compression ratio.

WRITE_BOTTOMUP=[YES/NO]: Set the y-axis order for export, overriding the order detected by the driver. NetCDF files are usually assumed "bottom-up", contrary to GDAL's model which is "north up". This normally does not create a problem in the y-axis order, unless there is no y axis geo-referencing. The default for this setting is YES, so files will be exported in the NetCDF default "bottom-up" order. For import see Configuration Option GDAL_NETCDF_BOTTOMUP below.

WRITE_GDAL_TAGS=[YES/NO]: Define if GDAL tags used for georeferencing (spatial_ref and GeoTransform) should be exported, in addition to CF tags. Not all information is stored in the CF tags (such as named datums and EPSG codes), therefore the driver exports these variables by default. In import the CF "grid_mapping" variable takes precedence and the GDAL tags are used if they do not conflict with CF metadata.

WRITE_LONLAT=[YES/NO/IF_NEEDED]: Define if CF lon/lat variables are written to file. Default is YES for geographic SRS and NO for projected SRS. This is normally not necessary for projected SRS as GDAL and many applications use the X/Y dimension variables and CF projection information. Use of IF_NEEDED option creates lon/lat variables if the projection is not part of the CF-1.5 standard.

TYPE_LONLAT=[float/double]: Set the variable type to use for lon/lat variables. Default is double for geographic SRS and float for projected SRS. If lon/lat variables are written for a projected SRS, the file is considerably large (each variable uses X*Y space), therefore TYPE_LONLAT=float and COMPRESS=DEFLATE are advisable in order to save space.

PIXELTYPE=[DEFAULT/SIGNEDBYTE]: By setting this to SIGNEDBYTE, a new Byte file can be forced to be written as signed byte.

Configuration Options

GDAL_NETCDF_BOTTOMUP=[YES/NO] : Set the y-axis order for import, overriding the order detected by the driver. This option is usually not needed unless a specific dataset is causing problems (which should be reported in GDAL trac).

VSI Virtual File System API support

Since GDAL 2.4, and with Linux kernel >=4.3 and libnetcdf >=4.5,
read operations on /vsi file systems are supported.

NetCDF-4 groups support on reading (GDAL >= 2.5.0)

The driver has undergone significant changes in GDAL 2.5.0 to support NetCDF-4 groups on reading:

Explore recursively all nested groups to create the subdatasets list

Subdatasets in nested groups use the /group1/group2/.../groupn/var standard NetCDF-4 convention, except for variables in the root group which do not have a leading slash for backward compatibility with the NetCDF-3 driver

Global attributes of each nested group are also collected in the GDAL dataset metadata, using the same convention /group1/group2/.../groupn/NC_GLOBAL#attr_name, except for the root group which do not have a leading slash for backward compatibility

When searching for a variable containing auxiliary information on the selected subdataset, like coordinate variables or grid_mapping, we now also search in parent groups and their childs as specified in Support of groups in CF

Driver building

This driver is compiled with the UNIDATA NetCDF library.

You need to download or compile the NetCDF library before configuring GDAL with NetCDF support.