GDALRasterAttributeTable Class Reference

Raster Attribute Table container. More...

#include <gdal_rat.h>

Public Member Functions
	GDALRasterAttributeTable ()
	Construct empty table.
	GDALRasterAttributeTable (const GDALRasterAttributeTable &)
	Copy constructor.
GDALRasterAttributeTable *	Clone () const
	Copy Raster Attribute Table.
int	GetColumnCount () const
	Fetch table column count.
const char *	GetNameOfCol (int) const
	Fetch name of indicated column.
GDALRATFieldUsage	GetUsageOfCol (int) const
	Fetch column usage value.
GDALRATFieldType	GetTypeOfCol (int) const
	Fetch color type.
int	GetColOfUsage (GDALRATFieldUsage) const
	Fetch column index for given usage.
int	GetRowCount () const
	Fetch row count.
const char *	GetValueAsString (int iRow, int iField) const
	Fetch field value as a string.
int	GetValueAsInt (int iRow, int iField) const
	Fetch field value as a integer.
double	GetValueAsDouble (int iRow, int iField) const
	Fetch field value as a double.
void	SetValue (int iRow, int iField, const char *pszValue)
	Set field value from string.
void	SetValue (int iRow, int iField, double dfValue)
	Set field value from double.
void	SetValue (int iRow, int iField, int nValue)
	Set field value from integer.
void	SetRowCount (int iCount)
	Set row count.
int	GetRowOfValue (double dfValue) const
	Get row for pixel value.
int	GetRowOfValue (int nValue) const
int	GetColorOfValue (double dfValue, GDALColorEntry *psEntry) const
double	GetRowMin (int iRow) const
double	GetRowMax (int iRow) const
CPLErr	CreateColumn (const char *pszFieldName, GDALRATFieldType eFieldType, GDALRATFieldUsage eFieldUsage)
	Create new column.
CPLErr	SetLinearBinning (double dfRow0Min, double dfBinSize)
	Set linear binning information.
int	GetLinearBinning (double pdfRow0Min, double pdfBinSize) const
	Get linear binning information.
CPLXMLNode *	Serialize () const
CPLErr	XMLInit (CPLXMLNode , const char )
CPLErr	InitializeFromColorTable (const GDALColorTable *)
	Initialize from color table.
GDALColorTable *	TranslateToColorTable (int nEntryCount=-1)
	Translate to a color table.
void	DumpReadable (FILE *=NULL)
	Dump RAT in readable form.
Friends
const char *	GDALRATGetNameOfCol (GDALRasterAttributeTableH, int)
const char *	GDALRATGetValueAsString (GDALRasterAttributeTableH, int, int)

Detailed Description

Raster Attribute Table container.

The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute information about pixel values. Each row in the table applies to a range of pixel values (or a single value in some cases), and might have attributes such as the histogram count for that range, the color pixels of that range should be drawn names of classes or any other generic information.

Raster attribute tables can be used to represent histograms, color tables, and classification information.

Each column in a raster attribute table has a name, a type (integer, floating point or string), and a GDALRATFieldUsage. The usage distinguishes columns with particular understood purposes (such as color, histogram count, name) and columns that have specific purposes not understood by the library (long label, suitability_for_growing_wheat, etc).

In the general case each row has a column indicating the minimum pixel values falling into that category, and a column indicating the maximum pixel value. These are indicated with usage values of GFU_Min, and GFU_Max. In other cases where each row is a discrete pixel value, one column of usage GFU_MinMax can be used.

In other cases all the categories are of equal size and regularly spaced and the categorization information can be determine just by knowing the value at which the categories start, and the size of a category. This is called "Linear Binning" and the information is kept specially on the raster attribute table as a whole.

RATs are normally associated with GDALRasterBands and be be queried using the GDALRasterBand::GetDefaultRAT() method.

Member Function Documentation

GDALRasterAttributeTable * GDALRasterAttributeTable::Clone ( ) const

Copy Raster Attribute Table.

Creates a new copy of an existing raster attribute table. The new copy becomes the responsibility of the caller to destroy.

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

Returns:: new copy of the RAT.

References GDALRasterAttributeTable().

Referenced by GDALPamRasterBand::SetDefaultRAT().

CPLErr GDALRasterAttributeTable::CreateColumn	(	const char *	pszFieldName,
		GDALRATFieldType	eFieldType,
		GDALRATFieldUsage	eFieldUsage
	)

Create new column.

If the table already has rows, all row values for the new column will be initialized to the default value ("", or zero). The new column is always created as the last column, can will be column (field) "GetColumnCount()-1" after CreateColumn() has completed successfully.

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

Parameters:

	pszFieldName	the name of the field to create.
	eFieldType	the field type (integer, double or string).
	eFieldUsage	the field usage, GFU_Generic if not known.

Returns:: CE_None on success or CE_Failure if something goes wrong.

References GFT_Integer, GFT_Real, and GFT_String.

Referenced by InitializeFromColorTable().

void GDALRasterAttributeTable::DumpReadable ( FILE * fp = NULL )

Dump RAT in readable form.

Currently the readable form is the XML encoding ... only barely readable.

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

Parameters:

fp

file to dump to or NULL for stdout.

int GDALRasterAttributeTable::GetColOfUsage ( GDALRATFieldUsage eUsage ) const

Fetch column index for given usage.

Returns the index of the first column of the requested usage type, or -1 if no match is found.

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

Parameters:

eUsage

usage type to search for.

Returns:: column index, or -1 on failure.

Referenced by TranslateToColorTable().

int GDALRasterAttributeTable::GetColumnCount ( ) const

Fetch table column count.

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

Returns:: the number of columns.

Referenced by InitializeFromColorTable().

int GDALRasterAttributeTable::GetLinearBinning	(	double *	pdfRow0Min,
		double *	pdfBinSize
	)			const

Get linear binning information.

Returns linear binning information if any is associated with the RAT.

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

Parameters:

	pdfRow0MinIn	(out) the lower bound (pixel value) of the first category.
	pdfBinSizeIn	(out) the width of each category (in pixel value units).

Returns:: TRUE if linear binning information exists or FALSE if there is none.

const char * GDALRasterAttributeTable::GetNameOfCol ( int iCol ) const

Fetch name of indicated column.

This method is the same as the C function GDALRATGetNameOfCol(), except that the C function returns "const char *".

Parameters:

iCol

the column index (zero based).

Returns:: the column name or an empty string for invalid column numbers.

int GDALRasterAttributeTable::GetRowCount ( ) const

Fetch row count.

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

Returns:: the number of rows.

Referenced by InitializeFromColorTable().

int GDALRasterAttributeTable::GetRowOfValue ( double dfValue ) const

Get row for pixel value.

Given a raw pixel value, the raster attribute table is scanned to determine which row in the table applies to the pixel value. The row index is returned.

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

Parameters:

dfValue

the pixel value.

Returns:: the row index or -1 if no row is appropriate.

References GFT_Integer, and GFT_Real.

Referenced by TranslateToColorTable().

GDALRATFieldType GDALRasterAttributeTable::GetTypeOfCol ( int iCol ) const

Fetch color type.

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

Parameters:

iCol

the column index (zero based).

Returns:: column type or GFT_Integer if the column index is illegal.

References GFT_Integer.

GDALRATFieldUsage GDALRasterAttributeTable::GetUsageOfCol ( int iCol ) const

Fetch column usage value.

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

Parameters:

iCol

the column index (zero based).

Returns:: the column usage, or GFU_Generic for improper column numbers.

References GFU_Generic.

double GDALRasterAttributeTable::GetValueAsDouble	(	int	iRow,
		int	iField
	)			const

Fetch field value as a double.

The value of the requested column in the requested row is returned as a double. Non double fields will be converted to double with the possibility of data loss.

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

Parameters:

	iRow	row to fetch (zero based).
	iField	column to fetch (zero based).

Returns:: field value

References GFT_Integer, GFT_Real, and GFT_String.

int GDALRasterAttributeTable::GetValueAsInt	(	int	iRow,
		int	iField
	)			const

Fetch field value as a integer.

The value of the requested column in the requested row is returned as an integer. Non-integer fields will be converted to integer with the possibility of data loss.

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

Parameters:

	iRow	row to fetch (zero based).
	iField	column to fetch (zero based).

Returns:: field value

References GFT_Integer, GFT_Real, and GFT_String.

Referenced by TranslateToColorTable().

const char * GDALRasterAttributeTable::GetValueAsString	(	int	iRow,
		int	iField
	)			const

Fetch field value as a string.

The value of the requested column in the requested row is returned as a string. If the field is numeric, it is formatted as a string using default rules, so some precision may be lost.

This method is the same as the C function GDALRATGetValueAsString(), except it returns a "const char *" result.

Parameters:

	iRow	row to fetch (zero based).
	iField	column to fetch (zero based).

Returns:: field value

References GFT_Integer, GFT_Real, and GFT_String.

CPLErr GDALRasterAttributeTable::InitializeFromColorTable ( const GDALColorTable * poTable )

Initialize from color table.

This method will setup a whole raster attribute table based on the contents of the passed color table. The Value (GFU_MinMax), Red (GFU_Red), Green (GFU_Green), Blue (GFU_Blue), and Alpha (GFU_Alpha) fields are created, and a row is set for each entry in the color table.

The raster attribute table must be empty before calling InitializeFromColorTable().

The Value fields are set based on the implicit assumption with color tables that entry 0 applies to pixel value 0, 1 to 1, etc.

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

Parameters:

	poTable	the color table to copy from.
	CE_None	on success or CE_Failure if something goes wrong.

References GDALColorEntry::c1, GDALColorEntry::c2, GDALColorEntry::c3, GDALColorEntry::c4, CreateColumn(), GDALColorTable::GetColorEntryAsRGB(), GDALColorTable::GetColorEntryCount(), GetColumnCount(), GetRowCount(), GFT_Integer, GFU_Alpha, GFU_Blue, GFU_Green, GFU_MinMax, GFU_Red, SetLinearBinning(), SetRowCount(), and SetValue().

CPLErr GDALRasterAttributeTable::SetLinearBinning	(	double	dfRow0MinIn,
		double	dfBinSizeIn
	)

Set linear binning information.

For RATs with equal sized categories (in pixel value space) that are evenly spaced, this method may be used to associate the linear binning information with the table.

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

Parameters:

	dfRow0MinIn	the lower bound (pixel value) of the first category.
	dfBinSizeIn	the width of each category (in pixel value units).

Returns:: CE_None on success or CE_Failure on failure.

Referenced by InitializeFromColorTable().

void GDALRasterAttributeTable::SetRowCount ( int nNewCount )

Set row count.

Resizes the table to include the indicated number of rows. Newly created rows will be initialized to their default values - "" for strings, and zero for numeric fields.

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

Parameters:

nNewCount

the new number of rows.

References GFT_Integer, GFT_Real, and GFT_String.

Referenced by InitializeFromColorTable(), and SetValue().

void GDALRasterAttributeTable::SetValue	(	int	iRow,
		int	iField,
		int	nValue
	)

Set field value from integer.

The indicated field (column) on the indicated row is set from the passed value. The value will be automatically converted for other field types, with a possible loss of precision.

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

Parameters:

	iRow	row to fetch (zero based).
	iField	column to fetch (zero based).
	nValue	the value to assign.

References GFT_Integer, GFT_Real, GFT_String, and SetRowCount().

void GDALRasterAttributeTable::SetValue	(	int	iRow,
		int	iField,
		double	dfValue
	)

Set field value from double.

The indicated field (column) on the indicated row is set from the passed value. The value will be automatically converted for other field types, with a possible loss of precision.

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

Parameters:

	iRow	row to fetch (zero based).
	iField	column to fetch (zero based).
	dfValue	the value to assign.

References GFT_Integer, GFT_Real, GFT_String, and SetRowCount().

void GDALRasterAttributeTable::SetValue	(	int	iRow,
		int	iField,
		const char *	pszValue
	)

Set field value from string.

The indicated field (column) on the indicated row is set from the passed value. The value will be automatically converted for other field types, with a possible loss of precision.

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

Parameters:

	iRow	row to fetch (zero based).
	iField	column to fetch (zero based).
	pszValue	the value to assign.

References GFT_Integer, GFT_Real, GFT_String, and SetRowCount().

Referenced by InitializeFromColorTable().

GDALColorTable * GDALRasterAttributeTable::TranslateToColorTable ( int nEntryCount = -1 )

Translate to a color table.

This method will attempt to create a corresponding GDALColorTable from this raster attribute table.

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

Parameters:

nEntryCount

The number of entries to produce (0 to nEntryCount-1), or -1 to auto-determine the number of entries.

Returns:: the generated color table or NULL on failure.

References GDALColorEntry::c1, GDALColorEntry::c2, GDALColorEntry::c3, GDALColorEntry::c4, GetColOfUsage(), GetRowOfValue(), GetValueAsInt(), GFU_Alpha, GFU_Blue, GFU_Green, GFU_Max, GFU_MinMax, GFU_Red, and GDALColorTable::SetColorEntry().

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

gdal_rat.h
gdal_rat.cpp

GDALRasterAttributeTable Class Reference

Public Member Functions

Friends

Detailed Description

Member Function Documentation