Package 'ximage'

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

x	something we can contour
extent	optional, numeric xmin,xmax,ymin,ymax
...	Arguments passed on to ximage zlim optional, absolute range of data to map colours to (maintains comparable colours across plots); values outside display as 'na.col'; single-band numeric data only xlab x axis label, empty by default ylab y axis label, empty by default col colours to map single-band data to breaks a set of finite numeric breakpoints for the colours, one more break than colour (if not, colours are interpolated to fit) alpha optional constant opacity in ⁠[0, 1]⁠ (or vector/matrix, recycled) applied on top of any existing alpha channel; not supported for nativeRaster input na.col colour for missing values, default "transparent" force proceed with a guessed dimension for very long bare vectors (see Details), default FALSE
add	add to plot, or start afresh

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

## S3 method for class 'raw'
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",
  force = FALSE
)

## S3 method for class 'numeric'
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",
  force = FALSE
)

## S3 method for class 'integer'
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",
  force = FALSE
)

## S3 method for class 'character'
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",
  force = FALSE
)

Arguments

x	matrix, array, raw or character matrix, native raster (nativeRaster, or raster), or list as output by GDAL reader functions
extent	optional, numeric xmin,xmax,ymin,ymax
zlim	optional, absolute range of data to map colours to (maintains comparable colours across plots); values outside display as 'na.col'; single-band numeric data only
add	add to plot, or start afresh
...	passed to plot when add = FALSE
xlab	x axis label, empty by default
ylab	y axis label, empty by default
col	colours to map single-band data to
breaks	a set of finite numeric breakpoints for the colours, one more break than colour (if not, colours are interpolated to fit)
alpha	optional constant opacity in ⁠[0, 1]⁠ (or vector/matrix, recycled) applied on top of any existing alpha channel; not supported for nativeRaster input
na.col	colour for missing values, default "transparent"
force	proceed with a guessed dimension for very long bare vectors (see Details), default FALSE

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

Bare atomic vectors (no dim, no 'gis' attribute from gdalraster, no width/height/depth attributes) are accepted and a dimension is guessed by integer-division detection of the vector length. The most nearly square factorization is chosen (preferring landscape, ncol >= nrow) and the data is assumed to be in raster scanline order, i.e. flat output from GDAL readers such as vapour::gdal_raster_data() or gdalraster::read_ds(), built as matrix(x, ncol = NC, byrow = TRUE); column-major R data needs dim(x) <- c(NR, NC) instead. A message reports the guess and the candidate factorizations from 1xN through Nx1, in GDAL dimension order (ncol x nrow, xsize x ysize). Raw vectors also consider 3-plane (RGB) and 4-plane (RGBA) scanline pixel-interleaved interpretations; numeric data never gets a plane interpretation (whole numbers in 0..255 are too common as ordinary data to imply an image, a much narrower opt-in detection may come later). For very long vectors (more than getOption("ximage.guess_max", 2^24) elements) the guess stops with an error unless force = TRUE, or set the dimension explicitly.

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

## bare vectors in GDAL scanline order get a guessed dimension, with a
## message listing candidate shapes (ncol x nrow); here the guess 87x61
## is the mirror of the true 61x87, so pick from the candidates
ximage(as.vector(t(volcano)))
ximage(matrix(as.vector(t(volcano)), ncol = 61, byrow = TRUE))

---

Rectangles

Description

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

Usage

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

Arguments

x	four columns worth of rectangles
add	instantiate a plot or add to existing (default is add = FALSE)
...	arguments passed to rect()
asp	aspect ratio, defaults to 1

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

x	a matrix of values to draw as labels, or a reader-output list
extent	optional, numeric xmin,xmax,ymin,ymax (defaults to the 0,ncol 0,nrow index space of the matrix)
add	add to plot, or start afresh
cex	text size, computed to fit the cells if not supplied
fit	fraction of the cell the largest label should occupy when 'cex' is computed, default 0.9
...	arguments passed to text(), for example 'col'

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

---