GDAL

gdal_pam.h
1/******************************************************************************
2 * $Id$
3 *
4 * Project: GDAL Core
5 * Purpose: Declaration for Peristable Auxiliary Metadata classes.
6 * Author: Frank Warmerdam, warmerdam@pobox.com
7 *
8 ******************************************************************************
9 * Copyright (c) 2005, Frank Warmerdam <warmerdam@pobox.com>
10 *
11 * SPDX-License-Identifier: MIT
12 ****************************************************************************/
13
14#ifndef GDAL_PAM_H_INCLUDED
15#define GDAL_PAM_H_INCLUDED
16
18
19#include "cpl_minixml.h"
20#include "gdal_priv.h"
21#include <array>
22#include <limits>
23#include <map>
24#include <vector>
25
26 class GDALPamRasterBand;
27
28/* Clone Info Flags */
29
30#define GCIF_GEOTRANSFORM 0x01
31#define GCIF_PROJECTION 0x02
32#define GCIF_METADATA 0x04
33#define GCIF_GCPS 0x08
34
35#define GCIF_NODATA 0x001000
36#define GCIF_CATEGORYNAMES 0x002000
37#define GCIF_MINMAX 0x004000
38#define GCIF_SCALEOFFSET 0x008000
39#define GCIF_UNITTYPE 0x010000
40#define GCIF_COLORTABLE 0x020000
41/* Same value as GCIF_COLORTABLE */
42#define GCIF_COLORINTERP 0x020000
43#define GCIF_BAND_METADATA 0x040000
44#define GCIF_RAT 0x080000
45#define GCIF_MASK 0x100000
46#define GCIF_BAND_DESCRIPTION 0x200000
47
48#define GCIF_ONLY_IF_MISSING 0x10000000
49#define GCIF_PROCESS_BANDS 0x20000000
50
51#define GCIF_PAM_DEFAULT \
52 (GCIF_GEOTRANSFORM | GCIF_PROJECTION | GCIF_METADATA | GCIF_GCPS | \
53 GCIF_NODATA | GCIF_CATEGORYNAMES | GCIF_MINMAX | GCIF_SCALEOFFSET | \
54 GCIF_UNITTYPE | GCIF_COLORTABLE | GCIF_BAND_METADATA | GCIF_RAT | \
55 GCIF_MASK | GCIF_ONLY_IF_MISSING | GCIF_PROCESS_BANDS | \
56 GCIF_BAND_DESCRIPTION)
57
58/* GDAL PAM Flags */
59/* ERO 2011/04/13 : GPF_AUXMODE seems to be unimplemented */
60#define GPF_DIRTY 0x01 // .pam file needs to be written on close
61#define GPF_TRIED_READ_FAILED 0x02 // no need to keep trying to read .pam.
62#define GPF_DISABLED 0x04 // do not try any PAM stuff.
63#define GPF_AUXMODE 0x08 // store info in .aux (HFA) file.
64#define GPF_NOSAVE 0x10 // do not try to save pam info.
65
66/* ==================================================================== */
67/* GDALDatasetPamInfo */
68/* */
69/* We make these things a separate structure of information */
70/* primarily so we can modify it without altering the size of */
71/* the GDALPamDataset. It is an effort to reduce ABI churn for */
72/* driver plugins. */
73/* ==================================================================== */
74 class GDALDatasetPamInfo
75{
76 public:
77 char *pszPamFilename = nullptr;
78
79 std::vector<CPLXMLTreeCloser> m_apoOtherNodes{};
80
81 OGRSpatialReference *poSRS = nullptr;
82
83 int bHaveGeoTransform = false;
84 std::array<double, 6> adfGeoTransform{};
85
86 std::vector<gdal::GCP> asGCPs{};
87 OGRSpatialReference *poGCP_SRS = nullptr;
88
89 CPLString osPhysicalFilename{};
90 CPLString osSubdatasetName{};
91 CPLString osDerivedDatasetName{};
92 CPLString osAuxFilename{};
93
94 int bHasMetadata = false;
95};
96
98
99/* ******************************************************************** */
100/* GDALPamDataset */
101/* ******************************************************************** */
102
104 class CPL_DLL GDALPamDataset : public GDALDataset
105{
106 friend class GDALPamRasterBand;
107
108 private:
109 int IsPamFilenameAPotentialSiblingFile();
110
111 protected:
112 GDALPamDataset(void);
114 int nPamFlags = 0;
115 GDALDatasetPamInfo *psPam = nullptr;
116
117 virtual CPLXMLNode *SerializeToXML(const char *);
118 virtual CPLErr XMLInit(const CPLXMLNode *, const char *);
119
120 virtual CPLErr TryLoadXML(CSLConstList papszSiblingFiles = nullptr);
121 virtual CPLErr TrySaveXML();
122
123 CPLErr TryLoadAux(CSLConstList papszSiblingFiles = nullptr);
124 CPLErr TrySaveAux();
125
126 virtual const char *BuildPamFilename();
127
128 void PamInitialize();
129 void PamClear();
130
131 void SetPhysicalFilename(const char *);
132 const char *GetPhysicalFilename();
133 void SetSubdatasetName(const char *);
134 const char *GetSubdatasetName();
135 void SetDerivedDatasetName(const char *);
137
138 public:
139 ~GDALPamDataset() override;
140
141 CPLErr FlushCache(bool bAtClosing) override;
142
143 const OGRSpatialReference *GetSpatialRef() const override;
144 CPLErr SetSpatialRef(const OGRSpatialReference *poSRS) override;
145
146 CPLErr GetGeoTransform(double *) override;
147 CPLErr SetGeoTransform(double *) override;
148 void DeleteGeoTransform();
149
150 int GetGCPCount() override;
151 const OGRSpatialReference *GetGCPSpatialRef() const override;
152 const GDAL_GCP *GetGCPs() override;
153 using GDALDataset::SetGCPs;
154 CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList,
155 const OGRSpatialReference *poSRS) override;
156
157 CPLErr SetMetadata(char **papszMetadata,
158 const char *pszDomain = "") override;
159 CPLErr SetMetadataItem(const char *pszName, const char *pszValue,
160 const char *pszDomain = "") override;
161 char **GetMetadata(const char *pszDomain = "") override;
162 const char *GetMetadataItem(const char *pszName,
163 const char *pszDomain = "") override;
164
165 char **GetFileList(void) override;
166
167 void ClearStatistics() override;
168
170 virtual CPLErr CloneInfo(GDALDataset *poSrcDS, int nCloneInfoFlags);
171
172 CPLErr IBuildOverviews(const char *pszResampling, int nOverviews,
173 const int *panOverviewList, int nListBands,
174 const int *panBandList, GDALProgressFunc pfnProgress,
175 void *pProgressData,
176 CSLConstList papszOptions) override;
177
178 // "semi private" methods.
179 void MarkPamDirty();
180
181 GDALDatasetPamInfo *GetPamInfo()
182 {
183 return psPam;
184 }
185
186 int GetPamFlags()
187 {
188 return nPamFlags;
189 }
190
191 void SetPamFlags(int nValue)
192 {
193 nPamFlags = nValue;
194 }
195
197
198 private:
199 CPL_DISALLOW_COPY_ASSIGN(GDALPamDataset)
200};
201
203
204 constexpr double GDAL_PAM_DEFAULT_NODATA_VALUE = 0;
205// Parenthesis for external code around std::numeric_limits<>::min/max,
206// for external Windows code that might have includes <windows.h> before
207// without defining NOMINMAX
208 constexpr int64_t GDAL_PAM_DEFAULT_NODATA_VALUE_INT64 =
209 (std::numeric_limits<int64_t>::min)();
210 constexpr uint64_t GDAL_PAM_DEFAULT_NODATA_VALUE_UINT64 =
211 (std::numeric_limits<uint64_t>::max)();
212
213/* ==================================================================== */
214/* GDALRasterBandPamInfo */
215/* */
216/* We make these things a separate structure of information */
217/* primarily so we can modify it without altering the size of */
218/* the GDALPamDataset. It is an effort to reduce ABI churn for */
219/* driver plugins. */
220/* ==================================================================== */
221 struct GDALRasterBandPamInfo
222{
223 GDALPamDataset *poParentDS = nullptr;
224
225 bool bNoDataValueSet = false;
226 bool bNoDataValueSetAsInt64 = false;
227 bool bNoDataValueSetAsUInt64 = false;
228
229 double dfNoDataValue = GDAL_PAM_DEFAULT_NODATA_VALUE;
230 int64_t nNoDataValueInt64 = GDAL_PAM_DEFAULT_NODATA_VALUE_INT64;
231 uint64_t nNoDataValueUInt64 = GDAL_PAM_DEFAULT_NODATA_VALUE_UINT64;
232
233 GDALColorTable *poColorTable = nullptr;
234
235 GDALColorInterp eColorInterp = GCI_Undefined;
236
237 char *pszUnitType = nullptr;
238 char **papszCategoryNames = nullptr;
239
240 double dfOffset = 0.0;
241 double dfScale = 1.0;
242
243 int bHaveMinMax = FALSE;
244 double dfMin = 0;
245 double dfMax = 0;
246
247 int bHaveStats = FALSE;
248 double dfMean = 0;
249 double dfStdDev = 0;
250
251 CPLXMLNode *psSavedHistograms = nullptr;
252
253 GDALRasterAttributeTable *poDefaultRAT = nullptr;
254
255 bool bOffsetSet = false;
256 bool bScaleSet = false;
257
258 void CopyFrom(const GDALRasterBandPamInfo &sOther);
259};
260
262/* ******************************************************************** */
263/* GDALPamRasterBand */
264/* ******************************************************************** */
265
267 class CPL_DLL GDALPamRasterBand : public GDALRasterBand
268{
269 friend class GDALPamDataset;
270
271 protected:
273 virtual CPLXMLNode *SerializeToXML(const char *pszVRTPath);
274 virtual CPLErr XMLInit(const CPLXMLNode *, const char *);
275
276 void PamInitialize();
277 void PamClear();
278 void PamInitializeNoParent();
279 void MarkPamDirty();
280
281 GDALRasterBandPamInfo *psPam = nullptr;
283
284 public:
285 GDALPamRasterBand();
287 explicit GDALPamRasterBand(int bForceCachedIO);
289 ~GDALPamRasterBand() override;
290
291 void SetDescription(const char *) override;
292
293 CPLErr SetNoDataValue(double) override;
294 CPLErr SetNoDataValueAsInt64(int64_t nNoData) override;
295 CPLErr SetNoDataValueAsUInt64(uint64_t nNoData) override;
296 double GetNoDataValue(int *pbSuccess = nullptr) override;
297 int64_t GetNoDataValueAsInt64(int *pbSuccess = nullptr) override;
298 uint64_t GetNoDataValueAsUInt64(int *pbSuccess = nullptr) override;
299 CPLErr DeleteNoDataValue() override;
300
301 CPLErr SetColorTable(GDALColorTable *) override;
302 GDALColorTable *GetColorTable() override;
303
304 CPLErr SetColorInterpretation(GDALColorInterp) override;
305 GDALColorInterp GetColorInterpretation() override;
306
307 const char *GetUnitType() override;
308 CPLErr SetUnitType(const char *) override;
309
310 char **GetCategoryNames() override;
311 CPLErr SetCategoryNames(char **) override;
312
313 double GetOffset(int *pbSuccess = nullptr) override;
314 CPLErr SetOffset(double) override;
315 double GetScale(int *pbSuccess = nullptr) override;
316 CPLErr SetScale(double) override;
317
318 CPLErr GetHistogram(double dfMin, double dfMax, int nBuckets,
319 GUIntBig *panHistogram, int bIncludeOutOfRange,
320 int bApproxOK, GDALProgressFunc,
321 void *pProgressData) override;
322
323 CPLErr GetDefaultHistogram(double *pdfMin, double *pdfMax, int *pnBuckets,
324 GUIntBig **ppanHistogram, int bForce,
325 GDALProgressFunc, void *pProgressData) override;
326
327 CPLErr SetDefaultHistogram(double dfMin, double dfMax, int nBuckets,
328 GUIntBig *panHistogram) override;
329
330 CPLErr SetMetadata(char **papszMetadata,
331 const char *pszDomain = "") override;
332 CPLErr SetMetadataItem(const char *pszName, const char *pszValue,
333 const char *pszDomain = "") override;
334
335 GDALRasterAttributeTable *GetDefaultRAT() override;
336 CPLErr SetDefaultRAT(const GDALRasterAttributeTable *) override;
337
339 // new in GDALPamRasterBand.
340 virtual CPLErr CloneInfo(GDALRasterBand *poSrcBand, int nCloneInfoFlags);
341
342 // "semi private" methods.
343 GDALRasterBandPamInfo *GetPamInfo()
344 {
345 return psPam;
346 }
347
349 private:
350 CPL_DISALLOW_COPY_ASSIGN(GDALPamRasterBand)
351
352 void ResetNoDataValues();
353};
354
356
357/* ******************************************************************** */
358/* GDALPamMultiDim */
359/* ******************************************************************** */
360
364 class CPL_DLL GDALPamMultiDim
365{
366 struct Private;
367 std::unique_ptr<Private> d;
368
369 void Load();
370 void Save();
371
372 public:
373 explicit GDALPamMultiDim(const std::string &osFilename);
374 virtual ~GDALPamMultiDim();
375
376 std::shared_ptr<OGRSpatialReference>
377 GetSpatialRef(const std::string &osArrayFullName,
378 const std::string &osContext);
379
380 void SetSpatialRef(const std::string &osArrayFullName,
381 const std::string &osContext,
382 const OGRSpatialReference *poSRS);
383
384 CPLErr GetStatistics(const std::string &osArrayFullName,
385 const std::string &osContext, bool bApproxOK,
386 double *pdfMin, double *pdfMax, double *pdfMean,
387 double *pdfStdDev, GUInt64 *pnValidCount);
388
389 void SetStatistics(const std::string &osArrayFullName,
390 const std::string &osContext, bool bApproxStats,
391 double dfMin, double dfMax, double dfMean,
392 double dfStdDev, GUInt64 nValidCount);
393
394 void ClearStatistics();
395
396 void ClearStatistics(const std::string &osArrayFullName,
397 const std::string &osContext);
398
399 static std::shared_ptr<GDALPamMultiDim>
400 GetPAM(const std::shared_ptr<GDALMDArray> &poParent);
401};
402
403/* ******************************************************************** */
404/* GDALPamMDArray */
405/* ******************************************************************** */
406
408 class CPL_DLL GDALPamMDArray : public GDALMDArray
409{
410 std::shared_ptr<GDALPamMultiDim> m_poPam;
411
412 protected:
413 GDALPamMDArray(const std::string &osParentName, const std::string &osName,
414 const std::shared_ptr<GDALPamMultiDim> &poPam,
415 const std::string &osContext = std::string());
416
417 bool SetStatistics(bool bApproxStats, double dfMin, double dfMax,
418 double dfMean, double dfStdDev, GUInt64 nValidCount,
419 CSLConstList papszOptions) override;
420
421 public:
422 const std::shared_ptr<GDALPamMultiDim> &GetPAM() const
423 {
424 return m_poPam;
425 }
426
427 CPLErr GetStatistics(bool bApproxOK, bool bForce, double *pdfMin,
428 double *pdfMax, double *pdfMean, double *padfStdDev,
429 GUInt64 *pnValidCount, GDALProgressFunc pfnProgress,
430 void *pProgressData) override;
431
432 void ClearStatistics() override;
433
434 bool SetSpatialRef(const OGRSpatialReference *poSRS) override;
435
436 std::shared_ptr<OGRSpatialReference> GetSpatialRef() const override;
437};
438
439// These are mainly helper functions for internal use.
440 int CPL_DLL PamParseHistogram(CPLXMLNode *psHistItem, double *pdfMin,
441 double *pdfMax, int *pnBuckets,
442 GUIntBig **ppanHistogram,
443 int *pbIncludeOutOfRange, int *pbApproxOK);
444 CPLXMLNode CPL_DLL *PamFindMatchingHistogram(CPLXMLNode *psSavedHistograms,
445 double dfMin, double dfMax,
446 int nBuckets,
447 int bIncludeOutOfRange,
448 int bApproxOK);
449 CPLXMLNode CPL_DLL *PamHistogramToXMLTree(double dfMin, double dfMax,
450 int nBuckets, GUIntBig *panHistogram,
451 int bIncludeOutOfRange, int bApprox);
452
453// For managing the proxy file database.
454 const char CPL_DLL *PamGetProxy(const char *);
455 const char CPL_DLL *PamAllocateProxy(const char *);
456 const char CPL_DLL *PamDeallocateProxy(const char *);
457 void CPL_DLL PamCleanProxyDB(void);
458
460
461#endif /* ndef GDAL_PAM_H_INCLUDED */
CPLString
Convenient string class based on std::string.
Definition cpl_string.h:307
GDALColorTable
A color table / palette.
Definition gdal_priv.h:1362
GDALDataset
A set of associated raster bands, usually from one file.
Definition gdal_priv.h:495
GDALDataset::GetGCPCount
virtual int GetGCPCount()
Get number of GCPs.
Definition gdaldataset.cpp:1774
GDALDataset::GetGeoTransform
virtual CPLErr GetGeoTransform(double *padfTransform)
Fetch the affine transformation coefficients.
Definition gdaldataset.cpp:1380
GDALDataset::GetGCPSpatialRef
virtual const OGRSpatialReference * GetGCPSpatialRef() const
Get output spatial reference system for GCPs.
Definition gdaldataset.cpp:1864
GDALDataset::ClearStatistics
virtual void ClearStatistics()
Clear statistics.
Definition gdaldataset.cpp:9080
GDALDataset::SetMetadata
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
GDALDataset::SetSpatialRef
virtual CPLErr SetSpatialRef(const OGRSpatialReference *poSRS)
Set the spatial reference system for this dataset.
Definition gdaldataset.cpp:1301
GDALDataset::FlushCache
virtual CPLErr FlushCache(bool bAtClosing=false)
Flush all write cached data to disk.
Definition gdaldataset.cpp:550
GDALDataset::SetGeoTransform
virtual CPLErr SetGeoTransform(double *padfTransform)
Set the affine transformation coefficients.
Definition gdaldataset.cpp:1434
GDALDataset::SetGCPs
virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList, const OGRSpatialReference *poGCP_SRS)
Assign GCPs.
Definition gdaldataset.cpp:2028
GDALDataset::GetSpatialRef
virtual const OGRSpatialReference * GetSpatialRef() const
Fetch the spatial reference for this dataset.
Definition gdaldataset.cpp:1196
GDALDataset::SetMetadataItem
CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain) override
Set single metadata item.
GDALDataset::GetMetadata
void static void char ** GetMetadata(const char *pszDomain="") override
Fetch metadata.
Definition gdaldataset.cpp:4682
GDALDataset::GetGCPs
virtual const GDAL_GCP * GetGCPs()
Fetch GCPs.
Definition gdaldataset.cpp:1921
GDALDataset::GetFileList
virtual char ** GetFileList(void)
Fetch files forming dataset.
Definition gdaldataset.cpp:3245
GDALMDArray
Class modeling a multi-dimensional array.
Definition gdal_priv.h:3469
GDALMajorObject::GetMetadataItem
virtual const char * GetMetadataItem(const char *pszName, const char *pszDomain="")
Fetch single metadata item.
Definition gdalmajorobject.cpp:325
GDALMajorObject::SetDescription
virtual void SetDescription(const char *)
Set object description.
Definition gdalmajorobject.cpp:102
GDALPamDataset
PAM dataset.
Definition gdal_pam.h:105
GDALPamRasterBand
PAM raster band.
Definition gdal_pam.h:268
GDALRasterAttributeTable
The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute ...
Definition gdal_rat.h:32
GDALRasterBand
A single raster band (or channel).
Definition gdal_priv.h:1519
OGRSpatialReference
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition ogr_spatialref.h:153
CPLErr
CPLErr
Error category.
Definition cpl_error.h:37
cpl_minixml.h
Definitions for CPL mini XML Parser/Serializer.
GUIntBig
unsigned long long GUIntBig
Large unsigned integer type (generally 64-bit unsigned integer type).
Definition cpl_port.h:202
CPL_DISALLOW_COPY_ASSIGN
#define CPL_DISALLOW_COPY_ASSIGN(ClassName)
Helper to remove the copy and assignment constructors so that the compiler will not generate the defa...
Definition cpl_port.h:1030
CSLConstList
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition cpl_port.h:1179
GUInt64
GUIntBig GUInt64
Unsigned 64 bit integer type.
Definition cpl_port.h:222
GDALColorInterp
GDALColorInterp
Types of color interpretation for raster bands.
Definition gdal.h:257
GCI_Undefined
@ GCI_Undefined
Definition gdal.h:258
gdal_priv.h
C++ GDAL entry points.
CPLXMLNode
Document node structure.
Definition cpl_minixml.h:55
GDAL_GCP
Ground Control Point.
Definition gdal.h:1168