oblicuboidsGrob {oblicubes}

Render 2D/3D cuboids via an oblique projection

Description

oblicuboidsGrob() / grid.oblicuboids() renders cuboids using a 3D oblique projection. oblicuboidsGrob() returns a grid grob object while grid.oblicuboids() also draws the grob to the graphic device. As a special case may also render a 2D primary view orthographic projection.

Usage

oblicuboidsGrob(
  x,
  y = NULL,
  z = NULL,
  ...,
  fill = NULL,
  light = darken_face,
  scale = 0.5,
  angle = 45,
  xo = NULL,
  yo = NULL,
  width = NULL,
  default.units = "snpc",
  name = NULL,
  gp = gpar(),
  vp = NULL
)

grid.oblicuboids(
  x,
  y = NULL,
  z = NULL,
  ...,
  fill = NULL,
  scale = 0.5,
  angle = 45,
  xo = NULL,
  yo = NULL,
  width = NULL,
  default.units = "snpc",
  name = NULL,
  gp = gpar(),
  vp = NULL
)

Arguments

x

Integer vector of x coordinates (if necessary will be rounded to integers). May be a data.frame of x,y,z coordinates (and maybe fill color). This will be the x-value at the center of the cuboid.

y

Integer vector of y coordinates (if necessary will be rounded to integers). If NULL and x is a data frame with a y column then we use that instead. This will be the x-value at the center of the cuboid.

z

Integer vector of z coordinates (if necessary will be rounded to integers). If NULL and x is a data frame with a z column then we use that instead. This will be the z-value at the top of the cuboid.

...

Passed to grid::gpar(). Will override any values set in gp.

fill

Fill color(s) for the cuboids. If NULL and x is a data frame with a fill or col column then we use that column; if no such column but gp has a fill value we use that; otherwise we fall back to "grey90".

light

If FALSE don't perform a "light" effect. Otherwise a function that takes two arguments: the first face of the cube/cuboid face (one of "top", "west", "east", "south", "north"). the second col of the fill color. By default we use darken_face().

scale

Oblique projection foreshortening factor. 0.5 corresponds to the “cabinet projection”. 1.0 corresponds to the “cavalier projection”. 0.0 corresponds to a “primary view orthographic projection”.

angle

Oblique projection angle.

xo, yo

The origin of the oblique projection coordinate system in grid units. The default is to try to guess a “good” value.

width

Width of the cuboids's (non-foreshortened) side. The default will be to try to guess a “good” value.

default.units

Default units for the xo, yo, and width arguments.

name

A character identifier (for grid).

gp

A ‘grid’ gpar object. See grid::gpar(). Will be merged with the values in ... and the value of fill.

vp

A ‘grid’ viewport object. See grid::viewport().

Value

A grid grob. As a side effect grid.oblicubes() also draws to the active graphics device.

Examples

if (require("grid")) {
  # we support arbitrary oblique projection angles
  mat <- matrix(c(1, 2, 1, 2, 3, 2, 1, 2, 1), nrow = 3, ncol = 3, byrow = TRUE)
  coords <- xyz_heightmap(mat, col = c("red", "yellow", "green"),
                          solid = FALSE)
  angles <- c(135, 90, 45, 180, 45, 0, -135, -90, -45)
  scales <- c(0.5, 0.5, 0.5, 0.5, 0.0, 0.5, 0.5, 0.5, 0.5)
  vp_x <- rep(1:3/3 - 1/6, 3)
  vp_y <- rep(3:1/3 - 1/6, each = 3)
  grid.newpage()
  for (i in 1:9) {
      pushViewport(viewport(x=vp_x[i], y=vp_y[i], width=1/3, height=1/3))
      grid.rect(gp = gpar(lty = "dashed"))
      grid.oblicuboids(coords, width = 0.15, xo = 0.25, yo = 0.15,
                     angle = angles[i], scale = scales[i],
                     gp = gpar(lwd=4))
      if(i != 5)
          grid.text(paste("angle =", angles[i]), y=0.92, gp = gpar(cex = 1.2))
      else
          grid.text(paste("scale = 0"), y=0.92, gp = gpar(cex = 1.2))
      popViewport()
  }
}
# volcano example
mat <- datasets::volcano
mat <- 0.3 * (mat - min(mat)) + 1.0
coords <- xyz_heightmap(mat, col = grDevices::terrain.colors,
                        solid = FALSE)
grid::grid.newpage()
grid.oblicuboids(coords)