GDAL
gdal_pam.h
1 /******************************************************************************
2  * $Id: gdal_pam.h c6cd0c925b6b3e838e01ab730a793e2aa818110e 2021-12-10 11:37:30 +0100 Even Rouault $
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 <map>
38 #include <vector>
39 
40 class GDALPamRasterBand;
41 
42 /* Clone Info Flags */
43 
44 #define GCIF_GEOTRANSFORM 0x01
45 #define GCIF_PROJECTION 0x02
46 #define GCIF_METADATA 0x04
47 #define GCIF_GCPS 0x08
48 
49 #define GCIF_NODATA 0x001000
50 #define GCIF_CATEGORYNAMES 0x002000
51 #define GCIF_MINMAX 0x004000
52 #define GCIF_SCALEOFFSET 0x008000
53 #define GCIF_UNITTYPE 0x010000
54 #define GCIF_COLORTABLE 0x020000
55 #define GCIF_COLORINTERP 0x020000
56 #define GCIF_BAND_METADATA 0x040000
57 #define GCIF_RAT 0x080000
58 #define GCIF_MASK 0x100000
59 #define GCIF_BAND_DESCRIPTION 0x200000
60 
61 #define GCIF_ONLY_IF_MISSING 0x10000000
62 #define GCIF_PROCESS_BANDS 0x20000000
63 
64 #define GCIF_PAM_DEFAULT (GCIF_GEOTRANSFORM | GCIF_PROJECTION | \
65  GCIF_METADATA | GCIF_GCPS | \
66  GCIF_NODATA | GCIF_CATEGORYNAMES | \
67  GCIF_MINMAX | GCIF_SCALEOFFSET | \
68  GCIF_UNITTYPE | GCIF_COLORTABLE | \
69  GCIF_COLORINTERP | GCIF_BAND_METADATA | \
70  GCIF_RAT | GCIF_MASK | \
71  GCIF_ONLY_IF_MISSING | GCIF_PROCESS_BANDS|\
72  GCIF_BAND_DESCRIPTION)
73 
74 /* GDAL PAM Flags */
75 /* ERO 2011/04/13 : GPF_AUXMODE seems to be unimplemented */
76 #define GPF_DIRTY 0x01 // .pam file needs to be written on close
77 #define GPF_TRIED_READ_FAILED 0x02 // no need to keep trying to read .pam.
78 #define GPF_DISABLED 0x04 // do not try any PAM stuff.
79 #define GPF_AUXMODE 0x08 // store info in .aux (HFA) file.
80 #define GPF_NOSAVE 0x10 // do not try to save pam info.
81 
82 /* ==================================================================== */
83 /* GDALDatasetPamInfo */
84 /* */
85 /* We make these things a separate structure of information */
86 /* primarily so we can modify it without altering the size of */
87 /* the GDALPamDataset. It is an effort to reduce ABI churn for */
88 /* driver plugins. */
89 /* ==================================================================== */
90 class GDALDatasetPamInfo
91 {
92 public:
93  char *pszPamFilename = nullptr;
94 
95  std::vector<CPLXMLTreeCloser> m_apoOtherNodes{};
96 
97  OGRSpatialReference* poSRS = nullptr;
98 
99  int bHaveGeoTransform = false;
100  double adfGeoTransform[6]{0,0,0,0,0,0};
101 
102  int nGCPCount = 0;
103  GDAL_GCP *pasGCPList = nullptr;
104  OGRSpatialReference* poGCP_SRS = nullptr;
105 
106  CPLString osPhysicalFilename{};
107  CPLString osSubdatasetName{};
108  CPLString osAuxFilename{};
109 
110  int bHasMetadata = false;
111 };
113 
114 /* ******************************************************************** */
115 /* GDALPamDataset */
116 /* ******************************************************************** */
117 
119 class CPL_DLL GDALPamDataset : public GDALDataset
120 {
121  friend class GDALPamRasterBand;
122 
123  private:
124  int IsPamFilenameAPotentialSiblingFile();
125 
126  protected:
127 
128  GDALPamDataset(void);
130  int nPamFlags = 0;
131  GDALDatasetPamInfo *psPam = nullptr;
132 
133  virtual const char *_GetProjectionRef() override;
134  virtual const char *_GetGCPProjection() override;
135  virtual CPLErr _SetProjection( const char * pszProjection ) override;
136  virtual CPLErr _SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
137  const char *pszGCPProjection ) override;
138 
139  virtual CPLXMLNode *SerializeToXML( const char *);
140  virtual CPLErr XMLInit( CPLXMLNode *, const char * );
141 
142  virtual CPLErr TryLoadXML(char **papszSiblingFiles = nullptr);
143  virtual CPLErr TrySaveXML();
144 
145  CPLErr TryLoadAux(char **papszSiblingFiles = nullptr);
146  CPLErr TrySaveAux();
147 
148  virtual const char *BuildPamFilename();
149 
150  void PamInitialize();
151  void PamClear();
152 
153  void SetPhysicalFilename( const char * );
154  const char *GetPhysicalFilename();
155  void SetSubdatasetName( const char *);
156  const char *GetSubdatasetName();
158 
159  public:
160  ~GDALPamDataset() override;
161 
162  void FlushCache(bool bAtClosing) override;
163 
164  const OGRSpatialReference* GetSpatialRef() const override;
165  CPLErr SetSpatialRef(const OGRSpatialReference* poSRS) override;
166 
167  CPLErr GetGeoTransform( double * ) override;
168  CPLErr SetGeoTransform( double * ) override;
169  void DeleteGeoTransform();
170 
171  int GetGCPCount() override;
172  const OGRSpatialReference* GetGCPSpatialRef() const override;
173  const GDAL_GCP *GetGCPs() override;
174  using GDALDataset::SetGCPs;
175  CPLErr SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
176  const OGRSpatialReference* poSRS ) override;
177 
178  CPLErr SetMetadata( char ** papszMetadata,
179  const char * pszDomain = "" ) override;
180  CPLErr SetMetadataItem( const char * pszName,
181  const char * pszValue,
182  const char * pszDomain = "" ) override;
183  char **GetMetadata( const char * pszDomain = "" ) override;
184  const char *GetMetadataItem( const char * pszName,
185  const char * pszDomain = "" ) override;
186 
187  char **GetFileList(void) override;
188 
189  void ClearStatistics() override;
190 
192  virtual CPLErr CloneInfo( GDALDataset *poSrcDS, int nCloneInfoFlags );
193 
194  CPLErr IBuildOverviews( const char *pszResampling,
195  int nOverviews, int *panOverviewList,
196  int nListBands, int *panBandList,
197  GDALProgressFunc pfnProgress,
198  void * pProgressData ) override;
199 
200  // "semi private" methods.
201  void MarkPamDirty() { nPamFlags |= GPF_DIRTY; }
202  GDALDatasetPamInfo *GetPamInfo() { return psPam; }
203  int GetPamFlags() { return nPamFlags; }
204  void SetPamFlags(int nValue ) { nPamFlags = nValue; }
206 
207  private:
209 };
210 
212 /* ==================================================================== */
213 /* GDALRasterBandPamInfo */
214 /* */
215 /* We make these things a separate structure of information */
216 /* primarily so we can modify it without altering the size of */
217 /* the GDALPamDataset. It is an effort to reduce ABI churn for */
218 /* driver plugins. */
219 /* ==================================================================== */
220 typedef struct {
221  GDALPamDataset *poParentDS;
222 
223  int bNoDataValueSet;
224  double dfNoDataValue;
225 
226  GDALColorTable *poColorTable;
227 
228  GDALColorInterp eColorInterp;
229 
230  char *pszUnitType;
231  char **papszCategoryNames;
232 
233  double dfOffset;
234  double dfScale;
235 
236  int bHaveMinMax;
237  double dfMin;
238  double dfMax;
239 
240  int bHaveStats;
241  double dfMean;
242  double dfStdDev;
243 
244  CPLXMLNode *psSavedHistograms;
245 
246  GDALRasterAttributeTable *poDefaultRAT;
247 
248  bool bOffsetSet;
249  bool bScaleSet;
250 } GDALRasterBandPamInfo;
252 /* ******************************************************************** */
253 /* GDALPamRasterBand */
254 /* ******************************************************************** */
255 
257 class CPL_DLL GDALPamRasterBand : public GDALRasterBand
258 {
259  friend class GDALPamDataset;
260 
261  protected:
263  virtual CPLXMLNode *SerializeToXML( const char *pszVRTPath );
264  virtual CPLErr XMLInit( CPLXMLNode *, const char * );
265 
266  void PamInitialize();
267  void PamClear();
268 
269  GDALRasterBandPamInfo *psPam = nullptr;
271 
272  public:
275  explicit GDALPamRasterBand(int bForceCachedIO);
277  ~GDALPamRasterBand() override;
278 
279  void SetDescription( const char * ) override;
280 
281  CPLErr SetNoDataValue( double ) override;
282  double GetNoDataValue( int *pbSuccess = nullptr ) override;
283  CPLErr DeleteNoDataValue() override;
284 
285  CPLErr SetColorTable( GDALColorTable * ) override;
286  GDALColorTable *GetColorTable() override;
287 
290 
291  const char *GetUnitType() override;
292  CPLErr SetUnitType( const char * ) override;
293 
294  char **GetCategoryNames() override;
295  CPLErr SetCategoryNames( char ** ) override;
296 
297  double GetOffset( int *pbSuccess = nullptr ) override;
298  CPLErr SetOffset( double ) override;
299  double GetScale( int *pbSuccess = nullptr ) override;
300  CPLErr SetScale( double ) override;
301 
302  CPLErr GetHistogram( double dfMin, double dfMax,
303  int nBuckets, GUIntBig * panHistogram,
304  int bIncludeOutOfRange, int bApproxOK,
305  GDALProgressFunc, void *pProgressData ) override;
306 
307  CPLErr GetDefaultHistogram( double *pdfMin, double *pdfMax,
308  int *pnBuckets, GUIntBig ** ppanHistogram,
309  int bForce,
310  GDALProgressFunc, void *pProgressData) override;
311 
312  CPLErr SetDefaultHistogram( double dfMin, double dfMax,
313  int nBuckets, GUIntBig *panHistogram ) override;
314 
315  CPLErr SetMetadata( char ** papszMetadata,
316  const char * pszDomain = "" ) override;
317  CPLErr SetMetadataItem( const char * pszName,
318  const char * pszValue,
319  const char * pszDomain = "" ) override;
320 
322  CPLErr SetDefaultRAT( const GDALRasterAttributeTable * ) override;
323 
325  // new in GDALPamRasterBand.
326  virtual CPLErr CloneInfo( GDALRasterBand *poSrcBand, int nCloneInfoFlags );
327 
328  // "semi private" methods.
329  GDALRasterBandPamInfo *GetPamInfo() { return psPam; }
331  private:
333 };
334 
336 
337 /* ******************************************************************** */
338 /* GDALPamMultiDim */
339 /* ******************************************************************** */
340 
344 class CPL_DLL GDALPamMultiDim
345 {
346  struct Private;
347  std::unique_ptr<Private> d;
348 
349  void Load();
350  void Save();
351 
352 public:
353  explicit GDALPamMultiDim(const std::string& osFilename);
354  virtual ~GDALPamMultiDim();
355 
356  std::shared_ptr<OGRSpatialReference> GetSpatialRef(const std::string& osArrayFullName);
357 
358  void SetSpatialRef(const std::string& osArrayFullName,
359  const OGRSpatialReference* poSRS);
360 
361  CPLErr GetStatistics( const std::string& osArrayFullName,
362  bool bApproxOK,
363  double *pdfMin, double *pdfMax,
364  double *pdfMean, double *pdfStdDev,
365  GUInt64* pnValidCount);
366 
367  void SetStatistics( const std::string& osArrayFullName,
368  bool bApproxStats,
369  double dfMin, double dfMax,
370  double dfMean, double dfStdDev,
371  GUInt64 nValidCount );
372 
373  void ClearStatistics();
374 
375  void ClearStatistics( const std::string& osArrayFullName );
376 };
377 
378 /* ******************************************************************** */
379 /* GDALPamMDArray */
380 /* ******************************************************************** */
381 
383 class CPL_DLL GDALPamMDArray: public GDALMDArray
384 {
385  std::shared_ptr<GDALPamMultiDim> m_poPam;
386 
387 protected:
388  GDALPamMDArray(const std::string& osParentName,
389  const std::string& osName,
390  const std::shared_ptr<GDALPamMultiDim>& poPam);
391 
392  bool SetStatistics( bool bApproxStats,
393  double dfMin, double dfMax,
394  double dfMean, double dfStdDev,
395  GUInt64 nValidCount ) override;
396 
397 public:
398  const std::shared_ptr<GDALPamMultiDim>& GetPAM() const { return m_poPam; }
399 
400  CPLErr GetStatistics( bool bApproxOK, bool bForce,
401  double *pdfMin, double *pdfMax,
402  double *pdfMean, double *padfStdDev,
403  GUInt64* pnValidCount,
404  GDALProgressFunc pfnProgress, void *pProgressData ) override;
405 
406  void ClearStatistics() override;
407 
408  bool SetSpatialRef(const OGRSpatialReference* poSRS) override;
409 
410  std::shared_ptr<OGRSpatialReference> GetSpatialRef() const override;
411 };
412 
413 // These are mainly helper functions for internal use.
414 int CPL_DLL PamParseHistogram( CPLXMLNode *psHistItem,
415  double *pdfMin, double *pdfMax,
416  int *pnBuckets, GUIntBig **ppanHistogram,
417  int *pbIncludeOutOfRange, int *pbApproxOK );
418 CPLXMLNode CPL_DLL *
419 PamFindMatchingHistogram( CPLXMLNode *psSavedHistograms,
420  double dfMin, double dfMax, int nBuckets,
421  int bIncludeOutOfRange, int bApproxOK );
422 CPLXMLNode CPL_DLL *
423 PamHistogramToXMLTree( double dfMin, double dfMax,
424  int nBuckets, GUIntBig * panHistogram,
425  int bIncludeOutOfRange, int bApprox );
426 
427 // For managing the proxy file database.
428 const char CPL_DLL * PamGetProxy( const char * );
429 const char CPL_DLL * PamAllocateProxy( const char * );
430 const char CPL_DLL * PamDeallocateProxy( const char * );
431 void CPL_DLL PamCleanProxyDB( void );
432 
434 
435 #endif /* ndef GDAL_PAM_H_INCLUDED */
The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute ...
Definition: gdal_rat.h:47
virtual CPLErr GetGeoTransform(double *padfTransform)
Fetch the affine transformation coefficients.
Definition: gdaldataset.cpp:1177
virtual CPLErr SetCategoryNames(char **papszNames)
Set the category names for this band.
Definition: gdalrasterband.cpp:1573
Document node structure.
Definition: cpl_minixml.h:69
Definitions for CPL mini XML Parser/Serializer.
virtual char ** GetCategoryNames()
Fetch the list of category names for this raster.
Definition: gdalrasterband.cpp:1525
virtual void SetDescription(const char *)
Set object description.
Definition: gdalmajorobject.cpp:120
virtual CPLErr GetDefaultHistogram(double *pdfMin, double *pdfMax, int *pnBuckets, GUIntBig **ppanHistogram, int bForce, GDALProgressFunc, void *pProgressData)
Fetch default raster histogram.
Definition: gdalrasterband.cpp:3479
C++ GDAL entry points.
virtual GDALColorInterp GetColorInterpretation()
How should this band be interpreted as color?
Definition: gdalrasterband.cpp:1968
virtual std::shared_ptr< OGRSpatialReference > GetSpatialRef() const
Return the spatial reference system object associated with the array.
Definition: gdalmultidim.cpp:2114
virtual CPLErr SetDefaultRAT(const GDALRasterAttributeTable *poRAT)
Set default Raster Attribute Table.
Definition: gdalrasterband.cpp:5872
virtual GDALRasterAttributeTable * GetDefaultRAT()
Fetch default Raster Attribute Table.
Definition: gdalrasterband.cpp:5824
virtual void ClearStatistics()
Clear statistics
Definition: gdaldataset.cpp:8415
virtual CPLErr GetHistogram(double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc, void *pProgressData)
Compute raster histogram.
Definition: gdalrasterband.cpp:2937
Convenient string class based on std::string.
Definition: cpl_string.h:332
virtual CPLErr SetOffset(double dfNewOffset)
Set scaling offset.
Definition: gdalrasterband.cpp:2484
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
void static void char ** GetMetadata(const char *pszDomain="") override
Fetch metadata.
Definition: gdaldataset.cpp:4229
CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain) override
Set single metadata item.
virtual bool SetSpatialRef(const OGRSpatialReference *poSRS)
Assign a spatial reference system object to the the array.
Definition: gdalmultidim.cpp:2100
virtual CPLErr SetDefaultHistogram(double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram)
Set default histogram.
Definition: gdalrasterband.cpp:5725
virtual double GetScale(int *pbSuccess=nullptr)
Fetch the raster value scale.
Definition: gdalrasterband.cpp:2541
GUIntBig GUInt64
Unsigned 64 bit integer type.
Definition: cpl_port.h:265
virtual const char * GetMetadataItem(const char *pszName, const char *pszDomain="")
Fetch single metadata item.
Definition: gdalmajorobject.cpp:344
PAM raster band.
Definition: gdal_pam.h:257
virtual const GDAL_GCP * GetGCPs()
Fetch GCPs.
Definition: gdaldataset.cpp:1729
virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList, const OGRSpatialReference *poGCP_SRS)
Assign GCPs.
Definition: gdaldataset.cpp:1834
virtual CPLErr DeleteNoDataValue()
Remove the no data value for this band.
Definition: gdalrasterband.cpp:1738
virtual CPLErr SetSpatialRef(const OGRSpatialReference *poSRS)
Set the spatial reference system for this dataset.
Definition: gdaldataset.cpp:1059
virtual const OGRSpatialReference * GetSpatialRef() const
Fetch the spatial reference for this dataset.
Definition: gdaldataset.cpp:928
virtual CPLErr SetGeoTransform(double *padfTransform)
Set the affine transformation coefficients.
Definition: gdaldataset.cpp:1232
virtual double GetNoDataValue(int *pbSuccess=nullptr)
Fetch the no data value for this band.
Definition: gdalrasterband.cpp:1625
virtual int GetGCPCount()
Get number of GCPs.
Definition: gdaldataset.cpp:1549
virtual void FlushCache(bool bAtClosing=false)
Flush all write cached data to disk.
Definition: gdaldataset.cpp:435
virtual CPLErr SetColorInterpretation(GDALColorInterp eColorInterp)
Set color interpretation of a band.
Definition: gdalrasterband.cpp:2013
virtual const char * GetUnitType()
Return raster unit type.
Definition: gdalrasterband.cpp:2637
PAM dataset.
Definition: gdal_pam.h:119
virtual const OGRSpatialReference * GetGCPSpatialRef() const
Get output spatial reference system for GCPs.
Definition: gdaldataset.cpp:1646
virtual CPLErr SetColorTable(GDALColorTable *poCT)
Set the raster color table.
Definition: gdalrasterband.cpp:2109
virtual GDALColorTable * GetColorTable()
Fetch the color table associated with band.
Definition: gdalrasterband.cpp:2060
unsigned long long GUIntBig
Large unsigned integer type (generally 64-bit unsigned integer type).
Definition: cpl_port.h:247
virtual char ** GetFileList(void)
Fetch files forming dataset.
Definition: gdaldataset.cpp:3026
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition: ogr_spatialref.h:157
virtual CPLErr SetScale(double dfNewScale)
Set scaling ratio.
Definition: gdalrasterband.cpp:2590
virtual double GetOffset(int *pbSuccess=nullptr)
Fetch the raster value offset.
Definition: gdalrasterband.cpp:2435
CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain) override
Set single metadata item.
virtual CPLErr SetUnitType(const char *pszNewValue)
Set unit type.
Definition: gdalrasterband.cpp:2685
A single raster band (or channel).
Definition: gdal_priv.h:1133
A set of associated raster bands, usually from one file.
Definition: gdal_priv.h:339
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
GDALColorInterp
Definition: gdal.h:203
Class modeling a multi-dimensional array.
Definition: gdal_priv.h:2375
virtual CPLErr SetNoDataValue(double dfNoData)
Set the no data value for this band.
Definition: gdalrasterband.cpp:1684
virtual void ClearStatistics()
Clear statistics.
Definition: gdalmultidim.cpp:7588
A color table / palette.
Definition: gdal_priv.h:1024
Ground Control Point.
Definition: gdal.h:710
CPLErr
Error category.
Definition: cpl_error.h:52
#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:955
virtual CPLErr GetStatistics(bool bApproxOK, bool bForce, double *pdfMin, double *pdfMax, double *pdfMean, double *padfStdDev, GUInt64 *pnValidCount, GDALProgressFunc pfnProgress, void *pProgressData)
Fetch statistics.
Definition: gdalmultidim.cpp:7347