GDAL
gdal_pam.h
1/******************************************************************************
2 * $Id: gdal_pam.h 8e5eeb35bf76390e3134a4ea7076dab7d478ea0e 2018-11-14 22:55:13 +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 "gdal_priv.h"
36
38
39/* Clone Info Flags */
40
41#define GCIF_GEOTRANSFORM 0x01
42#define GCIF_PROJECTION 0x02
43#define GCIF_METADATA 0x04
44#define GCIF_GCPS 0x08
45
46#define GCIF_NODATA 0x001000
47#define GCIF_CATEGORYNAMES 0x002000
48#define GCIF_MINMAX 0x004000
49#define GCIF_SCALEOFFSET 0x008000
50#define GCIF_UNITTYPE 0x010000
51#define GCIF_COLORTABLE 0x020000
52#define GCIF_COLORINTERP 0x020000
53#define GCIF_BAND_METADATA 0x040000
54#define GCIF_RAT 0x080000
55#define GCIF_MASK 0x100000
56#define GCIF_BAND_DESCRIPTION 0x200000
57
58#define GCIF_ONLY_IF_MISSING 0x10000000
59#define GCIF_PROCESS_BANDS 0x20000000
60
61#define GCIF_PAM_DEFAULT (GCIF_GEOTRANSFORM | GCIF_PROJECTION | \
62 GCIF_METADATA | GCIF_GCPS | \
63 GCIF_NODATA | GCIF_CATEGORYNAMES | \
64 GCIF_MINMAX | GCIF_SCALEOFFSET | \
65 GCIF_UNITTYPE | GCIF_COLORTABLE | \
66 GCIF_COLORINTERP | GCIF_BAND_METADATA | \
67 GCIF_RAT | GCIF_MASK | \
68 GCIF_ONLY_IF_MISSING | GCIF_PROCESS_BANDS|\
69 GCIF_BAND_DESCRIPTION)
70
71/* GDAL PAM Flags */
72/* ERO 2011/04/13 : GPF_AUXMODE seems to be unimplemented */
73#define GPF_DIRTY 0x01 // .pam file needs to be written on close
74#define GPF_TRIED_READ_FAILED 0x02 // no need to keep trying to read .pam.
75#define GPF_DISABLED 0x04 // do not try any PAM stuff.
76#define GPF_AUXMODE 0x08 // store info in .aux (HFA) file.
77#define GPF_NOSAVE 0x10 // do not try to save pam info.
78
79/* ==================================================================== */
80/* GDALDatasetPamInfo */
81/* */
82/* We make these things a separate structure of information */
83/* primarily so we can modify it without altering the size of */
84/* the GDALPamDataset. It is an effort to reduce ABI churn for */
85/* driver plugins. */
86/* ==================================================================== */
87class GDALDatasetPamInfo
88{
89public:
90 char *pszPamFilename = nullptr;
91
92 OGRSpatialReference* poSRS = nullptr;
93
94 int bHaveGeoTransform = false;
95 double adfGeoTransform[6]{0,0,0,0,0,0};
96
97 int nGCPCount = 0;
98 GDAL_GCP *pasGCPList = nullptr;
99 OGRSpatialReference* poGCP_SRS = nullptr;
100
101 CPLString osPhysicalFilename{};
102 CPLString osSubdatasetName{};
103 CPLString osAuxFilename{};
104
105 int bHasMetadata = false;
106};
108
109/* ******************************************************************** */
110/* GDALPamDataset */
111/* ******************************************************************** */
112
114class CPL_DLL GDALPamDataset : public GDALDataset
115{
116 friend class GDALPamRasterBand;
117
118 private:
119 int IsPamFilenameAPotentialSiblingFile();
120
121 protected:
122
123 GDALPamDataset(void);
125 int nPamFlags = 0;
126 GDALDatasetPamInfo *psPam = nullptr;
127
128 virtual const char *_GetProjectionRef() override;
129 virtual const char *_GetGCPProjection() override;
130 virtual CPLErr _SetProjection( const char * pszProjection ) override;
131 virtual CPLErr _SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
132 const char *pszGCPProjection ) override;
133
134 virtual CPLXMLNode *SerializeToXML( const char *);
135 virtual CPLErr XMLInit( CPLXMLNode *, const char * );
136
137 virtual CPLErr TryLoadXML(char **papszSiblingFiles = nullptr);
138 virtual CPLErr TrySaveXML();
139
140 CPLErr TryLoadAux(char **papszSiblingFiles = nullptr);
141 CPLErr TrySaveAux();
142
143 virtual const char *BuildPamFilename();
144
145 void PamInitialize();
146 void PamClear();
147
148 void SetPhysicalFilename( const char * );
149 const char *GetPhysicalFilename();
150 void SetSubdatasetName( const char *);
151 const char *GetSubdatasetName();
153
154 public:
155 ~GDALPamDataset() override;
156
157 void FlushCache(void) override;
158
159 const OGRSpatialReference* GetSpatialRef() const override;
160 CPLErr SetSpatialRef(const OGRSpatialReference* poSRS) override;
161
162 CPLErr GetGeoTransform( double * ) override;
163 CPLErr SetGeoTransform( double * ) override;
164
165 int GetGCPCount() override;
166 const OGRSpatialReference* GetGCPSpatialRef() const override;
167 const GDAL_GCP *GetGCPs() override;
169 CPLErr SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
170 const OGRSpatialReference* poSRS ) override;
171
172 CPLErr SetMetadata( char ** papszMetadata,
173 const char * pszDomain = "" ) override;
174 CPLErr SetMetadataItem( const char * pszName,
175 const char * pszValue,
176 const char * pszDomain = "" ) override;
177 char **GetMetadata( const char * pszDomain = "" ) override;
178 const char *GetMetadataItem( const char * pszName,
179 const char * pszDomain = "" ) override;
180
181 char **GetFileList(void) override;
182
184 virtual CPLErr CloneInfo( GDALDataset *poSrcDS, int nCloneInfoFlags );
185
186 CPLErr IBuildOverviews( const char *pszResampling,
187 int nOverviews, int *panOverviewList,
188 int nListBands, int *panBandList,
189 GDALProgressFunc pfnProgress,
190 void * pProgressData ) override;
191
192 // "semi private" methods.
193 void MarkPamDirty() { nPamFlags |= GPF_DIRTY; }
194 GDALDatasetPamInfo *GetPamInfo() { return psPam; }
195 int GetPamFlags() { return nPamFlags; }
196 void SetPamFlags(int nValue ) { nPamFlags = nValue; }
198
199 private:
201};
202
204/* ==================================================================== */
205/* GDALRasterBandPamInfo */
206/* */
207/* We make these things a separate structure of information */
208/* primarily so we can modify it without altering the size of */
209/* the GDALPamDataset. It is an effort to reduce ABI churn for */
210/* driver plugins. */
211/* ==================================================================== */
212typedef struct {
213 GDALPamDataset *poParentDS;
214
215 int bNoDataValueSet;
216 double dfNoDataValue;
217
218 GDALColorTable *poColorTable;
219
220 GDALColorInterp eColorInterp;
221
222 char *pszUnitType;
223 char **papszCategoryNames;
224
225 double dfOffset;
226 double dfScale;
227
228 int bHaveMinMax;
229 double dfMin;
230 double dfMax;
231
232 int bHaveStats;
233 double dfMean;
234 double dfStdDev;
235
236 CPLXMLNode *psSavedHistograms;
237
238 GDALRasterAttributeTable *poDefaultRAT;
239
240} GDALRasterBandPamInfo;
242/* ******************************************************************** */
243/* GDALPamRasterBand */
244/* ******************************************************************** */
245
247class CPL_DLL GDALPamRasterBand : public GDALRasterBand
248{
249 friend class GDALPamDataset;
250
251 protected:
253 virtual CPLXMLNode *SerializeToXML( const char *pszVRTPath );
254 virtual CPLErr XMLInit( CPLXMLNode *, const char * );
255
256 void PamInitialize();
257 void PamClear();
258
259 GDALRasterBandPamInfo *psPam = nullptr;
261
262 public:
265 explicit GDALPamRasterBand(int bForceCachedIO);
267 ~GDALPamRasterBand() override;
268
269 void SetDescription( const char * ) override;
270
271 CPLErr SetNoDataValue( double ) override;
272 double GetNoDataValue( int *pbSuccess = nullptr ) override;
273 CPLErr DeleteNoDataValue() override;
274
275 CPLErr SetColorTable( GDALColorTable * ) override;
276 GDALColorTable *GetColorTable() override;
277
278 CPLErr SetColorInterpretation( GDALColorInterp ) override;
279 GDALColorInterp GetColorInterpretation() override;
280
281 const char *GetUnitType() override;
282 CPLErr SetUnitType( const char * ) override;
283
284 char **GetCategoryNames() override;
285 CPLErr SetCategoryNames( char ** ) override;
286
287 double GetOffset( int *pbSuccess = nullptr ) override;
288 CPLErr SetOffset( double ) override;
289 double GetScale( int *pbSuccess = nullptr ) override;
290 CPLErr SetScale( double ) override;
291
292 CPLErr GetHistogram( double dfMin, double dfMax,
293 int nBuckets, GUIntBig * panHistogram,
294 int bIncludeOutOfRange, int bApproxOK,
295 GDALProgressFunc, void *pProgressData ) override;
296
297 CPLErr GetDefaultHistogram( double *pdfMin, double *pdfMax,
298 int *pnBuckets, GUIntBig ** ppanHistogram,
299 int bForce,
300 GDALProgressFunc, void *pProgressData) override;
301
302 CPLErr SetDefaultHistogram( double dfMin, double dfMax,
303 int nBuckets, GUIntBig *panHistogram ) override;
304
305 CPLErr SetMetadata( char ** papszMetadata,
306 const char * pszDomain = "" ) override;
307 CPLErr SetMetadataItem( const char * pszName,
308 const char * pszValue,
309 const char * pszDomain = "" ) override;
310
311 GDALRasterAttributeTable *GetDefaultRAT() override;
312 CPLErr SetDefaultRAT( const GDALRasterAttributeTable * ) override;
313
315 // new in GDALPamRasterBand.
316 virtual CPLErr CloneInfo( GDALRasterBand *poSrcBand, int nCloneInfoFlags );
317
318 // "semi private" methods.
319 GDALRasterBandPamInfo *GetPamInfo() { return psPam; }
321 private:
323};
324
326// These are mainly helper functions for internal use.
327int CPL_DLL PamParseHistogram( CPLXMLNode *psHistItem,
328 double *pdfMin, double *pdfMax,
329 int *pnBuckets, GUIntBig **ppanHistogram,
330 int *pbIncludeOutOfRange, int *pbApproxOK );
331CPLXMLNode CPL_DLL *
332PamFindMatchingHistogram( CPLXMLNode *psSavedHistograms,
333 double dfMin, double dfMax, int nBuckets,
334 int bIncludeOutOfRange, int bApproxOK );
335CPLXMLNode CPL_DLL *
336PamHistogramToXMLTree( double dfMin, double dfMax,
337 int nBuckets, GUIntBig * panHistogram,
338 int bIncludeOutOfRange, int bApprox );
339
340// For managing the proxy file database.
341const char CPL_DLL * PamGetProxy( const char * );
342const char CPL_DLL * PamAllocateProxy( const char * );
343const char CPL_DLL * PamDeallocateProxy( const char * );
344void CPL_DLL PamCleanProxyDB( void );
345
347
348#endif /* ndef GDAL_PAM_H_INCLUDED */
Convenient string class based on std::string.
Definition: cpl_string.h:330
A color table / palette.
Definition: gdal_priv.h:965
A set of associated raster bands, usually from one file.
Definition: gdal_priv.h:336
virtual int GetGCPCount()
Get number of GCPs.
Definition: gdaldataset.cpp:1500
virtual CPLErr GetGeoTransform(double *padfTransform)
Fetch the affine transformation coefficients.
Definition: gdaldataset.cpp:1158
virtual const OGRSpatialReference * GetGCPSpatialRef() const
Get output spatial reference system for GCPs.
Definition: gdaldataset.cpp:1595
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
virtual CPLErr SetSpatialRef(const OGRSpatialReference *poSRS)
Set the spatial reference system for this dataset.
Definition: gdaldataset.cpp:1040
virtual CPLErr SetGeoTransform(double *padfTransform)
Set the affine transformation coefficients.
Definition: gdaldataset.cpp:1213
virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList, const OGRSpatialReference *poGCP_SRS)
Assign GCPs.
Definition: gdaldataset.cpp:1783
virtual const OGRSpatialReference * GetSpatialRef() const
Fetch the spatial reference for this dataset.
Definition: gdaldataset.cpp:909
CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain) override
Set single metadata item.
virtual void FlushCache(void)
Flush all write cached data to disk.
Definition: gdaldataset.cpp:418
void char ** GetMetadata(const char *pszDomain="") override
Fetch metadata.
Definition: gdaldataset.cpp:4011
virtual const GDAL_GCP * GetGCPs()
Fetch GCPs.
Definition: gdaldataset.cpp:1678
virtual char ** GetFileList(void)
Fetch files forming dataset.
Definition: gdaldataset.cpp:2841
const char * GetMetadataItem(const char *pszName, const char *pszDomain) override
Fetch single metadata item.
virtual void SetDescription(const char *)
Set object description.
Definition: gdalmajorobject.cpp:120
PAM dataset.
Definition: gdal_pam.h:115
PAM raster band.
Definition: gdal_pam.h:248
The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute ...
Definition: gdal_rat.h:48
A single raster band (or channel).
Definition: gdal_priv.h:1069
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition: ogr_spatialref.h:157
CPLErr
Error category.
Definition: cpl_error.h:53
unsigned long long GUIntBig
Large unsigned integer type (generally 64-bit unsigned integer type).
Definition: cpl_port.h:251
#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:997
GDALColorInterp
Definition: gdal.h:191
C++ GDAL entry points.
Document node structure.
Definition: cpl_minixml.h:67
Ground Control Point.
Definition: gdal.h:564

Generated for GDAL by doxygen 1.9.4.