Multidimensional Raster Data Model
This document attempts to describe the GDAL multidimensional data model, that has been added in GDAL 3.1. That is the types of information that a GDAL multidimensional dataset can contain, and their semantics.
The multidimensional raster API is a generalization of the traditional Raster Data Model, to address 3D, 4D or higher dimension datasets. Currently, it is limited to basic read/write API, and is not that much plugged into other higher level utilities.
It is strongly inspired from the netCDF and HDF5 API and data models. See HDF5 format and data model.
GDALAttribute (modelling a HDF5 Attribute)
has a name and a value, and is typically used to describe a metadata item.
The value can be (for the HDF5 format) in the general case a multidimensional array
of “any” type (in most cases, this will be a single value of string or numeric type)
Most drivers use the row-major convention for dimensions: that is, when considering
that the array elements are stored consecutively in memory, the first dimension
is the slowest varying one (in a 2D image, the row), and the last dimension the
fastest varying one (in a 2D image, the column). That convention is the default
convention used for NumPy arrays, the MEM driver and the HDF5 and netCDF APIs.
The GDAL API is mostly agnostic
about that convention, except when passing a NULL array as the stride parameter
You can refer to NumPy documentation about multidimensional array indexing order issues
a GDALMDArray has also optional properties:
Coordinate reference system:
No data value:
Offset, such that unscaled_value = offset + scale * raw_value
Scale, such that unscaled_value = offset + scale * raw_value
GDALMDArray::Cache() method can be used to cache the value of
a view array into a sidecar file.
GDALDimension describes a dimension / axis used to index multidimensional arrays.
It has the following properties:
a size, that is the number of values that can be indexed along the dimension
a type, which is a string giving the nature of the dimension. Predefined values are: HORIZONTAL_X, HORIZONTAL_Y, VERTICAL, TEMPORAL, PARAMETRIC Other values might be used. Empty value means unknown.
a direction. Predefined values are: EAST, WEST, SOUTH, NORTH, UP, DOWN, FUTURE, PAST Other values might be used. Empty value means unknown.
a reference to a GDALMDArray variable, typically one-dimensional, describing the values taken by the dimension. For a georeferenced GDALMDArray and its X dimension, this will be typically the values of the easting/longitude for each grid point.
GDALExtendedDataType (modelling a
describes the type taken by an individual value of
a GDALAttribute or GDALMDArray. Its class can be NUMERIC,
STRING or COMPOUND. For NUMERIC, the existing
values are supported. For COMPOUND, the data type is a list of members, each
member being described by a name, a offset in byte in the compound structure and
The HDF5 modelisation allows for more complex datatypes.
HDF5 does not have native data types for complex values whereas GDALDataType does. So a driver may decide to expose a GDT_Cxxxx datatype from a HDF5 Compound data type representing a complex value.
Differences with the GDAL 2D raster data model
The concept of GDALRasterBand is no longer used for multidimensional. This can be modelled as either different GDALMDArray, or using a compound data type.