Public Member Functions | Protected Member Functions | Protected Attributes

VRTRasterBand Class Reference

Inheritance diagram for VRTRasterBand:
GDALRasterBand GDALMajorObject VRTRawRasterBand VRTSourcedRasterBand VRTWarpedRasterBand VRTDerivedRasterBand

List of all members.

Public Member Functions

virtual CPLErr XMLInit (CPLXMLNode *, const char *)
virtual CPLXMLNodeSerializeToXML (const char *pszVRTPath)
virtual CPLErr SetNoDataValue (double)
 Set the no data value for this band.
virtual double GetNoDataValue (int *pbSuccess=NULL)
 Fetch the no data value for this band.
virtual CPLErr SetColorTable (GDALColorTable *)
 Set the raster color table.
virtual GDALColorTableGetColorTable ()
 Fetch the color table associated with band.
virtual CPLErr SetColorInterpretation (GDALColorInterp)
 Set color interpretation of a band.
virtual GDALColorInterp GetColorInterpretation ()
 How should this band be interpreted as color?
virtual const char * GetUnitType ()
 Return raster unit type.
CPLErr SetUnitType (const char *)
 Set unit type.
virtual char ** GetCategoryNames ()
 Fetch the list of category names for this raster.
virtual CPLErr SetCategoryNames (char **)
 Set the category names for this band.
virtual CPLErr SetMetadata (char **papszMD, const char *pszDomain="")
 Set metadata.
virtual CPLErr SetMetadataItem (const char *pszName, const char *pszValue, const char *pszDomain="")
 Set single metadata item.
virtual double GetOffset (int *pbSuccess=NULL)
 Fetch the raster value offset.
CPLErr SetOffset (double)
 Set scaling offset.
virtual double GetScale (int *pbSuccess=NULL)
 Fetch the raster value scale.
CPLErr SetScale (double)
 Set scaling ratio.
virtual int GetOverviewCount ()
 Return the number of overview layers available.
virtual GDALRasterBandGetOverview (int)
 Fetch overview raster band object.
virtual CPLErr GetHistogram (double dfMin, double dfMax, int nBuckets, int *panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc, void *pProgressData)
 Compute raster histogram.
virtual CPLErr GetDefaultHistogram (double *pdfMin, double *pdfMax, int *pnBuckets, int **ppanHistogram, int bForce, GDALProgressFunc, void *pProgressData)
 Fetch default raster histogram.
virtual CPLErr SetDefaultHistogram (double dfMin, double dfMax, int nBuckets, int *panHistogram)
 Set default histogram.
CPLErr CopyCommonInfoFrom (GDALRasterBand *)
virtual void GetFileList (char ***ppapszFileList, int *pnSize, int *pnMaxSize, CPLHashSet *hSetFiles)
virtual void SetDescription (const char *)
 Set object description.
virtual GDALRasterBandGetMaskBand ()
 Return the mask band associated with the band.
virtual int GetMaskFlags ()
 Return the status flags of the mask band associated with the band.
virtual CPLErr CreateMaskBand (int nFlags)
 Adds a mask band to the current band.
void SetMaskBand (VRTRasterBand *poMaskBand)
void SetIsMaskBand ()
CPLErr UnsetNoDataValue ()
virtual int CloseDependentDatasets ()
virtual int IsSourcedRasterBand ()

Protected Member Functions

void Initialize (int nXSize, int nYSize)

Protected Attributes

int bIsMaskBand
int bNoDataValueSet
int bHideNoDataValue
double dfNoDataValue
GDALColorTablepoColorTable
GDALColorInterp eColorInterp
char * pszUnitType
char ** papszCategoryNames
double dfOffset
double dfScale
CPLXMLNodepsSavedHistograms
std::vector< VRTOverviewInfoapoOverviews
VRTRasterBandpoMaskBand

Member Function Documentation

CPLErr VRTRasterBand::CreateMaskBand ( int  nFlags  )  [virtual]

Adds a mask band to the current band.

The default implementation of the CreateMaskBand() method is implemented based on similar rules to the .ovr handling implemented using the GDALDefaultOverviews object. A TIFF file with the extension .msk will be created with the same basename as the original file, and it will have as many bands as the original image (or just one for GMF_PER_DATASET). The mask images will be deflate compressed tiled images with the same block size as the original image if possible.

Note that if you got a mask band with a previous call to GetMaskBand(), it might be invalidated by CreateMaskBand(). So you have to call GetMaskBand() again.

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

Since:
GDAL 1.5.0
Returns:
CE_None on success or CE_Failure on an error.
See also:
http://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask

Reimplemented from GDALRasterBand.

char ** VRTRasterBand::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 VRTRasterBand::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 * VRTRasterBand::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 VRTRasterBand::GetDefaultHistogram ( double *  pdfMin,
double *  pdfMax,
int *  pnBuckets,
int **  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 overriden 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 function GDALGetDefaultHistogram().

Parameters:
pdfMin pointer to double value that will contain the lower bound of the histogram.
pdfMax pointer to double value that will contain the upper bound of the histogram.
pnBuckets pointer to int value that will contain the number of buckets in *ppanHistogram.
ppanHistogram pointer to array into which the histogram totals are placed. To be freed with VSIFree
bForce TRUE to force the computation. If FALSE and no default histogram is available, the method will return CE_Warning
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 from GDALRasterBand.

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

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

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 from GDALRasterBand.

Reimplemented in VRTSourcedRasterBand.

GDALRasterBand * VRTRasterBand::GetMaskBand (  )  [virtual]

Return the mask band associated with the band.

The GDALRasterBand class includes a default implementation of GetMaskBand() that returns one of four default implementations :

  • If a corresponding .msk file exists it will be used for the mask band.
  • If the dataset has a NODATA_VALUES metadata item, an instance of the new GDALNoDataValuesMaskBand class will be returned. GetMaskFlags() will return GMF_NODATA | GMF_PER_DATASET.
    Since:
    GDAL 1.6.0
  • If the band has a nodata value set, an instance of the new GDALNodataMaskRasterBand class will be returned. GetMaskFlags() will return GMF_NODATA.
  • If there is no nodata value, but the dataset has an alpha band that seems to apply to this band (specific rules yet to be determined) and that is of type GDT_Byte then that alpha band will be returned, and the flags GMF_PER_DATASET and GMF_ALPHA will be returned in the flags.
  • If neither of the above apply, an instance of the new GDALAllValidRasterBand class will be returned that has 255 values for all pixels. The null flags will return GMF_ALL_VALID.

Note that the GetMaskBand() should always return a GDALRasterBand mask, even if it is only an all 255 mask with the flags indicating GMF_ALL_VALID.

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

Returns:
a valid mask band.
Since:
GDAL 1.5.0
See also:
http://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask

Reimplemented from GDALRasterBand.

int VRTRasterBand::GetMaskFlags (  )  [virtual]

Return the status flags of the mask band associated with the band.

The GetMaskFlags() method returns an bitwise OR-ed set of status flags with the following available definitions that may be extended in the future:

  • GMF_ALL_VALID(0x01): There are no invalid pixels, all mask values will be 255. When used this will normally be the only flag set.
  • GMF_PER_DATASET(0x02): The mask band is shared between all bands on the dataset.
  • GMF_ALPHA(0x04): The mask band is actually an alpha band and may have values other than 0 and 255.
  • GMF_NODATA(0x08): Indicates the mask is actually being generated from nodata values. (mutually exclusive of GMF_ALPHA)

The GDALRasterBand class includes a default implementation of GetMaskBand() that returns one of four default implementations :

  • If a corresponding .msk file exists it will be used for the mask band.
  • If the dataset has a NODATA_VALUES metadata item, an instance of the new GDALNoDataValuesMaskBand class will be returned. GetMaskFlags() will return GMF_NODATA | GMF_PER_DATASET.
    Since:
    GDAL 1.6.0
  • If the band has a nodata value set, an instance of the new GDALNodataMaskRasterBand class will be returned. GetMaskFlags() will return GMF_NODATA.
  • If there is no nodata value, but the dataset has an alpha band that seems to apply to this band (specific rules yet to be determined) and that is of type GDT_Byte then that alpha band will be returned, and the flags GMF_PER_DATASET and GMF_ALPHA will be returned in the flags.
  • If neither of the above apply, an instance of the new GDALAllValidRasterBand class will be returned that has 255 values for all pixels. The null flags will return GMF_ALL_VALID.

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

Since:
GDAL 1.5.0
Returns:
a valid mask band.
See also:
http://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask

Reimplemented from GDALRasterBand.

double VRTRasterBand::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 from GDALRasterBand.

double VRTRasterBand::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 from GDALRasterBand.

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

Reimplemented in VRTWarpedRasterBand.

int VRTRasterBand::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 from GDALRasterBand.

Reimplemented in VRTWarpedRasterBand.

double VRTRasterBand::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 from GDALRasterBand.

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

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

Set color interpretation of a band.

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

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 from GDALRasterBand.

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

CPLErr VRTRasterBand::SetDefaultHistogram ( double  dfMin,
double  dfMax,
int  nBuckets,
int *  panHistogram 
) [virtual]

Set default histogram.

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

Reimplemented from GDALRasterBand.

void VRTRasterBand::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 VRTRasterBand::SetMetadata ( char **  papszMetadataIn,
const char *  pszDomain = "" 
) [virtual]

Set metadata.

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

Parameters:
papszMetadataIn the metadata in name=value string list format to apply.
pszDomain the 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 GDALMajorObject.

Reimplemented in VRTSourcedRasterBand.

CPLErr VRTRasterBand::SetMetadataItem ( const char *  pszName,
const char *  pszValue,
const char *  pszDomain = "" 
) [virtual]

Set single metadata item.

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

Parameters:
pszName the key for the metadata item to fetch.
pszValue the value to assign to the key.
pszDomain the domain to set within, use NULL for the default domain.
Returns:
CE_None on success, or an error code on failure.

Reimplemented from GDALMajorObject.

Reimplemented in VRTSourcedRasterBand.

CPLErr VRTRasterBand::SetNoDataValue ( double  dfNoData  )  [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 from GDALRasterBand.

CPLErr VRTRasterBand::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:
dfNewOffset the new offset.
Returns:
CE_None or success or CE_Failure on failure.

Reimplemented from GDALRasterBand.

CPLErr VRTRasterBand::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:
dfNewScale the new scale.
Returns:
CE_None or success or CE_Failure on failure.

Reimplemented from GDALRasterBand.

CPLErr VRTRasterBand::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:
pszNewValue the new unit type value.
Returns:
CE_None on success or CE_Failure if not succuessful, or unsupported.

Reimplemented from GDALRasterBand.


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

Generated for GDAL by doxygen 1.7.1.