Class: QgsRasterAttributeTable

class qgis.core.QgsRasterAttributeTable

Bases: sip.wrapper

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.

New in version 3.30:

Methods

appendField

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.

appendRow

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

color

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

colorRamp

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

createFromRaster

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.

createRenderer

Creates and returns a (possibly None) 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.

data

Returns the Raster Attribute Table rows.

fieldByName

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

fields

Returns the Raster Attribute Table fields.

fieldsByUsage

Returns the list of fields matching fieldUsage.

filePath

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.

guessFieldUsage

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

hasColor

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

hasRamp

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

insertColor

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

insertField

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

insertRamp

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

insertRow

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

isDirty

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

isValid

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

maximumValue

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

minMaxClasses

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.

minimumValue

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

orderedRows

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.

qgisFeatures

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

qgisFields

Returns the Raster Attribute Table fields as QgsFields.

ramp

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.

readFromFile

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

removeField

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

removeRow

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

row

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

setColor

Sets the color for the row at rowIndex to color.

setDirty

Sets the Raster Attribute Table dirty state to isDirty;

setFieldUsage

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

setRamp

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

setValue

Sets the value for row and column.

type

Returns the Raster Attribute Table type.

usageInformation

Returns information about supported Raster Attribute Table usages.

usageName

Returns the translated human readable name of fieldUsage.

usages

Returns the list of field usages.

value

Returns the value for row and column.

valueAndColorFieldUsages

Returns the list of field usages for colors and values.

writeToFile

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

class Field

Bases: sip.wrapper

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

New in version 3.30.

QgsRasterAttributeTable.Field(name: str, usage: Qgis.RasterAttributeTableFieldUsage, type: QVariant.Type) Creates a new Field with name, type and usage.

QgsRasterAttributeTable.Field(QgsRasterAttributeTable.Field)

isColor(self) bool

Returns True if the field carries a color component (Red, Green, Blue and optionally Alpha) information.

Return type

bool

isRamp(self) bool

Returns True if the field carries a color ramp component information (RedMin/RedMax, GreenMin/GreenMax, BlueMin/BlueMax and optionally AlphaMin/AlphaMax) information.

Return type

bool

name
type
usage
class MinMaxClass

Bases: sip.wrapper

The Field struct represents a Raster Attribute Table classification entry for a thematic Raster Attribute Table.

New in version 3.30.

color
minMaxValues
name
class UsageInformation

Bases: sip.wrapper

The UsageInformation struct represents information about a field usage.

New in version 3.30.

allowedTypes
description
isColor
isRamp
maybeClass
required
supported
unique
appendField(self, name: str, usage: Qgis.RasterAttributeTableFieldUsage, type: QVariant.Type) Tuple[bool, str]

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.

appendField(self, field: QgsRasterAttributeTable.Field) -> Tuple[bool, str] Appends a new field, optionally reporting any error in errorMessage, returns True on success.

Parameters
Return type

Tuple[bool, str]

appendRow(self, data: Iterable[Any]) Tuple[bool, str]

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

Parameters

data (Iterable[Any]) –

Return type

Tuple[bool, str]

color(self, row: int) QColor

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()

See also

setColor()

See also

hasRamp()

See also

setRamp()

See also

ramp()

Parameters

row (int) –

Return type

QColor

colorRamp(self, labelColumn: int = -1) Tuple[QgsGradientColorRamp, List[str]]

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

Parameters

labelColumn (int = -1) –

Return type

Tuple[QgsGradientColorRamp, List[str]]

createFromRaster(rasterLayer: QgsRasterLayer) Tuple[QgsRasterAttributeTable, int]

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 (QgsRasterLayer) – raster layer

Return type

Tuple[QgsRasterAttributeTable, int]

Returns

  • NULL in case of errors or unsupported renderer.

  • bandNumber: band number

createRenderer(self, provider: QgsRasterDataProvider, bandNumber: int, classificationColumn: int = -1) QgsRasterRenderer

Creates and returns a (possibly None) 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.

Parameters
Return type

QgsRasterRenderer

data(self) object

Returns the Raster Attribute Table rows.

Return type

object

fieldByName(self, name: str) Tuple[QgsRasterAttributeTable.Field, bool]

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

Parameters

name (str) – of the field

Return type

Tuple[QgsRasterAttributeTable.Field, bool]

Returns

  • the matching field or a default constructed one.

  • ok: will be set to True if the field was found.

fields(self) List[QgsRasterAttributeTable.Field]

Returns the Raster Attribute Table fields.

See also

qgisFields()

Return type

List[QgsRasterAttributeTable.Field]

fieldsByUsage(self, fieldUsage: Qgis.RasterAttributeTableFieldUsage) List[QgsRasterAttributeTable.Field]

Returns the list of fields matching fieldUsage.

Parameters

fieldUsage (Qgis.RasterAttributeTableFieldUsage) –

Return type

List[QgsRasterAttributeTable.Field]

filePath(self) str

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()

See also

readFromFile()

Return type

str

guessFieldUsage(name: str, type: QVariant.Type) Qgis.RasterAttributeTableFieldUsage

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

Parameters
  • name (str) –

  • type (QVariant.Type) –

Return type

Qgis.RasterAttributeTableFieldUsage

hasColor(self) bool

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

See also

color()

See also

setColor()

See also

hasRamp()

See also

setRamp()

See also

ramp()

Return type

bool

hasRamp(self) bool

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

See also

setRamp()

See also

ramp()

See also

hasColor()

See also

setColor()

Return type

bool

insertColor(self, position: int) Tuple[bool, str]

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

Parameters

position (int) –

Return type

Tuple[bool, str]

insertField(self, position: int, field: QgsRasterAttributeTable.Field) Tuple[bool, str]

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.

insertField(self, position: int, name: str, usage: Qgis.RasterAttributeTableFieldUsage, type: QVariant.Type) -> Tuple[bool, str] Creates a new field from name, usage and type and inserts it at position, optionally reporting any error in errorMessage, returns True on success.

Parameters
Return type

Tuple[bool, str]

insertRamp(self, position: int) Tuple[bool, str]

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

Parameters

position (int) –

Return type

Tuple[bool, str]

insertRow(self, position: int, rowData: Iterable[Any]) Tuple[bool, str]

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.

Parameters
  • position (int) –

  • rowData (Iterable[Any]) –

Return type

Tuple[bool, str]

isDirty(self) bool

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

Return type

bool

isValid(self) Tuple[bool, str]

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

Return type

Tuple[bool, str]

maximumValue(self) float

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

Return type

float

minMaxClasses(self, classificationColumn: int = -1) List[QgsRasterAttributeTable.MinMaxClass]

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.

Parameters

classificationColumn (int = -1) –

Return type

List[QgsRasterAttributeTable.MinMaxClass]

minimumValue(self) float

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

Return type

float

orderedRows(self) object

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.

Return type

object

qgisFeatures(self) List[QgsFeature]

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

Return type

List[QgsFeature]

qgisFields(self) QgsFields

Returns the Raster Attribute Table fields as QgsFields.

See also

fields()

Return type

QgsFields

ramp(self, row: int) QgsGradientColorRamp

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()

See also

setRamp()

See also

hasColor()

See also

setColor()

See also

color()

Parameters

row (int) –

Return type

QgsGradientColorRamp

readFromFile(self, path: str) Tuple[bool, str]

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

Parameters

path (str) –

Return type

Tuple[bool, str]

removeField(self, name: str) Tuple[bool, str]

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

Parameters

name (str) –

Return type

Tuple[bool, str]

removeRow(self, position: int = 0) Tuple[bool, str]

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.

Parameters

position (int = 0) –

Return type

Tuple[bool, str]

row(self, matchValue: float) List[Any]

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

Parameters

matchValue (float) –

Return type

List[Any]

setColor(self, row: int, color: Union[QColor, Qt.GlobalColor, QGradient]) bool

Sets the color for the row at rowIndex to color. returns True on success.

See also

hasColor()

See also

setColor()

See also

hasRamp()

See also

setRamp()

See also

ramp()

Parameters
  • row (int) –

  • color (Union[QColor) –

Return type

bool

setDirty(self, isDirty: bool)

Sets the Raster Attribute Table dirty state to isDirty;

Parameters

isDirty (bool) –

setFieldUsage(self, fieldIndex: int, usage: Qgis.RasterAttributeTableFieldUsage) bool

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

Return type

bool

Returns

True on success.

Parameters
setRamp(self, row: int, colorMin: Union[QColor, Qt.GlobalColor, QGradient], colorMax: Union[QColor, Qt.GlobalColor, QGradient]) bool

Sets the color ramp for the row at rowIndex to colorMin and colorMax. returns True on success.

See also

hasRamp()

See also

ramp()

See also

hasColor()

See also

setColor()

Parameters
  • row (int) –

  • colorMin (Union[QColor) –

  • colorMax (Union[QColor) –

Return type

bool

setValue(self, row: int, column: int, value: Any) bool

Sets the value for row and column.

Return type

bool

Returns

True on success.

Parameters
  • row (int) –

  • column (int) –

  • value (Any) –

type(self) Qgis.RasterAttributeTableType

Returns the Raster Attribute Table type.

Return type

Qgis.RasterAttributeTableType

usageInformation() Dict[int, QgsRasterAttributeTable.UsageInformation]

Returns information about supported Raster Attribute Table usages.

See also

usageName()

Return type

Dict[int, QgsRasterAttributeTable.UsageInformation]

usageName(fieldusage: Qgis.RasterAttributeTableFieldUsage) str

Returns the translated human readable name of fieldUsage.

Parameters

fieldusage (Qgis.RasterAttributeTableFieldUsage) –

Return type

str

usages(self) List[int]

Returns the list of field usages.

Return type

List[int]

value(self, row: int, column: int) Any

Returns the value for row and column.

Parameters
  • row (int) –

  • column (int) –

Return type

Any

valueAndColorFieldUsages() List[Qgis.RasterAttributeTableFieldUsage]

Returns the list of field usages for colors and values.

Return type

List[Qgis.RasterAttributeTableFieldUsage]

writeToFile(self, path: str) Tuple[bool, str]

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.

Parameters

path (str) –

Return type

Tuple[bool, str]