render_piece: Render image of game pieces

In trevorld/piecepack: Board Game Graphics

Render image of game pieces

Description

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 = new_device,
  close_device = open_device && (!is.null(file) || !is.null(dev)),
  image = c("NULL", "raster", "nativeRaster"),
  xbreaks = NULL,
  ybreaks = NULL,
  new_device = TRUE
)

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.
new_device	If FALSE draw in the active graphics device instead of opening a new graphics device. This argument is deprecated. Use the open_device argument instead.

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")
 }
 ## Not run: # May take more than 5 seconds on CRAN servers
 if (require(rayvertex)) {
   envir3d <- game_systems("sans3d")
   render_piece(df, .f = piece_mesh, envir = envir3d,
                open_device = FALSE,
                op_scale = 0.5, trans = op_transform)
 }
 
## End(Not run)

trevorld/piecepack documentation built on March 29, 2025, 4:33 p.m.