GDAL
gdal_pam.h
1 /******************************************************************************
2  * $Id: gdal_pam.h 2e6733101e6356653e8c999cb7fe808abc22ed11 2020-08-11 14:57:51 +0200 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 "gdal_priv.h"
36 #include <map>
37 
38 class GDALPamRasterBand;
39 
40 /* Clone Info Flags */
41 
42 #define GCIF_GEOTRANSFORM 0x01
43 #define GCIF_PROJECTION 0x02
44 #define GCIF_METADATA 0x04
45 #define GCIF_GCPS 0x08
46 
47 #define GCIF_NODATA 0x001000
48 #define GCIF_CATEGORYNAMES 0x002000
49 #define GCIF_MINMAX 0x004000
50 #define GCIF_SCALEOFFSET 0x008000
51 #define GCIF_UNITTYPE 0x010000
52 #define GCIF_COLORTABLE 0x020000
53 #define GCIF_COLORINTERP 0x020000
54 #define GCIF_BAND_METADATA 0x040000
55 #define GCIF_RAT 0x080000
56 #define GCIF_MASK 0x100000
57 #define GCIF_BAND_DESCRIPTION 0x200000
58 
59 #define GCIF_ONLY_IF_MISSING 0x10000000
60 #define GCIF_PROCESS_BANDS 0x20000000
61 
62 #define GCIF_PAM_DEFAULT (GCIF_GEOTRANSFORM | GCIF_PROJECTION | \
63  GCIF_METADATA | GCIF_GCPS | \
64  GCIF_NODATA | GCIF_CATEGORYNAMES | \
65  GCIF_MINMAX | GCIF_SCALEOFFSET | \
66  GCIF_UNITTYPE | GCIF_COLORTABLE | \
67  GCIF_COLORINTERP | GCIF_BAND_METADATA | \
68  GCIF_RAT | GCIF_MASK | \
69  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 /* ==================================================================== */
88 class GDALDatasetPamInfo
89 {
90 public:
91  char *pszPamFilename = nullptr;
92 
93  OGRSpatialReference* poSRS = nullptr;
94 
95  int bHaveGeoTransform = false;
96  double adfGeoTransform[6]{0,0,0,0,0,0};
97 
98  int nGCPCount = 0;
99  GDAL_GCP *pasGCPList = nullptr;
100  OGRSpatialReference* poGCP_SRS = nullptr;
101 
102  CPLString osPhysicalFilename{};
103  CPLString osSubdatasetName{};
104  CPLString osAuxFilename{};
105 
106  int bHasMetadata = false;
107 
108  struct Statistics
109  {
110  bool bApproxStats;
111  double dfMin;
112  double dfMax;
113  double dfMean;
114  double dfStdDev;
115  GUInt64 nValidCount;
116  };
117  std::map<CPLString, Statistics> oMapMDArrayStatistics{};
118 };
120 
121 /* ******************************************************************** */
122 /* GDALPamDataset */
123 /* ******************************************************************** */
124 
126 class CPL_DLL GDALPamDataset : public GDALDataset
127 {
128  friend class GDALPamRasterBand;
129 
130  private:
131  int IsPamFilenameAPotentialSiblingFile();
132 
133  protected:
134 
135  GDALPamDataset(void);
137  int nPamFlags = 0;
138  GDALDatasetPamInfo *psPam = nullptr;
139 
140  virtual const char *_GetProjectionRef() override;
141  virtual const char *_GetGCPProjection() override;
142  virtual CPLErr _SetProjection( const char * pszProjection ) override;
143  virtual CPLErr _SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
144  const char *pszGCPProjection ) override;
145 
146  virtual CPLXMLNode *SerializeToXML( const char *);
147  virtual CPLErr XMLInit( CPLXMLNode *, const char * );
148 
149  virtual CPLErr TryLoadXML(char **papszSiblingFiles = nullptr);
150  virtual CPLErr TrySaveXML();
151 
152  CPLErr TryLoadAux(char **papszSiblingFiles = nullptr);
153  CPLErr TrySaveAux();
154 
155  void SerializeMDArrayStatistics(CPLXMLNode* psDSTree);
156 
157  virtual const char *BuildPamFilename();
158 
159  void PamInitialize();
160  void PamClear();
161 
162  void SetPhysicalFilename( const char * );
163  const char *GetPhysicalFilename();
164  void SetSubdatasetName( const char *);
165  const char *GetSubdatasetName();
167 
168  public:
169  ~GDALPamDataset() override;
170 
171  void FlushCache(void) override;
172 
173  const OGRSpatialReference* GetSpatialRef() const override;
174  CPLErr SetSpatialRef(const OGRSpatialReference* poSRS) override;
175 
176  CPLErr GetGeoTransform( double * ) override;
177  CPLErr SetGeoTransform( double * ) override;
178 
179  int GetGCPCount() override;
180  const OGRSpatialReference* GetGCPSpatialRef() const override;
181  const GDAL_GCP *GetGCPs() override;
182  using GDALDataset::SetGCPs;
183  CPLErr SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
184  const OGRSpatialReference* poSRS ) override;
185 
186  CPLErr SetMetadata( char ** papszMetadata,
187  const char * pszDomain = "" ) override;
188  CPLErr SetMetadataItem( const char * pszName,
189  const char * pszValue,
190  const char * pszDomain = "" ) override;
191  char **GetMetadata( const char * pszDomain = "" ) override;
192  const char *GetMetadataItem( const char * pszName,
193  const char * pszDomain = "" ) override;
194 
195  char **GetFileList(void) override;
196 
197  void ClearStatistics() override;
198 
200  virtual CPLErr CloneInfo( GDALDataset *poSrcDS, int nCloneInfoFlags );
201 
202  CPLErr IBuildOverviews( const char *pszResampling,
203  int nOverviews, int *panOverviewList,
204  int nListBands, int *panBandList,
205  GDALProgressFunc pfnProgress,
206  void * pProgressData ) override;
207 
208  bool GetMDArrayStatistics( const char* pszMDArrayId,
209  bool *pbApprox,
210  double *pdfMin, double *pdfMax,
211  double *pdfMean, double *pdfStdDev,
212  GUInt64 *pnValidCount );
213 
214  void StoreMDArrayStatistics( const char* pszMDArrayId,
215  bool bApprox,
216  double dfMin, double dfMax,
217  double dfMean, double dfStdDev,
218  GUInt64 nValidCount );
219 
220  // "semi private" methods.
221  void MarkPamDirty() { nPamFlags |= GPF_DIRTY; }
222  GDALDatasetPamInfo *GetPamInfo() { return psPam; }
223  int GetPamFlags() { return nPamFlags; }
224  void SetPamFlags(int nValue ) { nPamFlags = nValue; }
226 
227  private:
229 };
230 
232 /* ==================================================================== */
233 /* GDALRasterBandPamInfo */
234 /* */
235 /* We make these things a separate structure of information */
236 /* primarily so we can modify it without altering the size of */
237 /* the GDALPamDataset. It is an effort to reduce ABI churn for */
238 /* driver plugins. */
239 /* ==================================================================== */
240 typedef struct {
241  GDALPamDataset *poParentDS;
242 
243  int bNoDataValueSet;
244  double dfNoDataValue;
245 
246  GDALColorTable *poColorTable;
247 
248  GDALColorInterp eColorInterp;
249 
250  char *pszUnitType;
251  char **papszCategoryNames;
252 
253  double dfOffset;
254  double dfScale;
255 
256  int bHaveMinMax;
257  double dfMin;
258  double dfMax;
259 
260  int bHaveStats;
261  double dfMean;
262  double dfStdDev;
263 
264  CPLXMLNode *psSavedHistograms;
265 
266  GDALRasterAttributeTable *poDefaultRAT;
267 
268  bool bOffsetSet;
269  bool bScaleSet;
270 } GDALRasterBandPamInfo;
272 /* ******************************************************************** */
273 /* GDALPamRasterBand */
274 /* ******************************************************************** */
275 
277 class CPL_DLL GDALPamRasterBand : public GDALRasterBand
278 {
279  friend class GDALPamDataset;
280 
281  protected:
283  virtual CPLXMLNode *SerializeToXML( const char *pszVRTPath );
284  virtual CPLErr XMLInit( CPLXMLNode *, const char * );
285 
286  void PamInitialize();
287  void PamClear();
288 
289  GDALRasterBandPamInfo *psPam = nullptr;
291 
292  public:
295  explicit GDALPamRasterBand(int bForceCachedIO);
297  ~GDALPamRasterBand() override;
298 
299  void SetDescription( const char * ) override;
300 
301  CPLErr SetNoDataValue( double ) override;
302  double GetNoDataValue( int *pbSuccess = nullptr ) override;
303  CPLErr DeleteNoDataValue() override;
304 
305  CPLErr SetColorTable( GDALColorTable * ) override;
306  GDALColorTable *GetColorTable() override;
307 
310 
311  const char *GetUnitType() override;
312  CPLErr SetUnitType( const char * ) override;
313 
314  char **GetCategoryNames() override;
315  CPLErr SetCategoryNames( char ** ) override;
316 
317  double GetOffset( int *pbSuccess = nullptr ) override;
318  CPLErr SetOffset( double ) override;
319  double GetScale( int *pbSuccess = nullptr ) override;
320  CPLErr SetScale( double ) override;
321 
322  CPLErr GetHistogram( double dfMin, double dfMax,
323  int nBuckets, GUIntBig * panHistogram,
324  int bIncludeOutOfRange, int bApproxOK,
325  GDALProgressFunc, void *pProgressData ) override;
326 
327  CPLErr GetDefaultHistogram( double *pdfMin, double *pdfMax,
328  int *pnBuckets, GUIntBig ** ppanHistogram,
329  int bForce,
330  GDALProgressFunc, void *pProgressData) override;
331 
332  CPLErr SetDefaultHistogram( double dfMin, double dfMax,
333  int nBuckets, GUIntBig *panHistogram ) override;
334 
335  CPLErr SetMetadata( char ** papszMetadata,
336  const char * pszDomain = "" ) override;
337  CPLErr SetMetadataItem( const char * pszName,
338  const char * pszValue,
339  const char * pszDomain = "" ) override;
340 
342  CPLErr SetDefaultRAT( const GDALRasterAttributeTable * ) override;
343 
345  // new in GDALPamRasterBand.
346  virtual CPLErr CloneInfo( GDALRasterBand *poSrcBand, int nCloneInfoFlags );
347 
348  // "semi private" methods.
349  GDALRasterBandPamInfo *GetPamInfo() { return psPam; }
351  private:
353 };
354 
356 // These are mainly helper functions for internal use.
357 int CPL_DLL PamParseHistogram( CPLXMLNode *psHistItem,
358  double *pdfMin, double *pdfMax,
359  int *pnBuckets, GUIntBig **ppanHistogram,
360  int *pbIncludeOutOfRange, int *pbApproxOK );
361 CPLXMLNode CPL_DLL *
362 PamFindMatchingHistogram( CPLXMLNode *psSavedHistograms,
363  double dfMin, double dfMax, int nBuckets,
364  int bIncludeOutOfRange, int bApproxOK );
365 CPLXMLNode CPL_DLL *
366 PamHistogramToXMLTree( double dfMin, double dfMax,
367  int nBuckets, GUIntBig * panHistogram,
368  int bIncludeOutOfRange, int bApprox );
369 
370 // For managing the proxy file database.
371 const char CPL_DLL * PamGetProxy( const char * );
372 const char CPL_DLL * PamAllocateProxy( const char * );
373 const char CPL_DLL * PamDeallocateProxy( const char * );
374 void CPL_DLL PamCleanProxyDB( void );
375 
377 
378 #endif /* ndef GDAL_PAM_H_INCLUDED */
GDALRasterBand::SetNoDataValue
virtual CPLErr SetNoDataValue(double dfNoData)
Set the no data value for this band.
Definition: gdalrasterband.cpp:1674
GDALRasterBand::GetColorTable
virtual GDALColorTable * GetColorTable()
Fetch the color table associated with band.
Definition: gdalrasterband.cpp:2050
GUInt64
GUIntBig GUInt64
Unsigned 64 bit integer type.
Definition: cpl_port.h:269
GDALRasterBand::GetUnitType
virtual const char * GetUnitType()
Return raster unit type.
Definition: gdalrasterband.cpp:2627
GDALRasterBand::DeleteNoDataValue
virtual CPLErr DeleteNoDataValue()
Remove the no data value for this band.
Definition: gdalrasterband.cpp:1728
GDALRasterBand::GetOffset
virtual double GetOffset(int *pbSuccess=nullptr)
Fetch the raster value offset.
Definition: gdalrasterband.cpp:2425
GDALRasterBand::SetColorTable
virtual CPLErr SetColorTable(GDALColorTable *poCT)
Set the raster color table.
Definition: gdalrasterband.cpp:2099
GDALRasterBand::GetDefaultHistogram
virtual CPLErr GetDefaultHistogram(double *pdfMin, double *pdfMax, int *pnBuckets, GUIntBig **ppanHistogram, int bForce, GDALProgressFunc, void *pProgressData)
Fetch default raster histogram.
Definition: gdalrasterband.cpp:3469
GDALPamDataset
PAM dataset.
Definition: gdal_pam.h:127
GDALPamRasterBand
PAM raster band.
Definition: gdal_pam.h:278
OGRSpatialReference
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition: ogr_spatialref.h:158
GDALRasterBand::SetDefaultHistogram
virtual CPLErr SetDefaultHistogram(double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram)
Set default histogram.
Definition: gdalrasterband.cpp:5722
GDALRasterBand::SetUnitType
virtual CPLErr SetUnitType(const char *pszNewValue)
Set unit type.
Definition: gdalrasterband.cpp:2675
GDALRasterBand::GetColorInterpretation
virtual GDALColorInterp GetColorInterpretation()
How should this band be interpreted as color?
Definition: gdalrasterband.cpp:1958
GDALRasterBand::GetCategoryNames
virtual char ** GetCategoryNames()
Fetch the list of category names for this raster.
Definition: gdalrasterband.cpp:1515
GDALColorInterp
GDALColorInterp
Definition: gdal.h:194
GDALMajorObject::SetDescription
virtual void SetDescription(const char *)
Set object description.
Definition: gdalmajorobject.cpp:120
CPLString
Convenient string class based on std::string.
Definition: cpl_string.h:333
GDALDataset::FlushCache
virtual void FlushCache(void)
Flush all write cached data to disk.
Definition: gdaldataset.cpp:418
GDALRasterBand
A single raster band (or channel).
Definition: gdal_priv.h:1112
GDALDataset::GetMetadata
void static void char ** GetMetadata(const char *pszDomain="") override
Fetch metadata.
Definition: gdaldataset.cpp:4128
CPLXMLNode
Document node structure.
Definition: cpl_minixml.h:70
GDALMajorObject::GetMetadataItem
virtual const char * GetMetadataItem(const char *pszName, const char *pszDomain="")
Fetch single metadata item.
Definition: gdalmajorobject.cpp:344
GDALDataset::SetGCPs
virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList, const OGRSpatialReference *poGCP_SRS)
Assign GCPs.
Definition: gdaldataset.cpp:1783
GDALDataset::GetGCPs
virtual const GDAL_GCP * GetGCPs()
Fetch GCPs.
Definition: gdaldataset.cpp:1678
GDALDataset
A set of associated raster bands, usually from one file.
Definition: gdal_priv.h:340
GDALRasterBand::SetDefaultRAT
virtual CPLErr SetDefaultRAT(const GDALRasterAttributeTable *poRAT)
Set default Raster Attribute Table.
Definition: gdalrasterband.cpp:5869
GDALDataset::ClearStatistics
virtual void ClearStatistics()
Clear statistics.
Definition: gdaldataset.cpp:8266
GUIntBig
unsigned long long GUIntBig
Large unsigned integer type (generally 64-bit unsigned integer type).
Definition: cpl_port.h:251
GDALDataset::GetGCPSpatialRef
virtual const OGRSpatialReference * GetGCPSpatialRef() const
Get output spatial reference system for GCPs.
Definition: gdaldataset.cpp:1595
GDALDataset::SetSpatialRef
virtual CPLErr SetSpatialRef(const OGRSpatialReference *poSRS)
Set the spatial reference system for this dataset.
Definition: gdaldataset.cpp:1040
GDAL_GCP
Ground Control Point.
Definition: gdal.h:669
GDALDataset::GetGCPCount
virtual int GetGCPCount()
Get number of GCPs.
Definition: gdaldataset.cpp:1500
GDALRasterBand::SetScale
virtual CPLErr SetScale(double dfNewScale)
Set scaling ratio.
Definition: gdalrasterband.cpp:2580
GDALRasterBand::GetNoDataValue
virtual double GetNoDataValue(int *pbSuccess=nullptr)
Fetch the no data value for this band.
Definition: gdalrasterband.cpp:1615
gdal_priv.h
C++ GDAL entry points.
GDALDataset::GetSpatialRef
virtual const OGRSpatialReference * GetSpatialRef() const
Fetch the spatial reference for this dataset.
Definition: gdaldataset.cpp:909
GDALDataset::SetGeoTransform
virtual CPLErr SetGeoTransform(double *padfTransform)
Set the affine transformation coefficients.
Definition: gdaldataset.cpp:1213
GDALDataset::GetFileList
virtual char ** GetFileList(void)
Fetch files forming dataset.
Definition: gdaldataset.cpp:2943
GDALRasterBand::GetDefaultRAT
virtual GDALRasterAttributeTable * GetDefaultRAT()
Fetch default Raster Attribute Table.
Definition: gdalrasterband.cpp:5821
GDALRasterBand::GetScale
virtual double GetScale(int *pbSuccess=nullptr)
Fetch the raster value scale.
Definition: gdalrasterband.cpp:2531
GDALRasterBand::SetColorInterpretation
virtual CPLErr SetColorInterpretation(GDALColorInterp eColorInterp)
Set color interpretation of a band.
Definition: gdalrasterband.cpp:2003
GDALDataset::SetMetadataItem
CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain) override
Set single metadata item.
CPLErr
CPLErr
Error category.
Definition: cpl_error.h:53
GDALDataset::SetMetadata
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
GDALRasterBand::SetCategoryNames
virtual CPLErr SetCategoryNames(char **papszNames)
Set the category names for this band.
Definition: gdalrasterband.cpp:1563
GDALRasterBand::GetHistogram
virtual CPLErr GetHistogram(double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc, void *pProgressData)
Compute raster histogram.
Definition: gdalrasterband.cpp:2927
GDALDataset::GetGeoTransform
virtual CPLErr GetGeoTransform(double *padfTransform)
Fetch the affine transformation coefficients.
Definition: gdaldataset.cpp:1158
GDALRasterBand::SetMetadata
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
GDALRasterAttributeTable
The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute ...
Definition: gdal_rat.h:48
GDALRasterBand::SetMetadataItem
CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain) override
Set single metadata item.
GDALRasterBand::SetOffset
virtual CPLErr SetOffset(double dfNewOffset)
Set scaling offset.
Definition: gdalrasterband.cpp:2474
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:1007
GDALColorTable
A color table / palette.
Definition: gdal_priv.h:1006