#include <gdal_priv.h>
Inheritance diagram for GDALRasterBand:
Public Methods | |||
![]() | ![]() | GDALRasterBand () | |
![]() | ![]() | virtual | ~GDALRasterBand () |
![]() | ![]() | int | GetXSize () |
![]() | ![]() | Fetch XSize of raster. More... | |
![]() | ![]() | int | GetYSize () |
![]() | ![]() | Fetch YSize of raster. 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... | |
![]() | ![]() | GDALAccess | GetAccess () |
![]() | ![]() | Find out if we have update permission for this band. More... | |
![]() | ![]() | CPLErr | RasterIO ( GDALRWFlag, int, int, int, int, void *, int, int, GDALDataType, int, int ) |
![]() | ![]() | Read/write a region of image data for this band. More... | |
![]() | ![]() | CPLErr | ReadBlock ( int, int, void * ) |
![]() | ![]() | Read a block of image data efficiently. More... | |
![]() | ![]() | CPLErr | WriteBlock ( int, int, void * ) |
![]() | ![]() | Write a block of image data efficiently. More... | |
![]() | ![]() | GDALRasterBlock* | GetBlockRef ( int, int ) |
![]() | ![]() | Fetch a pointer to an internally cached raster block. More... | |
![]() | ![]() | CPLErr | FlushCache () |
![]() | ![]() | Flush raster data cache. More... | |
![]() | ![]() | CPLErr | FlushBlock ( int = -1, int = -1 ) |
![]() | ![]() | virtual const char* | GetDescription () |
![]() | ![]() | Return a description of this band. More... | |
![]() | ![]() | virtual char** | GetCategoryNames () |
![]() | ![]() | Fetch the list of category names for this raster. More... | |
![]() | ![]() | virtual double | GetNoDataValue ( int *pbSuccess = NULL ) |
![]() | ![]() | Fetch the no data value for this band. 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 double | GetOffset ( int *pbSuccess = NULL ) |
![]() | ![]() | Fetch the raster value offset. More... | |
![]() | ![]() | virtual double | GetScale ( int *pbSuccess = NULL ) |
![]() | ![]() | Fetch the raster value scale. More... | |
![]() | ![]() | virtual const char* | GetUnitType () |
![]() | ![]() | Return raster unit type. More... | |
![]() | ![]() | virtual GDALColorInterp | GetColorInterpretation () |
![]() | ![]() | How should this band be interpreted as color? More... | |
![]() | ![]() | virtual GDALColorTable* | GetColorTable () |
![]() | ![]() | Fetch the color table associated with band. More... | |
![]() | ![]() | virtual int | HasArbitraryOverviews () |
![]() | ![]() | Check for arbitrary overviews. More... | |
![]() | ![]() | virtual int | GetOverviewCount () |
![]() | ![]() | Return the number of overview layers available. More... | |
![]() | ![]() | virtual GDALRasterBand* | GetOverview (int) |
![]() | ![]() | Fetch overview raster band object. More... | |
![]() | ![]() | virtual CPLErr | BuildOverviews ( const char *, int, int *, GDALProgressFunc, void * ) |
![]() | ![]() | Build raster overview(s). More... | |
![]() | ![]() | CPLErr | GetHistogram ( double dfMin, double dfMax, int nBuckets, int * panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc, void *pProgressData ) |
![]() | ![]() | Compute raster histogram. More... | |
Protected Methods | |||
![]() | ![]() | 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 ) |
![]() | ![]() | CPLErr | AdoptBlock ( int, int, GDALRasterBlock * ) |
![]() | ![]() | void | InitBlockInfo () |
Protected Attributes | |||
![]() | ![]() | GDALDataset* | poDS |
![]() | ![]() | int | nBand |
![]() | ![]() | int | nRasterXSize |
![]() | ![]() | int | nRasterYSize |
![]() | ![]() | GDALDataType | eDataType |
![]() | ![]() | GDALAccess | eAccess |
![]() | ![]() | int | nBlockXSize |
![]() | ![]() | int | nBlockYSize |
![]() | ![]() | int | nBlocksPerRow |
![]() | ![]() | int | nBlocksPerColumn |
![]() | ![]() | GDALRasterBlock** | papoBlocks |
Friends | |||
![]() | ![]() | class | GDALDataset |
![]() | ![]() | class | GDALRasterBlock |
GDALRasterBand::GDALRasterBand () |
Constructor. Applications should never create GDALRasterBands directly.
GDALRasterBand::~GDALRasterBand () [virtual]
|
Destructor. Applications should never destroy GDALRasterBands directly, instead destroy the GDALDataset.
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 CPLGetLastError() will return CPLE_NonSupported.
pszResampling | one of "NEAREST", "AVERAGE" or "MODE" 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.
|
CPLErr GDALRasterBand::FlushCache (void) |
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().
GDALAccess GDALRasterBand::GetAccess () |
Find out if we have update permission for this band.
GDALRasterBlock * GDALRasterBand::GetBlockRef (int nXBlockOff, int nYBlockOff) |
Fetch a pointer to an internally cached raster block.
Note that calling GetBlockRef() on a previously uncached band will enable caching.
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.
|
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.
pnXSize |
integer to put the X block size into or NULL.
|
pnYSize | integer to put the Y block size into or NULL. |
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.
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().
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().
const char * GDALRasterBand::GetDescription () [virtual]
|
Return a description of this band.
CPLErr GDALRasterBand::GetHistogram (double dfMin, double dfMax, int nBuckets, int * panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc pfnProgress, void * pProgressData) |
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.
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.
|
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().
pbSuccess |
pointer to a boolean to use to indicate if the
returned value is a tight maximum or not. May be NULL (default).
|
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().
pbSuccess |
pointer to a boolean to use to indicate if the
returned value is a tight minimum or not. May be NULL (default).
|
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().
pbSuccess |
pointer to a boolean to use to indicate if a value
is actually associated with this layer. May be NULL (default).
|
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.
pbSuccess |
pointer to a boolean to use to indicate if the
returned value is meaningful or not. May be NULL (default).
|
GDALRasterBand * GDALRasterBand::GetOverview (int i) [virtual]
|
Fetch overview raster band object.
This method is the same as the C function GDALGetOverview().
i |
overview index between 0 and GetOverviewCount()-1.
|
int GDALRasterBand::GetOverviewCount () [virtual]
|
Return the number of overview layers available.
This method is the same as the C function GDALGetOverviewCount();
GDALDataType GDALRasterBand::GetRasterDataType (void) |
Fetch the pixel data type for this band.
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.
pbSuccess |
pointer to a boolean to use to indicate if the
returned value is meaningful or not. May be NULL (default).
|
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. If no units are available, a value of "" will be returned. The returned string should not be modified, nor freed by the calling application.
int GDALRasterBand::GetXSize () |
Fetch XSize of raster.
This method is the same as the C function GDALGetRasterBandXSize().
int GDALRasterBand::GetYSize () |
Fetch YSize of raster.
This method is the same as the C function GDALGetRasterBandYSize().
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.
CPLErr GDALRasterBand::RasterIO (GDALRWFlag eRWFlag, int nXOff, int, int, int, void * pData, int, int, GDALDataType, int, int) |
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.
eRWFlag |
Either GF_Read to read a region of data, or GT_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 into which the desired region is
to be read, or from which it is to be written.
|
nBufYSize |
the height of the buffer 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
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.
|
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 GetBlockRef() method for a way of accessing internally cached block oriented data without an extra copy into an application buffer.
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().
|
CPLErr GetHistogram( GDALRasterBand *poBand, int *panHistogram ) { int nXBlocks, nYBlocks, nXBlockSize, nYBlockSize; int iXBlock, iYBlock; 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 * nXBlockSize > poBand->GetXSize() ) nXValid = poBand->GetXSize() - iXBlock * nXBlockSize; else nXValid = nXBlockSize; if( iYBlock * nYBlockSize > poBand->GetYSize() ) nYValid = poBand->GetXSize() - iYBlock * nYBlockSize; else nYValid = nYBlockSize; // Collect the histogram counts. for( int iY = 0; iY < nXValid; iY++ ) { for( int iX = 0; iX < nXValid; iX++ ) { pabyHistogram[pabyData[iX + iY * nXBlockSize]] += 1; } } } } }
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.
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().
|