GDALGroup C++ API
Include file
gdal_priv.h
GDALGroup class
-
class GDALGroup : public GDALIHasAttribute
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
Subclassed by GDALSubsetGroup
Public Functions
-
inline const std::string &GetName() const
Return the name of the group.
This is the same as the C function GDALGroupGetName().
-
inline const std::string &GetFullName() const
Return the full name of the group.
This is the same as the C function GDALGroupGetFullName().
-
virtual std::vector<std::string> GetMDArrayNames(CSLConstList papszOptions = nullptr) const
Return the list of multidimensional array names contained in this group.
Drivers known to implement it: MEM, netCDF.
This is the same as the C function GDALGroupGetMDArrayNames().
Note
Driver implementation: optionally implemented. If implemented, OpenMDArray() should also be implemented.
- Parameters:
papszOptions -- Driver specific options determining how arrays should be retrieved. Pass nullptr for default behavior.
- Returns:
the array names.
-
virtual std::shared_ptr<GDALMDArray> OpenMDArray(const std::string &osName, CSLConstList papszOptions = nullptr) const
Open and return a multidimensional array.
Drivers known to implement it: MEM, netCDF.
This is the same as the C function GDALGroupOpenMDArray().
Note
Driver implementation: optionally implemented. If implemented, GetMDArrayNames() should also be implemented.
- 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.
-
virtual std::vector<std::string> GetGroupNames(CSLConstList papszOptions = nullptr) const
Return the list of sub-groups contained in this group.
Drivers known to implement it: MEM, netCDF.
This is the same as the C function GDALGroupGetGroupNames().
Note
Driver implementation: optionally implemented. If implemented, OpenGroup() should also be implemented.
- Parameters:
papszOptions -- Driver specific options determining how groups should be retrieved. Pass nullptr for default behavior.
- Returns:
the group names.
-
virtual std::shared_ptr<GDALGroup> OpenGroup(const std::string &osName, CSLConstList papszOptions = nullptr) const
Open and return a sub-group.
Drivers known to implement it: MEM, netCDF.
This is the same as the C function GDALGroupOpenGroup().
Note
Driver implementation: optionally implemented. If implemented, GetGroupNames() should also be implemented.
- 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.
-
virtual std::vector<std::string> GetVectorLayerNames(CSLConstList papszOptions = nullptr) const
Return the list of layer names contained in this group.
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().
- Since
GDAL 3.4
Note
Driver implementation: optionally implemented. If implemented, OpenVectorLayer() should also be implemented.
- Parameters:
papszOptions -- Driver specific options determining how layers should be retrieved. Pass nullptr for default behavior.
- Returns:
the vector layer names.
-
virtual OGRLayer *OpenVectorLayer(const std::string &osName, CSLConstList papszOptions = nullptr) const
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)
Drivers known to implement it: MEM, netCDF.
This is the same as the C function GDALGroupOpenVectorLayer().
Note
Driver implementation: optionally implemented. If implemented, GetVectorLayerNames() should also be implemented.
- 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.
-
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.
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.
-
virtual std::shared_ptr<GDALGroup> CreateGroup(const std::string &osName, CSLConstList papszOptions = nullptr)
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.
-
virtual bool DeleteGroup(const std::string &osName, CSLConstList papszOptions = nullptr)
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().
- Since
GDAL 3.8
- Parameters:
osName -- Sub-group name.
papszOptions -- Driver specific options determining how the group. should be deleted.
- Returns:
true in case of success
-
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.
Drivers known to implement it: MEM, netCDF
This is the same as the C function GDALGroupCreateDimension().
Note
Driver implementation: drivers supporting CreateDimension() should implement this method, but do not have necessarily to implement GDALGroup::GetDimensions().
- 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
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
-
virtual bool DeleteMDArray(const std::string &osName, CSLConstList papszOptions = nullptr)
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().
- Since
GDAL 3.8
- Parameters:
osName -- Arrayname.
papszOptions -- Driver specific options determining how the array. should be deleted.
- Returns:
true in case of success
-
GUInt64 GetTotalCopyCost() const
Return a total "cost" to copy the group.
Used as a parameter for CopFrom()
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).
-
virtual CSLConstList GetStructuralInfo() const
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().
-
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.
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.
- Since
GDAL 3.2
- 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()
-
std::shared_ptr<GDALGroup> OpenGroupFromFullname(const std::string &osFullName, CSLConstList papszOptions = nullptr) const
Get a group from its fully qualified name.
- Since
GDAL 3.2
-
std::shared_ptr<GDALDimension> OpenDimensionFromFullname(const std::string &osFullName) const
Get a dimension from its fully qualified name.
-
virtual void ClearStatistics()
Clear statistics.
- Since
GDAL 3.4
-
virtual bool Rename(const std::string &osNewName)
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().
- Since
GDAL 3.8
- Parameters:
osNewName -- New name.
- Returns:
true in case of success
-
std::shared_ptr<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().
- Since
3.8
- Parameters:
osSelection -- Selection criterion.
- Returns:
a virtual group, or nullptr in case of error