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 * Permission is hereby granted, free of charge, to any person obtaining a
12 * copy of this software and associated documentation files (the "Software"),
13 * to deal in the Software without restriction, including without limitation
14 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
15 * and/or sell copies of the Software, and to permit persons to whom the
16 * Software is furnished to do so, subject to the following conditions:
17 *
18 * The above copyright notice and this permission notice shall be included
19 * in all copies or substantial portions of the Software.
20 *
21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
22 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
24 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
27 * DEALINGS IN THE SOFTWARE.
28 ****************************************************************************/
29
30#ifndef GDAL_PAM_H_INCLUDED
31#define GDAL_PAM_H_INCLUDED
32
34
35#include "cpl_minixml.h"
36#include "gdal_priv.h"
37#include <limits>
38#include <map>
39#include <vector>
40
41class GDALPamRasterBand;
42
43/* Clone Info Flags */
44
45#define GCIF_GEOTRANSFORM 0x01
46#define GCIF_PROJECTION 0x02
47#define GCIF_METADATA 0x04
48#define GCIF_GCPS 0x08
49
50#define GCIF_NODATA 0x001000
51#define GCIF_CATEGORYNAMES 0x002000
52#define GCIF_MINMAX 0x004000
53#define GCIF_SCALEOFFSET 0x008000
54#define GCIF_UNITTYPE 0x010000
55#define GCIF_COLORTABLE 0x020000
56#define GCIF_COLORINTERP 0x020000
57#define GCIF_BAND_METADATA 0x040000
58#define GCIF_RAT 0x080000
59#define GCIF_MASK 0x100000
60#define GCIF_BAND_DESCRIPTION 0x200000
61
62#define GCIF_ONLY_IF_MISSING 0x10000000
63#define GCIF_PROCESS_BANDS 0x20000000
64
65#define GCIF_PAM_DEFAULT \
66 (GCIF_GEOTRANSFORM | GCIF_PROJECTION | GCIF_METADATA | GCIF_GCPS | \
67 GCIF_NODATA | GCIF_CATEGORYNAMES | GCIF_MINMAX | GCIF_SCALEOFFSET | \
68 GCIF_UNITTYPE | GCIF_COLORTABLE | GCIF_COLORINTERP | GCIF_BAND_METADATA | \
69 GCIF_RAT | GCIF_MASK | GCIF_ONLY_IF_MISSING | GCIF_PROCESS_BANDS | \
70 GCIF_BAND_DESCRIPTION)
71
72/* GDAL PAM Flags */
73/* ERO 2011/04/13 : GPF_AUXMODE seems to be unimplemented */
74#define GPF_DIRTY 0x01 // .pam file needs to be written on close
75#define GPF_TRIED_READ_FAILED 0x02 // no need to keep trying to read .pam.
76#define GPF_DISABLED 0x04 // do not try any PAM stuff.
77#define GPF_AUXMODE 0x08 // store info in .aux (HFA) file.
78#define GPF_NOSAVE 0x10 // do not try to save pam info.
79
80/* ==================================================================== */
81/* GDALDatasetPamInfo */
82/* */
83/* We make these things a separate structure of information */
84/* primarily so we can modify it without altering the size of */
85/* the GDALPamDataset. It is an effort to reduce ABI churn for */
86/* driver plugins. */
87/* ==================================================================== */
88class GDALDatasetPamInfo
89{
90 public:
91 char *pszPamFilename = nullptr;
92
93 std::vector<CPLXMLTreeCloser> m_apoOtherNodes{};
94
95 OGRSpatialReference *poSRS = nullptr;
96
97 int bHaveGeoTransform = false;
98 double adfGeoTransform[6]{0, 0, 0, 0, 0, 0};
99
100 std::vector<gdal::GCP> asGCPs{};
101 OGRSpatialReference *poGCP_SRS = nullptr;
102
103 CPLString osPhysicalFilename{};
104 CPLString osSubdatasetName{};
105 CPLString osDerivedDatasetName{};
106 CPLString osAuxFilename{};
107
108 int bHasMetadata = false;
109};
110
112
113/* ******************************************************************** */
114/* GDALPamDataset */
115/* ******************************************************************** */
116
118 class CPL_DLL GDALPamDataset : public GDALDataset
119{
120 friend class GDALPamRasterBand;
121
122 private:
123 int IsPamFilenameAPotentialSiblingFile();
124
125 protected:
126 GDALPamDataset(void);
128 int nPamFlags = 0;
129 GDALDatasetPamInfo *psPam = nullptr;
130
131 virtual CPLXMLNode *SerializeToXML(const char *);
132 virtual CPLErr XMLInit(const CPLXMLNode *, const char *);
133
134 virtual CPLErr TryLoadXML(char **papszSiblingFiles = nullptr);
135 virtual CPLErr TrySaveXML();
136
137 CPLErr TryLoadAux(char **papszSiblingFiles = nullptr);
138 CPLErr TrySaveAux();
139
140 virtual const char *BuildPamFilename();
141
142 void PamInitialize();
143 void PamClear();
144
145 void SetPhysicalFilename(const char *);
146 const char *GetPhysicalFilename();
147 void SetSubdatasetName(const char *);
148 const char *GetSubdatasetName();
149 void SetDerivedDatasetName(const char *);
151
152 public:
153 ~GDALPamDataset() override;
154
155 CPLErr FlushCache(bool bAtClosing) override;
156
157 const OGRSpatialReference *GetSpatialRef() const override;
158 CPLErr SetSpatialRef(const OGRSpatialReference *poSRS) override;
159
160 CPLErr GetGeoTransform(double *) override;
161 CPLErr SetGeoTransform(double *) override;
162 void DeleteGeoTransform();
163
164 int GetGCPCount() override;
165 const OGRSpatialReference *GetGCPSpatialRef() const override;
166 const GDAL_GCP *GetGCPs() override;
167 using GDALDataset::SetGCPs;
168 CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList,
169 const OGRSpatialReference *poSRS) override;
170
171 CPLErr SetMetadata(char **papszMetadata,
172 const char *pszDomain = "") override;
173 CPLErr SetMetadataItem(const char *pszName, const char *pszValue,
174 const char *pszDomain = "") override;
175 char **GetMetadata(const char *pszDomain = "") override;
176 const char *GetMetadataItem(const char *pszName,
177 const char *pszDomain = "") override;
178
179 char **GetFileList(void) override;
180
181 void ClearStatistics() override;
182
184 virtual CPLErr CloneInfo(GDALDataset *poSrcDS, int nCloneInfoFlags);
185
186 CPLErr IBuildOverviews(const char *pszResampling, int nOverviews,
187 const int *panOverviewList, int nListBands,
188 const int *panBandList, GDALProgressFunc pfnProgress,
189 void *pProgressData,
190 CSLConstList papszOptions) override;
191
192 // "semi private" methods.
193 void MarkPamDirty();
194
195 GDALDatasetPamInfo *GetPamInfo()
196 {
197 return psPam;
198 }
199
200 int GetPamFlags()
201 {
202 return nPamFlags;
203 }
204
205 void SetPamFlags(int nValue)
206 {
207 nPamFlags = nValue;
208 }
209
211
212 private:
213 CPL_DISALLOW_COPY_ASSIGN(GDALPamDataset)
214};
215
217
218constexpr double GDAL_PAM_DEFAULT_NODATA_VALUE = 0;
219// Parenthesis for external code around std::numeric_limits<>::min/max,
220// for external Windows code that might have includes <windows.h> before
221// without defining NOMINMAX
222constexpr int64_t GDAL_PAM_DEFAULT_NODATA_VALUE_INT64 =
223 (std::numeric_limits<int64_t>::min)();
224constexpr uint64_t GDAL_PAM_DEFAULT_NODATA_VALUE_UINT64 =
225 (std::numeric_limits<uint64_t>::max)();
226
227/* ==================================================================== */
228/* GDALRasterBandPamInfo */
229/* */
230/* We make these things a separate structure of information */
231/* primarily so we can modify it without altering the size of */
232/* the GDALPamDataset. It is an effort to reduce ABI churn for */
233/* driver plugins. */
234/* ==================================================================== */
235struct GDALRasterBandPamInfo
236{
237 GDALPamDataset *poParentDS = nullptr;
238
239 bool bNoDataValueSet = false;
240 bool bNoDataValueSetAsInt64 = false;
241 bool bNoDataValueSetAsUInt64 = false;
242
243 double dfNoDataValue = GDAL_PAM_DEFAULT_NODATA_VALUE;
244 int64_t nNoDataValueInt64 = GDAL_PAM_DEFAULT_NODATA_VALUE_INT64;
245 uint64_t nNoDataValueUInt64 = GDAL_PAM_DEFAULT_NODATA_VALUE_UINT64;
246
247 GDALColorTable *poColorTable = nullptr;
248
249 GDALColorInterp eColorInterp = GCI_Undefined;
250
251 char *pszUnitType = nullptr;
252 char **papszCategoryNames = nullptr;
253
254 double dfOffset = 0.0;
255 double dfScale = 1.0;
256
257 int bHaveMinMax = FALSE;
258 double dfMin = 0;
259 double dfMax = 0;
260
261 int bHaveStats = FALSE;
262 double dfMean = 0;
263 double dfStdDev = 0;
264
265 CPLXMLNode *psSavedHistograms = nullptr;
266
267 GDALRasterAttributeTable *poDefaultRAT = nullptr;
268
269 bool bOffsetSet = false;
270 bool bScaleSet = false;
271};
272
274/* ******************************************************************** */
275/* GDALPamRasterBand */
276/* ******************************************************************** */
277
279 class CPL_DLL GDALPamRasterBand : public GDALRasterBand
280{
281 friend class GDALPamDataset;
282
283 protected:
285 virtual CPLXMLNode *SerializeToXML(const char *pszVRTPath);
286 virtual CPLErr XMLInit(const CPLXMLNode *, const char *);
287
288 void PamInitialize();
289 void PamClear();
290 void PamInitializeNoParent();
291 void MarkPamDirty();
292
293 GDALRasterBandPamInfo *psPam = nullptr;
295
296 public:
297 GDALPamRasterBand();
299 explicit GDALPamRasterBand(int bForceCachedIO);
301 ~GDALPamRasterBand() override;
302
303 void SetDescription(const char *) override;
304
305 CPLErr SetNoDataValue(double) override;
306 CPLErr SetNoDataValueAsInt64(int64_t nNoData) override;
307 CPLErr SetNoDataValueAsUInt64(uint64_t nNoData) override;
308 double GetNoDataValue(int *pbSuccess = nullptr) override;
309 int64_t GetNoDataValueAsInt64(int *pbSuccess = nullptr) override;
310 uint64_t GetNoDataValueAsUInt64(int *pbSuccess = nullptr) override;
311 CPLErr DeleteNoDataValue() override;
312
313 CPLErr SetColorTable(GDALColorTable *) override;
314 GDALColorTable *GetColorTable() override;
315
316 CPLErr SetColorInterpretation(GDALColorInterp) override;
317 GDALColorInterp GetColorInterpretation() override;
318
319 const char *GetUnitType() override;
320 CPLErr SetUnitType(const char *) override;
321
322 char **GetCategoryNames() override;
323 CPLErr SetCategoryNames(char **) override;
324
325 double GetOffset(int *pbSuccess = nullptr) override;
326 CPLErr SetOffset(double) override;
327 double GetScale(int *pbSuccess = nullptr) override;
328 CPLErr SetScale(double) override;
329
330 CPLErr GetHistogram(double dfMin, double dfMax, int nBuckets,
331 GUIntBig *panHistogram, int bIncludeOutOfRange,
332 int bApproxOK, GDALProgressFunc,
333 void *pProgressData) override;
334
335 CPLErr GetDefaultHistogram(double *pdfMin, double *pdfMax, int *pnBuckets,
336 GUIntBig **ppanHistogram, int bForce,
337 GDALProgressFunc, void *pProgressData) override;
338
339 CPLErr SetDefaultHistogram(double dfMin, double dfMax, int nBuckets,
340 GUIntBig *panHistogram) override;
341
342 CPLErr SetMetadata(char **papszMetadata,
343 const char *pszDomain = "") override;
344 CPLErr SetMetadataItem(const char *pszName, const char *pszValue,
345 const char *pszDomain = "") override;
346
347 GDALRasterAttributeTable *GetDefaultRAT() override;
348 CPLErr SetDefaultRAT(const GDALRasterAttributeTable *) override;
349
351 // new in GDALPamRasterBand.
352 virtual CPLErr CloneInfo(GDALRasterBand *poSrcBand, int nCloneInfoFlags);
353
354 // "semi private" methods.
355 GDALRasterBandPamInfo *GetPamInfo()
356 {
357 return psPam;
358 }
359
361 private:
362 CPL_DISALLOW_COPY_ASSIGN(GDALPamRasterBand)
363
364 void ResetNoDataValues();
365};
366
368
369/* ******************************************************************** */
370/* GDALPamMultiDim */
371/* ******************************************************************** */
372
376class CPL_DLL GDALPamMultiDim
377{
378 struct Private;
379 std::unique_ptr<Private> d;
380
381 void Load();
382 void Save();
383
384 public:
385 explicit GDALPamMultiDim(const std::string &osFilename);
386 virtual ~GDALPamMultiDim();
387
388 std::shared_ptr<OGRSpatialReference>
389 GetSpatialRef(const std::string &osArrayFullName,
390 const std::string &osContext);
391
392 void SetSpatialRef(const std::string &osArrayFullName,
393 const std::string &osContext,
394 const OGRSpatialReference *poSRS);
395
396 CPLErr GetStatistics(const std::string &osArrayFullName,
397 const std::string &osContext, bool bApproxOK,
398 double *pdfMin, double *pdfMax, double *pdfMean,
399 double *pdfStdDev, GUInt64 *pnValidCount);
400
401 void SetStatistics(const std::string &osArrayFullName,
402 const std::string &osContext, bool bApproxStats,
403 double dfMin, double dfMax, double dfMean,
404 double dfStdDev, GUInt64 nValidCount);
405
406 void ClearStatistics();
407
408 void ClearStatistics(const std::string &osArrayFullName,
409 const std::string &osContext);
410
411 static std::shared_ptr<GDALPamMultiDim>
412 GetPAM(const std::shared_ptr<GDALMDArray> &poParent);
413};
414
415/* ******************************************************************** */
416/* GDALPamMDArray */
417/* ******************************************************************** */
418
420class CPL_DLL GDALPamMDArray : public GDALMDArray
421{
422 std::shared_ptr<GDALPamMultiDim> m_poPam;
423
424 protected:
425 GDALPamMDArray(const std::string &osParentName, const std::string &osName,
426 const std::shared_ptr<GDALPamMultiDim> &poPam,
427 const std::string &osContext = std::string());
428
429 bool SetStatistics(bool bApproxStats, double dfMin, double dfMax,
430 double dfMean, double dfStdDev, GUInt64 nValidCount,
431 CSLConstList papszOptions) override;
432
433 public:
434 const std::shared_ptr<GDALPamMultiDim> &GetPAM() const
435 {
436 return m_poPam;
437 }
438
439 CPLErr GetStatistics(bool bApproxOK, bool bForce, double *pdfMin,
440 double *pdfMax, double *pdfMean, double *padfStdDev,
441 GUInt64 *pnValidCount, GDALProgressFunc pfnProgress,
442 void *pProgressData) override;
443
444 void ClearStatistics() override;
445
446 bool SetSpatialRef(const OGRSpatialReference *poSRS) override;
447
448 std::shared_ptr<OGRSpatialReference> GetSpatialRef() const override;
449};
450
451// These are mainly helper functions for internal use.
452int CPL_DLL PamParseHistogram(CPLXMLNode *psHistItem, double *pdfMin,
453 double *pdfMax, int *pnBuckets,
454 GUIntBig **ppanHistogram,
455 int *pbIncludeOutOfRange, int *pbApproxOK);
456 CPLXMLNode CPL_DLL *PamFindMatchingHistogram(CPLXMLNode *psSavedHistograms,
457 double dfMin, double dfMax,
458 int nBuckets,
459 int bIncludeOutOfRange,
460 int bApproxOK);
461 CPLXMLNode CPL_DLL *PamHistogramToXMLTree(double dfMin, double dfMax,
462 int nBuckets, GUIntBig *panHistogram,
463 int bIncludeOutOfRange, int bApprox);
464
465// For managing the proxy file database.
466const char CPL_DLL *PamGetProxy(const char *);
467const char CPL_DLL *PamAllocateProxy(const char *);
468const char CPL_DLL *PamDeallocateProxy(const char *);
469void CPL_DLL PamCleanProxyDB(void);
470
472
473#endif /* ndef GDAL_PAM_H_INCLUDED */
CPLString
Convenient string class based on std::string.
Definition: cpl_string.h:320
GDALColorTable
A color table / palette.
Definition: gdal_priv.h:1312
GDALDataset
A set of associated raster bands, usually from one file.
Definition: gdal_priv.h:490
GDALDataset::GetGCPCount
virtual int GetGCPCount()
Get number of GCPs.
Definition: gdaldataset.cpp:1770
GDALDataset::GetGeoTransform
virtual CPLErr GetGeoTransform(double *padfTransform)
Fetch the affine transformation coefficients.
Definition: gdaldataset.cpp:1376
GDALDataset::GetGCPSpatialRef
virtual const OGRSpatialReference * GetGCPSpatialRef() const
Get output spatial reference system for GCPs.
Definition: gdaldataset.cpp:1855
GDALDataset::ClearStatistics
virtual void ClearStatistics()
Clear statistics.
Definition: gdaldataset.cpp:8989
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:1297
GDALDataset::FlushCache
virtual CPLErr FlushCache(bool bAtClosing=false)
Flush all write cached data to disk.
Definition: gdaldataset.cpp:558
GDALDataset::SetGeoTransform
virtual CPLErr SetGeoTransform(double *padfTransform)
Set the affine transformation coefficients.
Definition: gdaldataset.cpp:1430
GDALDataset::SetGCPs
virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList, const OGRSpatialReference *poGCP_SRS)
Assign GCPs.
Definition: gdaldataset.cpp:2019
GDALDataset::GetSpatialRef
virtual const OGRSpatialReference * GetSpatialRef() const
Fetch the spatial reference for this dataset.
Definition: gdaldataset.cpp:1192
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:4601
GDALDataset::GetGCPs
virtual const GDAL_GCP * GetGCPs()
Fetch GCPs.
Definition: gdaldataset.cpp:1912
GDALDataset::GetFileList
virtual char ** GetFileList(void)
Fetch files forming dataset.
Definition: gdaldataset.cpp:3233
GDALMDArray
Class modeling a multi-dimensional array.
Definition: gdal_priv.h:3284
GDALMajorObject::GetMetadataItem
virtual const char * GetMetadataItem(const char *pszName, const char *pszDomain="")
Fetch single metadata item.
Definition: gdalmajorobject.cpp:341
GDALMajorObject::SetDescription
virtual void SetDescription(const char *)
Set object description.
Definition: gdalmajorobject.cpp:118
GDALPamDataset
PAM dataset.
Definition: gdal_pam.h:119
GDALPamRasterBand
PAM raster band.
Definition: gdal_pam.h:280
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_priv.h:1468
OGRSpatialReference
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition: ogr_spatialref.h:169
CPLErr
CPLErr
Error category.
Definition: cpl_error.h:53
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:218
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:1042
CSLConstList
char ** CSLConstList
Type of a constant null-terminated list of nul terminated strings.
Definition: cpl_port.h:1183
GUInt64
GUIntBig GUInt64
Unsigned 64 bit integer type.
Definition: cpl_port.h:238
GDALColorInterp
GDALColorInterp
Definition: gdal.h:227
GCI_Undefined
@ GCI_Undefined
Definition: gdal.h:228
gdal_priv.h
C++ GDAL entry points.
CPLXMLNode
Document node structure.
Definition: cpl_minixml.h:71
GDAL_GCP
Ground Control Point.
Definition: gdal.h:1077