GDALMDArray C++ API

class GDALMDArray : public virtual GDALAbstractMDArray, public GDALIHasAttribute

Class modeling a multi-dimensional array.

It has a name, values organized as an array and a list of GDALAttribute.

This is based on the HDF5 dataset concept

Since

GDAL 3.1

Subclassed by GDALExtractFieldMDArray, GDALMDArrayFromRasterBand, GDALMDArrayTransposed, GDALSlicedMDArray

Public Functions

GUInt64 GetTotalCopyCost() const

Return a total “cost” to copy the array.

Used as a parameter for CopyFrom()

bool CopyFrom(GDALDataset *poSrcDS, const GDALMDArray *poSrcArray, bool bStrict, GUInt64 &nCurCost, const GUInt64 nTotalCost, GDALProgressFunc pfnProgress, void *pProgressData)

Copy the content of an array into a new (generally empty) array.

Return

true in case of success (or partial success if bStrict == false).

Parameters
  • poSrcDS: Source dataset. Migt be nullptr (but for correct behaviour of some output drivers this is not recommended)

  • poSrcArray: Source array. Should NOT be nullptr.

  • bStrict: Whether to enable stict mode. In strict mode, any error will stop the copy. In relaxed mode, the copy will be attempted to be pursued.

  • nCurCost: Should be provided as a variable initially set to 0.

  • nTotalCost: Total cost from GetTotalCopyCost().

  • pfnProgress: Progress callback, or nullptr.

  • pProgressData: Progress user data, or nulptr.

virtual bool IsWritable() const = 0

Return whether an array is writable;.

CSLConstList GetStructuralInfo() const

Return structural information on the array.

This may be the compression, etc..

The return value should not be freed and is valid until GDALMDArray is released or this function called again.

This is the same as the C function GDALMDArrayGetStruturalInfo().

const std::string &GetUnit() const

Return the array unit.

Values should conform as much as possible with those allowed by the NetCDF CF conventions: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html#units but others might be returned.

Few examples are “meter”, “degrees”, “second”, … Empty value means unknown.

This is the same as the C function GDALMDArrayGetUnit()

bool SetUnit(const std::string &osUnit)

Set the variable unit.

Values should conform as much as possible with those allowed by the NetCDF CF conventions: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html#units but others might be returned.

Few examples are “meter”, “degrees”, “second”, … Empty value means unknown.

This is the same as the C function GDALMDArraySetUnit()

Note

Driver implementation: optionally implemented.

Return

true in case of success.

Parameters
  • osUnit: unit name.

bool SetSpatialRef(const OGRSpatialReference *poSRS)

Assign a spatial reference system object to the the array.

This is the same as the C function GDALMDArraySetSpatialRef().

std::shared_ptr<OGRSpatialReference> GetSpatialRef() const

Return the spatial reference system object associated with the array.

This is the same as the C function GDALMDArrayGetSpatialRef().

const void *GetRawNoDataValue() const

Return the nodata value as a “raw” value.

The value returned might be nullptr in case of no nodata value. When a nodata value is registered, a non-nullptr will be returned whose size in bytes is GetDataType().GetSize().

The returned value should not be modified or freed. It is valid until the array is destroyed, or the next call to GetRawNoDataValue() or SetRawNoDataValue(), or any similar methods.

This is the same as the C function

GDALMDArrayGetRawNoDataValue().
Note

Driver implementation: this method shall be implemented if nodata is supported.

Return

nullptr or a pointer to GetDataType().GetSize() bytes.

double GetNoDataValueAsDouble(bool *pbHasNoData = nullptr) const

Return the nodata value as a double.

The value returned might be nullptr in case of no nodata value. When a nodata value is registered, a non-nullptr will be returned whose size in bytes is GetDataType().GetSize().

This is the same as the C function GDALMDArrayGetNoDataValueAsDouble().

Return

the nodata value as a double. A 0.0 value might also indicate the absence of a nodata value or an error in the conversion (*pbHasNoData will be set to false then).

Parameters
  • pbHasNoData: Pointer to a output boolean that will be set to true if a nodata value exists and can be converted to double. Might be nullptr.

bool SetRawNoDataValue(const void *pRawNoData)

Set the nodata value as a “raw” value.

The value passed might be nullptr in case of no nodata value. When a nodata value is registered, a non-nullptr whose size in bytes is GetDataType().GetSize() must be passed.

This is the same as the C function GDALMDArraySetRawNoDataValue().

Note

Driver implementation: this method shall be implemented if setting nodata is supported.

Return

true in case of success.

bool SetNoDataValue(double dfNoData)

Set the nodata value as a double.

If the natural data type of the attribute/array is not double, type conversion will occur to the type returned by GetDataType().

This is the same as the C function GDALMDArraySetNoDataValueAsDouble().

Return

true in case of success.

double GetOffset(bool *pbHasOffset = nullptr) const

Get the offset value to apply to raw values.

unscaled_value = raw_value * GetScale() + GetOffset()

This is the same as the C function GDALMDArrayGetOffset().

Note

Driver implementation: this method shall be implemented if gettings offset is supported.

Return

the offset value. A 0.0 value might also indicate the absence of a offset value.

Parameters
  • pbHasOffset: Pointer to a output boolean that will be set to true if a offset value exists. Might be nullptr.

double GetScale(bool *pbHasScale = nullptr) const

Get the scale value to apply to raw values.

unscaled_value = raw_value * GetScale() + GetOffset()

This is the same as the C function GDALMDArrayGetScale().

Note

Driver implementation: this method shall be implemented if gettings scale is supported.

Return

the scale value. A 1.0 value might also indicate the absence of a scale value.

Parameters
  • pbHasScale: Pointer to a output boolean that will be set to true if a scale value exists. Might be nullptr.

bool SetOffset(double dfOffset)

Set the offset value to apply to raw values.

unscaled_value = raw_value * GetScale() + GetOffset()

This is the same as the C function GDALMDArraySetOffset().

Note

Driver implementation: this method shall be implemented if setting offset is supported.

Return

true in case of success.

bool SetScale(double dfScale)

Set the scale value to apply to raw values.

unscaled_value = raw_value * GetScale() + GetOffset()

This is the same as the C function GDALMDArraySetScale().

Note

Driver implementation: this method shall be implemented if setting scale is supported.

Return

true in case of success.

std::shared_ptr<GDALMDArray> GetView(const std::string &viewExpr) const

Return a view of the array using slicing or field access.

The slice expression uses the same syntax as NumPy basic slicing and indexing. See https://www.numpy.org/devdocs/reference/arrays.indexing.html#basic-slicing-and-indexing Or it can use field access by name. See https://www.numpy.org/devdocs/reference/arrays.indexing.html#field-access

Multiple [] bracket elements can be concatenated, with a slice expression or field name inside each.

For basic slicing and indexing, inside each [] bracket element, a list of indexes that apply to successive source dimensions, can be specified, using integer indexing (e.g. 1), range indexing (start:stop:step), ellipsis (…) or newaxis, using a comma separator.

Examples with a 2-dimensional array whose content is [[0,1,2,3],[4,5,6,7]].

  • GetView(“[1][2]”): returns a 0-dimensional/scalar array with the value at index 1 in the first dimension, and index 2 in the second dimension from the source array. That is 5

  • GetView(“[1]”)->GetView(“[2]”): same as above. Above is actually implemented internally doing this intermediate slicing approach.

  • GetView(“[1,2]”): same as above, but a bit more performant.

  • GetView(“[1]”): returns a 1-dimensional array, sliced at index 1 in the first dimension. That is [4,5,6,7].

  • GetView(“[:,2]”): returns a 1-dimensional array, sliced at index 2 in the second dimension. That is [2,6].

  • GetView(“[:,2:3:]”): returns a 2-dimensional array, sliced at index 2 in the second dimension. That is [[2],[6]].

  • GetView(“[::,2]”): Same as above.

  • GetView(“[…,2]”): same as above, in that case, since the ellipsis only expands to one dimension here.

  • GetView(“[:,::2]”): returns a 2-dimensional array, with even-indexed elements of the second dimension. That is [[0,2],[4,6]].

  • GetView(“[:,1::2]”): returns a 2-dimensional array, with odd-indexed elements of the second dimension. That is [[1,3],[5,7]].

  • GetView(“[:,1:3:]”): returns a 2-dimensional array, with elements of the second dimension with index in the range [1,3[. That is [[1,2],[5,6]].

  • GetView(“[::-1,:]”): returns a 2-dimensional array, with the values in first dimension reversed. That is [[4,5,6,7],[0,1,2,3]].

  • GetView(“[newaxis,…]”): returns a 3-dimensional array, with an addditional dimension of size 1 put at the beginning. That is [[[0,1,2,3],[4,5,6,7]]].

One difference with NumPy behaviour is that ranges that would result in zero elements are not allowed (dimensions of size 0 not being allowed in the GDAL multidimensional model).

For field access, the syntax to use is [“field_name”] or [‘field_name’]. Multipe field specification is not supported currently.

Both type of access can be combined, e.g. GetView(“[1][‘field_name’]”)

The returned array holds a reference to the original one, and thus is a view of it (not a copy). If the content of the original array changes, the content of the view array too. When using basic slicing and indexing, the view can be written if the underlying array is writable.

Note

When using the GDAL Python bindings, natural Python syntax can be used. That is ar[0,::,1][“foo”] will be internally translated to ar.GetView(“[0,::,1][‘foo’]”)

Note

When using the C++ API and integer indexing only, you may use the at(idx0, idx1, …) method.

This is the same as the C function GDALMDArrayGetView()

Return

a new array, that holds a reference to the original one, and thus is a view of it (not a copy), or nullptr in case of error.

Parameters
  • viewExpr: Expression expressing basic slicing and indexing, or field access.

std::shared_ptr<GDALMDArray> operator[](const std::string &fieldName) const

Return a view of the array using field access.

Equivalent of GetView(“[‘fieldName’]”)

Note

When operationg on a shared_ptr, use (*array)[“fieldName”] syntax.

template<typename ...GUInt64VarArg>
std::shared_ptr<GDALMDArray> at(GUInt64 idx, GUInt64VarArg... tail) const

Return a view of the array using integer indexing.

Equivalent of GetView(“[indices_0,indices_1,…..,indices_last]”)

Example:

ar->at(0,3,2)

std::shared_ptr<GDALMDArray> Transpose(const std::vector<int> &anMapNewAxisToOldAxis) const

Return a view of the array whose axis have been reordered.

The anMapNewAxisToOldAxis parameter should contain all the values between 0 and GetDimensionCount() - 1, and each only once. -1 can be used as a special index value to ask for the insertion of a new axis of size 1. The new array will have anMapNewAxisToOldAxis.size() axis, and if i is the index of one of its dimension, it corresponds to the axis of index anMapNewAxisToOldAxis[i] from the current array.

This is similar to the numpy.transpose() method

The returned array holds a reference to the original one, and thus is a view of it (not a copy). If the content of the original array changes, the content of the view array too. The view can be written if the underlying array is writable.

Note that I/O performance in such a transposed view might be poor.

This is the same as the C function GDALMDArrayTranspose().

Return

a new array, that holds a reference to the original one, and thus is a view of it (not a copy), or nullptr in case of error.

GDALDataset *AsClassicDataset(size_t iXDim, size_t iYDim) const

Return a view of this array as a “classic” GDALDataset (ie 2D)

In the case of > 2D arrays, additional dimensions will be represented as raster bands.

The “reverse” method is GDALRasterBand::AsMDArray().

This is the same as the C function GDALMDArrayAsClassicDataset().

Return

a new GDALDataset that must be freed with GDALClose(), or nullptr

Parameters
  • iXDim: Index of the dimension that will be used as the X/width axis.

  • iYDim: Index of the dimension that will be used as the Y/height axis. Ignored if the dimension count is 1.