GDALGroup C++ API¶
-
class
GDALGroup
: public GDALIHasAttribute¶ Class modeling a named container of GDALAttribute, GDALMDArray or other GDALGroup.
Hence GDALGroup can describe a hierarchy of objects.
This is based on the HDF5 group concept
- Since
GDAL 3.1
Public Functions
-
const std::string &
GetName
() const¶ Return the name of the group.
This is the same as the C function GDALGroupGetName().
-
const std::string &
GetFullName
() const¶ Return the full name of the group.
This is the same as the C function GDALGroupGetFullName().
-
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.
- Note
Driver implementation: optionally implemented. If implemented, OpenMDArray() should also be implemented.
This is the same as the C function GDALGroupGetMDArrayNames().
- Return
the array names.
- Parameters
papszOptions
: Driver specific options determining how arrays should be retrieved. Pass nullptr for default behaviour.
-
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.
- Note
Driver implementation: optionally implemented. If implemented, GetMDArrayNames() should also be implemented.
This is the same as the C function GDALGroupOpenMDArray().
- Return
the array, or nullptr.
- Parameters
osName
: Array name.papszOptions
: Driver specific options determining how the array should be opened. Pass nullptr for default behaviour.
-
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.
- Note
Driver implementation: optionally implemented. If implemented, OpenGroup() should also be implemented.
This is the same as the C function GDALGroupGetGroupNames().
- Return
the group names.
- Parameters
papszOptions
: Driver specific options determining how groups should be retrieved. Pass nullptr for default behaviour.
-
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.
- Note
Driver implementation: optionally implemented. If implemented, GetGroupNames() should also be implemented.
This is the same as the C function GDALGroupOpenGroup().
- Return
the group, or nullptr.
- Parameters
osName
: Sub-group name.papszOptions
: Driver specific options determining how the sub-group should be opened. Pass nullptr for default behaviour.
-
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().
- Return
the dimensions.
- Parameters
papszOptions
: Driver specific options determining how groups should be retrieved. Pass nullptr for default behaviour.
-
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().
- Return
the new sub-group, or nullptr in case of error.
- Parameters
osName
: Sub-group name.papszOptions
: Driver specific options determining how the sub-group should be created.
-
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
- Note
Driver implementation: drivers supporting CreateDimension() should implement this method, but do not have necessarily to implement GDALGroup::GetDimensions().
This is the same as the C function GDALGroupCreateDimension().
- Return
the new dimension, or nullptr if case of error
- 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.
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.
- Return
the new array, or nullptr if case of error
- 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.
-
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.
- Return
true in case of success (or partial success if bStrict == false).
- Parameters
poDstRootGroup
: Destination root group. Must NOT be nullptr.poSrcDS
: Source dataset. Migt be nullptr (but for correct behaviour of some output drivers this is not recommended)poSrcGroup
: Source group. Must NOT be nullptr.bStrict
: Whether to enable stict mode. In strict mode, any error will stop the copy. In relaxed mode, the copy will be attempted to be pursued.nCurCost
: Should be provided as a variable initially set to 0.nTotalCost
: Total cost from GetTotalCopyCost().pfnProgress
: Progress callback, or nullptr.pProgressData
: Progress user data, or nulptr.
-
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 GDALGroupGetStruturalInfo().
-
std::shared_ptr<GDALMDArray>
OpenMDArrayFromFullname
(const std::string &osFullName, CSLConstList papszOptions = nullptr) const¶ Get an array from its fully qualified name.
-
std::shared_ptr<GDALDimension>
OpenDimensionFromFullname
(const std::string &osFullName) const¶ Get a dimension from its fully qualified name.