The QgsRasterAttributeTable class represents a Raster Attribute Table (RAT). More...

#include <qgsrasterattributetable.h>

Classes
class	Field
	The Field class represents a Raster Attribute Table field, including its name, usage and type. More...

class	MinMaxClass
	The Field class represents a Raster Attribute Table classification entry for a thematic Raster Attribute Table. More...

class	UsageInformation
	The UsageInformation class represents information about a field usage. More...

Public Member Functions
bool	appendField (const QgsRasterAttributeTable::Field &field, QString *errorMessage=nullptr)
	Appends a new field, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	appendField (const QString &name, const Qgis::RasterAttributeTableFieldUsage usage, const QVariant::Type type, QString *errorMessage=nullptr)
	Creates a new field from name, usage and type and appends it to the fields, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	appendRow (const QVariantList &data, QString *errorMessage=nullptr)
	Appends a row of data to the RAT, optionally reporting any error in errorMessage, returns `true` on success. More...

PRIVATE QColor	color (int row) const
	Returns the color of the rat row or an invalid color if row does not exist or if there is no color definition. More...

QgsGradientColorRamp	colorRamp (QStringList &labels, const int labelColumn=-1) const
	Returns the color ramp for an athematic Raster Attribute Table setting the labels in labels, optionally generated from labelColumn. More...

QgsRasterRenderer *	createRenderer (QgsRasterDataProvider *provider, const int bandNumber, const int classificationColumn=-1)
	Creates and returns a (possibly `nullptr`) raster renderer for the specified provider and bandNumber and optionally reclassified by classificationColumn, the default value of -1 makes the method guess the classification column based on the field usage. More...

const QList< QList< QVariant > >	data () const
	Returns the Raster Attribute Table rows. More...

const QgsRasterAttributeTable::Field	fieldByName (const QString name, bool *ok=nullptr) const
	Returns a field by name or a default constructed field with empty name if the field is not found. More...

QList< QgsRasterAttributeTable::Field >	fields () const
	Returns the Raster Attribute Table fields. More...

const QList< QgsRasterAttributeTable::Field >	fieldsByUsage (const Qgis::RasterAttributeTableFieldUsage fieldUsage) const
	Returns the list of fields matching fieldUsage. More...

QString	filePath () const
	Returns the (possibly empty) path of the file-based RAT, the path is set when a RAT is read or written from/to a file. More...

bool	hasColor () const
	Returns `true` if the Raster Attribute Table has color RGBA information. More...

bool	hasRamp () const
	Returns `true` if the Raster Attribute Table has ramp RGBA information. More...

bool	insertColor (int position, QString *errorMessage=nullptr)
	Create RGBA fields and inserts them at position, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	insertField (int position, const QgsRasterAttributeTable::Field &field, QString *errorMessage=nullptr)
	Inserts a new field at position, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	insertField (int position, const QString &name, const Qgis::RasterAttributeTableFieldUsage usage, const QVariant::Type type, QString *errorMessage=nullptr)
	Creates a new field from name, usage and type and inserts it at position, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	insertRamp (int position, QString *errorMessage=nullptr)
	Create RGBA minimum and maximum fields and inserts them at position, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	insertRow (int position, const QVariantList &rowData, QString *errorMessage=nullptr)
	Inserts a row of rowData in the Raster Attribute Table at position, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	isDirty () const
	Returns `true` if the Raster Attribute Table was modified from its last reading from the storage. More...

bool	isValid (QString *errorMessage=nullptr) const
	Returns `true` if the Raster Attribute Table is valid, optionally reporting validity checks results in errorMessage. More...

double	maximumValue () const
	Returns the maximum value of the MinMax (thematic) or Max (athematic) column, returns NaN on errors. More...

double	minimumValue () const
	Returns the minimum value of the MinMax (thematic) or Min (athematic) column, returns NaN on errors. More...

QList< QgsRasterAttributeTable::MinMaxClass >	minMaxClasses (const int classificationColumn=-1) const
	Returns the classes for a thematic Raster Attribute Table, classified by classificationColumn, the default value of -1 makes the method guess the classification column based on the field usage. More...

QList< QList< QVariant > >	orderedRows () const
	Returns the data rows ordered by the value column(s) in ascending order, if the attribute table type is athematic the middle value for each row range is considered for ordering. More...

QgsFeatureList	qgisFeatures () const
	Returns the Raster Attribute Table rows as a list of QgsFeature. More...

QgsFields	qgisFields () const
	Returns the Raster Attribute Table fields as QgsFields. More...

QgsGradientColorRamp	ramp (int row) const
	Returns the gradient color ramp of the rat row or a default constructed gradient if row does not exist or if there is no color ramp definition. More...

bool	readFromFile (const QString &path, QString *errorMessage=nullptr)
	Reads the Raster Attribute Table from a DBF file specified by path, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	removeField (const QString &name, QString *errorMessage=nullptr)
	Removes the field with name, optionally reporting any error in errorMessage, returns `true` on success. More...

bool	removeRow (int position=0, QString *errorMessage=nullptr)
	Removes the row in the Raster Attribute Table at position, optionally reporting any error in errorMessage, returns `true` on success. More...

QVariantList	row (const double matchValue) const
	Returns a row of data for the given matchValue or and empty row if there is not match. More...

bool	setColor (const int row, const QColor &color)
	Sets the color for the row at rowIndex to color. More...

void	setDirty (bool isDirty)
	Sets the Raster Attribute Table dirty state to isDirty;. More...

bool	setFieldUsage (int fieldIndex, const Qgis::RasterAttributeTableFieldUsage usage)
	Change the usage of the field at index fieldIndex to usage with checks for allowed types. More...

bool	setRamp (const int row, const QColor &colorMin, const QColor &colorMax)
	Sets the color ramp for the row at rowIndex to colorMin and colorMax. More...

bool	setValue (const int row, const int column, const QVariant &value)
	Sets the value for row and column. More...

Qgis::RasterAttributeTableType	type () const
	Returns the Raster Attribute Table type. More...

QList< Qgis::RasterAttributeTableFieldUsage >	usages () const
	Returns the list of field usages. More...

QVariant	value (const int row, const int column) const
	Returns the value for row and column. More...

bool	writeToFile (const QString &path, QString *errorMessage=nullptr)
	Writes the Raster Attribute Table to a DBF file specified by path, optionally reporting any error in errorMessage, returns `true` on success. More...

Static Public Member Functions
static QgsRasterAttributeTable *	createFromRaster (QgsRasterLayer rasterLayer, int bandNumber=nullptr)
	Creates a new Raster Attribute Table from a raster layer, the renderer must be Paletted or SingleBandPseudoColor, optionally reporting the raster band from which the attribute table was created. More...

static Qgis::RasterAttributeTableFieldUsage	guessFieldUsage (const QString &name, const QVariant::Type type)
	Try to determine the field usage from its name and type. More...

static QHash< Qgis::RasterAttributeTableFieldUsage, QgsRasterAttributeTable::UsageInformation >	usageInformation ()
	Returns information about supported Raster Attribute Table usages. More...

static QString	usageName (const Qgis::RasterAttributeTableFieldUsage fieldusage)
	Returns the translated human readable name of fieldUsage. More...

static QList< Qgis::RasterAttributeTableFieldUsage >	valueAndColorFieldUsages ()
	Returns the list of field usages for colors and values. More...

Detailed Description

The QgsRasterAttributeTable class represents a Raster Attribute Table (RAT).

This class is modeled after the GDAL Raster Attribute Table implementation, it adds some convenience methods to handle data from QGIS and to import/export a Raster Attribute Table from/to a DBF VAT file.

Since: QGIS 3.30

Definition at line 43 of file qgsrasterattributetable.h.

Member Function Documentation

◆ appendField() [1/2]

bool QgsRasterAttributeTable::appendField	(	const QgsRasterAttributeTable::Field &	field,
		QString *	errorMessage = `nullptr`
	)

Appends a new field, optionally reporting any error in errorMessage, returns true on success.

Definition at line 406 of file qgsrasterattributetable.cpp.

◆ appendField() [2/2]

bool QgsRasterAttributeTable::appendField	(	const QString &	name,
		const Qgis::RasterAttributeTableFieldUsage	usage,
		const QVariant::Type	type,
		QString *	errorMessage = `nullptr`
	)

Creates a new field from name, usage and type and appends it to the fields, optionally reporting any error in errorMessage, returns true on success.

Definition at line 401 of file qgsrasterattributetable.cpp.

◆ appendRow()

bool QgsRasterAttributeTable::appendRow	(	const QVariantList &	data,
		QString *	errorMessage = `nullptr`
	)

Appends a row of data to the RAT, optionally reporting any error in errorMessage, returns true on success.

Definition at line 490 of file qgsrasterattributetable.cpp.

◆ color()

private QColor QgsRasterAttributeTable::color ( int row ) const

Returns the color of the rat row or an invalid color if row does not exist or if there is no color definition.

See also: hasColor(); setColor(); hasRamp(); setRamp(); ramp()

Definition at line 155 of file qgsrasterattributetable.cpp.

◆ colorRamp()

QgsGradientColorRamp QgsRasterAttributeTable::colorRamp	(	QStringList &	labels,
		const int	labelColumn = `-1`
	)		const

Returns the color ramp for an athematic Raster Attribute Table setting the labels in labels, optionally generated from labelColumn.

Definition at line 1334 of file qgsrasterattributetable.cpp.

◆ createFromRaster()

QgsRasterAttributeTable * QgsRasterAttributeTable::createFromRaster	(	QgsRasterLayer *	rasterLayer,
		int *	bandNumber = `nullptr`
	)

static

Creates a new Raster Attribute Table from a raster layer, the renderer must be Paletted or SingleBandPseudoColor, optionally reporting the raster band from which the attribute table was created.

Parameters

rasterLayer	raster layer
bandNumber	band number

Returns: NULL in case of errors or unsupported renderer.

Definition at line 1046 of file qgsrasterattributetable.cpp.

◆ createRenderer()

QgsRasterRenderer * QgsRasterAttributeTable::createRenderer	(	QgsRasterDataProvider *	provider,
		const int	bandNumber,
		const int	classificationColumn = `-1`
	)

Creates and returns a (possibly nullptr) raster renderer for the specified provider and bandNumber and optionally reclassified by classificationColumn, the default value of -1 makes the method guess the classification column based on the field usage.

Note: athematic attribute tables with color ramps cannot be reclassified, the renderer will still use the classificationColumn for generating the class labels.

Definition at line 1489 of file qgsrasterattributetable.cpp.

◆ data()

const QList< QList< QVariant > > QgsRasterAttributeTable::data ( ) const

Returns the Raster Attribute Table rows.

Definition at line 681 of file qgsrasterattributetable.cpp.

◆ fieldByName()

const QgsRasterAttributeTable::Field QgsRasterAttributeTable::fieldByName	(	const QString	name,
		bool *	ok = `nullptr`
	)		const

Returns a field by name or a default constructed field with empty name if the field is not found.

Parameters

name	of the field
ok	if specified, will be set to `true` if the field was found.

Returns: the matching field or a default constructed one.

Definition at line 686 of file qgsrasterattributetable.cpp.

◆ fields()

QList< QgsRasterAttributeTable::Field > QgsRasterAttributeTable::fields ( ) const

Returns the Raster Attribute Table fields.

See also: qgisFields()

Definition at line 202 of file qgsrasterattributetable.cpp.

◆ fieldsByUsage()

const QList< QgsRasterAttributeTable::Field > QgsRasterAttributeTable::fieldsByUsage ( const Qgis::RasterAttributeTableFieldUsage fieldUsage ) const

Returns the list of fields matching fieldUsage.

Definition at line 706 of file qgsrasterattributetable.cpp.

◆ filePath()

PRIVATE QString QgsRasterAttributeTable::filePath ( ) const

Returns the (possibly empty) path of the file-based RAT, the path is set when a RAT is read or written from/to a file.

See also: writeToFile(); readFromFile()

Definition at line 1246 of file qgsrasterattributetable.cpp.

◆ guessFieldUsage()

Qgis::RasterAttributeTableFieldUsage QgsRasterAttributeTable::guessFieldUsage	(	const QString &	name,
		const QVariant::Type	type
	)

static

Try to determine the field usage from its name and type.

Definition at line 862 of file qgsrasterattributetable.cpp.

◆ hasColor()

bool QgsRasterAttributeTable::hasColor ( ) const

Returns true if the Raster Attribute Table has color RGBA information.

See also: color(); setColor(); hasRamp(); setRamp(); ramp()

Definition at line 44 of file qgsrasterattributetable.cpp.

◆ hasRamp()

bool QgsRasterAttributeTable::hasRamp ( ) const

Returns true if the Raster Attribute Table has ramp RGBA information.

See also: setRamp(); ramp(); hasColor(); setColor()

Definition at line 126 of file qgsrasterattributetable.cpp.

◆ insertColor()

bool QgsRasterAttributeTable::insertColor	(	int	position,
		QString *	errorMessage = `nullptr`
	)

Create RGBA fields and inserts them at position, optionally reporting any error in errorMessage, returns true on success.

Definition at line 345 of file qgsrasterattributetable.cpp.

◆ insertField() [1/2]

bool QgsRasterAttributeTable::insertField	(	int	position,
		const QgsRasterAttributeTable::Field &	field,
		QString *	errorMessage = `nullptr`
	)

Inserts a new field at position, optionally reporting any error in errorMessage, returns true on success.

Note: Out of range position is automatically clamped to a valid value.

Definition at line 245 of file qgsrasterattributetable.cpp.

◆ insertField() [2/2]

bool QgsRasterAttributeTable::insertField	(	int	position,
		const QString &	name,
		const Qgis::RasterAttributeTableFieldUsage	usage,
		const QVariant::Type	type,
		QString *	errorMessage = `nullptr`
	)

Creates a new field from name, usage and type and inserts it at position, optionally reporting any error in errorMessage, returns true on success.

Definition at line 340 of file qgsrasterattributetable.cpp.

◆ insertRamp()

bool QgsRasterAttributeTable::insertRamp	(	int	position,
		QString *	errorMessage = `nullptr`
	)

Create RGBA minimum and maximum fields and inserts them at position, optionally reporting any error in errorMessage, returns true on success.

Definition at line 379 of file qgsrasterattributetable.cpp.

◆ insertRow()

bool QgsRasterAttributeTable::insertRow	(	int	position,
		const QVariantList &	rowData,
		QString *	errorMessage = `nullptr`
	)

Inserts a row of rowData in the Raster Attribute Table at position, optionally reporting any error in errorMessage, returns true on success.

Note: Out of range position is automatically clamped to a valid value.

Definition at line 437 of file qgsrasterattributetable.cpp.

◆ isDirty()

bool QgsRasterAttributeTable::isDirty ( ) const

Returns true if the Raster Attribute Table was modified from its last reading from the storage.

Definition at line 235 of file qgsrasterattributetable.cpp.

◆ isValid()

bool QgsRasterAttributeTable::isValid ( QString * errorMessage = nullptr ) const

Returns true if the Raster Attribute Table is valid, optionally reporting validity checks results in errorMessage.

Definition at line 629 of file qgsrasterattributetable.cpp.

◆ maximumValue()

double QgsRasterAttributeTable::maximumValue ( ) const

Returns the maximum value of the MinMax (thematic) or Max (athematic) column, returns NaN on errors.

Definition at line 787 of file qgsrasterattributetable.cpp.

◆ minimumValue()

double QgsRasterAttributeTable::minimumValue ( ) const

Returns the minimum value of the MinMax (thematic) or Min (athematic) column, returns NaN on errors.

Definition at line 752 of file qgsrasterattributetable.cpp.

◆ minMaxClasses()

QList< QgsRasterAttributeTable::MinMaxClass > QgsRasterAttributeTable::minMaxClasses ( const int classificationColumn = -1 ) const

Returns the classes for a thematic Raster Attribute Table, classified by classificationColumn, the default value of -1 makes the method guess the classification column based on the field usage.

Definition at line 1251 of file qgsrasterattributetable.cpp.

◆ orderedRows()

QList< QList< QVariant > > QgsRasterAttributeTable::orderedRows ( ) const

Returns the data rows ordered by the value column(s) in ascending order, if the attribute table type is athematic the middle value for each row range is considered for ordering.

If the attribute table does not have any value field (and hence is not valid), the current data are returned without any change.

Definition at line 1574 of file qgsrasterattributetable.cpp.

◆ qgisFeatures()

QgsFeatureList QgsRasterAttributeTable::qgisFeatures ( ) const

Returns the Raster Attribute Table rows as a list of QgsFeature.

Definition at line 218 of file qgsrasterattributetable.cpp.

◆ qgisFields()

QgsFields QgsRasterAttributeTable::qgisFields ( ) const

Returns the Raster Attribute Table fields as QgsFields.

See also: fields()

Definition at line 207 of file qgsrasterattributetable.cpp.

◆ ramp()

QgsGradientColorRamp QgsRasterAttributeTable::ramp ( int row ) const

Returns the gradient color ramp of the rat row or a default constructed gradient if row does not exist or if there is no color ramp definition.

See also: hasRamp(); setRamp(); hasColor(); setColor(); color()

Definition at line 177 of file qgsrasterattributetable.cpp.

◆ readFromFile()

bool QgsRasterAttributeTable::readFromFile	(	const QString &	path,
		QString *	errorMessage = `nullptr`
	)

Reads the Raster Attribute Table from a DBF file specified by path, optionally reporting any error in errorMessage, returns true on success.

Definition at line 551 of file qgsrasterattributetable.cpp.

◆ removeField()

bool QgsRasterAttributeTable::removeField	(	const QString &	name,
		QString *	errorMessage = `nullptr`
	)

Removes the field with name, optionally reporting any error in errorMessage, returns true on success.

Definition at line 411 of file qgsrasterattributetable.cpp.

◆ removeRow()

bool QgsRasterAttributeTable::removeRow	(	int	position = `0`,
		QString *	errorMessage = `nullptr`
	)

Removes the row in the Raster Attribute Table at position, optionally reporting any error in errorMessage, returns true on success.

Note: position must be a valid position.

Definition at line 475 of file qgsrasterattributetable.cpp.

◆ row()

QVariantList QgsRasterAttributeTable::row ( const double matchValue ) const

Returns a row of data for the given matchValue or and empty row if there is not match.

Definition at line 822 of file qgsrasterattributetable.cpp.

◆ setColor()

bool QgsRasterAttributeTable::setColor	(	const int	row,
		const QColor &	color
	)

Sets the color for the row at rowIndex to color.

returns true on success.

See also: hasColor(); setColor(); hasRamp(); setRamp(); ramp()

Definition at line 50 of file qgsrasterattributetable.cpp.

◆ setDirty()

void QgsRasterAttributeTable::setDirty ( bool isDirty )

Sets the Raster Attribute Table dirty state to isDirty;.

Definition at line 240 of file qgsrasterattributetable.cpp.

◆ setFieldUsage()

bool QgsRasterAttributeTable::setFieldUsage	(	int	fieldIndex,
		const Qgis::RasterAttributeTableFieldUsage	usage
	)

Change the usage of the field at index fieldIndex to usage with checks for allowed types.

Returns: true on success.

Definition at line 360 of file qgsrasterattributetable.cpp.

◆ setRamp()

bool QgsRasterAttributeTable::setRamp	(	const int	row,
		const QColor &	colorMin,
		const QColor &	colorMax
	)

Sets the color ramp for the row at rowIndex to colorMin and colorMax.

returns true on success.

See also: hasRamp(); ramp(); hasColor(); setColor()

Definition at line 82 of file qgsrasterattributetable.cpp.

◆ setValue()

bool QgsRasterAttributeTable::setValue	(	const int	row,
		const int	column,
		const QVariant &	value
	)

Sets the value for row and column.

Returns: true on success.

Definition at line 719 of file qgsrasterattributetable.cpp.

◆ type()

private Qgis::RasterAttributeTableType QgsRasterAttributeTable::type ( ) const

Returns the Raster Attribute Table type.

Definition at line 38 of file qgsrasterattributetable.cpp.

◆ usageInformation()

QHash< Qgis::RasterAttributeTableFieldUsage, QgsRasterAttributeTable::UsageInformation > QgsRasterAttributeTable::usageInformation ( )

static

Returns information about supported Raster Attribute Table usages.

See also: usageName()

Definition at line 1198 of file qgsrasterattributetable.cpp.

◆ usageName()

QString QgsRasterAttributeTable::usageName ( const Qgis::RasterAttributeTableFieldUsage fieldusage )

static

Returns the translated human readable name of fieldUsage.

See also: usageInformation()

Definition at line 978 of file qgsrasterattributetable.cpp.

◆ usages()

QList< Qgis::RasterAttributeTableFieldUsage > QgsRasterAttributeTable::usages ( ) const

Returns the list of field usages.

Definition at line 133 of file qgsrasterattributetable.cpp.

◆ value()

QVariant QgsRasterAttributeTable::value	(	const int	row,
		const int	column
	)		const

Returns the value for row and column.

Definition at line 743 of file qgsrasterattributetable.cpp.

◆ valueAndColorFieldUsages()

QList< Qgis::RasterAttributeTableFieldUsage > QgsRasterAttributeTable::valueAndColorFieldUsages ( )

static

Returns the list of field usages for colors and values.

Definition at line 1024 of file qgsrasterattributetable.cpp.

◆ writeToFile()

bool QgsRasterAttributeTable::writeToFile	(	const QString &	path,
		QString *	errorMessage = `nullptr`
	)

Writes the Raster Attribute Table to a DBF file specified by path, optionally reporting any error in errorMessage, returns true on success.

Note: ".vat.dbf" extension is automatically added to the file path if not present.

Definition at line 495 of file qgsrasterattributetable.cpp.

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

/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/core/raster/qgsrasterattributetable.h
/build/qgis-3.37.0+git20240325+fdefdf9c27f+17bookworm/src/core/raster/qgsrasterattributetable.cpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ appendField() [1/2]

◆ appendField() [2/2]

◆ appendRow()

◆ color()

◆ colorRamp()

◆ createFromRaster()

◆ createRenderer()

◆ data()

◆ fieldByName()

◆ fields()

◆ fieldsByUsage()

◆ filePath()

◆ guessFieldUsage()

◆ hasColor()

◆ hasRamp()

◆ insertColor()

◆ insertField() [1/2]

◆ insertField() [2/2]

◆ insertRamp()

◆ insertRow()

◆ isDirty()

◆ isValid()

◆ maximumValue()

◆ minimumValue()

◆ minMaxClasses()

◆ orderedRows()

◆ qgisFeatures()

◆ qgisFields()

◆ ramp()

◆ readFromFile()

◆ removeField()

◆ removeRow()

◆ row()

◆ setColor()

◆ setDirty()

◆ setFieldUsage()

◆ setRamp()

◆ setValue()

◆ type()

◆ usageInformation()

◆ usageName()

◆ usages()

◆ value()

◆ valueAndColorFieldUsages()

◆ writeToFile()