plot_raster {gdalraster}

Display raster data

Description

plot_raster() displays raster data using base graphics.

Usage

plot_raster(
  data,
  xsize = NULL,
  ysize = NULL,
  nbands = 1,
  max_pixels = 2.5e+07,
  col_tbl = NULL,
  maxColorValue = 1,
  normalize = TRUE,
  minmax_def = NULL,
  minmax_pct_cut = NULL,
  col_map_fn = NULL,
  xlim = NULL,
  ylim = NULL,
  interpolate = TRUE,
  asp = 1,
  axes = TRUE,
  main = "",
  xlab = "x",
  ylab = "y",
  xaxs = "i",
  yaxs = "i",
  legend = FALSE,
  digits = 2,
  na_col = rgb(0, 0, 0, 0),
  ...
)

Arguments

data

Either a GDALRaster object from which data will be read, or a numeric vector of pixel values arranged in left to right, top to bottom order, or a list of band vectors. If input is vector or list, the information in attribute gis will be used if present (see read_ds()), potentially ignoring values below for xsize, ysize, nbands.

xsize

The number of pixels along the x dimension in data. If data is a GDALRaster object, specifies the size at which the raster will be read (used for argument out_xsize in GDALRaster$read()). By default, the entire raster will be read at full resolution.

ysize

The number of pixels along the y dimension in data. If data is a GDALRaster object, specifies the size at which the raster will be read (used for argument out_ysize in GDALRaster$read()). By default, the entire raster will be read at full resolution.

nbands

The number of bands in data. Must be either 1 (grayscale) or 3 (RGB). For RGB, data are interleaved by band.

max_pixels

The maximum number of pixels that the function will attempt to display (per band). An error is raised if (xsize * ysize) exceeds this value. Setting to NULL turns off this check.

col_tbl

A color table as a matrix or data frame with four or five columns. Column 1 contains the numeric pixel values. Columns 2:4 contain the intensities of the red, green and blue primaries (0:1 by default, or use integer 0:255 by setting maxColorValue = 255). An optional column 5 may contain alpha transparency values, 0 for fully transparent to 1 (or maxColorValue) for opaque (the default if column 5 is missing). If data is a GDALRaster object, a built-in color table will be used automatically if one exists in the dataset.

maxColorValue

A number giving the maximum of the color values range in col_tbl (see above). The default is 1.

normalize

Logical. TRUE to rescale pixel values so that their range is ⁠[0,1]⁠, normalized to the full range of the pixel data by default (min(data), max(data), per band). Ignored if col_tbl is used. Set normalize to FALSE if a color map function is used that operates on raw pixel values (see col_map_fn below).

minmax_def

Normalize to user-defined min/max values (in terms of the pixel data, per band). For single-band grayscale, a numeric vector of length two containing min, max. For 3-band RGB, a numeric vector of length six containing b1_min, b2_min, b3_min, b1_max, b2_max, b3_max.

minmax_pct_cut

Normalize to a truncated range of the pixel data using percentile cutoffs (removes outliers). A numeric vector of length two giving the percentiles to use (e.g., c(2, 98)). Applied per band. Ignored if minmax_def is used.

col_map_fn

An optional color map function (default is grDevices::gray for single-band data or grDevices::rgb for 3-band). Ignored if col_tbl is used. Set normalize to FALSE if using a color map function that operates on raw pixel values.

xlim

Numeric vector of length two giving the x coordinate range. If data is a GDALRaster object, the default is the raster xmin, xmax in georeferenced coordinates, otherwise the default uses pixel/line coordinates (c(0, xsize)).

ylim

Numeric vector of length two giving the y coordinate range. If data is a GDALRaster object, the default is the raster ymin, ymax in georeferenced coordinates, otherwise the default uses pixel/line coordinates (c(ysize, 0)).

interpolate

Logical indicating whether to apply linear interpolation to the image when drawing (default TRUE).

asp

Numeric. The aspect ratio y/x (see ?plot.window).

axes

Logical. TRUE to draw axes (the default).

main

The main title (on top).

xlab

Title for the x axis (see ?title).

ylab

Title for the y axis (see ?title).

xaxs

The style of axis interval calculation to be used for the x axis (see ?par).

yaxs

The style of axis interval calculation to be used for the y axis (see ?par).

legend

Logical indicating whether to include a legend on the plot. Currently, legends are only supported for continuous data. A color table will be used if one is specified or the raster has a built-in color table, otherwise the value for col_map_fn will be used.

digits

The number of digits to display after the decimal point in the legend labels when raster data are floating point.

na_col

Color to use for NA as a 7- or 9-character hexadecimal code. The default is transparent ("#00000000", the return value of rgb(0,0,0,0)).

...

Other parameters to be passed to plot.default().

Note

plot_raster() uses the function graphics::rasterImage() for plotting which is not supported on some devices (see ?rasterImage).

If data is an object of class GDALRaster, then plot_raster() will attempt to read the entire raster into memory by default (unless the number of pixels per band would exceed max_pixels). A reduced resolution overview can be read by setting xsize, ysize smaller than the raster size on disk. (If data is instead specified as a vector of pixel values, a reduced resolution overview would be read by setting out_xsize and out_ysize smaller than the raster region defined by xsize, ysize in a call to GDALRaster$read()). The GDAL_RASTERIO_RESAMPLING configuration option can be defined to override the default resampling (NEAREST) to one of BILINEAR, CUBIC, CUBICSPLINE, LANCZOS, AVERAGE or MODE, for example:

set_config_option("GDAL_RASTERIO_RESAMPLING", "BILINEAR")

See Also

GDALRaster$read(), read_ds(), set_config_option()

Examples

## Elevation
elev_file <- system.file("extdata/storml_elev.tif", package="gdalraster")
ds <- new(GDALRaster, elev_file)

# grayscale
plot_raster(ds, legend=TRUE, main="Storm Lake elevation (m)")

# color ramp from user-defined palette
elev_pal <- c("#00A60E","#63C600","#E6E600","#E9BD3B",
              "#ECB176","#EFC2B3","#F2F2F2")
ramp <- scales::colour_ramp(elev_pal, alpha=FALSE)
plot_raster(ds, col_map_fn=ramp, legend=TRUE,
            main="Storm Lake elevation (m)")

ds$close()

## Landsat band combination
b4_file <- system.file("extdata/sr_b4_20200829.tif", package="gdalraster")
b5_file <- system.file("extdata/sr_b5_20200829.tif", package="gdalraster")
b6_file <- system.file("extdata/sr_b6_20200829.tif", package="gdalraster")
band_files <- c(b6_file, b5_file, b4_file)

r <- vector("integer")
for (f in band_files) {
  ds <- new(GDALRaster, f)
  dm <- ds$dim()
  r <- c(r, read_ds(ds))
  ds$close()
}

plot_raster(r, xsize=dm[1], ysize=dm[2], nbands=3,
            main="Landsat 6-5-4 (vegetative analysis)")

## LANDFIRE Existing Vegetation Cover (EVC) with color map
evc_file <- system.file("extdata/storml_evc.tif", package="gdalraster")

# colors from the CSV attribute table distributed by LANDFIRE
evc_csv <- system.file("extdata/LF20_EVC_220.csv", package="gdalraster")
vat <- read.csv(evc_csv)
head(vat)
vat <- vat[,c(1,6:8)]

ds <- new(GDALRaster, evc_file)
plot_raster(ds, col_tbl=vat, interpolate=FALSE,
            main="Storm Lake LANDFIRE EVC")

ds$close()