GDALRasterBand Class Reference

A single raster band (or channel). More...

#include <gdal_priv.h>

Inheritance diagram for GDALRasterBand:
GDALMajorObject GDALAllValidMaskBand GDALNoDataMaskBand GDALNoDataValuesMaskBand GDALPamRasterBand GDALProxyRasterBand VRTRasterBand GDALProxyPoolRasterBand VRTRawRasterBand VRTSourcedRasterBand VRTWarpedRasterBand GDALProxyPoolMaskBand GDALProxyPoolOverviewRasterBand VRTDerivedRasterBand

List of all members.

Public Member Functions

 GDALRasterBand ()
virtual ~GDALRasterBand ()
int GetXSize ()
int GetYSize ()
int GetBand ()
GDALDataset * GetDataset ()
GDALDataType GetRasterDataType (void)
void GetBlockSize (int *, int *)
GDALAccess GetAccess ()
CPLErr RasterIO (GDALRWFlag, int, int, int, int, void *, int, int, GDALDataType, int, int)
CPLErr ReadBlock (int, int, void *)
CPLErr WriteBlock (int, int, void *)
GDALRasterBlock * GetLockedBlockRef (int nXBlockOff, int nYBlockOff, int bJustInitialize=FALSE)
CPLErr FlushBlock (int=-1, int=-1)
unsigned char * GetIndexColorTranslationTo (GDALRasterBand *poReferenceBand, unsigned char *pTranslationTable=NULL, int *pApproximateMatching=NULL)
virtual CPLErr FlushCache ()
virtual char ** GetCategoryNames ()
virtual double GetNoDataValue (int *pbSuccess=NULL)
virtual double GetMinimum (int *pbSuccess=NULL)
virtual double GetMaximum (int *pbSuccess=NULL)
virtual double GetOffset (int *pbSuccess=NULL)
virtual double GetScale (int *pbSuccess=NULL)
virtual const char * GetUnitType ()
virtual GDALColorInterp GetColorInterpretation ()
virtual GDALColorTable * GetColorTable ()
virtual CPLErr Fill (double dfRealValue, double dfImaginaryValue=0)
virtual CPLErr SetCategoryNames (char **)
virtual CPLErr SetNoDataValue (double)
virtual CPLErr SetColorTable (GDALColorTable *)
virtual CPLErr SetColorInterpretation (GDALColorInterp)
virtual CPLErr SetOffset (double)
virtual CPLErr SetScale (double)
virtual CPLErr SetUnitType (const char *)
virtual CPLErr GetStatistics (int bApproxOK, int bForce, double *pdfMin, double *pdfMax, double *pdfMean, double *padfStdDev)
virtual CPLErr ComputeStatistics (int bApproxOK, double *pdfMin, double *pdfMax, double *pdfMean, double *pdfStdDev, GDALProgressFunc, void *pProgressData)
virtual CPLErr SetStatistics (double dfMin, double dfMax, double dfMean, double dfStdDev)
virtual CPLErr ComputeRasterMinMax (int, double *)
virtual int HasArbitraryOverviews ()
virtual int GetOverviewCount ()
virtual GDALRasterBand * GetOverview (int)
virtual GDALRasterBand * GetRasterSampleOverview (int)
virtual CPLErr BuildOverviews (const char *, int, int *, GDALProgressFunc, void *)
virtual CPLErr AdviseRead (int nXOff, int nYOff, int nXSize, int nYSize, int nBufXSize, int nBufYSize, GDALDataType eDT, char **papszOptions)
virtual CPLErr GetHistogram (double dfMin, double dfMax, int nBuckets, int *panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc, void *pProgressData)
virtual CPLErr GetDefaultHistogram (double *pdfMin, double *pdfMax, int *pnBuckets, int **ppanHistogram, int bForce, GDALProgressFunc, void *pProgressData)
virtual CPLErr SetDefaultHistogram (double dfMin, double dfMax, int nBuckets, int *panHistogram)
virtual const
GDALRasterAttributeTable * 		GetDefaultRAT ()
virtual CPLErr SetDefaultRAT (const GDALRasterAttributeTable *)
virtual GDALRasterBand * GetMaskBand ()
virtual int GetMaskFlags ()
virtual CPLErr CreateMaskBand (int nFlags)

Protected Member Functions

virtual CPLErr IReadBlock (int, int, void *)=0
virtual CPLErr IWriteBlock (int, int, void *)
virtual CPLErr IRasterIO (GDALRWFlag, int, int, int, int, void *, int, int, GDALDataType, int, int)
CPLErr OverviewRasterIO (GDALRWFlag, int, int, int, int, void *, int, int, GDALDataType, int, int)
int InitBlockInfo ()
CPLErr AdoptBlock (int, int, GDALRasterBlock *)
GDALRasterBlock * TryGetLockedBlockRef (int nXBlockOff, int nYBlockYOff)

Protected Attributes

GDALDataset * poDS
int nBand
int nRasterXSize
int nRasterYSize
GDALDataType eDataType
GDALAccess eAccess
int nBlockXSize
int nBlockYSize
int nBlocksPerRow
int nBlocksPerColumn
int bSubBlockingActive
int nSubBlocksPerRow
int nSubBlocksPerColumn
GDALRasterBlock ** papoBlocks
int nBlockReads
int bForceCachedIO
GDALRasterBand * poMask
bool bOwnMask
int nMaskFlags

Friends

class GDALDataset
class GDALRasterBlock
class GDALProxyRasterBand

Detailed Description

A single raster band (or channel).

Constructor & Destructor Documentation

GDALRasterBand::GDALRasterBand (  ) 

Constructor. Applications should never create GDALRasterBands directly.

References GA_ReadOnly, and GDT_Byte.

GDALRasterBand::~GDALRasterBand (  )  [virtual]

Destructor. Applications should never destroy GDALRasterBands directly, instead destroy the GDALDataset.

References FlushCache(), and GDALMajorObject::GetDescription().

Member Function Documentation

CPLErr GDALRasterBand::AdviseRead ( int  nXOff,
int  nYOff,
int  nXSize,
int  nYSize,
int  nBufXSize,
int  nBufYSize,
GDALDataType  eDT,
char **  papszOptions 
) [virtual]

Advise driver of upcoming read requests.

Some GDAL drivers operate more efficiently if they know in advance what set of upcoming read requests will be made. The AdviseRead() method allows an application to notify the driver of the region of interest, and at what resolution the region will be read.

Many drivers just ignore the AdviseRead() call, but it can dramatically accelerate access via some drivers.

Parameters:
nXOff The pixel offset to the top left corner of the region of the band to be accessed. This would be zero to start from the left side.
nYOff The line offset to the top left corner of the region of the band to be accessed. This would be zero to start from the top.
nXSize The width of the region of the band to be accessed in pixels.
nYSize The height of the region of the band to be accessed in lines.
nBufXSize the width of the buffer image into which the desired region is to be read, or from which it is to be written.
nBufYSize the height of the buffer image into which the desired region is to be read, or from which it is to be written.
eBufType the type of the pixel values in the pData data buffer. The pixel values will automatically be translated to/from the GDALRasterBand data type as needed.
papszOptions a list of name=value strings with special control options. Normally this is NULL.
Returns:
CE_Failure if the request is invalid and CE_None if it works or is ignored.

Reimplemented in GDALProxyRasterBand.

Referenced by GDALDataset::AdviseRead().

CPLErr GDALRasterBand::BuildOverviews ( const char *  pszResampling,
int  nOverviews,
int *  panOverviewList,
GDALProgressFunc  pfnProgress,
void *  pProgressData 
) [virtual]

Build raster overview(s)

If the operation is unsupported for the indicated dataset, then CE_Failure is returned, and CPLGetLastErrorNo() will return CPLE_NotSupported.

WARNING: It is not possible to build overviews for a single band in TIFF format, and thus this method does not work for TIFF format, or any formats that use the default overview building in TIFF format. Instead it is necessary to build overviews on the dataset as a whole using GDALDataset::BuildOverviews(). That makes this method pretty useless from a practical point of view.

Parameters:
pszResampling one of "NEAREST", "AVERAGE", or "AVERAGE_MAGPHASE", "GAUSS" or "NONE" controlling the downsampling method applied.
nOverviews number of overviews to build.
panOverviewList the list of overview decimation factors to build.
pfnProgress a function to call to report progress, or NULL.
pProgressData application data to pass to the progress function.
Returns:
CE_None on success or CE_Failure if the operation doesn't work.

Reimplemented in GDALProxyRasterBand.

CPLErr GDALRasterBand::ComputeStatistics ( int  bApproxOK,
double *  pdfMin,
double *  pdfMax,
double *  pdfMean,
double *  pdfStdDev,
GDALProgressFunc  pfnProgress,
void *  pProgressData 
) [virtual]

Compute image statistics.

Returns the minimum, maximum, mean and standard deviation of all pixel values in this band. If approximate statistics are sufficient, the bApproxOK flag can be set to true in which case overviews, or a subset of image tiles may be used in computing the statistics.

Once computed, the statistics will generally be "set" back on the raster band using SetStatistics().

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

Parameters:
bApproxOK If TRUE statistics may be computed based on overviews or a subset of all tiles.
pdfMin Location into which to load image minimum (may be NULL).
pdfMax Location into which to load image maximum (may be NULL).-
pdfMean Location into which to load image mean (may be NULL).
pdfStdDev Location into which to load image standard deviation (may be NULL).
pfnProgress a function to call to report progress, or NULL.
pProgressData application data to pass to the progress function.
Returns:
CE_None on success, or CE_Failure if an error occurs or processing is terminated by the user.

Reimplemented in GDALProxyRasterBand.

References ComputeStatistics(), GDALGetDataTypeSize(), GDT_Byte, GDT_CFloat32, GDT_CFloat64, GDT_CInt16, GDT_CInt32, GDT_Float32, GDT_Float64, GDT_Int16, GDT_Int32, GDT_UInt16, GDT_UInt32, GetLockedBlockRef(), GetNoDataValue(), GetOverviewCount(), GetRasterSampleOverview(), GetXSize(), GetYSize(), GF_Read, HasArbitraryOverviews(), and SetStatistics().

Referenced by ComputeStatistics(), and GetStatistics().

CPLErr GDALRasterBand::Fill ( double  dfRealValue,
double  dfImaginaryValue = 0 
) [virtual]

Fill this band with a constant value. GDAL makes no guarantees about what values pixels in newly created files are set to, so this method can be used to clear a band to a specified "default" value. The fill value is passed in as a double but this will be converted to the underlying type before writing to the file. An optional second argument allows the imaginary component of a complex constant value to be specified.

Parameters:
dfRealvalue Real component of fill value
dfImaginaryValue Imaginary component of fill value, defaults to zero
Returns:
CE_Failure if the write fails, otherwise CE_None

Reimplemented in GDALProxyRasterBand.

References GA_ReadOnly, GDALCopyWords(), GDALGetDataTypeSize(), GDT_CFloat64, and GetLockedBlockRef().

CPLErr GDALRasterBand::FlushCache ( void   )  [virtual]

Flush raster data cache.

This call will recover memory used to cache data blocks for this raster band, and ensure that new requests are referred to the underlying driver.

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

Returns:
CE_None on success.

Reimplemented in GDALProxyRasterBand.

Referenced by GDALDataset::FlushCache(), GDALRegenerateOverviews(), and ~GDALRasterBand().

GDALAccess GDALRasterBand::GetAccess (  ) 

Find out if we have update permission for this band.

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

Returns:
Either GA_Update or GA_ReadOnly.
int GDALRasterBand::GetBand (  ) 

Fetch the band number.

This method returns the band that this GDALRasterBand objects represents within it's dataset. This method may return a value of 0 to indicate GDALRasterBand objects without an apparently relationship to a dataset, such as GDALRasterBands serving as overviews.

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

Returns:
band number (1+) or 0 if the band number isn't known.

Referenced by GDALRegenerateOverviews().

void GDALRasterBand::GetBlockSize ( int *  pnXSize,
int *  pnYSize 
)

Fetch the "natural" block size of this band.

GDAL contains a concept of the natural block size of rasters so that applications can organized data access efficiently for some file formats. The natural block size is the block size that is most efficient for accessing the format. For many formats this is simple a whole scanline in which case *pnXSize is set to GetXSize(), and *pnYSize is set to 1.

However, for tiled images this will typically be the tile size.

Note that the X and Y block sizes don't have to divide the image size evenly, meaning that right and bottom edge blocks may be incomplete. See ReadBlock() for an example of code dealing with these issues.

Parameters:
pnXSize integer to put the X block size into or NULL.
pnYSize integer to put the Y block size into or NULL.

Referenced by GDALDatasetCopyWholeRaster(), GDALGetBlockSize(), and GDALRegenerateOverviews().

char ** GDALRasterBand::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.

Returns:
list of names, or NULL if none.

Reimplemented in GDALPamRasterBand, GDALProxyRasterBand, GDALProxyPoolRasterBand, and VRTRasterBand.

Referenced by GDALProxyPoolRasterBand::GetCategoryNames().

GDALColorInterp GDALRasterBand::GetColorInterpretation (  )  [virtual]

How should this band be interpreted as color?

CV_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 in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.

Referenced by GDALRegenerateOverviews(), and GetIndexColorTranslationTo().

GDALColorTable * GDALRasterBand::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 in GDALPamRasterBand, GDALProxyRasterBand, GDALProxyPoolRasterBand, and VRTRasterBand.

Referenced by GDALRegenerateOverviews(), GDALProxyPoolRasterBand::GetColorTable(), and GetIndexColorTranslationTo().

GDALDataset * GDALRasterBand::GetDataset (  ) 

Fetch the owning dataset handle.

Note that some GDALRasterBands are not considered to be a part of a dataset, such as overviews or other "freestanding" bands.

There is currently no C analog to this method.

Returns:
the pointer to the GDALDataset to which this band belongs, or NULL if this cannot be determined.

Referenced by GDALRegenerateOverviews().

CPLErr GDALRasterBand::GetDefaultHistogram ( double *  pdfMin,
double *  pdfMax,
int *  pnBuckets,
int **  ppanHistogram,
int  bForce,
GDALProgressFunc  pfnProgress,
void *  pProgressData 
) [virtual]

Fetch default 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. 

    int 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.

Parameters:
dfMin the lower bound of the histogram.
dfMax the upper bound of the histogram.
nBuckets the number of buckets in panHistogram.
panHistogram array into which the histogram totals are placed.
bIncludeOutOfRange if 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.
bApproxOK TRUE if an approximate, or incomplete histogram OK.
pfnProgress function to report progress to completion.
pProgressData application 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 in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.

References GDT_Byte, GetHistogram(), GetRasterDataType(), and GetStatistics().

const GDALRasterAttributeTable * GDALRasterBand::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, or altered by the application.

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

Reimplemented in GDALPamRasterBand, and GDALProxyRasterBand.

CPLErr GDALRasterBand::GetHistogram ( double  dfMin,
double  dfMax,
int  nBuckets,
int *  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. 

    int 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.

Parameters:
dfMin the lower bound of the histogram.
dfMax the upper bound of the histogram.
nBuckets the number of buckets in panHistogram.
panHistogram array into which the histogram totals are placed.
bIncludeOutOfRange if 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.
bApproxOK TRUE if an approximate, or incomplete histogram OK.
pfnProgress function to report progress to completion.
pProgressData application data to pass to pfnProgress.
Returns:
CE_None on success, or CE_Failure if something goes wrong.

Reimplemented in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.

References GDALGetDataTypeSize(), GDT_Byte, GDT_CFloat32, GDT_CFloat64, GDT_CInt16, GDT_CInt32, GDT_Float32, GDT_Float64, GDT_Int16, GDT_Int32, GDT_UInt16, GDT_UInt32, GetHistogram(), GetLockedBlockRef(), GetOverviewCount(), GetRasterSampleOverview(), GetXSize(), GetYSize(), GF_Read, and HasArbitraryOverviews().

Referenced by GetDefaultHistogram(), and GetHistogram().

unsigned char * GDALRasterBand::GetIndexColorTranslationTo ( GDALRasterBand *  poReferenceBand,
unsigned char *  pTranslationTable = NULL,
int *  pApproximateMatching = NULL 
)

When the raster band has a palette index, it may be usefull to compute the "translation" of this palette to the palette of another band. The translation tries to do exact matching first, and then approximate matching if no exact matching is possible. This method returns a table such that table[i] = j where i is an index of the 'this' rasterband and j the corresponding index for the reference rasterband.

This method is thought as internal to GDAL and is used for drivers like RPFTOC.

The implementation only supports 1-byte palette rasterbands.

Parameters:
poReferenceBand the raster band
pTranslationTable an already allocated translation table (at least 256 bytes), or NULL to let the method allocate it
poApproximateMatching a pointer to a flag that is set if the matching is approximate. May be NULL.
Returns:
a translation table if the two bands are palette index and that they do not match or NULL in other cases. The table must be freed with CPLFree if NULL was passed for pTranslationTable.

References GDALColorEntry::c1, GDALColorEntry::c2, GDALColorEntry::c3, GCI_PaletteIndex, GDT_Byte, GDALColorTable::GetColorEntry(), GDALColorTable::GetColorEntryCount(), GetColorInterpretation(), GetColorTable(), GetNoDataValue(), and GetRasterDataType().

GDALRasterBlock * GDALRasterBand::GetLockedBlockRef ( int  nXBlockOff,
int  nYBlockOff,
int  bJustInitialize = FALSE 
)

Fetch a pointer to an internally cached raster block.

This method will returned the requested block (locked) if it is already in the block cache for the layer. If not, the block will be read from the driver, and placed in the layer block cached, then returned. If an error occurs reading the block from the driver, a NULL value will be returned.

If a non-NULL value is returned, then a lock for the block will have been acquired on behalf of the caller. It is absolutely imperative that the caller release this lock (with GDALRasterBlock::DropLock()) or else severe problems may result.

Note that calling GetLockedBlockRef() on a previously uncached band will enable caching.

Parameters:
nBlockXOff the horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.
nYBlockOff the vertical block offset, with zero indicating the top most block, 1 the next block and so forth.
bJustInitialize If TRUE the block will be allocated and initialized, but not actually read from the source. This is useful when it will just be completely set and written back.
Returns:
pointer to the block object, or NULL on failure.

References GDALMajorObject::GetDescription(), and TryGetLockedBlockRef().

Referenced by ComputeStatistics(), Fill(), and GetHistogram().

double GDALRasterBand::GetMaximum ( int *  pbSuccess = NULL  )  [virtual]

Fetch the maximum value for this band.

For file formats that don't know this intrinsically, the maximum supported value for the data type will generally be returned.

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

Parameters:
pbSuccess pointer to a boolean to use to indicate if the returned value is a tight maximum or not. May be NULL (default).
Returns:
the maximum raster value (excluding no data pixels)

Reimplemented in GDALProxyRasterBand.

References CPLAtofM(), GDT_Byte, GDT_CFloat32, GDT_CFloat64, GDT_CInt16, GDT_CInt32, GDT_Float32, GDT_Float64, GDT_Int16, GDT_Int32, GDT_UInt16, GDT_UInt32, and GDALMajorObject::GetMetadataItem().

Referenced by GetStatistics().

double GDALRasterBand::GetMinimum ( int *  pbSuccess = NULL  )  [virtual]

Fetch the minimum value for this band.

For file formats that don't know this intrinsically, the minimum supported value for the data type will generally be returned.

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

Parameters:
pbSuccess pointer to a boolean to use to indicate if the returned value is a tight minimum or not. May be NULL (default).
Returns:
the minimum raster value (excluding no data pixels)

Reimplemented in GDALProxyRasterBand.

References CPLAtofM(), GDT_Byte, GDT_Float32, GDT_Float64, GDT_Int16, GDT_Int32, GDT_UInt16, GDT_UInt32, and GDALMajorObject::GetMetadataItem().

Referenced by GetStatistics().

double GDALRasterBand::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:
pbSuccess pointer 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 in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.

Referenced by ComputeStatistics(), GDALRegenerateOverviews(), and GetIndexColorTranslationTo().

double GDALRasterBand::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:
pbSuccess pointer to a boolean to use to indicate if the returned value is meaningful or not. May be NULL (default).
Returns:
the raster offset.

Reimplemented in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.

GDALRasterBand * GDALRasterBand::GetOverview ( int  i  )  [virtual]

Fetch overview raster band object.

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

Parameters:
i overview index between 0 and GetOverviewCount()-1.
Returns:
overview GDALRasterBand.

Reimplemented in GDALProxyRasterBand, GDALProxyPoolRasterBand, and VRTWarpedRasterBand.

Referenced by GDALProxyPoolRasterBand::GetOverview(), and GetRasterSampleOverview().

int GDALRasterBand::GetOverviewCount (  )  [virtual]

Return the number of overview layers available.

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

Returns:
overview count, zero if none.

Reimplemented in GDALProxyRasterBand, and VRTWarpedRasterBand.

Referenced by ComputeStatistics(), GetHistogram(), GetRasterSampleOverview(), and VRTDerivedRasterBand::IRasterIO().

GDALDataType GDALRasterBand::GetRasterDataType ( void   ) 

Fetch the pixel data type for this band.

Returns:
the data type of pixels for this band.

Referenced by GDALCreateWarpedVRT(), GDALDatasetCopyWholeRaster(), GDALRasterizeGeometries(), GDALRegenerateOverviews(), GetDefaultHistogram(), and GetIndexColorTranslationTo().

GDALRasterBand * GDALRasterBand::GetRasterSampleOverview ( int  nDesiredSamples  )  [virtual]

Fetch best sampling overview.

Returns the most reduced overview of the given band that still satisfies the desired number of samples. This function can be used with zero as the number of desired samples to fetch the most reduced overview. The same band as was passed in will be returned if it has not overviews, or if none of the overviews have enough samples.

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

Parameters:
nDesiredSamples the returned band will have at least this many pixels.
Returns:
optimal overview or the band itself.

Reimplemented in GDALProxyRasterBand, and GDALProxyPoolRasterBand.

References GetOverview(), GetOverviewCount(), GetXSize(), and GetYSize().

Referenced by ComputeStatistics(), and GetHistogram().

double GDALRasterBand::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:
pbSuccess pointer to a boolean to use to indicate if the returned value is meaningful or not. May be NULL (default).
Returns:
the raster scale.

Reimplemented in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.

CPLErr GDALRasterBand::GetStatistics ( int  bApproxOK,
int  bForce,
double *  pdfMin,
double *  pdfMax,
double *  pdfMean,
double *  pdfStdDev 
) [virtual]

Fetch image statistics.

Returns the minimum, maximum, mean and standard deviation of all pixel values in this band. If approximate statistics are sufficient, the bApproxOK flag can be set to true in which case overviews, or a subset of image tiles may be used in computing the statistics.

If bForce is FALSE results will only be returned if it can be done quickly (ie. without scanning the data). If bForce is FALSE and results cannot be returned efficiently, the method will return CE_Warning but no warning will have been issued. This is a non-standard use of the CE_Warning return value to indicate "nothing done".

Note that file formats using PAM (Persistent Auxilary Metadata) services will generally cache statistics in the .pam file allowing fast fetch after the first request.

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

Parameters:
bApproxOK If TRUE statistics may be computed based on overviews or a subset of all tiles.
bForce If FALSE statistics will only be returned if it can be done without rescanning the image.
pdfMin Location into which to load image minimum (may be NULL).
pdfMax Location into which to load image maximum (may be NULL).-
pdfMean Location into which to load image mean (may be NULL).
pdfStdDev Location into which to load image standard deviation (may be NULL).
Returns:
CE_None on success, CE_Warning if no values returned, CE_Failure if an error occurs.

Reimplemented in GDALProxyRasterBand.

References ComputeStatistics(), GetMaximum(), GDALMajorObject::GetMetadataItem(), and GetMinimum().

Referenced by GetDefaultHistogram().

const char * GDALRasterBand::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 in GDALPamRasterBand, GDALProxyRasterBand, GDALProxyPoolRasterBand, and VRTRasterBand.

Referenced by GDALProxyPoolRasterBand::GetUnitType().

int GDALRasterBand::GetXSize (  ) 

Fetch XSize of raster.

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

Returns:
the width in pixels of this band.

Referenced by ComputeStatistics(), GDALRegenerateOverviews(), GetHistogram(), GetRasterSampleOverview(), and WriteBlock().

int GDALRasterBand::GetYSize (  ) 

Fetch YSize of raster.

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

Returns:
the height in pixels of this band.

Referenced by ComputeStatistics(), GDALRegenerateOverviews(), GetHistogram(), GetRasterSampleOverview(), and WriteBlock().

int GDALRasterBand::HasArbitraryOverviews (  )  [virtual]

Check for arbitrary overviews.

This returns TRUE if the underlying datastore can compute arbitrary overviews efficiently, such as is the case with OGDI over a network. Datastores with arbitrary overviews don't generally have any fixed overviews, but the RasterIO() method can be used in downsampling mode to get overview data efficiently.

This method is the same as the C function GDALHasArbitraryOverviews(),

Returns:
TRUE if arbitrary overviews available (efficiently), otherwise FALSE.

Reimplemented in GDALProxyRasterBand.

Referenced by ComputeStatistics(), and GetHistogram().

CPLErr GDALRasterBand::RasterIO ( GDALRWFlag  eRWFlag,
int  nXOff,
int  nYOff,
int  nXSize,
int  nYSize,
void *  pData,
int  nBufXSize,
int  nBufYSize,
GDALDataType  eBufType,
int  nPixelSpace,
int  nLineSpace 
)

Read/write a region of image data for this band.

This method allows reading a region of a GDALRasterBand into a buffer, or writing data from a buffer into a region of a GDALRasterBand. It automatically takes care of data type translation if the data type (eBufType) of the buffer is different than that of the GDALRasterBand. The method also takes care of image decimation / replication if the buffer size (nBufXSize x nBufYSize) is different than the size of the region being accessed (nXSize x nYSize).

The nPixelSpace and nLineSpace parameters allow reading into or writing from unusually organized buffers. This is primarily used for buffers containing more than one bands raster data in interleaved format.

Some formats may efficiently implement decimation into a buffer by reading from lower resolution overview images.

For highest performance full resolution data access, read and write on "block boundaries" as returned by GetBlockSize(), or use the ReadBlock() and WriteBlock() methods.

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

Parameters:
eRWFlag Either GF_Read to read a region of data, or GF_Write to write a region of data.
nXOff The pixel offset to the top left corner of the region of the band to be accessed. This would be zero to start from the left side.
nYOff The line offset to the top left corner of the region of the band to be accessed. This would be zero to start from the top.
nXSize The width of the region of the band to be accessed in pixels.
nYSize The height of the region of the band to be accessed in lines.
pData The buffer into which the data should be read, or from which it should be written. This buffer must contain at least nBufXSize * nBufYSize words of type eBufType. It is organized in left to right, top to bottom pixel order. Spacing is controlled by the nPixelSpace, and nLineSpace parameters.
nBufXSize the width of the buffer image into which the desired region is to be read, or from which it is to be written.
nBufYSize the height of the buffer image into which the desired region is to be read, or from which it is to be written.
eBufType the type of the pixel values in the pData data buffer. The pixel values will automatically be translated to/from the GDALRasterBand data type as needed.
nPixelSpace The byte offset from the start of one pixel value in pData to the start of the next pixel value within a scanline. If defaulted (0) the size of the datatype eBufType is used.
nLineSpace The byte offset from the start of one scanline in pData to the start of the next. If defaulted the size of the datatype eBufType * nBufXSize is used.
Returns:
CE_Failure if the access fails, otherwise CE_None.

References GDALGetDataTypeSize(), GF_Read, and GF_Write.

Referenced by GDALRasterIO(), and GDALRegenerateOverviews().

CPLErr GDALRasterBand::ReadBlock ( int  nXBlockOff,
int  nYBlockOff,
void *  pImage 
)

Read a block of image data efficiently.

This method accesses a "natural" block from the raster band without resampling, or data type conversion. For a more generalized, but potentially less efficient access use RasterIO().

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

See the GetLockedBlockRef() method for a way of accessing internally cached block oriented data without an extra copy into an application buffer.

Parameters:
nXBlockOff the horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.
nYBlockOff the vertical block offset, with zero indicating the left most block, 1 the next block and so forth.
pImage the buffer into which the data will be read. The buffer must be large enough to hold GetBlockXSize()*GetBlockYSize() words of type GetRasterDataType().
Returns:
CE_None on success or CE_Failure on an error.

The following code would efficiently compute a histogram of eight bit raster data. Note that the final block may be partial ... data beyond the edge of the underlying raster band in these edge blocks is of an undermined value.

 CPLErr GetHistogram( GDALRasterBand *poBand, int *panHistogram )
 {
     int        nXBlocks, nYBlocks, nXBlockSize, nYBlockSize;
     int        iXBlock, iYBlock;
     GByte      *pabyData;
     memset( panHistogram, 0, sizeof(int) * 256 );
     CPLAssert( poBand->GetRasterDataType() == GDT_Byte );
     poBand->GetBlockSize( &nXBlockSize, &nYBlockSize );
     nXBlocks = (poBand->GetXSize() + nXBlockSize - 1) / nXBlockSize;
     nYBlocks = (poBand->GetYSize() + nYBlockSize - 1) / nYBlockSize;
     pabyData = (GByte *) CPLMalloc(nXBlockSize * nYBlockSize);
     for( iYBlock = 0; iYBlock < nYBlocks; iYBlock++ )
     {
         for( iXBlock = 0; iXBlock < nXBlocks; iXBlock++ )
         {
             int        nXValid, nYValid;
             poBand->ReadBlock( iXBlock, iYBlock, pabyData );
             // Compute the portion of the block that is valid
             // for partial edge blocks.
             if( (iXBlock+1) * nXBlockSize > poBand->GetXSize() )
                 nXValid = poBand->GetXSize() - iXBlock * nXBlockSize;
             else
                 nXValid = nXBlockSize;
             if( (iYBlock+1) * nYBlockSize > poBand->GetYSize() )
                 nYValid = poBand->GetYSize() - iYBlock * nYBlockSize;
             else
                 nYValid = nYBlockSize;
             // Collect the histogram counts.
             for( int iY = 0; iY < nYValid; iY++ )
             {
                 for( int iX = 0; iX < nXValid; iX++ )
                 {
                     panHistogram[pabyData[iX + iY * nXBlockSize]] += 1;
                 }
             }
         }
     }
 }
 

Referenced by GDALReadBlock().











      

        

          CPLErr GDALRasterBand::SetCategoryNames 
          (
          char ** 
          
           ) 
           [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:

  

    
papszNames the 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 in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.











      

        

          CPLErr GDALRasterBand::SetColorInterpretation 
          (
          GDALColorInterp 
           eColorInterp
           ) 
           [virtual]
        

      






Set color interpretation of a band.


Parameters:

  

    
eColorInterp the new color interpretation to apply to this band.

  

  




Returns:
CE_None on success or CE_Failure if method is unsupported by format. 



Reimplemented in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.











      

        

          CPLErr GDALRasterBand::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:

  

    
poCT the 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 in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.











      

        

          CPLErr GDALRasterBand::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.


Parameters:

  

    
poRAT the RAT to assign to the band.

  

  




Returns:
CE_None on success or CE_Failure if unsupported or otherwise failing. 



Reimplemented in GDALPamRasterBand, and GDALProxyRasterBand.











      

        

          CPLErr GDALRasterBand::SetNoDataValue 
          (
          double 
          
           ) 
           [virtual]
        

      






Set the no data value for this band.


To clear the nodata value, just set it with an "out of range" value. Complex band no data values must have an imagery component of zero.


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


Parameters:

  

    
dfNoData the 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 in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.











      

        

          CPLErr GDALRasterBand::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.


Parameters:

  

    
dfNewOffset the new offset.

  

  




Returns:
CE_None or success or CE_Failure on failure. 



Reimplemented in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.











      

        

          CPLErr GDALRasterBand::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.


Parameters:

  

    
dfNewScale the new scale.

  

  




Returns:
CE_None or success or CE_Failure on failure. 



Reimplemented in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.











      

        

          CPLErr GDALRasterBand::SetStatistics 
          (
          double 
           dfMin, 
        

        

          
          
          double 
           dfMax, 
        

        

          
          
          double 
           dfMean, 
        

        

          
          
          double 
           dfStdDev 
        

        

          
          )
           [virtual]
        

      






Set statistics on band.


This method can be used to store min/max/mean/standard deviation statistics on a raster band.


The default implementation stores them as metadata, and will only work on formats that can save arbitrary metadata. This method cannot detect whether metadata will be properly saved and so may return CE_None even if the statistics will never be saved.


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


Parameters:

  

    
dfMin minimum pixel value.

    
dfMax maximum pixel value.

    
dfMean mean (average) of all pixel values.

    
dfStdDev Standard deviation of all pixel values.

  

  




Returns:
CE_None on success or CE_Failure on failure. 



Reimplemented in GDALProxyRasterBand.



References GDALMajorObject::SetMetadataItem().



Referenced by ComputeStatistics().











      

        

          CPLErr GDALRasterBand::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.


Parameters:

  

    
pszNewValue the new unit type value.

  

  




Returns:
CE_None on success or CE_Failure if not succuessful, or unsupported. 



Reimplemented in GDALPamRasterBand, GDALProxyRasterBand, and VRTRasterBand.











      

        

          GDALRasterBlock * GDALRasterBand::TryGetLockedBlockRef 
          (
          int 
           nXBlockOff, 
        

        

          
          
          int 
           nYBlockOff 
        

        

          
          )
           [protected]
        

      






Try fetching block ref.


This method will returned the requested block (locked) if it is already in the block cache for the layer. If not, NULL is returned.


If a non-NULL value is returned, then a lock for the block will have been acquired on behalf of the caller. It is absolutely imperative that the caller release this lock (with GDALRasterBlock::DropLock()) or else severe problems may result.


Parameters:

  

    
nBlockXOff the horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.

    
nYBlockOff the vertical block offset, with zero indicating the top most block, 1 the next block and so forth.

  

  




Returns:
NULL if block not available, or locked block pointer. 



References GDALRasterBlock::SafeLockBlock().



Referenced by GetLockedBlockRef().











      

        

          CPLErr GDALRasterBand::WriteBlock 
          (
          int 
           nXBlockOff, 
        

        

          
          
          int 
           nYBlockOff, 
        

        

          
          
          void * 
           pImage 
        

        

          
          )
          
        

      






Write a block of image data efficiently.


This method accesses a "natural" block from the raster band without resampling, or data type conversion. For a more generalized, but potentially less efficient access use RasterIO().


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


See ReadBlock() for an example of block oriented data access.


Parameters:

  

    
nXBlockOff the horizontal block offset, with zero indicating the left most block, 1 the next block and so forth.

    
nYBlockOff the vertical block offset, with zero indicating the left most block, 1 the next block and so forth.

    
pImage the buffer from which the data will be written. The buffer must be large enough to hold GetBlockXSize()*GetBlockYSize() words of type GetRasterDataType().

  

  




Returns:
CE_None on success or CE_Failure on an error.


The following code would efficiently compute a histogram of eight bit raster data. Note that the final block may be partial ... data beyond the edge of the underlying raster band in these edge blocks is of an undermined value. 



References GA_ReadOnly, GetXSize(), and GetYSize().



Referenced by GDALWriteBlock().







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





Generated for GDAL by 
doxygen 1.6.2-20100208.