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 "gdal_priv.h"
36 
37 class GDALPamRasterBand;
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 /* ==================================================================== */
87 class GDALDatasetPamInfo
88 {
89 public:
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 
114 class 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;
168  using GDALDataset::SetGCPs;
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 /* ==================================================================== */
212 typedef 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 
247 class 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 
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 
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.
327 int CPL_DLL PamParseHistogram( CPLXMLNode *psHistItem,
328  double *pdfMin, double *pdfMax,
329  int *pnBuckets, GUIntBig **ppanHistogram,
330  int *pbIncludeOutOfRange, int *pbApproxOK );
331 CPLXMLNode CPL_DLL *
332 PamFindMatchingHistogram( CPLXMLNode *psSavedHistograms,
333  double dfMin, double dfMax, int nBuckets,
334  int bIncludeOutOfRange, int bApproxOK );
335 CPLXMLNode CPL_DLL *
336 PamHistogramToXMLTree( double dfMin, double dfMax,
337  int nBuckets, GUIntBig * panHistogram,
338  int bIncludeOutOfRange, int bApprox );
339 
340 // For managing the proxy file database.
341 const char CPL_DLL * PamGetProxy( const char * );
342 const char CPL_DLL * PamAllocateProxy( const char * );
343 const char CPL_DLL * PamDeallocateProxy( const char * );
344 void CPL_DLL PamCleanProxyDB( void );
345 
347 
348 #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:1156
virtual CPLErr SetCategoryNames(char **papszNames)
Set the category names for this band.
Definition: gdalrasterband.cpp:1562
Document node structure.
Definition: cpl_minixml.h:66
virtual char ** GetCategoryNames()
Fetch the list of category names for this raster.
Definition: gdalrasterband.cpp:1514
virtual void SetDescription(const char *)
Set object description.
Definition: gdalmajorobject.cpp:120
virtual void FlushCache(void)
Flush all write cached data to disk.
Definition: gdaldataset.cpp:416
virtual CPLErr GetDefaultHistogram(double *pdfMin, double *pdfMax, int *pnBuckets, GUIntBig **ppanHistogram, int bForce, GDALProgressFunc, void *pProgressData)
Fetch default raster histogram.
Definition: gdalrasterband.cpp:3468
C++ GDAL entry points.
virtual GDALColorInterp GetColorInterpretation()
How should this band be interpreted as color?
Definition: gdalrasterband.cpp:1957
virtual CPLErr SetDefaultRAT(const GDALRasterAttributeTable *poRAT)
Set default Raster Attribute Table.
Definition: gdalrasterband.cpp:5867
virtual GDALRasterAttributeTable * GetDefaultRAT()
Fetch default Raster Attribute Table.
Definition: gdalrasterband.cpp:5819
virtual CPLErr GetHistogram(double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc, void *pProgressData)
Compute raster histogram.
Definition: gdalrasterband.cpp:2926
virtual const OGRSpatialReference * GetGCPSpatialRef() const
Get output spatial reference system for GCPs.
Definition: gdaldataset.cpp:1593
Convenient string class based on std::string.
Definition: cpl_string.h:329
virtual CPLErr SetOffset(double dfNewOffset)
Set scaling offset.
Definition: gdalrasterband.cpp:2473
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
void char ** GetMetadata(const char *pszDomain="") override
Fetch metadata.
Definition: gdaldataset.cpp:3963
CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain) override
Set single metadata item.
virtual CPLErr SetDefaultHistogram(double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram)
Set default histogram.
Definition: gdalrasterband.cpp:5720
virtual double GetScale(int *pbSuccess=nullptr)
Fetch the raster value scale.
Definition: gdalrasterband.cpp:2530
PAM raster band.
Definition: gdal_pam.h:247
virtual const GDAL_GCP * GetGCPs()
Fetch GCPs.
Definition: gdaldataset.cpp:1676
virtual CPLErr SetGCPs(int nGCPCount, const GDAL_GCP *pasGCPList, const OGRSpatialReference *poGCP_SRS)
Assign GCPs.
Definition: gdaldataset.cpp:1781
virtual CPLErr DeleteNoDataValue()
Remove the no data value for this band.
Definition: gdalrasterband.cpp:1727
virtual CPLErr SetSpatialRef(const OGRSpatialReference *poSRS)
Set the spatial reference system for this dataset.
Definition: gdaldataset.cpp:1038
virtual CPLErr SetGeoTransform(double *padfTransform)
Set the affine transformation coefficients.
Definition: gdaldataset.cpp:1211
virtual double GetNoDataValue(int *pbSuccess=nullptr)
Fetch the no data value for this band.
Definition: gdalrasterband.cpp:1614
virtual int GetGCPCount()
Get number of GCPs.
Definition: gdaldataset.cpp:1498
virtual CPLErr SetColorInterpretation(GDALColorInterp eColorInterp)
Set color interpretation of a band.
Definition: gdalrasterband.cpp:2002
virtual const char * GetUnitType()
Return raster unit type.
Definition: gdalrasterband.cpp:2626
PAM dataset.
Definition: gdal_pam.h:114
virtual CPLErr SetColorTable(GDALColorTable *poCT)
Set the raster color table.
Definition: gdalrasterband.cpp:2098
virtual GDALColorTable * GetColorTable()
Fetch the color table associated with band.
Definition: gdalrasterband.cpp:2049
unsigned long long GUIntBig
Large unsigned integer type (generally 64-bit unsigned integer type).
Definition: cpl_port.h:251
virtual char ** GetFileList(void)
Fetch files forming dataset.
Definition: gdaldataset.cpp:2839
This class represents an OpenGIS Spatial Reference System, and contains methods for converting betwee...
Definition: ogr_spatialref.h:156
virtual CPLErr SetScale(double dfNewScale)
Set scaling ratio.
Definition: gdalrasterband.cpp:2579
virtual double GetOffset(int *pbSuccess=nullptr)
Fetch the raster value offset.
Definition: gdalrasterband.cpp:2424
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:2674
A single raster band (or channel).
Definition: gdal_priv.h:1057
A set of associated raster bands, usually from one file.
Definition: gdal_priv.h:335
virtual const OGRSpatialReference * GetSpatialRef() const
Fetch the spatial reference for this dataset.
Definition: gdaldataset.cpp:907
CPLErr SetMetadata(char **papszMetadata, const char *pszDomain) override
Set metadata.
GDALColorInterp
Definition: gdal.h:190
virtual CPLErr SetNoDataValue(double dfNoData)
Set the no data value for this band.
Definition: gdalrasterband.cpp:1673
const char * GetMetadataItem(const char *pszName, const char *pszDomain) override
Fetch single metadata item.
A color table / palette.
Definition: gdal_priv.h:962
Ground Control Point.
Definition: gdal.h:563
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:989

Generated for GDAL by doxygen 1.8.8.