warningnull1 /******************************************************************************
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
33 //! @cond Doxygen_Suppress
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 };
119 //! @endcond
120
121 /* ******************************************************************** */
122 /* GDALPamDataset */
123 /* ******************************************************************** */
124
125 /** PAM dataset */
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);
136 //! @cond Doxygen_Suppress
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();
166 //! @endcond
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
199 //! @cond Doxygen_Suppress
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; }
225 //! @endcond
226
227 private:
228 CPL_DISALLOW_COPY_ASSIGN(GDALPamDataset)
229 };
230
231 //! @cond Doxygen_Suppress
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;
271 //! @endcond
272 /* ******************************************************************** */
273 /* GDALPamRasterBand */
274 /* ******************************************************************** */
275
276 /** PAM raster band */
277 class CPL_DLL GDALPamRasterBand : public GDALRasterBand
278 {
279 friend class GDALPamDataset;
280
281 protected:
282 //! @cond Doxygen_Suppress
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;
290 //! @endcond
291
292 public:
293 GDALPamRasterBand();
294 //! @cond Doxygen_Suppress
295 explicit GDALPamRasterBand(int bForceCachedIO);
296 //! @endcond
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
308 CPLErr SetColorInterpretation( GDALColorInterp ) override;
309 GDALColorInterp GetColorInterpretation() override;
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
341 GDALRasterAttributeTable *GetDefaultRAT() override;
342 CPLErr SetDefaultRAT( const GDALRasterAttributeTable * ) override;
343
344 //! @cond Doxygen_Suppress
345 // new in GDALPamRasterBand.
346 virtual CPLErr CloneInfo( GDALRasterBand *poSrcBand, int nCloneInfoFlags );
347
348 // "semi private" methods.
349 GDALRasterBandPamInfo *GetPamInfo() { return psPam; }
350 //! @endcond
351 private:
352 CPL_DISALLOW_COPY_ASSIGN(GDALPamRasterBand)
353 };
354
355 //! @cond Doxygen_Suppress
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
376 //! @endcond
377
378 #endif /* ndef GDAL_PAM_H_INCLUDED */
379