Type: Package
Title: Universal Graphics Device
Version: 0.1.3
Description: A unified R graphics backend. Render R graphics fast and easy to many common file formats. Provides a thread safe 'C' interface for asynchronous rendering of R graphics.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Depends: R (≥ 3.2.0)
Imports: systemfonts (≥ 1.0.0)
LinkingTo: cpp11 (≥ 0.2.4), systemfonts
Encoding: UTF-8
SystemRequirements: libpng, cairo, freetype2, fontconfig
RoxygenNote: 7.3.2
URL: https://github.com/nx10/unigd, https://nx10.github.io/unigd/
BugReports: https://github.com/nx10/unigd/issues
Suggests: testthat (≥ 3.0.0), xml2 (≥ 1.0.0), fontquiver (≥ 0.2.0), covr, knitr, rmarkdown
Config/testthat/edition: 3
Config/Needs/website: tidyverse/tidytemplate
VignetteBuilder: knitr
NeedsCompilation: yes
Packaged: 2025-02-18 23:21:43 UTC; floru
Author: Florian Rupprecht ORCID iD [aut, cre], Kun Ren [ctb], Tatsuya Shima [ctb], Jeroen Ooms ORCID iD [ctb], Hadley Wickham [cph] (Author of included svglite code), Lionel Henry [cph] (Author of included svglite code), Thomas Lin Pedersen [cph] (Author and creator of included svglite code), T Jake Luciani [cph] (Author of included svglite code), Matthieu Decorde [cph] (Author of included svglite code), Vaudor Lise [cph] (Author of included svglite code), Tony Plate [cph] (Contributor to included svglite code), David Gohel [cph] (Contributor to included svglite code), Yixuan Qiu [cph] (Contributor to included svglite code), Håkon Malmedal [cph] (Contributor to included svglite code), RStudio [cph] (Copyright holder of included svglite code), Brett Robinson [cph] (Author of included belle library), Google [cph] (Copyright holder of included material design icons), Victor Zverovich [cph] (Author of included fmt library), Andrzej Krzemienski [cph] (Author of included std::experimental::optional library)
Maintainer: Florian Rupprecht <floruppr@gmail.com>
Repository: CRAN
Date/Publication: 2025-02-19 08:20:02 UTC

unigd: Universal graphics device

Description

Universal graphics device

Author(s)

Maintainer: Florian Rupprecht floruppr@gmail.com (ORCID)

Other contributors:

See Also

Useful links:

A unified R graphics backend.

Description

This function initializes a unigd graphics device.

Usage

ugd(
  width = getOption("unigd.width", 720),
  height = getOption("unigd.height", 576),
  bg = getOption("unigd.bg", "white"),
  pointsize = getOption("unigd.pointsize", 12),
  system_fonts = getOption("unigd.system_fonts", list()),
  user_fonts = getOption("unigd.user_fonts", list()),
  reset_par = getOption("unigd.reset_par", FALSE)
)

Arguments

width

Graphics device width (pixels).

height

Graphics device height (pixels).

bg

Background color.

pointsize

Graphics device point size.

system_fonts

Named list of font names to be aliased with fonts installed on your system. If unspecified, the R default families sans, serif, mono and symbol are aliased to the family returned by systemfonts::font_info().

user_fonts

Named list of fonts to be aliased with font files provided by the user rather than fonts properly installed on the system. The aliases can be fonts from the fontquiver package, strings containing a path to a font file, or a list containing name and file elements with name indicating the font alias in the SVG output and file the path to a font file.

reset_par

If set to TRUE, global graphics parameters will be saved on device start and reset every time ugd_clear() is called (see graphics::par()).

Details

All font settings and descriptions are adopted from the excellent 'svglite' package.

Value

No return value, called to initialize graphics device.

Examples

ugd() # Initialize graphics device

# Plot something
x <- seq(0, 3 * pi, by = 0.1)
plot(x, sin(x), type = "l")

# Render plot as SVG
ugd_render(width = 600, height = 400, as = "svg")

dev.off() # alternatively: ugd_close()

Clear all unigd plot pages.

Description

This function will only work after starting a device with ugd().

Usage

ugd_clear(which = dev.cur())

Arguments

which

Which device (ID).

Value

Whether there were any pages to remove.

Examples

ugd()
plot(1, 1)
hist(rnorm(100))
ugd_clear() # Clear all previous plots
hist(rnorm(100))

dev.off()

Close unigd device.

Description

This achieves the same effect as grDevices::dev.off(), but will only close the device if it has the unigd type.

Usage

ugd_close(which = dev.cur(), all = FALSE)

Arguments

which

Which device (ID).

all

Should all running unigd devices be closed.

Value

Number and name of the new active device (after the specified device has been shut down).

Examples

ugd()
hist(rnorm(100))
ugd_close() # Equvalent to dev.off()

ugd()
ugd()
ugd()
ugd_close(all = TRUE)

Query unigd plot IDs

Description

Query unigd graphics device static plot IDs. Available plot IDs starting from index will be returned. limit specifies the number of plots. This function will only work after starting a device with ugd().

Usage

ugd_id(index = 0, limit = 1, which = dev.cur(), state = FALSE)

Arguments

index

Plot index. If this is set to 0, the last page will be selected.

limit

Limit the number of returned IDs. If this is set to a value > 1 the returned type is a list if IDs. Set to 0 for all.

which

Which device (ID).

state

Include the current device state in the returned result (see also: ugd_state()).

Value

List containing static plot IDs.

Examples

ugd() # Initialize graphics device

# Page 1
plot.new()
text(.5, .5, "#1")

# Page 2
plot.new()
text(.5, .5, "#2")

# Page 3
plot.new()
text(.5, .5, "#3")

third <- ugd_id() # Get ID of page 3 (last page)
second <- ugd_id(2) # Get ID of page 2
all <- ugd_id(1, limit = Inf) # Get all IDs

ugd_remove(1) # Remove page 1
ugd_render(second) # Render page 2

dev.off() # Close device

unigd device information.

Description

Access general information of a unigd graphics device. This function will only work after starting a device with ugd().

Usage

ugd_info(which = dev.cur())

Arguments

which

Which device (ID).

Value

List of status variables with the following named items: ⁠$id⁠: Server unique ID, ⁠$version⁠: unigd and library versions.

Examples

ugd() # Initialize graphics device
ugd_info() # Get device information
dev.off() # Close device

Remove a unigd plot page.

Description

This function will only work after starting a device with ugd().

Usage

ugd_remove(page = 0, which = dev.cur())

Arguments

page

Plot page to remove. If this is set to 0, the last page will be selected. Can be set to a numeric plot index or plot ID (see ugd_id()).

which

Which device (ID).

Value

Whether the page existed (and thereby was successfully removed).

Examples

ugd()
plot(1, 1) # page 1
hist(rnorm(100)) # page 2
ugd_remove(page = 1) # remove page 1

dev.off()

Render unigd plot and return it.

Description

See ugd_save() for saving rendered plots as files. This function will only work after starting a device with ugd().

Usage

ugd_render(
  page = 0,
  width = -1,
  height = -1,
  zoom = 1,
  as = "svg",
  which = dev.cur()
)

Arguments

page

Plot page to render. If this is set to 0, the last page will be selected. Can be set to a numeric plot index or plot ID (see ugd_id()).

width

Width of the plot. If this is set to -1, the last width will be selected.

height

Height of the plot. If this is set to -1, the last height will be selected.

zoom

Zoom level. (For example: 2 corresponds to 200%, 0.5 would be 50%.)

as

Renderer.

which

Which device (ID).

Value

Rendered plot. Text renderers return strings, binary renderers return byte arrays.

Examples

ugd()
plot(1, 1)
ugd_render(width = 600, height = 400, as = "svg")
dev.off()

Inline plot rendering.

Description

Convenience function for quick inline plot rendering. This is similar to ugd_render() but the plotting code is specified inline and an unigd graphics device is managed (created and closed) automatically. Starting a device with ugd() is therefore not necessary.

Usage

ugd_render_inline(
  code,
  page = 0,
  width = getOption("unigd.width", 720),
  height = getOption("unigd.height", 576),
  zoom = 1,
  as = "svg",
  ...
)

Arguments

code

Plotting code. See examples for more information.

page

Plot page to render. If this is set to 0, the last page will be selected. Can be set to a numeric plot index or plot ID (see ugd_id()).

width

Width of the plot.

height

Height of the plot.

zoom

Zoom level. (For example: 2 corresponds to 200%, 0.5 would be 50%.)

as

Renderer.

...

Additional parameters passed to ugd(...)

Value

Rendered plot. Text renderers return strings, binary renderers return byte arrays.

Examples

ugd_render_inline({
  hist(rnorm(100))
}, as = "svgz")

s <- ugd_render_inline({
  plot.new()
  lines(c(0.5, 1, 0.5), c(0.5, 1, 1))
})
cat(s)

unigd device renderers.

Description

Get a list of available renderers. This function will only work after starting a device with ugd().

Usage

ugd_renderers()

Value

List of renderers with the following named items: ⁠$id⁠: Renderer ID, ⁠$mime⁠: File mime type, ⁠$ext⁠: File extension, ⁠$name⁠: Human readable name, ⁠$type⁠: Renderer type (currently either plot or other), ⁠$bin⁠: Is the file a binary blob or text.

Examples


ugd_renderers()

Render unigd plot to a file.

Description

See ugd_render() for accessing plot data directly in memory without saving as a file. This function will only work after starting a device with ugd().

Usage

ugd_save(
  file,
  page = 0,
  width = -1,
  height = -1,
  zoom = 1,
  as = "auto",
  which = dev.cur()
)

Arguments

file

Filepath to save plot.

page

Plot page to render. If this is set to 0, the last page will be selected. Can be set to a numeric plot index or plot ID (see ugd_id()).

width

Width of the plot. If this is set to -1, the last width will be selected.

height

Height of the plot. If this is set to -1, the last height will be selected.

zoom

Zoom level. (For example: 2 corresponds to 200%, 0.5 would be 50%.)

as

Renderer. When set to "auto" renderer is inferred from the file extension.

which

Which device (ID).

Value

No return value. Plot will be saved to file.

Examples

ugd()

plot(1, 1)

tf <- tempfile()
on.exit(unlink(tf))

ugd_save(file = tf, width = 600, height = 400, as = "png")

dev.off()

Inline plot rendering to a file.

Description

Convenience function for quick inline plot rendering. This is similar to ugd_save() but the plotting code is specified inline and an unigd graphics device is managed (created and closed) automatically. Starting a device with ugd() is therefore not necessary.

Usage

ugd_save_inline(
  code,
  file,
  page = 0,
  width = getOption("unigd.width", 720),
  height = getOption("unigd.height", 576),
  zoom = 1,
  as = "auto",
  ...
)

Arguments

code

Plotting code. See examples for more information.

file

Filepath to save plot.

page

Plot page to render. If this is set to 0, the last page will be selected. Can be set to a numeric plot index or plot ID (see ugd_id()).

width

Width of the plot.

height

Height of the plot.

zoom

Zoom level. (For example: 2 corresponds to 200%, 0.5 would be 50%.)

as

Renderer.

...

Additional parameters passed to ugd(...)

Value

No return value. Plot will be saved to file.

Examples

tf <- tempfile(fileext=".svg")
on.exit(unlink(tf))

ugd_save_inline({
  plot.new()
  lines(c(0.5, 1, 0.5), c(0.5, 1, 1))
}, file = tf)

unigd device status.

Description

Access status information of a unigd graphics device. This function will only work after starting a device with ugd().

Usage

ugd_state(which = dev.cur())

Arguments

which

Which device (ID).

Value

List of status variables with the following named items: ⁠$hsize⁠: Plot history size (how many plots are accessible), ⁠$upid⁠: Update ID (changes when the device has received new information), ⁠$active⁠: Is the device the currently activated device.

Examples

ugd()
ugd_state()
plot(1, 1)
ugd_state()

dev.off()

Plot a test pattern that can be used to evaluate and compare graphics devices.

Description

Plot a test pattern that can be used to evaluate and compare graphics devices.

Usage

ugd_test_pattern()

Value

Nothing, but a plot is generated.

Examples

## Not run: 

ugd_test_pattern()

## End(Not run)