Render image of game pieces

render_piece() renders an image of game pieces to a file or graphics device. It is a wrapper around pmap_piece() that can auto-size files and graphic devices, apply axes offsets, annotate coordinates, and set up rayrender / rayvertex scenes.

Usage

render_piece(
  df,
  file = NULL,
  ...,
  .f = piecepackr::grid.piece,
  cfg = getOption("piecepackr.cfg", NULL),
  envir = getOption("piecepackr.envir", game_systems("sans")),
  width = NULL,
  height = NULL,
  ppi = 72,
  bg = "white",
  xoffset = NULL,
  yoffset = NULL,
  annotate = FALSE,
  annotation_scale = NULL,
  dev = NULL,
  dev.args = list(res = ppi, bg = bg, units = "in"),
  open_device = TRUE,
  close_device = open_device && (!is.null(file) || !is.null(dev)),
  image = c("NULL", "raster", "nativeRaster"),
  xbreaks = NULL,
  ybreaks = NULL
)

Arguments

df

A data frame of game piece information with (at least) the named columns “piece_side”, “x”, and “y”.

file

Filename to save image to unless NULL in which case it either uses the current graphics device or opens a new device (depending on open_device argument).

...

Arguments to pmap_piece()

.f

Low level graphics function to use e.g. grid.piece(), piece3d(), piece_mesh(), or piece().

cfg

A piecepackr configuration list

envir

Environment (or named list) of piecepackr configuration lists

width

Width of image (in inches). Inferred by default.

height

Height of image (in inches). Inferred by default.

ppi

Resolution of image in pixels per inch.

bg

Background color (use "transparent" for transparent)

xoffset

Number to add to the x column in df. Inferred by default.

yoffset

Number to add to the y column in df. Inferred by default.

annotate

If TRUE or "algebraic" annotate the plot with “algrebraic” coordinates, if FALSE or "none" don't annotate, if "cartesian" annotate the plot with “cartesian” coordinates.

annotation_scale

Multiplicative factor that scales (stretches) any annotation coordinates. By default uses attr(df, "scale_factor") %||% 1.

dev

Graphics device function to use if open_device is FALSE. If NULL infer a reasonable choice from file.

dev.args

Additional arguments to pass to dev (besides filename, width, and height). Will filter out any names that aren't in formals(dev).

open_device

If TRUE open a new graphics device otherwise draw in the active graphics.

close_device

If TRUE close the graphics device (if open_device = TRUE close the newly opened device otherwise close the previously existing graphics device).

image

Class of image object to return in the "image" field of returned list. If "NULL" (the default) return NULL. If "raster" or "nativeRaster" try to return a raster object of the image using [grDevices::dev.capture()] or as.raster(magick::image_read())`.

xbreaks, ybreaks

Subset (of integers) to provide axis labels for if annotate is TRUE. If NULL infer a reasonable choice.

Value

An invisible list of the dimensions of the image and possibly an image object specified by image. As a side effect may save a file and/or open/close a graphics device.

See also

This function is a wrapper around pmap_piece().

Examples

 df_board <- data.frame(piece_side = "board_face", suit = 3, rank = 5,
                        x = 3.0, y = 3.0, stringsAsFactors = FALSE)
 df_w <- data.frame(piece_side = "bit_back", suit = 6, rank = 1,
                    x = rep(1:5, 2), y = rep(1:2, each=5),
                    stringsAsFactors = FALSE)
 df_b <- data.frame(piece_side = "bit_back", suit = 1, rank = 1,
                    x = rep(1:5, 2), y = rep(4:5, each=5),
                    stringsAsFactors = FALSE)
 df <- rbind(df_board, df_w, df_b)
 df$cfg <- "checkers1"

 if (requireNamespace("grid", quietly = TRUE)) {
   render_piece(df, open_device = FALSE)
 }

 if (requireNamespace("grid", quietly = TRUE)) {
   grid::grid.newpage()
   render_piece(df, open_device = FALSE,
                op_scale = 0.5, trans = op_transform,
                annotate = "algrebraic")
 }

 if (FALSE) # May take more than 5 seconds on CRAN servers
 if (require(rayvertex)) {
   envir3d <- game_systems("sans", border = FALSE)
   render_piece(df, .f = piece_mesh, envir = envir3d,
                open_device = FALSE,
                op_scale = 0.5, trans = op_transform)
 }
  # \dontrun{}