The GDALRasterAttributeTable (or RAT) class is used to encapsulate a table used to provide attribute information about pixel values. More...

Inheritance diagram for GDALRasterAttributeTable:

Public Member Functions
virtual GDALRasterAttributeTable *	Clone () const =0
	Copy Raster Attribute Table. More...

virtual int	GetColumnCount () const =0
	Fetch table column count. More...

virtual const char *	GetNameOfCol (int iCol) const =0
	Fetch name of indicated column. More...

virtual GDALRATFieldUsage	GetUsageOfCol (int iCol) const =0
	Fetch column usage value. More...

virtual GDALRATFieldType	GetTypeOfCol (int iCol) const =0
	Fetch column type. More...

virtual int	GetColOfUsage (GDALRATFieldUsage eUsage) const =0
	Fetch column index for given usage. More...

virtual int	GetRowCount () const =0
	Fetch row count. More...

virtual const char *	GetValueAsString (int iRow, int iField) const =0
	Fetch field value as a string. More...

virtual int	GetValueAsInt (int iRow, int iField) const =0
	Fetch field value as a integer. More...

virtual double	GetValueAsDouble (int iRow, int iField) const =0
	Fetch field value as a double. More...

virtual void	SetValue (int iRow, int iField, const char *pszValue)=0
	Set field value from string. More...

virtual void	SetValue (int iRow, int iField, int nValue)=0
	Set field value from integer. More...

virtual void	SetValue (int iRow, int iField, double dfValue)=0
	Set field value from double. More...

virtual int	ChangesAreWrittenToFile ()=0
	Determine whether changes made to this RAT are reflected directly in the dataset. More...

virtual CPLErr	SetTableType (const GDALRATTableType eInTableType)=0
	Set the RAT table type. More...

virtual GDALRATTableType	GetTableType () const =0
	Get the RAT table type. More...

virtual CPLErr	ValuesIO (GDALRWFlag eRWFlag, int iField, int iStartRow, int iLength, double *pdfData)
	Read or Write a block of doubles to/from the Attribute Table. More...

virtual CPLErr	ValuesIO (GDALRWFlag eRWFlag, int iField, int iStartRow, int iLength, int *pnData)
	Read or Write a block of integers to/from the Attribute Table. More...

virtual CPLErr	ValuesIO (GDALRWFlag eRWFlag, int iField, int iStartRow, int iLength, char **papszStrList)
	Read or Write a block of strings to/from the Attribute Table. More...

virtual void	SetRowCount (int iCount)
	Set row count. More...

virtual int	GetRowOfValue (double dfValue) const
	Get row for pixel value. More...

virtual int	GetRowOfValue (int nValue) const
	Get row for pixel value. More...

virtual CPLErr	CreateColumn (const char *pszFieldName, GDALRATFieldType eFieldType, GDALRATFieldUsage eFieldUsage)
	Create new column. More...

virtual CPLErr	SetLinearBinning (double dfRow0Min, double dfBinSize)
	Set linear binning information. More...

virtual int	GetLinearBinning (double pdfRow0Min, double pdfBinSize) const
	Get linear binning information. More...

virtual CPLXMLNode *	Serialize () const
	Serialize. More...

virtual void *	SerializeJSON () const
	Serialize as a JSON object. More...

virtual CPLErr	XMLInit (CPLXMLNode , const char )
	Deserialize from XML. More...

virtual CPLErr	InitializeFromColorTable (const GDALColorTable *)
	Initialize from color table. More...

virtual GDALColorTable *	TranslateToColorTable (int nEntryCount=-1)
	Translate to a color table. More...

virtual void	DumpReadable (FILE *=nullptr)
	Dump RAT in readable form. More...

virtual void	RemoveStatistics ()=0
	Remove statistics from the RAT. More...

Static Public Member Functions
static GDALRasterAttributeTableH	ToHandle (GDALRasterAttributeTable *poRAT)
	Convert a GDALRasterAttributeTable* to a GDALRasterAttributeTableH. More...

static GDALRasterAttributeTable *	FromHandle (GDALRasterAttributeTableH hRAT)
	Convert a GDALRasterAttributeTableH to a GDALRasterAttributeTable*. More...

Detailed Description

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

◆ ChangesAreWrittenToFile()

virtual int GDALRasterAttributeTable::ChangesAreWrittenToFile ( )

pure virtual

Determine whether changes made to this RAT are reflected directly in the dataset.

If this returns FALSE then GDALRasterBand.SetDefaultRAT() should be called. Otherwise this is unnecessary since changes to this object are reflected in the dataset.

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

Implemented in GDALDefaultRasterAttributeTable.

◆ Clone()

virtual GDALRasterAttributeTable* GDALRasterAttributeTable::Clone ( ) const

pure virtual

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. May fail (return nullptr) if the attribute table is too large to clone (GetRowCount() * GetColCount() > RAT_MAX_ELEM_FOR_CLONE)

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

Returns: new copy of the RAT as an in-memory implementation.

Implemented in GDALDefaultRasterAttributeTable.

◆ CreateColumn()

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

virtual

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.

Reimplemented in GDALDefaultRasterAttributeTable.

◆ DumpReadable()

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

virtual

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.

◆ FromHandle()

static GDALRasterAttributeTable* GDALRasterAttributeTable::FromHandle ( GDALRasterAttributeTableH hRAT )

inlinestatic

Convert a GDALRasterAttributeTableH to a GDALRasterAttributeTable*.

Since: GDAL 2.3

◆ GetColOfUsage()

virtual int GDALRasterAttributeTable::GetColOfUsage ( GDALRATFieldUsage eUsage ) const

pure virtual

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.

Implemented in GDALDefaultRasterAttributeTable.

◆ GetColumnCount()

virtual int GDALRasterAttributeTable::GetColumnCount ( ) const

pure virtual

Fetch table column count.

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

Returns: the number of columns.

Implemented in GDALDefaultRasterAttributeTable.

◆ GetLinearBinning()

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

virtual

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

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

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

Reimplemented in GDALDefaultRasterAttributeTable.

◆ GetNameOfCol()

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

pure virtual

Fetch name of indicated column.

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

Parameters

iCol	the column index (zero based).

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

Implemented in GDALDefaultRasterAttributeTable.

◆ GetRowCount()

virtual int GDALRasterAttributeTable::GetRowCount ( ) const

pure virtual

Fetch row count.

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

Returns: the number of rows.

Implemented in GDALDefaultRasterAttributeTable.

◆ GetRowOfValue() [1/2]

int GDALRasterAttributeTable::GetRowOfValue ( double dfValue ) const

virtual

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.

Reimplemented in GDALDefaultRasterAttributeTable.

◆ GetRowOfValue() [2/2]

int GDALRasterAttributeTable::GetRowOfValue ( int nValue ) const

virtual

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.

Int arg for now just converted to double. Perhaps we will handle this in a special way some day?

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

Parameters

nValue the pixel value.

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

Reimplemented in GDALDefaultRasterAttributeTable.

◆ GetTableType()

virtual GDALRATTableType GDALRasterAttributeTable::GetTableType ( ) const

pure virtual

Get the RAT table type.

Indicates whether the RAT is thematic or athematic (continuous).

Since: GDAL 2.4

Returns: table type

Implemented in GDALDefaultRasterAttributeTable.

◆ GetTypeOfCol()

virtual GDALRATFieldType GDALRasterAttributeTable::GetTypeOfCol ( int iCol ) const

pure virtual

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

Implemented in GDALDefaultRasterAttributeTable.

◆ GetUsageOfCol()

virtual GDALRATFieldUsage GDALRasterAttributeTable::GetUsageOfCol ( int iCol ) const

pure virtual

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.

Implemented in GDALDefaultRasterAttributeTable.

◆ GetValueAsDouble()

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

pure virtual

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

Implemented in GDALDefaultRasterAttributeTable.

◆ GetValueAsInt()

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

pure virtual

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

Implemented in GDALDefaultRasterAttributeTable.

◆ GetValueAsString()

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

pure virtual

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.

The returned string is temporary and cannot be expected to be available after the next GDAL call.

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

Parameters

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

Returns: field value.

Implemented in GDALDefaultRasterAttributeTable.

◆ InitializeFromColorTable()

CPLErr GDALRasterAttributeTable::InitializeFromColorTable ( const GDALColorTable * poTable )

virtual

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.

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

◆ RemoveStatistics()

virtual void GDALRasterAttributeTable::RemoveStatistics ( )

pure virtual

Remove statistics from the RAT.

Since: GDAL 2.4

Implemented in GDALDefaultRasterAttributeTable.

◆ Serialize()

CPLXMLNode * GDALRasterAttributeTable::Serialize ( ) const

virtual

Serialize.

Serialize as a XML tree.

May fail (return nullptr) if the attribute table is too large to serialize (GetRowCount() * GetColCount() > RAT_MAX_ELEM_FOR_CLONE)

Returns: XML tree.

◆ SerializeJSON()

void * GDALRasterAttributeTable::SerializeJSON ( ) const

virtual

Serialize as a JSON object.

Returns: JSON object (of type json_object*)

◆ SetLinearBinning()

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

virtual

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.

Reimplemented in GDALDefaultRasterAttributeTable.

◆ SetRowCount()

void GDALRasterAttributeTable::SetRowCount ( int nNewCount )

virtual

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.

Reimplemented in GDALDefaultRasterAttributeTable.

◆ SetTableType()

virtual CPLErr GDALRasterAttributeTable::SetTableType ( const GDALRATTableType eInTableType )

pure virtual

Set the RAT table type.

Set whether the RAT is thematic or athematic (continuous).

Since: GDAL 2.4

Implemented in GDALDefaultRasterAttributeTable.

◆ SetValue() [1/3]

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

pure virtual

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.

Implemented in GDALDefaultRasterAttributeTable.

◆ SetValue() [2/3]

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

pure virtual

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.

Implemented in GDALDefaultRasterAttributeTable.

◆ SetValue() [3/3]

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

pure virtual

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.

Implemented in GDALDefaultRasterAttributeTable.

◆ ToHandle()

static GDALRasterAttributeTableH GDALRasterAttributeTable::ToHandle ( GDALRasterAttributeTable * poRAT )

inlinestatic

Convert a GDALRasterAttributeTable* to a GDALRasterAttributeTableH.

Since: GDAL 2.3

◆ TranslateToColorTable()

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

virtual

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.

◆ ValuesIO() [1/3]

CPLErr GDALRasterAttributeTable::ValuesIO	(	GDALRWFlag	eRWFlag,
		int	iField,
		int	iStartRow,
		int	iLength,
		double *	pdfData
	)

virtual

Read or Write a block of doubles to/from the Attribute Table.

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

Parameters

eRWFlag	Either GF_Read or GF_Write
iField	column of the Attribute Table
iStartRow	start row to start reading/writing (zero based)
iLength	number of rows to read or write
pdfData	pointer to array of doubles to read/write. Should be at least iLength long.

Returns: CE_None or CE_Failure if iStartRow + iLength greater than number of rows in table.

◆ ValuesIO() [2/3]

CPLErr GDALRasterAttributeTable::ValuesIO	(	GDALRWFlag	eRWFlag,
		int	iField,
		int	iStartRow,
		int	iLength,
		int *	pnData
	)

virtual

Read or Write a block of integers to/from the Attribute Table.

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

Parameters

eRWFlag	Either GF_Read or GF_Write
iField	column of the Attribute Table
iStartRow	start row to start reading/writing (zero based)
iLength	number of rows to read or write
pnData	pointer to array of ints to read/write. Should be at least iLength long.

Returns: CE_None or CE_Failure if iStartRow + iLength greater than number of rows in table.

◆ ValuesIO() [3/3]

CPLErr GDALRasterAttributeTable::ValuesIO	(	GDALRWFlag	eRWFlag,
		int	iField,
		int	iStartRow,
		int	iLength,
		char **	papszStrList
	)

virtual

Read or Write a block of strings to/from the Attribute Table.

This method is the same as the C function GDALRATValuesIOAsString(). When reading, papszStrList must be already allocated to the correct size. The caller is expected to call CPLFree on each read string.

Parameters

eRWFlag	Either GF_Read or GF_Write
iField	column of the Attribute Table
iStartRow	start row to start reading/writing (zero based)
iLength	number of rows to read or write
papszStrList	pointer to array of strings to read/write. Should be at least iLength long.

Returns: CE_None or CE_Failure if iStartRow + iLength greater than number of rows in table.

◆ XMLInit()

CPLErr GDALRasterAttributeTable::XMLInit	(	CPLXMLNode *	psTree,
		const char *
	)

virtual

Deserialize from XML.

Parameters

psTree XML tree

Returns: error code.

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

gdal_rat.h
gdal_rat.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ChangesAreWrittenToFile()

◆ Clone()

◆ CreateColumn()

◆ DumpReadable()

◆ FromHandle()

◆ GetColOfUsage()

◆ GetColumnCount()

◆ GetLinearBinning()

◆ GetNameOfCol()

◆ GetRowCount()

◆ GetRowOfValue() [1/2]

◆ GetRowOfValue() [2/2]

◆ GetTableType()

◆ GetTypeOfCol()

◆ GetUsageOfCol()

◆ GetValueAsDouble()

◆ GetValueAsInt()

◆ GetValueAsString()

◆ InitializeFromColorTable()

◆ RemoveStatistics()

◆ Serialize()

◆ SerializeJSON()

◆ SetLinearBinning()

◆ SetRowCount()

◆ SetTableType()

◆ SetValue() [1/3]

◆ SetValue() [2/3]

◆ SetValue() [3/3]

◆ ToHandle()

◆ TranslateToColorTable()

◆ ValuesIO() [1/3]

◆ ValuesIO() [2/3]

◆ ValuesIO() [3/3]

◆ XMLInit()