Class modeling a multi-dimensional array. More...

#include <gdal_priv.h>

Inheritance diagram for GDALMDArray:

Public Types
typedef bool(*	FuncProcessPerChunkType) (GDALAbstractMDArray array, const GUInt64 chunkArrayStartIdx, const size_t chunkCount, GUInt64 iCurChunk, GUInt64 nChunkCount, void pUserData)
	Type of pfnFunc argument of ProcessPerChunk().

Public Member Functions
GUInt64	GetTotalCopyCost () const
	Return a total "cost" to copy the array.

virtual 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.

virtual bool	IsWritable () const =0
	Return whether an array is writable.

virtual const std::string &	GetFilename () const =0
	Return the filename that contains that array.

virtual CSLConstList	GetStructuralInfo () const
	Return structural information on the array.

virtual const std::string &	GetUnit () const
	Return the array unit.

virtual bool	SetUnit (const std::string &osUnit)
	Set the variable unit.

virtual bool	SetSpatialRef (const OGRSpatialReference *poSRS)
	Assign a spatial reference system object to the array.

virtual std::shared_ptr< OGRSpatialReference >	GetSpatialRef () const
	Return the spatial reference system object associated with the array.

virtual const void *	GetRawNoDataValue () const
	Return the nodata value as a "raw" value.

double	GetNoDataValueAsDouble (bool *pbHasNoData=nullptr) const
	Return the nodata value as a double.

int64_t	GetNoDataValueAsInt64 (bool *pbHasNoData=nullptr) const
	Return the nodata value as a Int64.

uint64_t	GetNoDataValueAsUInt64 (bool *pbHasNoData=nullptr) const
	Return the nodata value as a UInt64.

virtual bool	SetRawNoDataValue (const void *pRawNoData)
	Set the nodata value as a "raw" value.

bool	SetNoDataValue (double dfNoData)
	Set the nodata value as a double.

bool	SetNoDataValue (int64_t nNoData)
	Set the nodata value as a Int64.

bool	SetNoDataValue (uint64_t nNoData)
	Set the nodata value as a Int64.

virtual bool	Resize (const std::vector< GUInt64 > &anNewDimSizes, CSLConstList papszOptions)
	Resize an array to new dimensions.

virtual double	GetOffset (bool pbHasOffset=nullptr, GDALDataType peStorageType=nullptr) const
	Get the offset value to apply to raw values.

virtual double	GetScale (bool pbHasScale=nullptr, GDALDataType peStorageType=nullptr) const
	Get the scale value to apply to raw values.

virtual bool	SetOffset (double dfOffset, GDALDataType eStorageType=GDT_Unknown)
	Set the offset value to apply to raw values.

virtual bool	SetScale (double dfScale, GDALDataType eStorageType=GDT_Unknown)
	Set the scale value to apply to raw values.

std::shared_ptr< GDALMDArray >	GetView (const std::string &viewExpr) const
	Return a view of the array using slicing or field access.

std::shared_ptr< GDALMDArray >	operator[] (const std::string &fieldName) const
	Return a view of the array using field access.

std::shared_ptr< GDALMDArray >	at (GUInt64 idx, GUInt64VarArg... tail) const
	Return a view of the array using integer indexing.

virtual std::shared_ptr< GDALMDArray >	Transpose (const std::vector< int > &anMapNewAxisToOldAxis) const
	Return a view of the array whose axis have been reordered.

std::shared_ptr< GDALMDArray >	GetUnscaled (double dfOverriddenScale=std::numeric_limits< double >::quiet_NaN(), double dfOverriddenOffset=std::numeric_limits< double >::quiet_NaN(), double dfOverriddenDstNodata=std::numeric_limits< double >::quiet_NaN()) const
	Return an array that is the unscaled version of the current one.

virtual std::shared_ptr< GDALMDArray >	GetMask (CSLConstList papszOptions) const
	Return an array that is a mask for the current array.

virtual std::shared_ptr< GDALMDArray >	GetResampled (const std::vector< std::shared_ptr< GDALDimension > > &apoNewDims, GDALRIOResampleAlg resampleAlg, const OGRSpatialReference *poTargetSRS, CSLConstList papszOptions) const
	Return an array that is a resampled / reprojected view of the current array.

std::shared_ptr< GDALMDArray >	GetGridded (const std::string &osGridOptions, const std::shared_ptr< GDALMDArray > &poXArray=nullptr, const std::shared_ptr< GDALMDArray > &poYArray=nullptr, CSLConstList papszOptions=nullptr) const
	Return a gridded array from scattered point data, that is from an array whose last dimension is the indexing variable of X and Y arrays.

virtual GDALDataset *	AsClassicDataset (size_t iXDim, size_t iYDim, const std::shared_ptr< GDALGroup > &poRootGroup=nullptr, CSLConstList papszOptions=nullptr) const
	Return a view of this array as a "classic" GDALDataset (ie 2D)

virtual CPLErr	GetStatistics (bool bApproxOK, bool bForce, double pdfMin, double pdfMax, double pdfMean, double padfStdDev, GUInt64 pnValidCount, GDALProgressFunc pfnProgress, void pProgressData)
	Fetch statistics.

virtual bool	ComputeStatistics (bool bApproxOK, double pdfMin, double pdfMax, double pdfMean, double pdfStdDev, GUInt64 pnValidCount, GDALProgressFunc, void pProgressData, CSLConstList papszOptions)
	Compute statistics.

virtual void	ClearStatistics ()
	Clear statistics.

virtual std::vector< std::shared_ptr< GDALMDArray > >	GetCoordinateVariables () const
	Return coordinate variables.

bool	AdviseRead (const GUInt64 arrayStartIdx, const size_t count, CSLConstList papszOptions=nullptr) const
	Advise driver of upcoming read requests.

bool	IsRegularlySpaced (double &dfStart, double &dfIncrement) const
	Returns whether an array is a 1D regularly spaced array.

bool	GuessGeoTransform (size_t nDimX, size_t nDimY, bool bPixelIsPoint, double adfGeoTransform[6]) const
	Returns whether 2 specified dimensions form a geotransform.

bool	Cache (CSLConstList papszOptions=nullptr) const
	Cache the content of the array into an auxiliary filename.

bool	Read (const GUInt64 arrayStartIdx, const size_t count, const GInt64 arrayStep, const GPtrDiff_t bufferStride, const GDALExtendedDataType &bufferDataType, void pDstBuffer, const void pDstBufferAllocStart=nullptr, size_t nDstBufferAllocSize=0) const override
	Read part or totality of a multidimensional array or attribute.

virtual std::shared_ptr< GDALGroup >	GetRootGroup () const
	Return the root group to which this arrays belongs too.

const std::string &	GetName () const
	Return the name of an array or attribute.

const std::string &	GetFullName () const
	Return the name of an array or attribute.

GUInt64	GetTotalElementsCount () const
	Return the total number of values in the array.

virtual size_t	GetDimensionCount () const
	Return the number of dimensions.

virtual const std::vector< std::shared_ptr< GDALDimension > > &	GetDimensions () const =0
	Return the dimensions of an attribute/array.

virtual const GDALExtendedDataType &	GetDataType () const =0
	Return the data type of an attribute/array.

virtual std::vector< GUInt64 >	GetBlockSize () const
	Return the "natural" block size of the array along all dimensions.

virtual std::vector< size_t >	GetProcessingChunkSize (size_t nMaxChunkMemory) const
	Return an optimal chunk size for read/write operations, given the natural block size and memory constraints specified.

virtual bool	ProcessPerChunk (const GUInt64 arrayStartIdx, const GUInt64 count, const size_t chunkSize, FuncProcessPerChunkType pfnFunc, void pUserData)
	Call a user-provided function to operate on an array chunk by chunk.

bool	Write (const GUInt64 arrayStartIdx, const size_t count, const GInt64 arrayStep, const GPtrDiff_t bufferStride, const GDALExtendedDataType &bufferDataType, const void pSrcBuffer, const void pSrcBufferAllocStart=nullptr, size_t nSrcBufferAllocSize=0)
	Write part or totality of a multidimensional array or attribute.

virtual bool	Rename (const std::string &osNewName)
	Rename the attribute/array.

virtual std::shared_ptr< GDALAttribute >	GetAttribute (const std::string &osName) const
	Return an attribute by its name.

virtual std::vector< std::shared_ptr< GDALAttribute > >	GetAttributes (CSLConstList papszOptions=nullptr) const
	Return the list of attributes contained in a GDALMDArray or GDALGroup.

virtual std::shared_ptr< GDALAttribute >	CreateAttribute (const std::string &osName, const std::vector< GUInt64 > &anDimensions, const GDALExtendedDataType &oDataType, CSLConstList papszOptions=nullptr)
	Create an attribute within a GDALMDArray or GDALGroup.

virtual bool	DeleteAttribute (const std::string &osName, CSLConstList papszOptions=nullptr)
	Delete an attribute from a GDALMDArray or GDALGroup.

Static Public Member Functions
static std::vector< std::shared_ptr< GDALMDArray > >	GetMeshGrid (const std::vector< std::shared_ptr< GDALMDArray > > &apoArrays, CSLConstList papszOptions=nullptr)
	Return a list of multidimensional arrays from a list of one-dimensional arrays.

Protected Member Functions
std::shared_ptr< GDALAttribute >	GetAttributeFromAttributes (const std::string &osName) const
	Possible fallback implementation for GetAttribute() using GetAttributes().

Friends
class	GDALMDArrayResampled

Detailed Description

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

Member Typedef Documentation

◆ FuncProcessPerChunkType

typedef bool(* GDALAbstractMDArray::FuncProcessPerChunkType) (GDALAbstractMDArray *array, const GUInt64 *chunkArrayStartIdx, const size_t *chunkCount, GUInt64 iCurChunk, GUInt64 nChunkCount, void *pUserData)

inherited

Type of pfnFunc argument of ProcessPerChunk().

Parameters

array	Array on which ProcessPerChunk was called.
chunkArrayStartIdx	Values representing the starting index to use in each dimension (in [0, aoDims[i].GetSize()-1] range) for the current chunk. Will be nullptr for a zero-dimensional array.
chunkCount	Values representing the number of values to use in each dimension for the current chunk. Will be nullptr for a zero-dimensional array.
iCurChunk	Number of current chunk being processed. In [1, nChunkCount] range.
nChunkCount	Total number of chunks to process.
pUserData	User data.

Returns: return true in case of success.

Member Function Documentation

◆ AdviseRead()

bool GDALMDArray::AdviseRead	(	const GUInt64 *	arrayStartIdx,
		const size_t *	count,
		CSLConstList	papszOptions = `nullptr`
	)		const

Advise driver of upcoming read requests.

Some GDAL drivers operate more efficiently if they know in advance what set of upcoming read requests will be made. The AdviseRead() method allows an application to notify the driver of the region of interest.

Many drivers just ignore the AdviseRead() call, but it can dramatically accelerate access via some drivers. One such case is when reading through a DAP dataset with the netCDF driver (a in-memory cache array is then created with the region of interest defined by AdviseRead())

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

Parameters

arrayStartIdx	Values representing the starting index to read in each dimension (in [0, aoDims[i].GetSize()-1] range). Array of GetDimensionCount() values. Can be nullptr as a synonymous for [0 for i in range(GetDimensionCount() ]
count	Values representing the number of values to extract in each dimension. Array of GetDimensionCount() values. Can be nullptr as a synonymous for [ aoDims[i].GetSize() - arrayStartIdx[i] for i in range(GetDimensionCount() ]
papszOptions	Driver specific options, or nullptr. Consult driver documentation.

Returns: true in case of success (ignoring the advice is a success)

Since: GDAL 3.2

◆ AsClassicDataset()

GDALDataset * GDALMDArray::AsClassicDataset	(	size_t	iXDim,
		size_t	iYDim,
		const std::shared_ptr< GDALGroup > &	poRootGroup = `nullptr`,
		CSLConstList	papszOptions = `nullptr`
	)		const

virtual

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().

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.
poRootGroup	(Added in GDAL 3.8) Root group. Used with the BAND_METADATA option.
papszOptions	(Added in GDAL 3.8) Null-terminated list of options, or nullptr. Current supported options are: BAND_METADATA: JSON serialized array defining which arrays of the poRootGroup, indexed by non-X and Y dimensions, should be mapped as band metadata items. Each array item should be an object with the following members: "array": full name of a band parameter array. Such array must be a one dimensional array, and its dimension must be one of the dimensions of the array on which the method is called (excluding the X and Y dimensons). "item_name": band metadata item name "item_value": (optional) String, where "%[x][.y]f", "%[x][.y]g" or "%s" printf-like formatting can be used to format the corresponding value of the parameter array. The percentage character should be repeated: "%%" "${attribute_name}" can also be used to include the value of an attribute for the array. If "item_value" is not provided, a default formatting of the value will be applied. Example: [ { "array": "/sensor_band_parameters/wavelengths", "item_name": "WAVELENGTH", "item_value": "%.1f ${units}" }, { "array": "/sensor_band_parameters/fwhm", "item_name": "FWHM" }, { "array": "/sensor_band_parameters/fwhm", "item_name": "FWHM_UNIT", "item_value": "${units}" } ] LOAD_EXTRA_DIM_METADATA_DELAY: Maximum delay in seconds allowed to set the DIM_{dimname}_VALUE band metadata items from the indexing variable of the dimensions. Default value is 5. 'unlimited' can be used to mean unlimited delay. Can also be defined globally with the GDAL_LOAD_EXTRA_DIM_METADATA_DELAY configuration option.

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

◆ at()

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

inline

Return a view of the array using integer indexing.

Equivalent of GetView("[indices_0,indices_1,.....,indices_last]")

Example:

ar->at(0,3,2)

GDALMDArray::Cache

bool Cache(CSLConstList papszOptions=nullptr) const

Cache the content of the array into an auxiliary filename.

Definition gdalmultidim.cpp:4336

◆ Cache()

bool GDALMDArray::Cache ( CSLConstList papszOptions = nullptr ) const

Cache the content of the array into an auxiliary filename.

The main purpose of this method is to be able to cache views that are expensive to compute, such as transposed arrays.

The array will be stored in a file whose name is the one of GetFilename(), with an extra .gmac extension (stands for GDAL Multidimensional Array Cache). The cache is a netCDF dataset.

If the .gmac file cannot be written next to the dataset, the GDAL_PAM_PROXY_DIR will be used, if set, to write the cache file into that directory.

The GDALMDArray::Read() method will automatically use the cache when it exists. There is no timestamp checks between the source array and the cached array. If the source arrays changes, the cache must be manually deleted.

This is the same as the C function GDALMDArrayCache()

Note: Driver implementation: optionally implemented.

Parameters

papszOptions List of options, null terminated, or NULL. Currently the only option supported is BLOCKSIZE=bs0,bs1,...,bsN to specify the block size of the cached array.

Returns: true in case of success.

◆ ClearStatistics()

void GDALMDArray::ClearStatistics ( )

virtual

Clear statistics.

Since: GDAL 3.4

◆ ComputeStatistics()

bool GDALMDArray::ComputeStatistics	(	bool	bApproxOK,
		double *	pdfMin,
		double *	pdfMax,
		double *	pdfMean,
		double *	pdfStdDev,
		GUInt64 *	pnValidCount,
		GDALProgressFunc	pfnProgress,
		void *	pProgressData,
		CSLConstList	papszOptions
	)

virtual

Compute statistics.

Returns the minimum, maximum, mean and standard deviation of all pixel values in this array.

Pixels taken into account in statistics are those whose mask value (as determined by GetMask()) is non-zero.

Once computed, the statistics will generally be "set" back on the owing dataset.

Cached statistics can be cleared with GDALDataset::ClearStatistics().

This method is the same as the C functions GDALMDArrayComputeStatistics(). and GDALMDArrayComputeStatisticsEx().

Parameters

bApproxOK	Currently ignored. In the future, should be set to true if statistics on the whole array are wished, or to false if a subset of it may be used.
pdfMin	Location into which to load image minimum (may be NULL).
pdfMax	Location into which to load image maximum (may be NULL).-
pdfMean	Location into which to load image mean (may be NULL).
pdfStdDev	Location into which to load image standard deviation (may be NULL).
pnValidCount	Number of samples whose value is different from the nodata value. (may be NULL)
pfnProgress	a function to call to report progress, or NULL.
pProgressData	application data to pass to the progress function.
papszOptions	NULL-terminated list of options, of NULL. Added in 3.8. Options are driver specific. For now the netCDF and Zarr drivers recognize UPDATE_METADATA=YES, whose effect is to add or update the actual_range attribute with the computed min/max, only if done on the full array, in non approximate mode, and the dataset is opened in update mode.

Returns: true on success

Since: GDAL 3.2

◆ CopyFrom()

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

virtual

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

Parameters

poSrcDS	Source dataset. Might be nullptr (but for correct behavior of some output drivers this is not recommended)
poSrcArray	Source array. Should NOT be nullptr.
bStrict	Whether to enable strict 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.

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

◆ CreateAttribute()

std::shared_ptr< GDALAttribute > GDALIHasAttribute::CreateAttribute	(	const std::string &	osName,
		const std::vector< GUInt64 > &	anDimensions,
		const GDALExtendedDataType &	oDataType,
		CSLConstList	papszOptions = `nullptr`
	)

virtualinherited

Create an attribute within a GDALMDArray or GDALGroup.

The attribute might not be "physically" created until a value is written into it.

Optionally implemented.

Drivers known to implement it: MEM, netCDF

This is the same as the C function GDALGroupCreateAttribute() or GDALMDArrayCreateAttribute()

Parameters

osName	Attribute name.
anDimensions	List of dimension sizes, ordered from the slowest varying dimension first to the fastest varying dimension last. Empty for a scalar attribute (common case)
oDataType	Attribute data type.
papszOptions	Driver specific options determining how the attribute. should be created.

Returns: the new attribute, or nullptr if case of error

◆ DeleteAttribute()

bool GDALIHasAttribute::DeleteAttribute	(	const std::string &	osName,
		CSLConstList	papszOptions = `nullptr`
	)

virtualinherited

Delete an attribute from a GDALMDArray or GDALGroup.

Optionally implemented.

After this call, if a previously obtained instance of the deleted object is still alive, no method other than for freeing it should be invoked.

Drivers known to implement it: MEM, netCDF

This is the same as the C function GDALGroupDeleteAttribute() or GDALMDArrayDeleteAttribute()

Parameters

osName	Attribute name.
papszOptions	Driver specific options determining how the attribute. should be deleted.

Returns: true in case of success

Since: GDAL 3.8

◆ GetAttribute()

std::shared_ptr< GDALAttribute > GDALIHasAttribute::GetAttribute ( const std::string & osName ) const

virtualinherited

Return an attribute by its name.

If the attribute does not exist, nullptr should be silently returned.

Note: Driver implementation: this method will fallback to GetAttributeFromAttributes() is not explicitly implemented

Drivers known to implement it for groups and arrays: MEM, netCDF.

This is the same as the C function GDALGroupGetAttribute() or GDALMDArrayGetAttribute().

Parameters

osName Attribute name

Returns: the attribute, or nullptr if it does not exist or an error occurred.

◆ GetAttributes()

std::vector< std::shared_ptr< GDALAttribute > > GDALIHasAttribute::GetAttributes ( CSLConstList papszOptions = nullptr ) const

virtualinherited

Return the list of attributes contained in a GDALMDArray or GDALGroup.

If the attribute does not exist, nullptr should be silently returned.

Note: Driver implementation: optionally implemented. If implemented, GetAttribute() should also be implemented.

Drivers known to implement it for groups and arrays: MEM, netCDF.

This is the same as the C function GDALGroupGetAttributes() or GDALMDArrayGetAttributes().

Parameters

papszOptions Driver specific options determining how attributes should be retrieved. Pass nullptr for default behavior.

Returns: the attributes.

◆ GetBlockSize()

std::vector< GUInt64 > GDALAbstractMDArray::GetBlockSize ( ) const

virtualinherited

Return the "natural" block size of the array along all dimensions.

Some drivers might organize the array in tiles/blocks and reading/writing aligned on those tile/block boundaries will be more efficient.

The returned number of elements in the vector is the same as GetDimensionCount(). A value of 0 should be interpreted as no hint regarding the natural block size along the considered dimension. "Flat" arrays will typically return a vector of values set to 0.

The default implementation will return a vector of values set to 0.

This method is used by GetProcessingChunkSize().

Pedantic note: the returned type is GUInt64, so in the highly unlikeley theoretical case of a 32-bit platform, this might exceed its size_t allocation capabilities.

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

Returns: the block size, in number of elements along each dimension.

◆ GetCoordinateVariables()

std::vector< std::shared_ptr< GDALMDArray > > GDALMDArray::GetCoordinateVariables ( ) const

virtual

Return coordinate variables.

Coordinate variables are an alternate way of indexing an array that can be sometimes used. For example, an array collected through remote sensing might be indexed by (scanline, pixel). But there can be a longitude and latitude arrays alongside that are also both indexed by (scanline, pixel), and are referenced from operational arrays for reprojection purposes.

For netCDF, this will return the arrays referenced by the "coordinates" attribute.

This method is the same as the C function GDALMDArrayGetCoordinateVariables().

Returns: a vector of arrays

Since: GDAL 3.4

◆ GetDataType()

GDALAbstractMDArray::GetDataType ( ) const

pure virtualinherited

Return the data type of an attribute/array.

This is the same as the C functions GDALMDArrayGetDataType() and GDALAttributeGetDataType()

◆ GetDimensionCount()

size_t GDALAbstractMDArray::GetDimensionCount ( ) const

virtualinherited

Return the number of dimensions.

Default implementation is GetDimensions().size(), and may be overridden by drivers if they have a faster / less expensive implementations.

This is the same as the C function GDALMDArrayGetDimensionCount() or GDALAttributeGetDimensionCount().

◆ GetDimensions()

GDALAbstractMDArray::GetDimensions ( ) const

pure virtualinherited

Return the dimensions of an attribute/array.

This is the same as the C functions GDALMDArrayGetDimensions() and similar to GDALAttributeGetDimensionsSize().

◆ GetFilename()

virtual const std::string & GDALMDArray::GetFilename ( ) const

pure virtual

Return the filename that contains that array.

This is used in particular for caching.

Might be empty if the array is not linked to a file.

Since: GDAL 3.4

◆ GetFullName()

const std::string & GDALAbstractMDArray::GetFullName ( ) const

inlineinherited

Return the name of an array or attribute.

This is the same as the C function GDALMDArrayGetFullName() or GDALAttributeGetFullName().

◆ GetGridded()

std::shared_ptr< GDALMDArray > GDALMDArray::GetGridded	(	const std::string &	osGridOptions,
		const std::shared_ptr< GDALMDArray > &	poXArrayIn = `nullptr`,
		const std::shared_ptr< GDALMDArray > &	poYArrayIn = `nullptr`,
		CSLConstList	papszOptions = `nullptr`
	)		const

Return a gridded array from scattered point data, that is from an array whose last dimension is the indexing variable of X and Y arrays.

The gridding is done in 2D, using GDALGridCreate(), on-the-fly at Read() time, taking into account the spatial extent of the request to limit the gridding. The results got on the whole extent or a subset of it might not be strictly identical depending on the gridding algorithm and its radius. Setting a radius in osGridOptions is recommended to improve performance. For arrays which have more dimensions than the dimension of the indexing variable of the X and Y arrays, Read() must be called on slices of the extra dimensions (ie count[i] must be set to 1, except for the X and Y dimensions of the array returned by this method).

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

Parameters

osGridOptions	Gridding algorithm and options. e.g. "invdist:nodata=nan:radius1=1:radius2=1:max_points=5". See documentation of the gdal_grid utility for all options.
poXArrayIn	Single-dimension array containing X values, and whose dimension is the last one of this array. If set to nullptr, the "coordinates" attribute must exist on this array, and the X variable will be the (N-1)th one mentioned in it, unless there is a "x" or "lon" variable in "coordinates".
poYArrayIn	Single-dimension array containing Y values, and whose dimension is the last one of this array. If set to nullptr, the "coordinates" attribute must exist on this array, and the Y variable will be the (N-2)th one mentioned in it, unless there is a "y" or "lat" variable in "coordinates".
papszOptions	NULL terminated list of options, or nullptr. Supported options are: RESOLUTION=val: Spatial resolution of the returned array. If not set, will be guessed from the typical spacing of (X,Y) points.

Returns: gridded array, or nullptr in case of error.

Since: GDAL 3.7

◆ GetMask()

std::shared_ptr< GDALMDArray > GDALMDArray::GetMask ( CSLConstList papszOptions ) const

virtual

Return an array that is a mask for the current array.

This array will be of type Byte, with values set to 0 to indicate invalid pixels of the current array, and values set to 1 to indicate valid pixels.

The generic implementation honours the NoDataValue, as well as various netCDF CF attributes: missing_value, _FillValue, valid_min, valid_max and valid_range.

Starting with GDAL 3.8, option UNMASK_FLAGS=flag_meaning_1[,flag_meaning_2,...] can be used to specify strings of the "flag_meanings" attribute (cf https://cfconventions.org/cf-conventions/cf-conventions.html#flags) for which pixels matching any of those flags will be set at 1 in the mask array, and pixels matching none of those flags will be set at 0. For example, let's consider the following netCDF variable defined with:

l2p_flags:valid_min = 0s ;
l2p_flags:valid_max = 256s ;
l2p_flags:flag_meanings = "microwave land ice lake river reserved_for_future_use unused_currently unused_currently unused_currently" ;
l2p_flags:flag_masks = 1s, 2s, 4s, 8s, 16s, 32s, 64s, 128s, 256s ;

GetMask(["UNMASK_FLAGS=microwave,land"]) will return an array such that:

for pixel values outside valid_range [0,256], the mask value will be 0.
for a pixel value with bit 0 or bit 1 at 1 within [0,256], the mask value will be 1.
for a pixel value with bit 0 and bit 1 at 0 within [0,256], the mask value will be 0.

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

Parameters

papszOptions NULL-terminated list of options, or NULL.

Returns: 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.

◆ GetMeshGrid()

std::vector< std::shared_ptr< GDALMDArray > > GDALMDArray::GetMeshGrid	(	const std::vector< std::shared_ptr< GDALMDArray > > &	apoArrays,
		CSLConstList	papszOptions = `nullptr`
	)

static

Return a list of multidimensional arrays from a list of one-dimensional arrays.

This is typically used to transform one-dimensional longitude, latitude arrays into 2D ones.

More formally, for one-dimensional arrays x1, x2,..., xn with lengths Ni=len(xi), returns (N1, N2, ..., Nn) shaped arrays if indexing="ij" or (N2, N1, ..., Nn) shaped arrays if indexing="xy" with the elements of xi repeated to fill the matrix along the first dimension for x1, the second for x2 and so on.

For example, if x = [1, 2], and y = [3, 4, 5], GetMeshGrid([x, y], ["INDEXING=xy"]) will return [xm, ym] such that xm=[[1, 2],[1, 2],[1, 2]] and ym=[[3, 3],[4, 4],[5, 5]], or more generally xm[any index][i] = x[i] and ym[i][any index]=y[i]

and GetMeshGrid([x, y], ["INDEXING=ij"]) will return [xm, ym] such that xm=[[1, 1, 1],[2, 2, 2]] and ym=[[3, 4, 5],[3, 4, 5]], or more generally xm[i][any index] = x[i] and ym[any index][i]=y[i]

The currently supported options are:

INDEXING=xy/ij: Cartesian ("xy", default) or matrix ("ij") indexing of output.

This is the same as numpy.meshgrid() function.

This is the same as the C function GDALMDArrayGetMeshGrid()

Parameters

apoArrays	Input arrays
papszOptions	NULL, or NULL terminated list of options.

Returns: an array of coordinate matrices

Since: 3.10

◆ GetName()

const std::string & GDALAbstractMDArray::GetName ( ) const

inlineinherited

Return the name of an array or attribute.

This is the same as the C function GDALMDArrayGetName() or GDALAttributeGetName().

◆ GetNoDataValueAsDouble()

double GDALMDArray::GetNoDataValueAsDouble ( bool * pbHasNoData = nullptr ) const

Return the nodata value as a double.

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

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.

Returns: 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).

◆ GetNoDataValueAsInt64()

int64_t GDALMDArray::GetNoDataValueAsInt64 ( bool * pbHasNoData = nullptr ) const

Return the nodata value as a Int64.

Parameters

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

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

Returns: the nodata value as a Int64

Since: GDAL 3.5

◆ GetNoDataValueAsUInt64()

uint64_t GDALMDArray::GetNoDataValueAsUInt64 ( bool * pbHasNoData = nullptr ) const

Return the nodata value as a UInt64.

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

Parameters

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

Returns: the nodata value as a UInt64

Since: GDAL 3.5

◆ GetOffset()

double GDALMDArray::GetOffset	(	bool *	pbHasOffset = `nullptr`,
		GDALDataType *	peStorageType = `nullptr`
	)		const

virtual

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.

Parameters

pbHasOffset	Pointer to a output boolean that will be set to true if a offset value exists. Might be nullptr.
peStorageType	Pointer to a output GDALDataType that will be set to the storage type of the offset value, when known/relevant. Otherwise will be set to GDT_Unknown. Might be nullptr. Since GDAL 3.3

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

◆ GetProcessingChunkSize()

std::vector< size_t > GDALAbstractMDArray::GetProcessingChunkSize ( size_t nMaxChunkMemory ) const

virtualinherited

Return an optimal chunk size for read/write operations, given the natural block size and memory constraints specified.

This method will use GetBlockSize() to define a chunk whose dimensions are multiple of those returned by GetBlockSize() (unless the block define by GetBlockSize() is larger than nMaxChunkMemory, in which case it will be returned by this method).

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

Parameters

nMaxChunkMemory Maximum amount of memory, in bytes, to use for the chunk.

Returns: the chunk size, in number of elements along each dimension.

◆ GetRawNoDataValue()

const void * GDALMDArray::GetRawNoDataValue ( ) const

virtual

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.

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

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

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

◆ GetResampled()

std::shared_ptr< GDALMDArray > GDALMDArray::GetResampled	(	const std::vector< std::shared_ptr< GDALDimension > > &	apoNewDims,
		GDALRIOResampleAlg	resampleAlg,
		const OGRSpatialReference *	poTargetSRS,
		CSLConstList	papszOptions
	)		const

virtual

Return an array that is a resampled / reprojected view of the current array.

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

Currently this method can only resample along the last 2 dimensions, unless orthorectifying a NASA EMIT dataset.

For NASA EMIT datasets, if apoNewDims[] and poTargetSRS is NULL, the geometry lookup table (GLT) is used by default for fast orthorectification.

Options available are:

EMIT_ORTHORECTIFICATION=YES/NO: defaults to YES for a NASA EMIT dataset. Can be set to NO to use generic reprojection method.
USE_GOOD_WAVELENGTHS=YES/NO: defaults to YES. Only used for EMIT orthorectification to take into account the value of the /sensor_band_parameters/good_wavelengths array to decide if slices of the current array along the band dimension are valid.

Parameters

apoNewDims	New dimensions. Its size should be GetDimensionCount(). apoNewDims[i] can be NULL to let the method automatically determine it.
resampleAlg	Resampling algorithm
poTargetSRS	Target SRS, or nullptr
papszOptions	NULL-terminated list of options, or NULL.

Returns: 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.

Since: 3.4

◆ GetRootGroup()

std::shared_ptr< GDALGroup > GDALMDArray::GetRootGroup ( ) const

virtual

Return the root group to which this arrays belongs too.

Note that arrays may be free standing and some drivers may not implement this method, hence nullptr may be returned.

It is used internally by the GetResampled() method to detect if GLT orthorectification is available.

Returns: the root group, or nullptr.

Since: GDAL 3.8

◆ GetScale()

double GDALMDArray::GetScale	(	bool *	pbHasScale = `nullptr`,
		GDALDataType *	peStorageType = `nullptr`
	)		const

virtual

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.

Parameters

pbHasScale	Pointer to a output boolean that will be set to true if a scale value exists. Might be nullptr.
peStorageType	Pointer to a output GDALDataType that will be set to the storage type of the scale value, when known/relevant. Otherwise will be set to GDT_Unknown. Might be nullptr. Since GDAL 3.3

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

◆ GetSpatialRef()

std::shared_ptr< OGRSpatialReference > GDALMDArray::GetSpatialRef ( ) const

virtual

Return the spatial reference system object associated with the array.

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

◆ GetStatistics()

CPLErr GDALMDArray::GetStatistics	(	bool	bApproxOK,
		bool	bForce,
		double *	pdfMin,
		double *	pdfMax,
		double *	pdfMean,
		double *	pdfStdDev,
		GUInt64 *	pnValidCount,
		GDALProgressFunc	pfnProgress,
		void *	pProgressData
	)

virtual

Fetch statistics.

Returns the minimum, maximum, mean and standard deviation of all pixel values in this array.

If bForce is FALSE results will only be returned if it can be done quickly (i.e. without scanning the data). If bForce is FALSE and results cannot be returned efficiently, the method will return CE_Warning but no warning will have been issued. This is a non-standard use of the CE_Warning return value to indicate "nothing done".

When cached statistics are not available, and bForce is TRUE, ComputeStatistics() is called.

Note that file formats using PAM (Persistent Auxiliary Metadata) services will generally cache statistics in the .aux.xml file allowing fast fetch after the first request.

Cached statistics can be cleared with GDALDataset::ClearStatistics().

This method is the same as the C function GDALMDArrayGetStatistics().

Parameters

bApproxOK	Currently ignored. In the future, should be set to true if statistics on the whole array are wished, or to false if a subset of it may be used.
bForce	If false statistics will only be returned if it can be done without rescanning the image.
pdfMin	Location into which to load image minimum (may be NULL).
pdfMax	Location into which to load image maximum (may be NULL).-
pdfMean	Location into which to load image mean (may be NULL).
pdfStdDev	Location into which to load image standard deviation (may be NULL).
pnValidCount	Number of samples whose value is different from the nodata value. (may be NULL)
pfnProgress	a function to call to report progress, or NULL.
pProgressData	application data to pass to the progress function.

Returns: CE_None on success, CE_Warning if no values returned, CE_Failure if an error occurs.

Since: GDAL 3.2

◆ GetStructuralInfo()

CSLConstList GDALMDArray::GetStructuralInfo ( ) const

virtual

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 GDALMDArrayGetStructuralInfo().

◆ GetTotalCopyCost()

GUInt64 GDALMDArray::GetTotalCopyCost ( ) const

Return a total "cost" to copy the array.

Used as a parameter for CopyFrom()

◆ GetTotalElementsCount()

GUInt64 GDALAbstractMDArray::GetTotalElementsCount ( ) const

inherited

Return the total number of values in the array.

This is the same as the C functions GDALMDArrayGetTotalElementsCount() and GDALAttributeGetTotalElementsCount().

◆ GetUnit()

const std::string & GDALMDArray::GetUnit ( ) const

virtual

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()

◆ GetUnscaled()

std::shared_ptr< GDALMDArray > GDALMDArray::GetUnscaled	(	double	dfOverriddenScale = `std::numeric_limits<double>::quiet_NaN()`,
		double	dfOverriddenOffset = `std::numeric_limits<double>::quiet_NaN()`,
		double	dfOverriddenDstNodata = `std::numeric_limits<double>::quiet_NaN()`
	)		const

Return an array that is the unscaled version of the current one.

That is each value of the unscaled array will be unscaled_value = raw_value * GetScale() + GetOffset()

Starting with GDAL 3.3, the Write() method is implemented and will convert from unscaled values to raw values.

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

Parameters

dfOverriddenScale	Custom scale value instead of GetScale()
dfOverriddenOffset	Custom offset value instead of GetOffset()
dfOverriddenDstNodata	Custom target nodata value instead of NaN

Returns: 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.

◆ GetView()

std::shared_ptr< GDALMDArray > 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 additional dimension of size 1 put at the beginning. That is [[[0,1,2,3],[4,5,6,7]]].

One difference with NumPy behavior 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']. Multiple field specification is not supported currently.

Both type of access can be combined, e.g. GetView("[1]['field_name']")

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']"); When using the C++ API and integer indexing only, you may use the at(idx0, idx1, ...) 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. When using basic slicing and indexing, the view can be written if the underlying array is writable.

This is the same as the C function GDALMDArrayGetView()

Parameters

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

Returns: 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.

◆ GuessGeoTransform()

bool GDALMDArray::GuessGeoTransform	(	size_t	nDimX,
		size_t	nDimY,
		bool	bPixelIsPoint,
		double	adfGeoTransform[6]
	)		const

Returns whether 2 specified dimensions form a geotransform.

Parameters

	nDimX	Index of the X axis.
	nDimY	Index of the Y axis.
	bPixelIsPoint	Whether the geotransform should be returned with the pixel-is-point (pixel-center) convention (bPixelIsPoint = true), or with the pixel-is-area (top left corner convention) (bPixelIsPoint = false)
[out]	adfGeoTransform	Computed geotransform

Returns: true if a geotransform could be computed.

◆ IsRegularlySpaced()

bool GDALMDArray::IsRegularlySpaced	(	double &	dfStart,
		double &	dfIncrement
	)		const

Returns whether an array is a 1D regularly spaced array.

Parameters

[out]	dfStart	First value in the array
[out]	dfIncrement	Increment/spacing between consecutive values.

Returns: true if the array is regularly spaced.

◆ operator[]()

std::shared_ptr< GDALMDArray > 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.

◆ ProcessPerChunk()

bool GDALAbstractMDArray::ProcessPerChunk	(	const GUInt64 *	arrayStartIdx,
		const GUInt64 *	count,
		const size_t *	chunkSize,
		FuncProcessPerChunkType	pfnFunc,
		void *	pUserData
	)

virtualinherited

Call a user-provided function to operate on an array chunk by chunk.

This method is to be used when doing operations on an array, or a subset of it, in a chunk by chunk way.

Parameters

arrayStartIdx	Values representing the starting index to use in each dimension (in [0, aoDims[i].GetSize()-1] range). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
count	Values representing the number of values to use in each dimension. Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
chunkSize	Values representing the chunk size in each dimension. Might typically the output of GetProcessingChunkSize(). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
pfnFunc	User-provided function of type FuncProcessPerChunkType. Must NOT be nullptr.
pUserData	Pointer to pass as the value of the pUserData argument of FuncProcessPerChunkType. Might be nullptr (depends on pfnFunc.

Returns: true in case of success.

◆ Read()

bool GDALMDArray::Read	(	const GUInt64 *	arrayStartIdx,
		const size_t *	count,
		const GInt64 *	arrayStep,
		const GPtrDiff_t *	bufferStride,
		const GDALExtendedDataType &	bufferDataType,
		void *	pDstBuffer,
		const void *	pDstBufferAllocStart = `nullptr`,
		size_t	nDstBufferAllocSize = `0`
	)		const

overridevirtual

Read part or totality of a multidimensional array or attribute.

This will extract the content of a hyper-rectangle from the array into a user supplied buffer.

If bufferDataType is of type string, the values written in pDstBuffer will be char* pointers and the strings should be freed with CPLFree().

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

Parameters

arrayStartIdx	Values representing the starting index to read in each dimension (in [0, aoDims[i].GetSize()-1] range). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
count	Values representing the number of values to extract in each dimension. Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
arrayStep	Spacing between values to extract in each dimension. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. If set to nullptr, [1, 1, ... 1] will be used as a default to indicate consecutive elements.
bufferStride	Spacing between values to store in pDstBuffer. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. Negative values are possible (for example to reorder from bottom-to-top to top-to-bottom). If set to nullptr, will be set so that pDstBuffer is written in a compact way, with elements of the last / fastest varying dimension being consecutive.
bufferDataType	Data type of values in pDstBuffer.
pDstBuffer	User buffer to store the values read. Should be big enough to store the number of values indicated by count[] and with the spacing of bufferStride[].
pDstBufferAllocStart	Optional pointer that can be used to validate the validity of pDstBuffer. pDstBufferAllocStart should be the pointer returned by the malloc() or equivalent call used to allocate the buffer. It will generally be equal to pDstBuffer (when bufferStride[] values are all positive), but not necessarily. If specified, nDstBufferAllocSize should be also set to the appropriate value. If no validation is needed, nullptr can be passed.
nDstBufferAllocSize	Optional buffer size, that can be used to validate the validity of pDstBuffer. This is the size of the buffer starting at pDstBufferAllocStart. If specified, pDstBufferAllocStart should be also set to the appropriate value. If no validation is needed, 0 can be passed.

Returns: true in case of success.

Reimplemented from GDALAbstractMDArray.

◆ Rename()

bool GDALAbstractMDArray::Rename ( const std::string & osNewName )

virtualinherited

Rename the attribute/array.

This is not implemented by all drivers.

Drivers known to implement it: MEM, netCDF, Zarr.

This is the same as the C functions GDALMDArrayRename() or GDALAttributeRename().

Parameters

osNewName New name.

Returns: true in case of success

Since: GDAL 3.8

◆ Resize()

bool GDALMDArray::Resize	(	const std::vector< GUInt64 > &	anNewDimSizes,
		CSLConstList	papszOptions
	)

virtual

Resize an array to new dimensions.

Not all drivers may allow this operation, and with restrictions (e.g. for netCDF, this is limited to growing of "unlimited" dimensions)

Resizing a dimension used in other arrays will cause those other arrays to be resized.

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

Parameters

anNewDimSizes	Array of GetDimensionCount() values containing the new size of each indexing dimension.
papszOptions	Options. (Driver specific)

Returns: true in case of success.

Since: GDAL 3.7

◆ SetNoDataValue() [1/3]

bool GDALMDArray::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().

Returns: true in case of success.

◆ SetNoDataValue() [2/3]

bool GDALMDArray::SetNoDataValue ( int64_t nNoData )

Set the nodata value as a Int64.

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

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

Returns: true in case of success.

Since: GDAL 3.5

◆ SetNoDataValue() [3/3]

bool GDALMDArray::SetNoDataValue ( uint64_t nNoData )

Set the nodata value as a Int64.

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

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

Returns: true in case of success.

Since: GDAL 3.5

◆ SetOffset()

bool GDALMDArray::SetOffset	(	double	dfOffset,
		GDALDataType	eStorageType = `GDT_Unknown`
	)

virtual

Set the offset value to apply to raw values.

unscaled_value = raw_value * GetScale() + GetOffset()

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

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

Parameters

dfOffset	Offset
eStorageType	Data type to which create the potential attribute that will store the offset. Added in GDAL 3.3 If let to its GDT_Unknown value, the implementation will decide automatically the data type. Note that changing the data type after initial setting might not be supported.

Returns: true in case of success.

◆ SetRawNoDataValue()

bool GDALMDArray::SetRawNoDataValue ( const void * pRawNoData )

virtual

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.

Returns: true in case of success.

◆ SetScale()

bool GDALMDArray::SetScale	(	double	dfScale,
		GDALDataType	eStorageType = `GDT_Unknown`
	)

virtual

Set the scale value to apply to raw values.

unscaled_value = raw_value * GetScale() + GetOffset()

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

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

Parameters

dfScale	scale
eStorageType	Data type to which create the potential attribute that will store the scale. Added in GDAL 3.3 If let to its GDT_Unknown value, the implementation will decide automatically the data type. Note that changing the data type after initial setting might not be supported.

Returns: true in case of success.

◆ SetSpatialRef()

bool GDALMDArray::SetSpatialRef ( const OGRSpatialReference * poSRS )

virtual

Assign a spatial reference system object to the array.

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

◆ SetUnit()

bool GDALMDArray::SetUnit ( const std::string & osUnit )

virtual

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.

Parameters

osUnit unit name.

Returns: true in case of success.

◆ Transpose()

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

virtual

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().

Returns: 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.

◆ Write()

bool GDALAbstractMDArray::Write	(	const GUInt64 *	arrayStartIdx,
		const size_t *	count,
		const GInt64 *	arrayStep,
		const GPtrDiff_t *	bufferStride,
		const GDALExtendedDataType &	bufferDataType,
		const void *	pSrcBuffer,
		const void *	pSrcBufferAllocStart = `nullptr`,
		size_t	nSrcBufferAllocSize = `0`
	)

inherited

Write part or totality of a multidimensional array or attribute.

This will set the content of a hyper-rectangle into the array from a user supplied buffer.

If bufferDataType is of type string, the values read from pSrcBuffer will be char* pointers.

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

Parameters

arrayStartIdx	Values representing the starting index to write in each dimension (in [0, aoDims[i].GetSize()-1] range). Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
count	Values representing the number of values to write in each dimension. Array of GetDimensionCount() values. Must not be nullptr, unless for a zero-dimensional array.
arrayStep	Spacing between values to write in each dimension. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. If set to nullptr, [1, 1, ... 1] will be used as a default to indicate consecutive elements.
bufferStride	Spacing between values to read from pSrcBuffer. The spacing is in number of array elements, not bytes. If provided, must contain GetDimensionCount() values. Negative values are possible (for example to reorder from bottom-to-top to top-to-bottom). If set to nullptr, will be set so that pSrcBuffer is written in a compact way, with elements of the last / fastest varying dimension being consecutive.
bufferDataType	Data type of values in pSrcBuffer.
pSrcBuffer	User buffer to read the values from. Should be big enough to store the number of values indicated by count[] and with the spacing of bufferStride[].
pSrcBufferAllocStart	Optional pointer that can be used to validate the validity of pSrcBuffer. pSrcBufferAllocStart should be the pointer returned by the malloc() or equivalent call used to allocate the buffer. It will generally be equal to pSrcBuffer (when bufferStride[] values are all positive), but not necessarily. If specified, nSrcBufferAllocSize should be also set to the appropriate value. If no validation is needed, nullptr can be passed.
nSrcBufferAllocSize	Optional buffer size, that can be used to validate the validity of pSrcBuffer. This is the size of the buffer starting at pSrcBufferAllocStart. If specified, pDstBufferAllocStart should be also set to the appropriate value. If no validation is needed, 0 can be passed.

Returns: true in case of success.

The documentation for this class was generated from the following files:

gdal_priv.h
gdalmultidim.cpp
gdalmultidim_gridded.cpp
gdalmultidim_meshgrid.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ FuncProcessPerChunkType

Member Function Documentation

◆ AdviseRead()

◆ AsClassicDataset()

◆ at()

◆ Cache()

◆ ClearStatistics()

◆ ComputeStatistics()

◆ CopyFrom()

◆ CreateAttribute()

◆ DeleteAttribute()

◆ GetAttribute()

◆ GetAttributes()

◆ GetBlockSize()

◆ GetCoordinateVariables()

◆ GetDataType()

◆ GetDimensionCount()

◆ GetDimensions()

◆ GetFilename()

◆ GetFullName()

◆ GetGridded()

◆ GetMask()

◆ GetMeshGrid()

◆ GetName()

◆ GetNoDataValueAsDouble()

◆ GetNoDataValueAsInt64()

◆ GetNoDataValueAsUInt64()

◆ GetOffset()

◆ GetProcessingChunkSize()

◆ GetRawNoDataValue()

◆ GetResampled()

◆ GetRootGroup()

◆ GetScale()

◆ GetSpatialRef()

◆ GetStatistics()

◆ GetStructuralInfo()

◆ GetTotalCopyCost()

◆ GetTotalElementsCount()

◆ GetUnit()

◆ GetUnscaled()

◆ GetView()

◆ GuessGeoTransform()

◆ IsRegularlySpaced()

◆ operator[]()

◆ ProcessPerChunk()

◆ Read()

◆ Rename()

◆ Resize()

◆ SetNoDataValue() [1/3]

◆ SetNoDataValue() [2/3]

◆ SetNoDataValue() [3/3]

◆ SetOffset()

◆ SetRawNoDataValue()

◆ SetScale()

◆ SetSpatialRef()

◆ SetUnit()

◆ Transpose()

◆ Write()