Package {ximage}

ximage: Draw Images of Raster Data and Related Adornments

Description

Draw images easily, set up a plot with an image, specify where that image should be placed. Image plot by default reflects the index of the image data itself, or can be specified in simple extent terms 'xmin,xmax,ymin,ymax'. Numeric matrices, integer arrays, byte arrays, character arrays, and native rasters are (or will be) supported. A combination of image() and rasterImage() from the 'graphics' package with their good features in one place.

Author(s)

Maintainer: Michael D. Sumner mdsumner@gmail.com [copyright holder]

Authors:

• Michael D. Sumner mdsumner@gmail.com [copyright holder]

Other contributors:

• Chris Toney [contributor]

See Also

Useful links:

• https://github.com/hypertidy/ximage

• Report bugs at https://github.com/hypertidy/ximage/issues

R logo as an RGB image

Description

Data obtained from png package.

Details

logo_n A matrix of colour values in native raster form.

logo_a An array of RGB colour values.

Examples

ximage(logo_n, asp = .3)
ximage(logo_a, extent = c(8, 18, 60, 80), add = TRUE)
rect(8, 60, 18, 80)

topographic elevation

Description

Data obtained from GEBCO 2019, via whatarelief package from AAD COG (GeoTIFF).

Details

A matrix of global elevation values in a smallish matrix, extent is -180,180,-90,90, crs is "OGC:CRS84".

Examples

ximage(topo, extent = c(-180, 180, -90, 90))
ximage(logo_n, extent = c(135, 155, -48, -30), add = TRUE)

Contour matrix data and draw

Description

Like contour() but to work with ximage()

Usage

xcontour(x, extent = NULL, ..., add = FALSE)

Arguments

Details

Input may be a matrix or a list from gdal_raster_data() in the vapour package or from read_ds() in the gdalraster package.

Value

nothing, called for its side effect of creating or adding to a plot

Examples

#EPSG:27200 see https://github.com/mdsumner/volcano
ex <- c(2667400, 2668010, 6478700, 6479570)
v <- volcano[nrow(volcano):1, ncol(volcano):1]
ximage(v, extent = ex, asp = 1)

xcontour(v, add = TRUE, extent = ex, col = "white")
xrect(ex, add = TRUE, border = "hotpink", lwd = 5)

Plot an image

Description

ximage combines the best of graphics::image() and graphics::rasterImage().

Usage

ximage(
  x,
  extent = NULL,
  zlim = NULL,
  add = FALSE,
  ...,
  xlab = NULL,
  ylab = NULL,
  col = hcl.colors(96, "YlOrRd", rev = TRUE),
  breaks = NULL,
  alpha = NULL,
  na.col = "transparent"
)

Arguments

Details

ximage() is a combination those graphics function with the the best features in one.

1. Allow arrays with RGB/A.

2. Allow matrix with character (named colours, or hex) or raw (Byte) values

3. Allow list output from vapour or gdalraster, a list with numeric values, hex character, or nativeRaster

4. Plot in 0,ncol 0,nrow by default

5. Override default with extent (xmin, xmax, ymin, ymax)

6. Allow general numeric values.

7. Start a plot from scratch without setting up a plot to paint to.

8. Plot by default in 0,ncol,0,nrow if unspecified.

Data orientation is "raster order", the first cell is the top-left of the displayed image, following scan lines down the page (see the package vignette on orientation).

Colour mapping via 'col', 'breaks', and 'zlim' applies to single-band numeric data only. Multi-band (grey/alpha, RGB, RGBA) data is scaled automatically: values within 0,1 are used as-is, within 0,255 are divided by 255, and anything else is rescaled by the finite range of the colour bands. Missing values (NA, NaN) display as 'na.col' in all cases.

Value

invisibly, a list with 'x' (the colour data as plotted) and 'extent' (xmin, xmax, ymin, ymax used, the 0,ncol 0,nrow index space of the input if not supplied)

Examples

ximage(volcano)
ximage(as.raster(matrix(0:1, 49, 56)))
v <- volcano
v[v > 180] <- NA
ximage(v, na.col = "hotpink")

Rectangles

Description

Draw rectangles from four colummns xmin,xmax,ymin,ymax

Usage

xrect(x, add = FALSE, ..., asp = 1L)

Arguments

Details

Calls rect(), but will instantiate a plot if add = FALSE.

Value

nothing, called for side effect of creating or adding to a plot

Examples

xrect(runif(100))
xrect(sort(runif(100)))
xrect(runif(100), col = hcl.colors(25, alpha = seq(.2, .8, length.out = 25)))

ex <- c(0.2, 0.8, .2, .6)
xrect(ex, add = TRUE, lwd = 5, lty = 2)

Label the cells of a matrix in place

Description

Draw the values of a matrix as text labels, each at the centre of its cell in the same layout used by ximage(). The first cell of the matrix is the top-left label, and each row of the matrix is a line of labels reading left to right down the page ("raster order").

Usage

xtext(x, extent = NULL, add = FALSE, cex = NULL, fit = 0.9, ...)

Arguments

Details

Text size is chosen automatically to fit the largest label within a cell, scaled by 'fit' (use 'cex' to override). Labels that are NA are not drawn.

Input may be a matrix (values are used as labels via format()), or a list in the style of vapour or gdalraster reader output (a row-major vector with 'dimension'/'extent' attributes, or a 'gis' attribute).

Value

invisibly, a list with 'x', 'y' (label positions), 'labels', and 'cex' as used

Examples

m <- matrix(1:12, 3, byrow = TRUE)
ximage(m)
xtext(m, add = TRUE)

## the label positions are cell centres in the extent
ximage(volcano, extent = c(0, 1, 0, 1))
xtext(volcano[seq(1, 87, by = 8), seq(1, 61, by = 6)],
      extent = c(0, 1, 0, 1), add = TRUE, col = "white")