Raster Attribute Tables

A GDAL Raster Attribute Table (RAT) provides attribute information about pixel values. Raster attribute tables can be used to represent histograms, color tables, and classification information. Each row in the table applies to either a single pixel value or a range of values, and might have attributes such as the histogram count for that value (or range), the color that pixels of that value (or range) should be displayed, names of classes, or various other information. gdalraster supports reading Raster Attribute Tables as R data frame, building new tables, and setting a default RAT on a raster band.

Format of GDAL RAT

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

In the general case, each row has a field indicating the minimum pixel value falling into that category, and a field indicating the maximum pixel value. In the GDAL API, these are indicated with usage values of GFU_Min and GFU_Max (GDALRATFieldUsage enumeration constants). This vignette will focus on the particular but common case where each row is a discrete pixel value. In this case, a single column with usage GFU_MinMax (indicating class value) would be used instead of separate min and max columns. The table is represented in R as a data frame with column attribute "GFU" containing the field usage, e.g., "MinMax" (case-sensitive string). Other field usage types include "PixelCount" (GFU_PixelCount, histogram pixel count), "Name" (GFU_Name, class name), "Red" (GFU_Red, class color 0-255), "Green" (GFU_Green, class color 0-255), "Blue" (GFU_Blue, class color 0-255), and "Generic" (GFU_Generic, general purpose field).

A raster attribute table can be used with thematic or athematic (continuous) data. This is defined in R by an attribute on the data frame named "GDALRATTableType" with a value of either "thematic" or "athematic".

Read/build/set attribute tables

gdalraster can read, build and set Raster Attribute Tables via data frame. An object of class GDALRaster has method $getDefaultRAT() to read an existing RAT, and method $setDefaultRAT() to set a RAT from a data frame. The stand-alone function buildRAT() scans a raster to obtain the set of unique pixel values and their counts, optionally joins additional columns from a passed data frame, and returns a data frame with the appropriate metadata automatically assigned (i.e., R attributes assigned on the data frame and its columns that define usage as a GDAL RAT, for passing to GDALRaster$setDefaultRAT()):

library(gdalraster)

# LANDFIRE Existing Vegetation Type (EVT)
evt_file <- system.file("extdata/storml_evt.tif", package="gdalraster")

# make a copy to modify
f <- paste0(tempdir(), "/", "storml_evt_tmp.tif")
file.copy(evt_file,  f)
#> [1] TRUE
ds <- new(GDALRaster, f, read_only=FALSE)
ds$getDefaultRAT(band=1)
#> NULL

# get the full attribute table for LANDFIRE EVT from its CSV file
evt_csv <- system.file("extdata/LF20_EVT_220.csv", package="gdalraster")
evt_df <- read.csv(evt_csv)
nrow(evt_df)
#> [1] 1068
head(evt_df)
#>   VALUE                                                   EVT_NAME EVT_LF
#> 1 -9999                                                Fill-NoData   <NA>
#> 2  4401                Alaska Arctic Coastal Sedge-Dwarf-Shrubland  Shrub
#> 3  4402                            Alaska Arctic Floodplain Forest   Tree
#> 4  4403                Alaska Arctic Large River Floodplain Forest   Tree
#> 5  4404                        Alaska Arctic Mesic Alder Shrubland  Shrub
#> 6  4405 Alaska Arctic Permafrost Plateau Dwarf-Shrub Lichen Tundra  Shrub
#>    EVT_PHYS   R   G   B      RED    GREEN     BLUE
#> 1      <NA> 255 255 255 1.000000 1.000000 1.000000
#> 2 Shrubland 255 205 112 1.000000 0.803922 0.439216
#> 3  Riparian  18  76 135 0.070588 0.298039 0.529412
#> 4  Riparian  18  76 135 0.070588 0.298039 0.529412
#> 5 Shrubland 146 237 224 0.572549 0.929412 0.878431
#> 6 Shrubland 255  37  13 1.000000 0.145098 0.050980

# keep just the R, G, B fields (0-255) and drop RED, GREEN, BLUE
evt_df <- evt_df[,1:7]

# build a RAT for the EVT raster, attaching additional columns from evt_df
tbl <- buildRAT(ds,
                table_type = "thematic",
                na_value = -9999,
                join_df = evt_df)
#> Scanning raster...
#> 0...10...20...30...40...50...60...70...80...90...100 - done.

nrow(tbl)
#> [1] 24
head(tbl)
#>   VALUE COUNT                                                          EVT_NAME
#> 1 -9999   876                                                       Fill-NoData
#> 2  7011    28                          Rocky Mountain Aspen Forest and Woodland
#> 3  7046  4564           Northern Rocky Mountain Subalpine Woodland and Parkland
#> 4  7050   570                              Rocky Mountain Lodgepole Pine Forest
#> 5  7055   889 Rocky Mountain Subalpine Dry-Mesic Spruce-Fir Forest and Woodland
#> 6  7056   304 Rocky Mountain Subalpine Mesic-Wet Spruce-Fir Forest and Woodland
#>   EVT_LF EVT_PHYS   R   G   B
#> 1   <NA>     <NA> 255 255 255
#> 2   Tree Hardwood 192 255 138
#> 3   Tree  Conifer 191 255 233
#> 4   Tree  Conifer 163 240 219
#> 5   Tree  Conifer 236 252 204
#> 6   Tree  Conifer 236 252 204

# attributes on the returned data frame and its columns define RAT metadata
attributes(tbl)
#> $names
#> [1] "VALUE"    "COUNT"    "EVT_NAME" "EVT_LF"   "EVT_PHYS" "R"        "G"       
#> [8] "B"       
#> 
#> $row.names
#>  [1]  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
#> 
#> $class
#> [1] "data.frame"
#> 
#> $GDALRATTableType
#> [1] "thematic"
attributes(tbl$VALUE)     # GFU_MinMax for column of discrete pixel values
#> $GFU
#> [1] "MinMax"
attributes(tbl$COUNT)
#> $GFU
#> [1] "PixelCount"
attributes(tbl$EVT_NAME)  # the class names
#> $GFU
#> [1] "Name"
attributes(tbl$EVT_LF)
#> $GFU
#> [1] "Generic"
attributes(tbl$EVT_PHYS)
#> $GFU
#> [1] "Generic"
attributes(tbl$R)
#> $GFU
#> [1] "Red"
attributes(tbl$G)
#> $GFU
#> [1] "Green"
attributes(tbl$B)
#> $GFU
#> [1] "Blue"

# set as default RAT on the EVT raster
ds$setDefaultRAT(band=1, tbl)
#> [1] TRUE
ds$flushCache()

tbl2 <- ds$getDefaultRAT(band=1)
nrow(tbl2)
#> [1] 24
head(tbl2)
#>   VALUE COUNT                                                          EVT_NAME
#> 1 -9999   876                                                       Fill-NoData
#> 2  7011    28                          Rocky Mountain Aspen Forest and Woodland
#> 3  7046  4564           Northern Rocky Mountain Subalpine Woodland and Parkland
#> 4  7050   570                              Rocky Mountain Lodgepole Pine Forest
#> 5  7055   889 Rocky Mountain Subalpine Dry-Mesic Spruce-Fir Forest and Woodland
#> 6  7056   304 Rocky Mountain Subalpine Mesic-Wet Spruce-Fir Forest and Woodland
#>   EVT_LF EVT_PHYS   R   G   B
#> 1     NA       NA 255 255 255
#> 2   Tree Hardwood 192 255 138
#> 3   Tree  Conifer 191 255 233
#> 4   Tree  Conifer 163 240 219
#> 5   Tree  Conifer 236 252 204
#> 6   Tree  Conifer 236 252 204

ds$close()

Display attribute tables

The function displayRAT() generates a presentation table. Colors are shown if the RAT contains RGB columns:

displayRAT(tbl, title = "Raster Attribute Table for Storm Lake EVT")
Raster Attribute Table for Storm Lake EVT
Color VALUE COUNT EVT_NAME EVT_LF EVT_PHYS R G B
#FFFFFF -9999 876 Fill-NoData NA NA 255 255 255
#C0FF8A 7011 28 Rocky Mountain Aspen Forest and Woodland Tree Hardwood 192 255 138
#BFFFE9 7046 4564 Northern Rocky Mountain Subalpine Woodland and Parkland Tree Conifer 191 255 233
#A3F0DB 7050 570 Rocky Mountain Lodgepole Pine Forest Tree Conifer 163 240 219
#ECFCCC 7055 889 Rocky Mountain Subalpine Dry-Mesic Spruce-Fir Forest and Woodland Tree Conifer 236 252 204
#ECFCCC 7056 304 Rocky Mountain Subalpine Mesic-Wet Spruce-Fir Forest and Woodland Tree Conifer 236 252 204
#3FFF2E 7057 11 Rocky Mountain Subalpine-Montane Limber-Bristlecone Pine Woodland Tree Conifer 63 255 46
#AB916A 7070 267 Rocky Mountain Alpine Dwarf-Shrubland Shrub Shrubland 171 145 106
#75573D 7106 3 Northern Rocky Mountain Montane-Foothill Deciduous Shrubland Shrub Shrubland 117 87 61
#E69729 7125 1 Inter-Mountain Basins Big Sagebrush Steppe Shrub Shrubland 230 151 41
#DB8C25 7126 1082 Inter-Mountain Basins Montane Sagebrush Steppe Shrub Shrubland 219 140 37
#FFB861 7140 679 Northern Rocky Mountain Subalpine-Upper Montane Grassland Herb Grassland 255 184 97
#AB916A 7143 199 Rocky Mountain Alpine Fell-Field Herb Grassland 171 145 106
#AB916A 7144 765 Rocky Mountain Alpine Turf Herb Grassland 171 145 106
#FFA352 7145 681 Rocky Mountain Subalpine-Montane Mesic Meadow Herb Grassland 255 163 82
#003300 7166 32 Middle Rocky Mountain Montane Douglas-fir Forest and Woodland Tree Conifer 0 51 0
#806145 7169 60 Northern Rocky Mountain Subalpine Deciduous Shrubland Shrub Shrubland 128 97 69
#0000FF 7292 397 Open Water Water Open Water 0 0 255
#AA66CD 7901 2 Western Cool Temperate Urban Evergreen Forest Tree Developed 170 102 205
#646464 9016 2486 Rocky Mountain Alpine Bedrock and Scree Sparse Sparsely Vegetated 100 100 100
#B86018 9017 13 Rocky Mountain Alpine-Montane Wet Meadow Herb Riparian 184 96 24
#646464 9018 1280 Rocky Mountain Cliff Canyon and Massive Bedrock Sparse Sparsely Vegetated 100 100 100
#B86018 9021 14 Rocky Mountain Subalpine-Montane Riparian Shrubland Shrub Riparian 184 96 24
#B86018 9022 98 Rocky Mountain Subalpine-Montane Riparian Woodland Tree Riparian 184 96 24

displayRAT() returns an object of class "gt_tbl". The table object could be modified using functions of the gt package.

Using in QGIS

QGIS since 3.30 includes extensive support for Raster Attribute Tables.

For QGIS < 3.30, the Raster Attribute Table Plugin can be used to edit and display RATs for discrete rasters using the paletted/unique-values renderer (QGIS-style classification on arbitrary RAT columns). With the plugin enabled, “Open Attribute Table” can be selected after right-clicking a raster layer that has an associated RAT. For the LANDFIRE EVT layer as modified above, classifying on EVT_NAME generates the following display:

LANDFIRE EVT in the Raster Attribute Table QGIS Plugin

LANDFIRE EVT in the Raster Attribute Table QGIS Plugin

See also

Data sources

The example dataset is Existing Vegetation Type (EVT) from the LANDFIRE Program (LF 2020 version, https://landfire.gov/). Map units are based on NatureServe Ecological Systems.