GDAL
Public Member Functions | Friends | List of all members
GDALPamRasterBand Class Reference

PAM raster band. More...

#include <gdal_pam.h>

Inheritance diagram for GDALPamRasterBand:
GDALRasterBand GDALMajorObject

Public Member Functions

virtual void SetDescription (const char *) CPL_OVERRIDE
 Set object description. More...
 
virtual CPLErr SetNoDataValue (double) CPL_OVERRIDE
 Set the no data value for this band. More...
 
virtual double GetNoDataValue (int *pbSuccess=NULL) CPL_OVERRIDE
 Fetch the no data value for this band. More...
 
virtual CPLErr DeleteNoDataValue () CPL_OVERRIDE
 Remove the no data value for this band. More...
 
virtual CPLErr SetColorTable (GDALColorTable *) CPL_OVERRIDE
 Set the raster color table. More...
 
virtual GDALColorTableGetColorTable () CPL_OVERRIDE
 Fetch the color table associated with band. More...
 
virtual CPLErr SetColorInterpretation (GDALColorInterp) CPL_OVERRIDE
 Set color interpretation of a band. More...
 
virtual GDALColorInterp GetColorInterpretation () CPL_OVERRIDE
 How should this band be interpreted as color? More...
 
virtual const char * GetUnitType () CPL_OVERRIDE
 Return raster unit type. More...
 
CPLErr SetUnitType (const char *) CPL_OVERRIDE
 Set unit type. More...
 
virtual char ** GetCategoryNames () CPL_OVERRIDE
 Fetch the list of category names for this raster. More...
 
virtual CPLErr SetCategoryNames (char **) CPL_OVERRIDE
 Set the category names for this band. More...
 
virtual double GetOffset (int *pbSuccess=NULL) CPL_OVERRIDE
 Fetch the raster value offset. More...
 
CPLErr SetOffset (double) CPL_OVERRIDE
 Set scaling offset. More...
 
virtual double GetScale (int *pbSuccess=NULL) CPL_OVERRIDE
 Fetch the raster value scale. More...
 
CPLErr SetScale (double) CPL_OVERRIDE
 Set scaling ratio. More...
 
virtual CPLErr GetHistogram (double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc, void *pProgressData) CPL_OVERRIDE
 Compute raster histogram. More...
 
virtual CPLErr GetDefaultHistogram (double *pdfMin, double *pdfMax, int *pnBuckets, GUIntBig **ppanHistogram, int bForce, GDALProgressFunc, void *pProgressData) CPL_OVERRIDE
 Fetch default raster histogram. More...
 
virtual CPLErr SetDefaultHistogram (double dfMin, double dfMax, int nBuckets, GUIntBig *panHistogram) CPL_OVERRIDE
 Set default histogram. More...
 
virtual CPLErr SetMetadata (char **papszMetadata, const char *pszDomain="") CPL_OVERRIDE
 Set metadata. More...
 
virtual CPLErr SetMetadataItem (const char *pszName, const char *pszValue, const char *pszDomain="") CPL_OVERRIDE
 Set single metadata item. More...
 
virtual GDALRasterAttributeTableGetDefaultRAT () CPL_OVERRIDE
 Fetch default Raster Attribute Table. More...
 
virtual CPLErr SetDefaultRAT (const GDALRasterAttributeTable *) CPL_OVERRIDE
 Set default Raster Attribute Table. More...
 
- Public Member Functions inherited from GDALRasterBand
 GDALRasterBand ()
 
 GDALRasterBand (int bForceCachedIO)
 Constructor. More...
 
virtual ~GDALRasterBand ()
 
int GetXSize ()
 Fetch XSize of raster. More...
 
int GetYSize ()
 Fetch YSize of raster. More...
 
int GetBand ()
 Fetch the band number. More...
 
GDALDatasetGetDataset ()
 Fetch the owning dataset handle. More...
 
GDALDataType GetRasterDataType (void)
 Fetch the pixel data type for this band. More...
 
void GetBlockSize (int *, int *)
 Fetch the "natural" block size of this band. More...
 
CPLErr GetActualBlockSize (int, int, int *, int *)
 Fetch the actual block size for a given block offset. More...
 
GDALAccess GetAccess ()
 Find out if we have update permission for this band. More...
 
CPLErr RasterIO (GDALRWFlag, int, int, int, int, void *, int, int, GDALDataType, GSpacing, GSpacing, GDALRasterIOExtraArg *psExtraArg) CPL_WARN_UNUSED_RESULT
 Read/write a region of image data for this band. More...
 
CPLErr ReadBlock (int, int, void *) CPL_WARN_UNUSED_RESULT
 Read a block of image data efficiently. More...
 
CPLErr WriteBlock (int, int, void *) CPL_WARN_UNUSED_RESULT
 Write a block of image data efficiently. More...
 
GDALRasterBlockGetLockedBlockRef (int nXBlockOff, int nYBlockOff, int bJustInitialize=FALSE) CPL_WARN_UNUSED_RESULT
 Fetch a pointer to an internally cached raster block. More...
 
CPLErr FlushBlock (int, int, int bWriteDirtyBlock=TRUE)
 Flush a block out of the block cache. More...
 
unsigned char * GetIndexColorTranslationTo (GDALRasterBand *poReferenceBand, unsigned char *pTranslationTable=NULL, int *pApproximateMatching=NULL)
 Compute translation table for color tables. More...
 
virtual CPLErr FlushCache ()
 Flush raster data cache. More...
 
virtual double GetMinimum (int *pbSuccess=NULL)
 Fetch the minimum value for this band. More...
 
virtual double GetMaximum (int *pbSuccess=NULL)
 Fetch the maximum value for this band. More...
 
virtual CPLErr Fill (double dfRealValue, double dfImaginaryValue=0)
 Fill this band with a constant value. More...
 
virtual CPLErr GetStatistics (int bApproxOK, int bForce, double *pdfMin, double *pdfMax, double *pdfMean, double *padfStdDev)
 Fetch image statistics. More...
 
virtual CPLErr ComputeStatistics (int bApproxOK, double *pdfMin, double *pdfMax, double *pdfMean, double *pdfStdDev, GDALProgressFunc, void *pProgressData)
 Compute image statistics. More...
 
virtual CPLErr SetStatistics (double dfMin, double dfMax, double dfMean, double dfStdDev)
 Set statistics on band. More...
 
virtual CPLErr ComputeRasterMinMax (int, double *)
 Compute the min/max values for a band. More...
 
virtual char ** GetMetadata (const char *pszDomain="") CPL_OVERRIDE
 Fetch metadata. More...
 
virtual const char * GetMetadataItem (const char *pszName, const char *pszDomain) CPL_OVERRIDE
 Fetch single metadata item. More...
 
virtual int HasArbitraryOverviews ()
 Check for arbitrary overviews. More...
 
virtual int GetOverviewCount ()
 Return the number of overview layers available. More...
 
virtual GDALRasterBandGetOverview (int)
 Fetch overview raster band object. More...
 
virtual GDALRasterBandGetRasterSampleOverview (GUIntBig)
 Fetch best sampling overview. More...
 
virtual CPLErr BuildOverviews (const char *pszResampling, int nOverviews, int *panOverviewList, GDALProgressFunc pfnProgress, void *pProgressData)
 Build raster overview(s) More...
 
virtual CPLErr AdviseRead (int nXOff, int nYOff, int nXSize, int nYSize, int nBufXSize, int nBufYSize, GDALDataType eBufType, char **papszOptions)
 Advise driver of upcoming read requests. More...
 
virtual GDALRasterBandGetMaskBand ()
 Return the mask band associated with the band. More...
 
virtual int GetMaskFlags ()
 Return the status flags of the mask band associated with the band. More...
 
virtual CPLErr CreateMaskBand (int nFlagsIn)
 Adds a mask band to the current band. More...
 
virtual CPLVirtualMemGetVirtualMemAuto (GDALRWFlag eRWFlag, int *pnPixelSpace, GIntBig *pnLineSpace, char **papszOptions) CPL_WARN_UNUSED_RESULT
 Create a CPLVirtualMem object from a GDAL raster band object. More...
 
int GetDataCoverageStatus (int nXOff, int nYOff, int nXSize, int nYSize, int nMaskFlagStop=0, double *pdfDataPct=NULL)
 Get the coverage status of a sub-window of the raster. More...
 
void ReportError (CPLErr eErrClass, CPLErrorNum err_no, const char *fmt,...) CPL_PRINT_FUNC_FORMAT(4
 Emits an error related to a raster band. More...
 
- Public Member Functions inherited from GDALMajorObject
int GetMOFlags () const
 Returns the GMO_ flags. More...
 
void SetMOFlags (int nFlagsIn)
 Assign GMO_flags. More...
 
virtual const char * GetDescription () const
 Fetch object description. More...
 
virtual char ** GetMetadataDomainList ()
 Fetch list of metadata domains. More...
 

Friends

class GDALPamDataset
 

Additional Inherited Members

- Protected Member Functions inherited from GDALRasterBand
virtual CPLErr IReadBlock (int nBlockXOff, int nBlockYOff, void *pData)=0
 Read a block of data. More...
 
virtual CPLErr IWriteBlock (int nBlockXOff, int nBlockYOff, void *pData)
 Write a block of data. More...
 
virtual CPLErr IRasterIO (GDALRWFlag, int, int, int, int, void *, int, int, GDALDataType, GSpacing, GSpacing, GDALRasterIOExtraArg *psExtraArg) CPL_WARN_UNUSED_RESULT
 Read/write a region of image data for this band. More...
 
virtual int IGetDataCoverageStatus (int nXOff, int nYOff, int nXSize, int nYSize, int nMaskFlagStop, double *pdfDataPct)
 Get the coverage status of a sub-window of the raster. More...
 
GDALRasterBlockTryGetLockedBlockRef (int nXBlockOff, int nYBlockYOff)
 Try fetching block ref. More...
 
- Protected Member Functions inherited from GDALMajorObject
char ** BuildMetadataDomainList (char **papszList, int bCheckNonEmpty,...) CPL_NULL_TERMINATED
 Helper function for custom implementations of GetMetadataDomainList() More...
 

Detailed Description

PAM raster band.

Member Function Documentation

CPLErr GDALPamRasterBand::DeleteNoDataValue ( )
virtual

Remove the no data value for this band.

This method is the same as the C function GDALDeleteRasterNoDataValue().

Returns
CE_None on success, or CE_Failure on failure. If unsupported by the driver, CE_Failure is returned by no error message will have been emitted.
Since
GDAL 2.1

Reimplemented from GDALRasterBand.

char ** GDALPamRasterBand::GetCategoryNames ( )
virtual

Fetch the list of category names for this raster.

The return list is a "StringList" in the sense of the CPL functions. That is a NULL terminated array of strings. Raster values without associated names will have an empty string in the returned list. The first entry in the list is for raster values of zero, and so on.

The returned stringlist should not be altered or freed by the application. It may change on the next GDAL call, so please copy it if it is needed for any period of time.

This method is the same as the C function GDALGetRasterCategoryNames().

Returns
list of names, or NULL if none.

Reimplemented from GDALRasterBand.

GDALColorInterp GDALPamRasterBand::GetColorInterpretation ( )
virtual

How should this band be interpreted as color?

GCI_Undefined is returned when the format doesn't know anything about the color interpretation.

This method is the same as the C function GDALGetRasterColorInterpretation().

Returns
color interpretation value for band.

Reimplemented from GDALRasterBand.

GDALColorTable * GDALPamRasterBand::GetColorTable ( )
virtual

Fetch the color table associated with band.

If there is no associated color table, the return result is NULL. The returned color table remains owned by the GDALRasterBand, and can't be depended on for long, nor should it ever be modified by the caller.

This method is the same as the C function GDALGetRasterColorTable().

Returns
internal color table, or NULL.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::GetDefaultHistogram ( double *  pdfMin,
double *  pdfMax,
int *  pnBuckets,
GUIntBig **  ppanHistogram,
int  bForce,
GDALProgressFunc  pfnProgress,
void *  pProgressData 
)
virtual

Fetch default raster histogram.

The default method in GDALRasterBand will compute a default histogram. This method is overridden by derived classes (such as GDALPamRasterBand, VRTDataset, HFADataset...) that may be able to fetch efficiently an already stored histogram.

This method is the same as the C functions GDALGetDefaultHistogram() and GDALGetDefaultHistogramEx().

Parameters
pdfMinpointer to double value that will contain the lower bound of the histogram.
pdfMaxpointer to double value that will contain the upper bound of the histogram.
pnBucketspointer to int value that will contain the number of buckets in *ppanHistogram.
ppanHistogrampointer to array into which the histogram totals are placed. To be freed with VSIFree
bForceTRUE to force the computation. If FALSE and no default histogram is available, the method will return CE_Warning
pfnProgressfunction to report progress to completion.
pProgressDataapplication data to pass to pfnProgress.
Returns
CE_None on success, CE_Failure if something goes wrong, or CE_Warning if no default histogram is available.

Reimplemented from GDALRasterBand.

GDALRasterAttributeTable * GDALPamRasterBand::GetDefaultRAT ( )
virtual

Fetch default Raster Attribute Table.

A RAT will be returned if there is a default one associated with the band, otherwise NULL is returned. The returned RAT is owned by the band and should not be deleted by the application.

This method is the same as the C function GDALGetDefaultRAT().

Returns
NULL, or a pointer to an internal RAT owned by the band.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::GetHistogram ( double  dfMin,
double  dfMax,
int  nBuckets,
GUIntBig panHistogram,
int  bIncludeOutOfRange,
int  bApproxOK,
GDALProgressFunc  pfnProgress,
void *  pProgressData 
)
virtual

Compute raster histogram.

Note that the bucket size is (dfMax-dfMin) / nBuckets.

For example to compute a simple 256 entry histogram of eight bit data, the following would be suitable. The unusual bounds are to ensure that bucket boundaries don't fall right on integer values causing possible errors due to rounding after scaling.

    GUIntBig anHistogram[256];
    poBand->GetHistogram( -0.5, 255.5, 256, anHistogram, FALSE, FALSE,
                          GDALDummyProgress, NULL );

Note that setting bApproxOK will generally result in a subsampling of the file, and will utilize overviews if available. It should generally produce a representative histogram for the data that is suitable for use in generating histogram based luts for instance. Generally bApproxOK is much faster than an exactly computed histogram.

This method is the same as the C functions GDALGetRasterHistogram() and GDALGetRasterHistogramEx().

Parameters
dfMinthe lower bound of the histogram.
dfMaxthe upper bound of the histogram.
nBucketsthe number of buckets in panHistogram.
panHistogramarray into which the histogram totals are placed.
bIncludeOutOfRangeif TRUE values below the histogram range will mapped into panHistogram[0], and values above will be mapped into panHistogram[nBuckets-1] otherwise out of range values are discarded.
bApproxOKTRUE if an approximate, or incomplete histogram OK.
pfnProgressfunction to report progress to completion.
pProgressDataapplication data to pass to pfnProgress.
Returns
CE_None on success, or CE_Failure if something goes wrong.

Reimplemented from GDALRasterBand.

double GDALPamRasterBand::GetNoDataValue ( int *  pbSuccess = NULL)
virtual

Fetch the no data value for this band.

If there is no out of data value, an out of range value will generally be returned. The no data value for a band is generally a special marker value used to mark pixels that are not valid data. Such pixels should generally not be displayed, nor contribute to analysis operations.

This method is the same as the C function GDALGetRasterNoDataValue().

Parameters
pbSuccesspointer to a boolean to use to indicate if a value is actually associated with this layer. May be NULL (default).
Returns
the nodata value for this band.

Reimplemented from GDALRasterBand.

double GDALPamRasterBand::GetOffset ( int *  pbSuccess = NULL)
virtual

Fetch the raster value offset.

This value (in combination with the GetScale() value) is used to transform raw pixel values into the units returned by GetUnits(). For example this might be used to store elevations in GUInt16 bands with a precision of 0.1, and starting from -100.

Units value = (raw value * scale) + offset

For file formats that don't know this intrinsically a value of zero is returned.

This method is the same as the C function GDALGetRasterOffset().

Parameters
pbSuccesspointer to a boolean to use to indicate if the returned value is meaningful or not. May be NULL (default).
Returns
the raster offset.

Reimplemented from GDALRasterBand.

double GDALPamRasterBand::GetScale ( int *  pbSuccess = NULL)
virtual

Fetch the raster value scale.

This value (in combination with the GetOffset() value) is used to transform raw pixel values into the units returned by GetUnits(). For example this might be used to store elevations in GUInt16 bands with a precision of 0.1, and starting from -100.

Units value = (raw value * scale) + offset

For file formats that don't know this intrinsically a value of one is returned.

This method is the same as the C function GDALGetRasterScale().

Parameters
pbSuccesspointer to a boolean to use to indicate if the returned value is meaningful or not. May be NULL (default).
Returns
the raster scale.

Reimplemented from GDALRasterBand.

const char * GDALPamRasterBand::GetUnitType ( )
virtual

Return raster unit type.

Return a name for the units of this raster's values. For instance, it might be "m" for an elevation model in meters, or "ft" for feet. If no units are available, a value of "" will be returned. The returned string should not be modified, nor freed by the calling application.

This method is the same as the C function GDALGetRasterUnitType().

Returns
unit name string.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetCategoryNames ( char **  papszNames)
virtual

Set the category names for this band.

See the GetCategoryNames() method for more on the interpretation of category names.

This method is the same as the C function GDALSetRasterCategoryNames().

Parameters
papszNamesthe NULL terminated StringList of category names. May be NULL to just clear the existing list.
Returns
CE_None on success of CE_Failure on failure. If unsupported by the driver CE_Failure is returned, but no error message is reported.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetColorInterpretation ( GDALColorInterp  eColorInterp)
virtual

Set color interpretation of a band.

This method is the same as the C function GDALSetRasterColorInterpretation().

Parameters
eColorInterpthe new color interpretation to apply to this band.
Returns
CE_None on success or CE_Failure if method is unsupported by format.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetColorTable ( GDALColorTable poCT)
virtual

Set the raster color table.

The driver will make a copy of all desired data in the colortable. It remains owned by the caller after the call.

This method is the same as the C function GDALSetRasterColorTable().

Parameters
poCTthe color table to apply. This may be NULL to clear the color table (where supported).
Returns
CE_None on success, or CE_Failure on failure. If the action is unsupported by the driver, a value of CE_Failure is returned, but no error is issued.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetDefaultHistogram ( double  dfMin,
double  dfMax,
int  nBuckets,
GUIntBig panHistogram 
)
virtual

Set default histogram.

This method is the same as the C function GDALSetDefaultHistogram() and GDALSetDefaultHistogramEx()

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetDefaultRAT ( const GDALRasterAttributeTable poRAT)
virtual

Set default Raster Attribute Table.

Associates a default RAT with the band. If not implemented for the format a CPLE_NotSupported error will be issued. If successful a copy of the RAT is made, the original remains owned by the caller.

This method is the same as the C function GDALSetDefaultRAT().

Parameters
poRATthe RAT to assign to the band.
Returns
CE_None on success or CE_Failure if unsupported or otherwise failing.

Reimplemented from GDALRasterBand.

void GDALPamRasterBand::SetDescription ( const char *  pszNewDesc)
virtual

Set object description.

The semantics of the description are specific to the derived type. For GDALDatasets it is the dataset name. For GDALRasterBands it is actually a description (if supported) or "".

Normally application code should not set the "description" for GDALDatasets. It is handled internally.

This method is the same as the C function GDALSetDescription().

Reimplemented from GDALMajorObject.

CPLErr GDALPamRasterBand::SetMetadata ( char **  papszMetadata,
const char *  pszDomain = "" 
)
virtual

Set metadata.

CAUTION: depending on the format, older values of the updated information might still be found in the file in a "ghost" state, even if no longer accessible through the GDAL API. This is for example the case of the GTiff format (this is not a exhaustive list)

The C function GDALSetMetadata() does the same thing as this method.

Parameters
papszMetadatathe metadata in name=value string list format to apply.
pszDomainthe domain of interest. Use "" or NULL for the default domain.
Returns
CE_None on success, CE_Failure on failure and CE_Warning if the metadata has been accepted, but is likely not maintained persistently by the underlying object between sessions.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetMetadataItem ( const char *  pszName,
const char *  pszValue,
const char *  pszDomain = "" 
)
virtual

Set single metadata item.

CAUTION: depending on the format, older values of the updated information might still be found in the file in a "ghost" state, even if no longer accessible through the GDAL API. This is for example the case of the GTiff format (this is not a exhaustive list)

The C function GDALSetMetadataItem() does the same thing as this method.

Parameters
pszNamethe key for the metadata item to fetch.
pszValuethe value to assign to the key.
pszDomainthe domain to set within, use NULL for the default domain.
Returns
CE_None on success, or an error code on failure.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetNoDataValue ( double  dfNoData)
virtual

Set the no data value for this band.

Depending on drivers, changing the no data value may or may not have an effect on the pixel values of a raster that has just been created. It is thus advised to explicitly called Fill() if the intent is to initialize the raster to the nodata value. In ay case, changing an existing no data value, when one already exists and the dataset exists or has been initialized, has no effect on the pixel whose value matched the previous nodata value.

To clear the nodata value, use DeleteNoDataValue().

This method is the same as the C function GDALSetRasterNoDataValue().

Parameters
dfNoDatathe value to set.
Returns
CE_None on success, or CE_Failure on failure. If unsupported by the driver, CE_Failure is returned by no error message will have been emitted.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetOffset ( double  dfNewOffset)
virtual

Set scaling offset.

Very few formats implement this method. When not implemented it will issue a CPLE_NotSupported error and return CE_Failure.

This method is the same as the C function GDALSetRasterOffset().

Parameters
dfNewOffsetthe new offset.
Returns
CE_None or success or CE_Failure on failure.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetScale ( double  dfNewScale)
virtual

Set scaling ratio.

Very few formats implement this method. When not implemented it will issue a CPLE_NotSupported error and return CE_Failure.

This method is the same as the C function GDALSetRasterScale().

Parameters
dfNewScalethe new scale.
Returns
CE_None or success or CE_Failure on failure.

Reimplemented from GDALRasterBand.

CPLErr GDALPamRasterBand::SetUnitType ( const char *  pszNewValue)
virtual

Set unit type.

Set the unit type for a raster band. Values should be one of "" (the default indicating it is unknown), "m" indicating meters, or "ft" indicating feet, though other nonstandard values are allowed.

This method is the same as the C function GDALSetRasterUnitType().

Parameters
pszNewValuethe new unit type value.
Returns
CE_None on success or CE_Failure if not successful, or unsupported.

Reimplemented from GDALRasterBand.


The documentation for this class was generated from the following files:

Generated for GDAL by doxygen 1.8.8.