GDAL
gdal_pam.h
1 /******************************************************************************
2  * $Id: gdal_pam.h 33694 2016-03-10 17:54:30Z goatbar $
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 #include "gdal_priv.h"
34 
35 class GDALPamRasterBand;
36 
37 /* Clone Info Flags */
38 
39 #define GCIF_GEOTRANSFORM 0x01
40 #define GCIF_PROJECTION 0x02
41 #define GCIF_METADATA 0x04
42 #define GCIF_GCPS 0x08
43 
44 #define GCIF_NODATA 0x001000
45 #define GCIF_CATEGORYNAMES 0x002000
46 #define GCIF_MINMAX 0x004000
47 #define GCIF_SCALEOFFSET 0x008000
48 #define GCIF_UNITTYPE 0x010000
49 #define GCIF_COLORTABLE 0x020000
50 #define GCIF_COLORINTERP 0x020000
51 #define GCIF_BAND_METADATA 0x040000
52 #define GCIF_RAT 0x080000
53 #define GCIF_MASK 0x100000
54 #define GCIF_BAND_DESCRIPTION 0x200000
55 
56 #define GCIF_ONLY_IF_MISSING 0x10000000
57 #define GCIF_PROCESS_BANDS 0x20000000
58 
59 #define GCIF_PAM_DEFAULT (GCIF_GEOTRANSFORM | GCIF_PROJECTION | \
60  GCIF_METADATA | GCIF_GCPS | \
61  GCIF_NODATA | GCIF_CATEGORYNAMES | \
62  GCIF_MINMAX | GCIF_SCALEOFFSET | \
63  GCIF_UNITTYPE | GCIF_COLORTABLE | \
64  GCIF_COLORINTERP | GCIF_BAND_METADATA | \
65  GCIF_RAT | GCIF_MASK | \
66  GCIF_ONLY_IF_MISSING | GCIF_PROCESS_BANDS|\
67  GCIF_BAND_DESCRIPTION)
68 
69 /* GDAL PAM Flags */
70 /* ERO 2011/04/13 : GPF_AUXMODE seems to be unimplemented */
71 #define GPF_DIRTY 0x01 // .pam file needs to be written on close
72 #define GPF_TRIED_READ_FAILED 0x02 // no need to keep trying to read .pam.
73 #define GPF_DISABLED 0x04 // do not try any PAM stuff.
74 #define GPF_AUXMODE 0x08 // store info in .aux (HFA) file.
75 #define GPF_NOSAVE 0x10 // do not try to save pam info.
76 
77 /* ==================================================================== */
78 /* GDALDatasetPamInfo */
79 /* */
80 /* We make these things a separate structure of information */
81 /* primarily so we can modify it without altering the size of */
82 /* the GDALPamDataset. It is an effort to reduce ABI churn for */
83 /* driver plugins. */
84 /* ==================================================================== */
86 {
87 public:
88  char *pszPamFilename;
89 
90  char *pszProjection;
91 
92  int bHaveGeoTransform;
93  double adfGeoTransform[6];
94 
95  int nGCPCount;
96  GDAL_GCP *pasGCPList;
97  char *pszGCPProjection;
98 
99  CPLString osPhysicalFilename;
100  CPLString osSubdatasetName;
101  CPLString osAuxFilename;
102 
103  int bHasMetadata;
104 };
105 
106 /* ******************************************************************** */
107 /* GDALPamDataset */
108 /* ******************************************************************** */
109 
110 class CPL_DLL GDALPamDataset : public GDALDataset
111 {
112  friend class GDALPamRasterBand;
113 
114  private:
115  int IsPamFilenameAPotentialSiblingFile();
116 
117  protected:
118  GDALPamDataset(void);
119 
120  int nPamFlags;
121  GDALDatasetPamInfo *psPam;
122 
123  virtual CPLXMLNode *SerializeToXML( const char *);
124  virtual CPLErr XMLInit( CPLXMLNode *, const char * );
125 
126  virtual CPLErr TryLoadXML(char **papszSiblingFiles = NULL);
127  virtual CPLErr TrySaveXML();
128 
129  CPLErr TryLoadAux(char **papszSiblingFiles = NULL);
130  CPLErr TrySaveAux();
131 
132  virtual const char *BuildPamFilename();
133 
134  void PamInitialize();
135  void PamClear();
136 
137  void SetPhysicalFilename( const char * );
138  const char *GetPhysicalFilename();
139  void SetSubdatasetName( const char *);
140  const char *GetSubdatasetName();
141 
142  public:
143  virtual ~GDALPamDataset();
144 
145  virtual void FlushCache(void);
146 
147  virtual const char *GetProjectionRef(void);
148  virtual CPLErr SetProjection( const char * );
149 
150  virtual CPLErr GetGeoTransform( double * );
151  virtual CPLErr SetGeoTransform( double * );
152 
153  virtual int GetGCPCount();
154  virtual const char *GetGCPProjection();
155  virtual const GDAL_GCP *GetGCPs();
156  virtual CPLErr SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
157  const char *pszGCPProjection );
158 
159  virtual CPLErr SetMetadata( char ** papszMetadata,
160  const char * pszDomain = "" );
161  virtual CPLErr SetMetadataItem( const char * pszName,
162  const char * pszValue,
163  const char * pszDomain = "" );
164  virtual char **GetMetadata( const char * pszDomain = "" );
165  virtual const char *GetMetadataItem( const char * pszName,
166  const char * pszDomain = "" );
167 
168  virtual char **GetFileList(void);
169 
170  virtual CPLErr CloneInfo( GDALDataset *poSrcDS, int nCloneInfoFlags );
171 
172  virtual CPLErr IBuildOverviews( const char *pszResampling,
173  int nOverviews, int *panOverviewList,
174  int nListBands, int *panBandList,
175  GDALProgressFunc pfnProgress,
176  void * pProgressData );
177 
178 
179  // "semi private" methods.
180  void MarkPamDirty() { nPamFlags |= GPF_DIRTY; }
181  GDALDatasetPamInfo *GetPamInfo() { return psPam; }
182  int GetPamFlags() { return nPamFlags; }
183  void SetPamFlags(int nValue ) { nPamFlags = nValue; }
184 
185  private:
186  CPL_DISALLOW_COPY_ASSIGN(GDALPamDataset);
187 };
188 
189 /* ==================================================================== */
190 /* GDALRasterBandPamInfo */
191 /* */
192 /* We make these things a separate structure of information */
193 /* primarily so we can modify it without altering the size of */
194 /* the GDALPamDataset. It is an effort to reduce ABI churn for */
195 /* driver plugins. */
196 /* ==================================================================== */
197 typedef struct {
198  GDALPamDataset *poParentDS;
199 
200  int bNoDataValueSet;
201  double dfNoDataValue;
202 
203  GDALColorTable *poColorTable;
204 
205  GDALColorInterp eColorInterp;
206 
207  char *pszUnitType;
208  char **papszCategoryNames;
209 
210  double dfOffset;
211  double dfScale;
212 
213  int bHaveMinMax;
214  double dfMin;
215  double dfMax;
216 
217  int bHaveStats;
218  double dfMean;
219  double dfStdDev;
220 
221  CPLXMLNode *psSavedHistograms;
222 
223  GDALRasterAttributeTable *poDefaultRAT;
224 
226 
227 /* ******************************************************************** */
228 /* GDALPamRasterBand */
229 /* ******************************************************************** */
230 class CPL_DLL GDALPamRasterBand : public GDALRasterBand
231 {
232  friend class GDALPamDataset;
233 
234  protected:
235 
236  virtual CPLXMLNode *SerializeToXML( const char *pszVRTPath );
237  virtual CPLErr XMLInit( CPLXMLNode *, const char * );
238 
239  void PamInitialize();
240  void PamClear();
241 
242  GDALRasterBandPamInfo *psPam;
243 
244  public:
246  GDALPamRasterBand(int bForceCachedIO);
247  virtual ~GDALPamRasterBand();
248 
249  virtual void SetDescription( const char * );
250 
251  virtual CPLErr SetNoDataValue( double );
252  virtual double GetNoDataValue( int *pbSuccess = NULL );
253  virtual CPLErr DeleteNoDataValue();
254 
255  virtual CPLErr SetColorTable( GDALColorTable * );
256  virtual GDALColorTable *GetColorTable();
257 
258  virtual CPLErr SetColorInterpretation( GDALColorInterp );
259  virtual GDALColorInterp GetColorInterpretation();
260 
261  virtual const char *GetUnitType();
262  CPLErr SetUnitType( const char * );
263 
264  virtual char **GetCategoryNames();
265  virtual CPLErr SetCategoryNames( char ** );
266 
267  virtual double GetOffset( int *pbSuccess = NULL );
268  CPLErr SetOffset( double );
269  virtual double GetScale( int *pbSuccess = NULL );
270  CPLErr SetScale( double );
271 
272  virtual CPLErr GetHistogram( double dfMin, double dfMax,
273  int nBuckets, GUIntBig * panHistogram,
274  int bIncludeOutOfRange, int bApproxOK,
275  GDALProgressFunc, void *pProgressData );
276 
277  virtual CPLErr GetDefaultHistogram( double *pdfMin, double *pdfMax,
278  int *pnBuckets, GUIntBig ** ppanHistogram,
279  int bForce,
280  GDALProgressFunc, void *pProgressData);
281 
282  virtual CPLErr SetDefaultHistogram( double dfMin, double dfMax,
283  int nBuckets, GUIntBig *panHistogram );
284 
285  virtual CPLErr SetMetadata( char ** papszMetadata,
286  const char * pszDomain = "" );
287  virtual CPLErr SetMetadataItem( const char * pszName,
288  const char * pszValue,
289  const char * pszDomain = "" );
290 
291  virtual GDALRasterAttributeTable *GetDefaultRAT();
292  virtual CPLErr SetDefaultRAT( const GDALRasterAttributeTable * );
293 
294  // new in GDALPamRasterBand.
295  virtual CPLErr CloneInfo( GDALRasterBand *poSrcBand, int nCloneInfoFlags );
296 
297  // "semi private" methods.
298  GDALRasterBandPamInfo *GetPamInfo() { return psPam; }
299 
300  private:
301  CPL_DISALLOW_COPY_ASSIGN(GDALPamRasterBand);
302 };
303 
304 // These are mainly helper functions for internal use.
305 int CPL_DLL PamParseHistogram( CPLXMLNode *psHistItem,
306  double *pdfMin, double *pdfMax,
307  int *pnBuckets, GUIntBig **ppanHistogram,
308  int *pbIncludeOutOfRange, int *pbApproxOK );
309 CPLXMLNode CPL_DLL *
310 PamFindMatchingHistogram( CPLXMLNode *psSavedHistograms,
311  double dfMin, double dfMax, int nBuckets,
312  int bIncludeOutOfRange, int bApproxOK );
313 CPLXMLNode CPL_DLL *
314 PamHistogramToXMLTree( double dfMin, double dfMax,
315  int nBuckets, GUIntBig * panHistogram,
316  int bIncludeOutOfRange, int bApprox );
317 
318 // For managing the proxy file database.
319 const char CPL_DLL * PamGetProxy( const char * );
320 const char CPL_DLL * PamAllocateProxy( const char * );
321 const char CPL_DLL * PamDeallocateProxy( const char * );
322 void CPL_DLL PamCleanProxyDB( void );
323 
324 #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:46
Definition: gdal_pam.h:197
Document node structure.
Definition: cpl_minixml.h:65
virtual CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain="")
Set single metadata item.
Definition: gdalpamdataset.cpp:1221
virtual void SetDescription(const char *)
Set object description.
Definition: gdalmajorobject.cpp:116
C++ GDAL entry points.
virtual CPLErr SetMetadataItem(const char *pszName, const char *pszValue, const char *pszDomain="")
Set single metadata item.
Definition: gdalpamrasterband.cpp:668
Definition: gdal_pam.h:85
virtual char ** GetMetadata(const char *pszDomain="")
Fetch metadata.
Definition: gdalmajorobject.cpp:243
Convenient string class based on std::string.
Definition: cpl_string.h:283
virtual CPLErr SetMetadata(char **papszMetadata, const char *pszDomain="")
Set metadata.
Definition: gdalpamrasterband.cpp:652
virtual CPLErr FlushCache()
Flush raster data cache.
Definition: gdalrasterband.cpp:849
virtual const char * GetMetadataItem(const char *pszName, const char *pszDomain="")
Fetch single metadata item.
Definition: gdalmajorobject.cpp:331
Definition: gdal_pam.h:230
virtual CPLErr SetMetadata(char **papszMetadata, const char *pszDomain="")
Set metadata.
Definition: gdalpamdataset.cpp:1202
A subclass of GDALDataset which introduces the ability to save and restore auxiliary information (coo...
Definition: gdal_pam.h:110
A single raster band (or channel).
Definition: gdal_priv.h:735
A set of associated raster bands, usually from one file.
Definition: gdal_priv.h:296
GDALColorInterp
Definition: gdal.h:173
Definition: gdal_priv.h:659
Ground Control Point.
Definition: gdal.h:492

Generated for GDAL by doxygen 1.8.11.