GDAL

gdal_multidim.h
1/******************************************************************************
2 *
3 * Name: gdal_multidim.h
4 * Project: GDAL Core
5 * Purpose: Declaration of classes for multidimensional support
6 * Author: Even Rouault <even.rouault at spatialys.com>
7 *
8 ******************************************************************************
9 * Copyright (c) 2019, Even Rouault <even.rouault at spatialys.com>
10 *
11 * SPDX-License-Identifier: MIT
12 ****************************************************************************/
13
14#ifndef GDALMULTIDIM_H_INCLUDED
15#define GDALMULTIDIM_H_INCLUDED
16
17#include "cpl_conv.h"
18#include "cpl_string.h"
19#include "gdal.h"
20#include "gdal_geotransform.h"
21
22#include <cstddef>
23#include <cstdint>
24#include <limits>
25#include <memory>
26#include <vector>
27
28/* ******************************************************************** */
29/* Multidimensional array API */
30/* ******************************************************************** */
31
32 class GDALMDArray;
33 class GDALAttribute;
34 class GDALDataset;
35 class GDALDimension;
36 class GDALEDTComponent;
37 class GDALRasterAttributeTable;
38 class GDALRasterBand;
39 class OGRLayer;
40 class OGRSpatialReference;
41
42/* ******************************************************************** */
43/* GDALExtendedDataType */
44/* ******************************************************************** */
45
53 class CPL_DLL GDALExtendedDataType
54{
55 public:
56 ~GDALExtendedDataType();
57
58 GDALExtendedDataType(GDALExtendedDataType &&);
59 GDALExtendedDataType(const GDALExtendedDataType &);
60
61 GDALExtendedDataType &operator=(const GDALExtendedDataType &);
62 GDALExtendedDataType &operator=(GDALExtendedDataType &&);
63
64 static GDALExtendedDataType Create(GDALDataType eType);
65 static GDALExtendedDataType
66 Create(const std::string &osName, GDALDataType eBaseType,
67 std::unique_ptr<GDALRasterAttributeTable>);
68 static GDALExtendedDataType
69 Create(const std::string &osName, size_t nTotalSize,
70 std::vector<std::unique_ptr<GDALEDTComponent>> &&components);
71 static GDALExtendedDataType
72 CreateString(size_t nMaxStringLength = 0,
73 GDALExtendedDataTypeSubType eSubType = GEDTST_NONE);
74
75 bool operator==(const GDALExtendedDataType &) const;
76
78 bool operator!=(const GDALExtendedDataType &other) const
79 {
80 return !(operator==(other));
81 }
82
87 const std::string &GetName() const
88 {
89 return m_osName;
90 }
91
96 GDALExtendedDataTypeClass GetClass() const
97 {
98 return m_eClass;
99 }
100
106 GDALDataType GetNumericDataType() const
107 {
108 return m_eNumericDT;
109 }
110
117 GDALExtendedDataTypeSubType GetSubType() const
118 {
119 return m_eSubType;
120 }
121
127 const std::vector<std::unique_ptr<GDALEDTComponent>> &GetComponents() const
128 {
129 return m_aoComponents;
130 }
131
138 size_t GetSize() const
139 {
140 return m_nSize;
141 }
142
147 size_t GetMaxStringLength() const
148 {
149 return m_nMaxStringLength;
150 }
151
162 const GDALRasterAttributeTable *GetRAT() const
163 {
164 return m_poRAT.get();
165 }
166
167 bool CanConvertTo(const GDALExtendedDataType &other) const;
168
169 bool NeedsFreeDynamicMemory() const;
170
171 void FreeDynamicMemory(void *pBuffer) const;
172
173 static bool CopyValue(const void *pSrc, const GDALExtendedDataType &srcType,
174 void *pDst, const GDALExtendedDataType &dstType);
175
176 static bool CopyValues(const void *pSrc,
177 const GDALExtendedDataType &srcType,
178 GPtrDiff_t nSrcStrideInElts, void *pDst,
179 const GDALExtendedDataType &dstType,
180 GPtrDiff_t nDstStrideInElts, size_t nValues);
181
182 private:
183 GDALExtendedDataType(size_t nMaxStringLength,
184 GDALExtendedDataTypeSubType eSubType);
185 explicit GDALExtendedDataType(GDALDataType eType);
186 GDALExtendedDataType(const std::string &osName, GDALDataType eBaseType,
187 std::unique_ptr<GDALRasterAttributeTable>);
188 GDALExtendedDataType(
189 const std::string &osName, size_t nTotalSize,
190 std::vector<std::unique_ptr<GDALEDTComponent>> &&components);
191
192 std::string m_osName{};
193 GDALExtendedDataTypeClass m_eClass = GEDTC_NUMERIC;
194 GDALExtendedDataTypeSubType m_eSubType = GEDTST_NONE;
195 GDALDataType m_eNumericDT = GDT_Unknown;
196 std::vector<std::unique_ptr<GDALEDTComponent>> m_aoComponents{};
197 size_t m_nSize = 0;
198 size_t m_nMaxStringLength = 0;
199 std::unique_ptr<GDALRasterAttributeTable> m_poRAT{};
200};
201
202/* ******************************************************************** */
203/* GDALEDTComponent */
204/* ******************************************************************** */
205
211 class CPL_DLL GDALEDTComponent
212{
213 public:
214 ~GDALEDTComponent();
215 GDALEDTComponent(const std::string &name, size_t offset,
216 const GDALExtendedDataType &type);
217 GDALEDTComponent(const GDALEDTComponent &);
218
219 bool operator==(const GDALEDTComponent &) const;
220
225 const std::string &GetName() const
226 {
227 return m_osName;
228 }
229
234 size_t GetOffset() const
235 {
236 return m_nOffset;
237 }
238
243 const GDALExtendedDataType &GetType() const
244 {
245 return m_oType;
246 }
247
248 private:
249 std::string m_osName;
250 size_t m_nOffset;
251 GDALExtendedDataType m_oType;
252};
253
254/* ******************************************************************** */
255/* GDALIHasAttribute */
256/* ******************************************************************** */
257
263 class CPL_DLL GDALIHasAttribute
264{
265 protected:
266 std::shared_ptr<GDALAttribute>
267 GetAttributeFromAttributes(const std::string &osName) const;
268
269 public:
270 virtual ~GDALIHasAttribute();
271
272 virtual std::shared_ptr<GDALAttribute>
273 GetAttribute(const std::string &osName) const;
274
275 virtual std::vector<std::shared_ptr<GDALAttribute>>
276 GetAttributes(CSLConstList papszOptions = nullptr) const;
277
278 virtual std::shared_ptr<GDALAttribute>
279 CreateAttribute(const std::string &osName,
280 const std::vector<GUInt64> &anDimensions,
281 const GDALExtendedDataType &oDataType,
282 CSLConstList papszOptions = nullptr);
283
284 virtual bool DeleteAttribute(const std::string &osName,
285 CSLConstList papszOptions = nullptr);
286};
287
288/* ******************************************************************** */
289/* GDALGroup */
290/* ******************************************************************** */
291
292/* clang-format off */
302/* clang-format on */
303
304 class CPL_DLL GDALGroup : public GDALIHasAttribute
305{
306 protected:
308 std::string m_osName{};
309
310 // This is actually a path of the form "/parent_path/{m_osName}"
311 std::string m_osFullName{};
312
313 // Used for example by GDALSubsetGroup to distinguish a derived group
314 //from its original, without altering its name
315 const std::string m_osContext{};
316
317 // List of types owned by the group.
318 std::vector<std::shared_ptr<GDALExtendedDataType>> m_apoTypes{};
319
321 std::weak_ptr<GDALGroup> m_pSelf{};
322
324 bool m_bValid = true;
325
326 GDALGroup(const std::string &osParentName, const std::string &osName,
327 const std::string &osContext = std::string());
328
329 const GDALGroup *
330 GetInnerMostGroup(const std::string &osPathOrArrayOrDim,
331 std::shared_ptr<GDALGroup> &curGroupHolder,
332 std::string &osLastPart) const;
333
334 void BaseRename(const std::string &osNewName);
335
336 bool CheckValidAndErrorOutIfNot() const;
337
338 void SetSelf(const std::shared_ptr<GDALGroup> &self)
339 {
340 m_pSelf = self;
341 }
342
343 virtual void NotifyChildrenOfRenaming()
344 {
345 }
346
347 virtual void NotifyChildrenOfDeletion()
348 {
349 }
350
352
353 public:
354 ~GDALGroup() override;
355
360 const std::string &GetName() const
361 {
362 return m_osName;
363 }
364
369 const std::string &GetFullName() const
370 {
371 return m_osFullName;
372 }
373
380 const std::vector<std::shared_ptr<GDALExtendedDataType>> &
381 GetDataTypes() const
382 {
383 return m_apoTypes;
384 }
385
386 virtual std::vector<std::string>
387 GetMDArrayNames(CSLConstList papszOptions = nullptr) const;
388 virtual std::shared_ptr<GDALMDArray>
389 OpenMDArray(const std::string &osName,
390 CSLConstList papszOptions = nullptr) const;
391
392 std::vector<std::string> GetMDArrayFullNamesRecursive(
393 CSLConstList papszGroupOptions = nullptr,
394 CSLConstList papszArrayOptions = nullptr) const;
395
396 virtual std::vector<std::string>
397 GetGroupNames(CSLConstList papszOptions = nullptr) const;
398 virtual std::shared_ptr<GDALGroup>
399 OpenGroup(const std::string &osName,
400 CSLConstList papszOptions = nullptr) const;
401
402 virtual std::vector<std::string>
403 GetVectorLayerNames(CSLConstList papszOptions = nullptr) const;
404 virtual OGRLayer *
405 OpenVectorLayer(const std::string &osName,
406 CSLConstList papszOptions = nullptr) const;
407
408 virtual std::vector<std::shared_ptr<GDALDimension>>
409 GetDimensions(CSLConstList papszOptions = nullptr) const;
410
411 virtual std::shared_ptr<GDALGroup>
412 CreateGroup(const std::string &osName, CSLConstList papszOptions = nullptr);
413
414 virtual bool DeleteGroup(const std::string &osName,
415 CSLConstList papszOptions = nullptr);
416
417 virtual std::shared_ptr<GDALDimension>
418 CreateDimension(const std::string &osName, const std::string &osType,
419 const std::string &osDirection, GUInt64 nSize,
420 CSLConstList papszOptions = nullptr);
421
422 virtual std::shared_ptr<GDALMDArray> CreateMDArray(
423 const std::string &osName,
424 const std::vector<std::shared_ptr<GDALDimension>> &aoDimensions,
425 const GDALExtendedDataType &oDataType,
426 CSLConstList papszOptions = nullptr);
427
428 virtual bool DeleteMDArray(const std::string &osName,
429 CSLConstList papszOptions = nullptr);
430
431 GUInt64 GetTotalCopyCost() const;
432
433 virtual bool CopyFrom(const std::shared_ptr<GDALGroup> &poDstRootGroup,
434 GDALDataset *poSrcDS,
435 const std::shared_ptr<GDALGroup> &poSrcGroup,
436 bool bStrict, GUInt64 &nCurCost,
437 const GUInt64 nTotalCost,
438 GDALProgressFunc pfnProgress, void *pProgressData,
439 CSLConstList papszOptions = nullptr);
440
441 virtual CSLConstList GetStructuralInfo() const;
442
443 std::shared_ptr<GDALMDArray>
444 OpenMDArrayFromFullname(const std::string &osFullName,
445 CSLConstList papszOptions = nullptr) const;
446
447 std::shared_ptr<GDALAttribute>
448 OpenAttributeFromFullname(const std::string &osFullName,
449 CSLConstList papszOptions = nullptr) const;
450
451 std::shared_ptr<GDALMDArray>
452 ResolveMDArray(const std::string &osName, const std::string &osStartingPath,
453 CSLConstList papszOptions = nullptr) const;
454
455 std::shared_ptr<GDALGroup>
456 OpenGroupFromFullname(const std::string &osFullName,
457 CSLConstList papszOptions = nullptr) const;
458
459 std::shared_ptr<GDALDimension>
460 OpenDimensionFromFullname(const std::string &osFullName) const;
461
462 virtual void ClearStatistics();
463
464 virtual bool Rename(const std::string &osNewName);
465
466 std::shared_ptr<GDALGroup>
467 SubsetDimensionFromSelection(const std::string &osSelection) const;
468
470 virtual void ParentRenamed(const std::string &osNewParentFullName);
471
472 virtual void Deleted();
473
474 virtual void ParentDeleted();
475
476 const std::string &GetContext() const
477 {
478 return m_osContext;
479 }
480
482
484 static constexpr GUInt64 COPY_COST = 1000;
486};
487
488/* ******************************************************************** */
489/* GDALAbstractMDArray */
490/* ******************************************************************** */
491
497 class CPL_DLL GDALAbstractMDArray
498{
499 protected:
501 std::string m_osName{};
502
503 // This is actually a path of the form "/parent_path/{m_osName}"
504 std::string m_osFullName{};
505 std::weak_ptr<GDALAbstractMDArray> m_pSelf{};
506
508 bool m_bValid = true;
509
510 GDALAbstractMDArray(const std::string &osParentName,
511 const std::string &osName);
512
513 void SetSelf(const std::shared_ptr<GDALAbstractMDArray> &self)
514 {
515 m_pSelf = self;
516 }
517
518 bool CheckValidAndErrorOutIfNot() const;
519
520 bool CheckReadWriteParams(const GUInt64 *arrayStartIdx, const size_t *count,
521 const GInt64 *&arrayStep,
522 const GPtrDiff_t *&bufferStride,
523 const GDALExtendedDataType &bufferDataType,
524 const void *buffer,
525 const void *buffer_alloc_start,
526 size_t buffer_alloc_size,
527 std::vector<GInt64> &tmp_arrayStep,
528 std::vector<GPtrDiff_t> &tmp_bufferStride) const;
529
530 virtual bool
531 IRead(const GUInt64 *arrayStartIdx, // array of size GetDimensionCount()
532 const size_t *count, // array of size GetDimensionCount()
533 const GInt64 *arrayStep, // step in elements
534 const GPtrDiff_t *bufferStride, // stride in elements
535 const GDALExtendedDataType &bufferDataType,
536 void *pDstBuffer) const = 0;
537
538 virtual bool
539 IWrite(const GUInt64 *arrayStartIdx, // array of size GetDimensionCount()
540 const size_t *count, // array of size GetDimensionCount()
541 const GInt64 *arrayStep, // step in elements
542 const GPtrDiff_t *bufferStride, // stride in elements
543 const GDALExtendedDataType &bufferDataType, const void *pSrcBuffer);
544
545 void BaseRename(const std::string &osNewName);
546
547 virtual void NotifyChildrenOfRenaming()
548 {
549 }
550
551 virtual void NotifyChildrenOfDeletion()
552 {
553 }
554
556
557 public:
558 virtual ~GDALAbstractMDArray();
559
565 const std::string &GetName() const
566 {
567 return m_osName;
568 }
569
575 const std::string &GetFullName() const
576 {
577 return m_osFullName;
578 }
579
580 GUInt64 GetTotalElementsCount() const;
581
582 virtual size_t GetDimensionCount() const;
583
584 virtual const std::vector<std::shared_ptr<GDALDimension>> &
585 GetDimensions() const = 0;
586
587 virtual const GDALExtendedDataType &GetDataType() const = 0;
588
589 virtual std::vector<GUInt64> GetBlockSize() const;
590
591 virtual std::vector<size_t>
592 GetProcessingChunkSize(size_t nMaxChunkMemory) const;
593
594 /* clang-format off */
610 typedef bool (*FuncProcessPerChunkType)(
611 GDALAbstractMDArray *array,
612 const GUInt64 *chunkArrayStartIdx,
613 const size_t *chunkCount,
614 GUInt64 iCurChunk,
615 GUInt64 nChunkCount,
616 void *pUserData);
617 /* clang-format on */
618
619 virtual bool ProcessPerChunk(const GUInt64 *arrayStartIdx,
620 const GUInt64 *count, const size_t *chunkSize,
621 FuncProcessPerChunkType pfnFunc,
622 void *pUserData);
623
624 virtual bool
625 Read(const GUInt64 *arrayStartIdx, // array of size GetDimensionCount()
626 const size_t *count, // array of size GetDimensionCount()
627 const GInt64 *arrayStep, // step in elements
628 const GPtrDiff_t *bufferStride, // stride in elements
629 const GDALExtendedDataType &bufferDataType, void *pDstBuffer,
630 const void *pDstBufferAllocStart = nullptr,
631 size_t nDstBufferAllocSize = 0) const;
632
633 bool
634 Write(const GUInt64 *arrayStartIdx, // array of size GetDimensionCount()
635 const size_t *count, // array of size GetDimensionCount()
636 const GInt64 *arrayStep, // step in elements
637 const GPtrDiff_t *bufferStride, // stride in elements
638 const GDALExtendedDataType &bufferDataType, const void *pSrcBuffer,
639 const void *pSrcBufferAllocStart = nullptr,
640 size_t nSrcBufferAllocSize = 0);
641
642 virtual bool Rename(const std::string &osNewName);
643
645 virtual void Deleted();
646
647 virtual void ParentDeleted();
648
649 virtual void ParentRenamed(const std::string &osNewParentFullName);
651};
652
653/* ******************************************************************** */
654/* GDALRawResult */
655/* ******************************************************************** */
656
663 class CPL_DLL GDALRawResult
664{
665 private:
666 GDALExtendedDataType m_dt;
667 size_t m_nEltCount;
668 size_t m_nSize;
669 GByte *m_raw;
670
671 void FreeMe();
672
673 GDALRawResult(const GDALRawResult &) = delete;
674 GDALRawResult &operator=(const GDALRawResult &) = delete;
675
676 protected:
677 friend class GDALAttribute;
679 GDALRawResult(GByte *raw, const GDALExtendedDataType &dt, size_t nEltCount);
681
682 public:
683 ~GDALRawResult();
684 GDALRawResult(GDALRawResult &&);
685 GDALRawResult &operator=(GDALRawResult &&);
686
688 const GByte &operator[](size_t idx) const
689 {
690 return m_raw[idx];
691 }
692
694 const GByte *data() const
695 {
696 return m_raw;
697 }
698
700 size_t size() const
701 {
702 return m_nSize;
703 }
704
706 GByte *StealData();
708};
709
710/* ******************************************************************** */
711/* GDALAttribute */
712/* ******************************************************************** */
713
714/* clang-format off */
726/* clang-format on */
727
728 class CPL_DLL GDALAttribute : virtual public GDALAbstractMDArray
729{
730 mutable std::string m_osCachedVal{};
731
732 protected:
734 GDALAttribute(const std::string &osParentName, const std::string &osName);
736
737 public:
739 ~GDALAttribute() override;
741
742 std::vector<GUInt64> GetDimensionsSize() const;
743
744 GDALRawResult ReadAsRaw() const;
745 const char *ReadAsString() const;
746 int ReadAsInt() const;
747 int64_t ReadAsInt64() const;
748 double ReadAsDouble() const;
749 CPLStringList ReadAsStringArray() const;
750 std::vector<int> ReadAsIntArray() const;
751 std::vector<int64_t> ReadAsInt64Array() const;
752 std::vector<double> ReadAsDoubleArray() const;
753
754 using GDALAbstractMDArray::Write;
755 bool Write(const void *pabyValue, size_t nLen);
756 bool Write(const char *);
757 bool WriteInt(int);
758 bool WriteInt64(int64_t);
759 bool Write(double);
760 bool Write(CSLConstList);
761 bool Write(const int *, size_t);
762 bool Write(const int64_t *, size_t);
763 bool Write(const double *, size_t);
764
766 static constexpr GUInt64 COPY_COST = 100;
768};
769
770/************************************************************************/
771/* GDALAttributeString */
772/************************************************************************/
773
775 class CPL_DLL GDALAttributeString final : public GDALAttribute
776{
777 std::vector<std::shared_ptr<GDALDimension>> m_dims{};
778 GDALExtendedDataType m_dt = GDALExtendedDataType::CreateString();
779 std::string m_osValue;
780
781 protected:
782 bool IRead(const GUInt64 *, const size_t *, const GInt64 *,
783 const GPtrDiff_t *, const GDALExtendedDataType &bufferDataType,
784 void *pDstBuffer) const override;
785
786 public:
787 GDALAttributeString(const std::string &osParentName,
788 const std::string &osName, const std::string &osValue,
789 GDALExtendedDataTypeSubType eSubType = GEDTST_NONE);
790
791 const std::vector<std::shared_ptr<GDALDimension>> &
792 GetDimensions() const override;
793
794 const GDALExtendedDataType &GetDataType() const override;
795};
796
798
799/************************************************************************/
800/* GDALAttributeNumeric */
801/************************************************************************/
802
804 class CPL_DLL GDALAttributeNumeric final : public GDALAttribute
805{
806 std::vector<std::shared_ptr<GDALDimension>> m_dims{};
807 GDALExtendedDataType m_dt;
808 int m_nValue = 0;
809 double m_dfValue = 0;
810 std::vector<GUInt32> m_anValuesUInt32{};
811
812 protected:
813 bool IRead(const GUInt64 *, const size_t *, const GInt64 *,
814 const GPtrDiff_t *, const GDALExtendedDataType &bufferDataType,
815 void *pDstBuffer) const override;
816
817 public:
818 GDALAttributeNumeric(const std::string &osParentName,
819 const std::string &osName, double dfValue);
820 GDALAttributeNumeric(const std::string &osParentName,
821 const std::string &osName, int nValue);
822 GDALAttributeNumeric(const std::string &osParentName,
823 const std::string &osName,
824 const std::vector<GUInt32> &anValues);
825
826 const std::vector<std::shared_ptr<GDALDimension>> &
827 GetDimensions() const override;
828
829 const GDALExtendedDataType &GetDataType() const override;
830};
831
833
834/* ******************************************************************** */
835/* GDALMDArray */
836/* ******************************************************************** */
837
838/* clang-format off */
848/* clang-format on */
849
850 class CPL_DLL GDALMDArray : virtual public GDALAbstractMDArray,
851 public GDALIHasAttribute
852{
853 friend class GDALMDArrayResampled;
854 std::shared_ptr<GDALMDArray>
855 GetView(const std::vector<GUInt64> &indices) const;
856
857 inline std::shared_ptr<GDALMDArray>
858 atInternal(const std::vector<GUInt64> &indices) const
859 {
860 return GetView(indices);
861 }
862
863 template <typename... GUInt64VarArg>
864 // cppcheck-suppress functionStatic
865 inline std::shared_ptr<GDALMDArray>
866 atInternal(std::vector<GUInt64> &indices, GUInt64 idx,
867 GUInt64VarArg... tail) const
868 {
869 indices.push_back(idx);
870 return atInternal(indices, tail...);
871 }
872
873 // Used for example by GDALSubsetGroup to distinguish a derived group
874 //from its original, without altering its name
875 const std::string m_osContext{};
876
877 mutable bool m_bHasTriedCachedArray = false;
878 mutable std::shared_ptr<GDALMDArray> m_poCachedArray{};
879
880 protected:
882 GDALMDArray(const std::string &osParentName, const std::string &osName,
883 const std::string &osContext = std::string());
884
885 virtual bool IAdviseRead(const GUInt64 *arrayStartIdx, const size_t *count,
886 CSLConstList papszOptions) const;
887
888 virtual bool IsCacheable() const
889 {
890 return true;
891 }
892
893 virtual bool SetStatistics(bool bApproxStats, double dfMin, double dfMax,
894 double dfMean, double dfStdDev,
895 GUInt64 nValidCount, CSLConstList papszOptions);
896
897 static std::string MassageName(const std::string &inputName);
898
899 std::shared_ptr<GDALGroup>
900 GetCacheRootGroup(bool bCanCreate, std::string &osCacheFilenameOut) const;
901
902 // Returns if bufferStride values express a transposed view of the array
903 bool IsTransposedRequest(const size_t *count,
904 const GPtrDiff_t *bufferStride) const;
905
906 // Should only be called if IsTransposedRequest() returns true
907 bool ReadForTransposedRequest(const GUInt64 *arrayStartIdx,
908 const size_t *count, const GInt64 *arrayStep,
909 const GPtrDiff_t *bufferStride,
910 const GDALExtendedDataType &bufferDataType,
911 void *pDstBuffer) const;
912
913 bool IsStepOneContiguousRowMajorOrderedSameDataType(
914 const size_t *count, const GInt64 *arrayStep,
915 const GPtrDiff_t *bufferStride,
916 const GDALExtendedDataType &bufferDataType) const;
917
918 // Should only be called if IsStepOneContiguousRowMajorOrderedSameDataType()
919 // returns false
920 bool ReadUsingContiguousIRead(const GUInt64 *arrayStartIdx,
921 const size_t *count, const GInt64 *arrayStep,
922 const GPtrDiff_t *bufferStride,
923 const GDALExtendedDataType &bufferDataType,
924 void *pDstBuffer) const;
925
926 static std::shared_ptr<GDALMDArray> CreateGLTOrthorectified(
927 const std::shared_ptr<GDALMDArray> &poParent,
928 const std::shared_ptr<GDALGroup> &poRootGroup,
929 const std::shared_ptr<GDALMDArray> &poGLTX,
930 const std::shared_ptr<GDALMDArray> &poGLTY, int nGLTIndexOffset,
931 const std::vector<double> &adfGeoTransform, CSLConstList papszOptions);
932
934
935 public:
936 GUInt64 GetTotalCopyCost() const;
937
938 virtual bool CopyFrom(GDALDataset *poSrcDS, const GDALMDArray *poSrcArray,
939 bool bStrict, GUInt64 &nCurCost,
940 const GUInt64 nTotalCost,
941 GDALProgressFunc pfnProgress, void *pProgressData);
942
944 virtual bool IsWritable() const = 0;
945
954 virtual const std::string &GetFilename() const = 0;
955
956 virtual CSLConstList GetStructuralInfo() const;
957
958 virtual const std::string &GetUnit() const;
959
960 virtual bool SetUnit(const std::string &osUnit);
961
962 virtual bool SetSpatialRef(const OGRSpatialReference *poSRS);
963
964 virtual std::shared_ptr<OGRSpatialReference> GetSpatialRef() const;
965
966 virtual const void *GetRawNoDataValue() const;
967
968 double GetNoDataValueAsDouble(bool *pbHasNoData = nullptr) const;
969
970 int64_t GetNoDataValueAsInt64(bool *pbHasNoData = nullptr) const;
971
972 uint64_t GetNoDataValueAsUInt64(bool *pbHasNoData = nullptr) const;
973
974 virtual bool SetRawNoDataValue(const void *pRawNoData);
975
977 bool SetNoDataValue(int nNoData)
978 {
979 return SetNoDataValue(static_cast<int64_t>(nNoData));
980 }
981
983
984 bool SetNoDataValue(double dfNoData);
985
986 bool SetNoDataValue(int64_t nNoData);
987
988 bool SetNoDataValue(uint64_t nNoData);
989
990 virtual bool Resize(const std::vector<GUInt64> &anNewDimSizes,
991 CSLConstList papszOptions);
992
993 virtual double GetOffset(bool *pbHasOffset = nullptr,
994 GDALDataType *peStorageType = nullptr) const;
995
996 virtual double GetScale(bool *pbHasScale = nullptr,
997 GDALDataType *peStorageType = nullptr) const;
998
999 virtual bool SetOffset(double dfOffset,
1000 GDALDataType eStorageType = GDT_Unknown);
1001
1002 virtual bool SetScale(double dfScale,
1003 GDALDataType eStorageType = GDT_Unknown);
1004
1005 std::shared_ptr<GDALMDArray> GetView(const std::string &viewExpr) const;
1006
1007 std::shared_ptr<GDALMDArray> operator[](const std::string &fieldName) const;
1008
1018 // sphinx 4.1.0 / breathe 4.30.0 don't like typename...
1020 template <typename... GUInt64VarArg>
1022 // cppcheck-suppress functionStatic
1023 std::shared_ptr<GDALMDArray> at(GUInt64 idx, GUInt64VarArg... tail) const
1024 {
1025 std::vector<GUInt64> indices;
1026 indices.push_back(idx);
1027 return atInternal(indices, tail...);
1028 }
1029
1030 virtual std::shared_ptr<GDALMDArray>
1031 Transpose(const std::vector<int> &anMapNewAxisToOldAxis) const;
1032
1033 std::shared_ptr<GDALMDArray> GetUnscaled(
1034 double dfOverriddenScale = std::numeric_limits<double>::quiet_NaN(),
1035 double dfOverriddenOffset = std::numeric_limits<double>::quiet_NaN(),
1036 double dfOverriddenDstNodata =
1037 std::numeric_limits<double>::quiet_NaN()) const;
1038
1039 virtual std::shared_ptr<GDALMDArray>
1040 GetMask(CSLConstList papszOptions) const;
1041
1042 virtual std::shared_ptr<GDALMDArray>
1043 GetResampled(const std::vector<std::shared_ptr<GDALDimension>> &apoNewDims,
1044 GDALRIOResampleAlg resampleAlg,
1045 const OGRSpatialReference *poTargetSRS,
1046 CSLConstList papszOptions) const;
1047
1048 std::shared_ptr<GDALMDArray>
1049 GetGridded(const std::string &osGridOptions,
1050 const std::shared_ptr<GDALMDArray> &poXArray = nullptr,
1051 const std::shared_ptr<GDALMDArray> &poYArray = nullptr,
1052 CSLConstList papszOptions = nullptr) const;
1053
1054 static std::vector<std::shared_ptr<GDALMDArray>>
1055 GetMeshGrid(const std::vector<std::shared_ptr<GDALMDArray>> &apoArrays,
1056 CSLConstList papszOptions = nullptr);
1057
1058 virtual GDALDataset *
1059 AsClassicDataset(size_t iXDim, size_t iYDim,
1060 const std::shared_ptr<GDALGroup> &poRootGroup = nullptr,
1061 CSLConstList papszOptions = nullptr) const;
1062
1063 virtual CPLErr GetStatistics(bool bApproxOK, bool bForce, double *pdfMin,
1064 double *pdfMax, double *pdfMean,
1065 double *padfStdDev, GUInt64 *pnValidCount,
1066 GDALProgressFunc pfnProgress,
1067 void *pProgressData);
1068
1069 virtual bool ComputeStatistics(bool bApproxOK, double *pdfMin,
1070 double *pdfMax, double *pdfMean,
1071 double *pdfStdDev, GUInt64 *pnValidCount,
1072 GDALProgressFunc, void *pProgressData,
1073 CSLConstList papszOptions);
1074
1075 virtual void ClearStatistics();
1076
1077 virtual std::vector<std::shared_ptr<GDALMDArray>>
1078 GetCoordinateVariables() const;
1079
1080 bool AdviseRead(const GUInt64 *arrayStartIdx, const size_t *count,
1081 CSLConstList papszOptions = nullptr) const;
1082
1083 bool IsRegularlySpaced(double &dfStart, double &dfIncrement) const;
1084
1085 bool GuessGeoTransform(size_t nDimX, size_t nDimY, bool bPixelIsPoint,
1086 GDALGeoTransform &gt) const;
1087
1088 bool GuessGeoTransform(size_t nDimX, size_t nDimY, bool bPixelIsPoint,
1089 double adfGeoTransform[6]) const;
1090
1091 bool Cache(CSLConstList papszOptions = nullptr) const;
1092
1093 bool
1094 Read(const GUInt64 *arrayStartIdx, // array of size GetDimensionCount()
1095 const size_t *count, // array of size GetDimensionCount()
1096 const GInt64 *arrayStep, // step in elements
1097 const GPtrDiff_t *bufferStride, // stride in elements
1098 const GDALExtendedDataType &bufferDataType, void *pDstBuffer,
1099 const void *pDstBufferAllocStart = nullptr,
1100 size_t nDstBufferAllocSize = 0) const override final;
1101
1102 virtual std::shared_ptr<GDALGroup> GetRootGroup() const;
1103
1104 virtual bool GetRawBlockInfo(const uint64_t *panBlockCoordinates,
1105 GDALMDArrayRawBlockInfo &info) const;
1106
1108 static constexpr GUInt64 COPY_COST = 1000;
1109
1110 bool CopyFromAllExceptValues(const GDALMDArray *poSrcArray, bool bStrict,
1111 GUInt64 &nCurCost, const GUInt64 nTotalCost,
1112 GDALProgressFunc pfnProgress,
1113 void *pProgressData);
1114
1115 struct Range
1116 {
1117 GUInt64 m_nStartIdx;
1118 GInt64 m_nIncr;
1119
1120 explicit Range(GUInt64 nStartIdx = 0, GInt64 nIncr = 0)
1121 : m_nStartIdx(nStartIdx), m_nIncr(nIncr)
1122 {
1123 }
1124 };
1125
1126 struct ViewSpec
1127 {
1128 std::string m_osFieldName{};
1129
1130 // or
1131
1132 std::vector<size_t>
1133 m_mapDimIdxToParentDimIdx{}; // of size m_dims.size()
1134 std::vector<Range>
1135 m_parentRanges{}; // of size m_poParent->GetDimensionCount()
1136 };
1137
1138 virtual std::shared_ptr<GDALMDArray>
1139 GetView(const std::string &viewExpr, bool bRenameDimensions,
1140 std::vector<ViewSpec> &viewSpecs) const;
1141
1142 const std::string &GetContext() const
1143 {
1144 return m_osContext;
1145 }
1146
1148};
1149
1151 bool GDALMDRasterIOFromBand(GDALRasterBand *poBand, GDALRWFlag eRWFlag,
1152 size_t iDimX, size_t iDimY,
1153 const GUInt64 *arrayStartIdx, const size_t *count,
1154 const GInt64 *arrayStep,
1155 const GPtrDiff_t *bufferStride,
1156 const GDALExtendedDataType &bufferDataType,
1157 void *pBuffer);
1158
1160
1161/************************************************************************/
1162/* GDALMDArrayRegularlySpaced */
1163/************************************************************************/
1164
1166 class CPL_DLL GDALMDArrayRegularlySpaced final : public GDALMDArray
1167{
1168 double m_dfStart = 0;
1169 double m_dfIncrement = 0;
1170 double m_dfOffsetInIncrement = 0;
1171 const GDALExtendedDataType m_dt = GDALExtendedDataType::Create(GDT_Float64);
1172 const std::vector<std::shared_ptr<GDALDimension>> m_dims;
1173 std::vector<std::shared_ptr<GDALAttribute>> m_attributes{};
1174 const std::string m_osEmptyFilename{};
1175
1176 protected:
1177 bool IRead(const GUInt64 *, const size_t *, const GInt64 *,
1178 const GPtrDiff_t *, const GDALExtendedDataType &bufferDataType,
1179 void *pDstBuffer) const override;
1180
1181 public:
1182 GDALMDArrayRegularlySpaced(const std::string &osParentName,
1183 const std::string &osName,
1184 const std::shared_ptr<GDALDimension> &poDim,
1185 double dfStart, double dfIncrement,
1186 double dfOffsetInIncrement);
1187
1188 static std::shared_ptr<GDALMDArrayRegularlySpaced>
1189 Create(const std::string &osParentName, const std::string &osName,
1190 const std::shared_ptr<GDALDimension> &poDim, double dfStart,
1191 double dfIncrement, double dfOffsetInIncrement);
1192
1193 bool IsWritable() const override
1194 {
1195 return false;
1196 }
1197
1198 const std::string &GetFilename() const override
1199 {
1200 return m_osEmptyFilename;
1201 }
1202
1203 const std::vector<std::shared_ptr<GDALDimension>> &
1204 GetDimensions() const override;
1205
1206 const GDALExtendedDataType &GetDataType() const override;
1207
1208 std::vector<std::shared_ptr<GDALAttribute>>
1209 GetAttributes(CSLConstList) const override;
1210
1211 void AddAttribute(const std::shared_ptr<GDALAttribute> &poAttr);
1212};
1213
1215
1216/* ******************************************************************** */
1217/* GDALDimension */
1218/* ******************************************************************** */
1219
1231 class CPL_DLL GDALDimension
1232{
1233 public:
1235 GDALDimension(const std::string &osParentName, const std::string &osName,
1236 const std::string &osType, const std::string &osDirection,
1237 GUInt64 nSize);
1239
1240 virtual ~GDALDimension();
1241
1246 const std::string &GetName() const
1247 {
1248 return m_osName;
1249 }
1250
1255 const std::string &GetFullName() const
1256 {
1257 return m_osFullName;
1258 }
1259
1268 const std::string &GetType() const
1269 {
1270 return m_osType;
1271 }
1272
1281 const std::string &GetDirection() const
1282 {
1283 return m_osDirection;
1284 }
1285
1290 GUInt64 GetSize() const
1291 {
1292 return m_nSize;
1293 }
1294
1295 virtual std::shared_ptr<GDALMDArray> GetIndexingVariable() const;
1296
1297 virtual bool
1298 SetIndexingVariable(std::shared_ptr<GDALMDArray> poIndexingVariable);
1299
1300 virtual bool Rename(const std::string &osNewName);
1301
1303 virtual void ParentRenamed(const std::string &osNewParentFullName);
1304
1305 virtual void ParentDeleted();
1307
1308 protected:
1310 std::string m_osName;
1311 std::string m_osFullName;
1312 std::string m_osType;
1313 std::string m_osDirection;
1314 GUInt64 m_nSize;
1315
1316 void BaseRename(const std::string &osNewName);
1317
1319};
1320
1321/************************************************************************/
1322/* GDALDimensionWeakIndexingVar() */
1323/************************************************************************/
1324
1326 class CPL_DLL GDALDimensionWeakIndexingVar : public GDALDimension
1327{
1328 std::weak_ptr<GDALMDArray> m_poIndexingVariable{};
1329
1330 public:
1331 GDALDimensionWeakIndexingVar(const std::string &osParentName,
1332 const std::string &osName,
1333 const std::string &osType,
1334 const std::string &osDirection, GUInt64 nSize);
1335
1336 std::shared_ptr<GDALMDArray> GetIndexingVariable() const override;
1337
1338 bool SetIndexingVariable(
1339 std::shared_ptr<GDALMDArray> poIndexingVariable) override;
1340
1341 void SetSize(GUInt64 nNewSize);
1342};
1343
1345
1346#endif
CPLStringList
String list class designed around our use of C "char**" string lists.
Definition cpl_string.h:458
GDALAbstractMDArray
Abstract class, implemented by GDALAttribute and GDALMDArray.
Definition gdal_multidim.h:498
GDALAbstractMDArray::GetFullName
const std::string & GetFullName() const
Return the name of an array or attribute.
Definition gdal_multidim.h:575
GDALAbstractMDArray::GetDimensions
virtual const std::vector< std::shared_ptr< GDALDimension > > & GetDimensions() const =0
Return the dimensions of an attribute/array.
GDALAbstractMDArray::GetDataType
virtual const GDALExtendedDataType & GetDataType() const =0
Return the data type of an attribute/array.
GDALAbstractMDArray::GetName
const std::string & GetName() const
Return the name of an array or attribute.
Definition gdal_multidim.h:565
GDALAbstractMDArray::Write
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.
Definition gdalmultidim.cpp:2344
GDALAttribute
Class modeling an attribute that has a name, a value and a type, and is typically used to describe a ...
Definition gdal_multidim.h:729
GDALDataset
A set of associated raster bands, usually from one file.
Definition gdal_dataset.h:76
GDALDimension
Class modeling a a dimension / axis used to index multidimensional arrays.
Definition gdal_multidim.h:1232
GDALDimension::GetName
const std::string & GetName() const
Return the name.
Definition gdal_multidim.h:1246
GDALDimension::GetDirection
const std::string & GetDirection() const
Return the axis direction.
Definition gdal_multidim.h:1281
GDALDimension::GetFullName
const std::string & GetFullName() const
Return the full name.
Definition gdal_multidim.h:1255
GDALDimension::GetSize
GUInt64 GetSize() const
Return the size, that is the number of values along the dimension.
Definition gdal_multidim.h:1290
GDALDimension::GetType
const std::string & GetType() const
Return the axis type.
Definition gdal_multidim.h:1268
GDALEDTComponent
Class for a component of a compound extended data type.
Definition gdal_multidim.h:212
GDALEDTComponent::GetType
const GDALExtendedDataType & GetType() const
Return the data type of the component.
Definition gdal_multidim.h:243
GDALEDTComponent::GetOffset
size_t GetOffset() const
Return the offset (in bytes) of the component in the compound data type.
Definition gdal_multidim.h:234
GDALEDTComponent::GetName
const std::string & GetName() const
Return the name.
Definition gdal_multidim.h:225
GDALEDTComponent::GDALEDTComponent
GDALEDTComponent(const GDALEDTComponent &)
Copy constructor.
GDALExtendedDataType
Class used to represent potentially complex data types.
Definition gdal_multidim.h:54
GDALExtendedDataType::operator!=
bool operator!=(const GDALExtendedDataType &other) const
Non-equality operator.
Definition gdal_multidim.h:78
GDALExtendedDataType::GetSubType
GDALExtendedDataTypeSubType GetSubType() const
Return subtype.
Definition gdal_multidim.h:117
GDALExtendedDataType::GetSize
size_t GetSize() const
Return data type size in bytes.
Definition gdal_multidim.h:138
GDALExtendedDataType::operator=
GDALExtendedDataType & operator=(GDALExtendedDataType &&)
Move assignment.
GDALExtendedDataType::GetMaxStringLength
size_t GetMaxStringLength() const
Return the maximum length of a string in bytes.
Definition gdal_multidim.h:147
GDALExtendedDataType::GetRAT
const GDALRasterAttributeTable * GetRAT() const
Return associated raster attribute table, when there is one.
Definition gdal_multidim.h:162
GDALExtendedDataType::Create
static GDALExtendedDataType Create(GDALDataType eType)
Return a new GDALExtendedDataType of class GEDTC_NUMERIC.
Definition gdalmultidim.cpp:10687
GDALExtendedDataType::CreateString
static GDALExtendedDataType CreateString(size_t nMaxStringLength=0, GDALExtendedDataTypeSubType eSubType=GEDTST_NONE)
Return a new GDALExtendedDataType of class GEDTC_STRING.
Definition gdalmultidim.cpp:10770
GDALExtendedDataType::GetNumericDataType
GDALDataType GetNumericDataType() const
Return numeric data type (only valid when GetClass() == GEDTC_NUMERIC)
Definition gdal_multidim.h:106
GDALExtendedDataType::GDALExtendedDataType
GDALExtendedDataType(GDALExtendedDataType &&)
Move constructor.
GDALExtendedDataType::GetClass
GDALExtendedDataTypeClass GetClass() const
Return type class.
Definition gdal_multidim.h:96
GDALExtendedDataType::GetComponents
const std::vector< std::unique_ptr< GDALEDTComponent > > & GetComponents() const
Return the components of the data type (only valid when GetClass() == GEDTC_COMPOUND)
Definition gdal_multidim.h:127
GDALExtendedDataType::GetName
const std::string & GetName() const
Return type name.
Definition gdal_multidim.h:87
GDALGeoTransform
Class that encapsulates a geotransform matrix.
Definition gdal_geotransform.h:42
GDALGroup
Class modeling a named container of GDALAttribute, GDALMDArray, OGRLayer or other GDALGroup.
Definition gdal_multidim.h:305
GDALGroup::GetName
const std::string & GetName() const
Return the name of the group.
Definition gdal_multidim.h:360
GDALGroup::GetDataTypes
const std::vector< std::shared_ptr< GDALExtendedDataType > > & GetDataTypes() const
Return data types associated with the group (typically enumerations)
Definition gdal_multidim.h:381
GDALGroup::GetFullName
const std::string & GetFullName() const
Return the full name of the group.
Definition gdal_multidim.h:369
GDALIHasAttribute
Interface used to get a single GDALAttribute or a set of GDALAttribute.
Definition gdal_multidim.h:264
GDALMDArray
Class modeling a multi-dimensional array.
Definition gdal_multidim.h:852
GDALMDArray::IsWritable
virtual bool IsWritable() const =0
Return whether an array is writable.
GDALMDArray::GetFilename
virtual const std::string & GetFilename() const =0
Return the filename that contains that array.
GDALMDArray::at
std::shared_ptr< GDALMDArray > at(GUInt64 idx, GUInt64VarArg... tail) const
Return a view of the array using integer indexing.
Definition gdal_multidim.h:1023
GDALRasterAttributeTable
The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute ...
Definition gdal_rat.h:48
GDALRasterBand
A single raster band (or channel).
Definition gdal_rasterband.h:105
GDALRawResult
Store the raw result of an attribute value, which might contain dynamically allocated structures (lik...
Definition gdal_multidim.h:664
GDALRawResult::size
size_t size() const
Return the size in bytes of the raw result.
Definition gdal_multidim.h:700
GDALRawResult::data
const GByte * data() const
Return pointer to the start of data.
Definition gdal_multidim.h:694
GDALRawResult::operator[]
const GByte & operator[](size_t idx) const
Return byte at specified index.
Definition gdal_multidim.h:688
OGRLayer
This class represents a layer of simple features, with access methods.
Definition ogrsf_frmts.h:61
OGRSpatialReference
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition ogr_spatialref.h:152
cpl_conv.h
Various convenience functions for CPL.
CPLErr
CPLErr
Error category.
Definition cpl_error.h:37
GPtrDiff_t
int GPtrDiff_t
Integer type large enough to hold the difference between 2 addresses.
Definition cpl_port.h:246
GInt64
GIntBig GInt64
Signed 64 bit integer type.
Definition cpl_port.h:226
CSLConstList
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition cpl_port.h:1087
GUInt64
GUIntBig GUInt64
Unsigned 64 bit integer type.
Definition cpl_port.h:228
GByte
unsigned char GByte
Unsigned byte type.
Definition cpl_port.h:175
cpl_string.h
Various convenience functions for working with strings and string lists.
gdal.h
Public (C callable) GDAL entry points.
GDALDataType
GDALDataType
Definition gdal.h:48
GDT_Float64
@ GDT_Float64
Definition gdal.h:60
GDT_Unknown
@ GDT_Unknown
Definition gdal.h:49
GDALExtendedDataTypeClass
GDALExtendedDataTypeClass
Enumeration giving the class of a GDALExtendedDataType.
Definition gdal.h:394
GEDTC_NUMERIC
@ GEDTC_NUMERIC
Numeric value.
Definition gdal.h:396
GDALRIOResampleAlg
GDALRIOResampleAlg
RasterIO() resampling method.
Definition gdal.h:137
GDALExtendedDataTypeSubType
GDALExtendedDataTypeSubType
Enumeration giving the subtype of a GDALExtendedDataType.
Definition gdal.h:407
GEDTST_NONE
@ GEDTST_NONE
None.
Definition gdal.h:409
GDALRWFlag
GDALRWFlag
Definition gdal.h:127
GDALMDArrayRawBlockInfo
Information on a raw block of a GDALMDArray.
Definition gdal.h:2830