Class modeling a named container of GDALAttribute, GDALMDArray, OGRLayer or other GDALGroup. More...

#include <gdal_priv.h>

Inheritance diagram for GDALGroup:

Public Member Functions
const std::string &	GetName () const
	Return the name of the group.

const std::string &	GetFullName () const
	Return the full name of the group.

virtual std::vector< std::string >	GetMDArrayNames (CSLConstList papszOptions=nullptr) const
	Return the list of multidimensional array names contained in this group.

virtual std::shared_ptr< GDALMDArray >	OpenMDArray (const std::string &osName, CSLConstList papszOptions=nullptr) const
	Open and return a multidimensional array.

virtual std::vector< std::string >	GetGroupNames (CSLConstList papszOptions=nullptr) const
	Return the list of sub-groups contained in this group.

virtual std::shared_ptr< GDALGroup >	OpenGroup (const std::string &osName, CSLConstList papszOptions=nullptr) const
	Open and return a sub-group.

virtual std::vector< std::string >	GetVectorLayerNames (CSLConstList papszOptions=nullptr) const
	Return the list of layer names contained in this group.

virtual OGRLayer *	OpenVectorLayer (const std::string &osName, CSLConstList papszOptions=nullptr) const
	Open and return a vector layer.

virtual std::vector< std::shared_ptr< GDALDimension > >	GetDimensions (CSLConstList papszOptions=nullptr) const
	Return the list of dimensions contained in this group and used by its arrays.

virtual std::shared_ptr< GDALGroup >	CreateGroup (const std::string &osName, CSLConstList papszOptions=nullptr)
	Create a sub-group within a group.

virtual bool	DeleteGroup (const std::string &osName, CSLConstList papszOptions=nullptr)
	Delete a sub-group from a group.

virtual std::shared_ptr< GDALDimension >	CreateDimension (const std::string &osName, const std::string &osType, const std::string &osDirection, GUInt64 nSize, CSLConstList papszOptions=nullptr)
	Create a dimension within a group.

virtual std::shared_ptr< GDALMDArray >	CreateMDArray (const std::string &osName, const std::vector< std::shared_ptr< GDALDimension > > &aoDimensions, const GDALExtendedDataType &oDataType, CSLConstList papszOptions=nullptr)
	Create a multidimensional array within a group.

virtual bool	DeleteMDArray (const std::string &osName, CSLConstList papszOptions=nullptr)
	Delete an array from a group.

GUInt64	GetTotalCopyCost () const
	Return a total "cost" to copy the group.

virtual bool	CopyFrom (const std::shared_ptr< GDALGroup > &poDstRootGroup, GDALDataset poSrcDS, const std::shared_ptr< GDALGroup > &poSrcGroup, bool bStrict, GUInt64 &nCurCost, const GUInt64 nTotalCost, GDALProgressFunc pfnProgress, void pProgressData, CSLConstList papszOptions=nullptr)
	Copy the content of a group into a new (generally empty) group.

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

std::shared_ptr< GDALMDArray >	OpenMDArrayFromFullname (const std::string &osFullName, CSLConstList papszOptions=nullptr) const
	Get an array from its fully qualified name.

std::shared_ptr< GDALMDArray >	ResolveMDArray (const std::string &osName, const std::string &osStartingPath, CSLConstList papszOptions=nullptr) const
	Locate an array in a group and its subgroups by name.

std::shared_ptr< GDALGroup >	OpenGroupFromFullname (const std::string &osFullName, CSLConstList papszOptions=nullptr) const
	Get a group from its fully qualified name.

std::shared_ptr< GDALDimension >	OpenDimensionFromFullname (const std::string &osFullName) const
	Get a dimension from its fully qualified name.

virtual void	ClearStatistics ()
	Clear statistics.

virtual bool	Rename (const std::string &osNewName)
	Rename the group.

std::shared_ptr< GDALGroup >	SubsetDimensionFromSelection (const std::string &osSelection) const
	Return a virtual group whose one dimension has been subset according to a selection.

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.

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

Detailed Description

Class modeling a named container of GDALAttribute, GDALMDArray, OGRLayer or other GDALGroup.

Hence GDALGroup can describe a hierarchy of objects.

This is based on the HDF5 group concept

Since: GDAL 3.1

Member Function Documentation

◆ ClearStatistics()

void GDALGroup::ClearStatistics ( )

virtual

Clear statistics.

Since: GDAL 3.4

◆ CopyFrom()

bool GDALGroup::CopyFrom	(	const std::shared_ptr< GDALGroup > &	poDstRootGroup,
		GDALDataset *	poSrcDS,
		const std::shared_ptr< GDALGroup > &	poSrcGroup,
		bool	bStrict,
		GUInt64 &	nCurCost,
		const GUInt64	nTotalCost,
		GDALProgressFunc	pfnProgress,
		void *	pProgressData,
		CSLConstList	papszOptions = `nullptr`
	)

virtual

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

Parameters

poDstRootGroup	Destination root group. Must NOT be nullptr.
poSrcDS	Source dataset. Might be nullptr (but for correct behavior of some output drivers this is not recommended)
poSrcGroup	Source group. Must 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.
papszOptions	Creation options. Currently, only array creation options are supported. They must be prefixed with "ARRAY:" . The scope may be further restricted to arrays of a certain dimension by adding "IF(DIM={ndims}):" after "ARRAY:". For example, "ARRAY:IF(DIM=2):BLOCKSIZE=256,256" will restrict BLOCKSIZE=256,256 to arrays of dimension 2. Restriction to arrays of a given name is done with adding "IF(NAME={name}):" after "ARRAY:". {name} can also be a full qualified name. A non-driver specific ARRAY option, "AUTOSCALE=YES" can be used to ask (non indexing) variables of type Float32 or Float64 to be scaled to UInt16 with scale and offset values being computed from the minimum and maximum of the source array. The integer data type used can be set with AUTOSCALE_DATA_TYPE=Byte/UInt16/Int16/UInt32/Int32.

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

◆ CreateDimension()

std::shared_ptr< GDALDimension > GDALGroup::CreateDimension	(	const std::string &	osName,
		const std::string &	osType,
		const std::string &	osDirection,
		GUInt64	nSize,
		CSLConstList	papszOptions = `nullptr`
	)

virtual

Create a dimension within a group.

Note: Driver implementation: drivers supporting CreateDimension() should implement this method, but do not have necessarily to implement GDALGroup::GetDimensions().

Drivers known to implement it: MEM, netCDF

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

Parameters

osName	Dimension name.
osType	Dimension type (might be empty, and ignored by drivers)
osDirection	Dimension direction (might be empty, and ignored by drivers)
nSize	Number of values indexed by this dimension. Should be > 0.
papszOptions	Driver specific options determining how the dimension should be created.

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

◆ CreateGroup()

std::shared_ptr< GDALGroup > GDALGroup::CreateGroup	(	const std::string &	osName,
		CSLConstList	papszOptions = `nullptr`
	)

virtual

Create a sub-group within a group.

Optionally implemented by drivers.

Drivers known to implement it: MEM, netCDF

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

Parameters

osName	Sub-group name.
papszOptions	Driver specific options determining how the sub-group should be created.

Returns: the new sub-group, or nullptr in case of error.

◆ CreateMDArray()

std::shared_ptr< GDALMDArray > GDALGroup::CreateMDArray	(	const std::string &	osName,
		const std::vector< std::shared_ptr< GDALDimension > > &	aoDimensions,
		const GDALExtendedDataType &	oDataType,
		CSLConstList	papszOptions = `nullptr`
	)

virtual

Create a multidimensional array within a group.

It is recommended that the GDALDimension objects passed in aoDimensions belong to this group, either by retrieving them with GetDimensions() or creating a new one with CreateDimension().

Optionally implemented.

Drivers known to implement it: MEM, netCDF

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

Note: Driver implementation: drivers should take into account the possibility that GDALDimension object passed in aoDimensions might belong to a different group / dataset / driver and act accordingly.

Parameters

osName	Array name.
aoDimensions	List of dimensions, ordered from the slowest varying dimension first to the fastest varying dimension last. Might be empty for a scalar array (if supported by driver)
oDataType	Array data type.
papszOptions	Driver specific options determining how the array should be created.

Returns: the new array, 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

◆ DeleteGroup()

bool GDALGroup::DeleteGroup	(	const std::string &	osName,
		CSLConstList	papszOptions = `nullptr`
	)

virtual

Delete a sub-group from a group.

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, Zarr

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

Parameters

osName	Sub-group name.
papszOptions	Driver specific options determining how the group. should be deleted.

Returns: true in case of success

Since: GDAL 3.8

◆ DeleteMDArray()

bool GDALGroup::DeleteMDArray	(	const std::string &	osName,
		CSLConstList	papszOptions = `nullptr`
	)

virtual

Delete an array from a group.

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, Zarr

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

Parameters

osName	Arrayname.
papszOptions	Driver specific options determining how the array. 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.

◆ GetDimensions()

std::vector< std::shared_ptr< GDALDimension > > GDALGroup::GetDimensions ( CSLConstList papszOptions = nullptr ) const

virtual

Return the list of dimensions contained in this group and used by its arrays.

This is for dimensions that can potentially be used by several arrays. Not all drivers might implement this. To retrieve the dimensions used by a specific array, use GDALMDArray::GetDimensions().

Drivers known to implement it: MEM, netCDF

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

Parameters

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

Returns: the dimensions.

◆ GetFullName()

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

inline

Return the full name of the group.

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

◆ GetGroupNames()

std::vector< std::string > GDALGroup::GetGroupNames ( CSLConstList papszOptions = nullptr ) const

virtual

Return the list of sub-groups contained in this group.

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

Drivers known to implement it: MEM, netCDF.

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

Parameters

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

Returns: the group names.

◆ GetMDArrayNames()

std::vector< std::string > GDALGroup::GetMDArrayNames ( CSLConstList papszOptions = nullptr ) const

virtual

Return the list of multidimensional array names contained in this group.

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

Drivers known to implement it: MEM, netCDF.

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

Parameters

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

Returns: the array names.

◆ GetName()

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

inline

Return the name of the group.

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

◆ GetStructuralInfo()

CSLConstList GDALGroup::GetStructuralInfo ( ) const

virtual

Return structural information on the group.

This may be the compression, etc..

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

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

◆ GetTotalCopyCost()

GUInt64 GDALGroup::GetTotalCopyCost ( ) const

Return a total "cost" to copy the group.

Used as a parameter for CopFrom()

◆ GetVectorLayerNames()

std::vector< std::string > GDALGroup::GetVectorLayerNames ( CSLConstList papszOptions = nullptr ) const

virtual

Return the list of layer names contained in this group.

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

Drivers known to implement it: OpenFileGDB, FileGDB

Other drivers will return an empty list. GDALDataset::GetLayerCount() and GDALDataset::GetLayer() should then be used.

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

Parameters

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

Returns: the vector layer names.

Since: GDAL 3.4

◆ OpenGroup()

std::shared_ptr< GDALGroup > GDALGroup::OpenGroup	(	const std::string &	osName,
		CSLConstList	papszOptions = `nullptr`
	)		const

virtual

Open and return a sub-group.

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

Drivers known to implement it: MEM, netCDF.

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

Parameters

osName	Sub-group name.
papszOptions	Driver specific options determining how the sub-group should be opened. Pass nullptr for default behavior.

Returns: the group, or nullptr.

◆ OpenGroupFromFullname()

std::shared_ptr< GDALGroup > GDALGroup::OpenGroupFromFullname	(	const std::string &	osFullName,
		CSLConstList	papszOptions = `nullptr`
	)		const

Get a group from its fully qualified name.

Since: GDAL 3.2

◆ OpenMDArray()

std::shared_ptr< GDALMDArray > GDALGroup::OpenMDArray	(	const std::string &	osName,
		CSLConstList	papszOptions = `nullptr`
	)		const

virtual

Open and return a multidimensional array.

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

Drivers known to implement it: MEM, netCDF.

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

Parameters

osName	Array name.
papszOptions	Driver specific options determining how the array should be opened. Pass nullptr for default behavior.

Returns: the array, or nullptr.

◆ OpenVectorLayer()

OGRLayer * GDALGroup::OpenVectorLayer	(	const std::string &	osName,
		CSLConstList	papszOptions = `nullptr`
	)		const

virtual

Open and return a vector layer.

Due to the historical ownership of OGRLayer* by GDALDataset*, the lifetime of the returned OGRLayer* is linked to the one of the owner dataset (contrary to the general design of this class where objects can be used independently of the object that returned them)

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

Drivers known to implement it: MEM, netCDF.

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

Parameters

osName	Vector layer name.
papszOptions	Driver specific options determining how the layer should be opened. Pass nullptr for default behavior.

Returns: the group, or nullptr.

◆ Rename()

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

virtual

Rename the group.

This is not implemented by all drivers.

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

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

Parameters

osNewName New name.

Returns: true in case of success

Since: GDAL 3.8

◆ ResolveMDArray()

std::shared_ptr< GDALMDArray > GDALGroup::ResolveMDArray	(	const std::string &	osName,
		const std::string &	osStartingPath,
		CSLConstList	papszOptions = `nullptr`
	)		const

Locate an array in a group and its subgroups by name.

If osName is a fully qualified name, then OpenMDArrayFromFullname() is first used Otherwise the search will start from the group identified by osStartingPath, and an array whose name is osName will be looked for in this group (if osStartingPath is empty or "/", then the current group is used). If there is no match, then a recursive descendent search will be made in its subgroups. If there is no match in the subgroups, then the parent (if existing) of the group pointed by osStartingPath will be used as the new starting point for the search.

Parameters

osName	name, qualified or not
osStartingPath	fully qualified name of the (sub-)group from which the search should be started. If this is a non-empty string, the group on which this method is called should nominally be the root group (otherwise the path will be interpreted as from the current group)
papszOptions	options to pass to OpenMDArray()

Since: GDAL 3.2

◆ SubsetDimensionFromSelection()

std::shared_ptr< GDALGroup > GDALGroup::SubsetDimensionFromSelection ( const std::string & osSelection ) const

Return a virtual group whose one dimension has been subset according to a selection.

The selection criterion is currently restricted to the form "/path/to/array=numeric_value" (no spaces around equal)

This is similar to XArray indexing by name and label on a XArray Dataset using the sel() method. Cf https://docs.xarray.dev/en/latest/user-guide/indexing.html#quick-overview

For example on a EMIT L2A product (https://github.com/nasa/EMIT-Data-Resources/blob/main/python/tutorials/Exploring_EMIT_L2A_Reflectance.ipynb), this can be used to keep only valid bands with SubsetDimensionFromSelection("/sensor_band_parameters/good_wavelengths=1")

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

Parameters

osSelection Selection criterion.

Returns: a virtual group, or nullptr in case of error

Since: 3.8

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

gdal_priv.h
gdalmultidim.cpp
gdalmultidim_subsetdimension.cpp

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ ClearStatistics()

◆ CopyFrom()

◆ CreateAttribute()

◆ CreateDimension()

◆ CreateGroup()

◆ CreateMDArray()

◆ DeleteAttribute()

◆ DeleteGroup()

◆ DeleteMDArray()

◆ GetAttribute()

◆ GetAttributes()

◆ GetDimensions()

◆ GetFullName()

◆ GetGroupNames()

◆ GetMDArrayNames()

◆ GetName()

◆ GetStructuralInfo()

◆ GetTotalCopyCost()

◆ GetVectorLayerNames()

◆ OpenGroup()

◆ OpenGroupFromFullname()

◆ OpenMDArray()

◆ OpenVectorLayer()

◆ Rename()

◆ ResolveMDArray()

◆ SubsetDimensionFromSelection()