The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Type: Package
Title: Graphical Output in Terminals
Version: 0.1.1
Description: Defines a graphics device and functions for graphical output in terminal emulators that support graphical output. Currently terminals that support the Terminal Graphics Protocol (https://sw.kovidgoyal.net/kitty/graphics-protocol/) and terminal supporting Sixel (https://en.wikipedia.org/wiki/Sixel) are supported.
BugReports: https://codeberg.org/djvanderlaan/terminalgraphics/issues
URL: https://codeberg.org/djvanderlaan/terminalgraphics
Depends: R (≥ 4.1.0)
Imports: Rcpp, utils, graphics, grDevices, ragg, base64enc
Suggests: magick
LinkingTo: Rcpp
License: GPL-3
SystemRequirements: A terminal emulator supporting the Terminal Graphics Protocol (<https://sw.kovidgoyal.net/kitty/graphics-protocol/>) or Sixel.
LazyLoad: yes
Encoding: UTF-8
RoxygenNote: 7.3.2
NeedsCompilation: yes
Packaged: 2025-08-22 20:54:32 UTC; eoos
Author: Jan van der Laan ORCID iD [aut, cre]
Maintainer: Jan van der Laan <r@eoos.dds.nl>
Repository: CRAN
Date/Publication: 2025-08-28 07:40:02 UTC

Determine if terminal supports Sixel

Description

Determine if terminal supports Sixel

Usage

has_sixel_support(warn = FALSE, throw = FALSE)

Arguments

warn

show warnings when the protocol is not supported.

throw

throw an error when we are running in a kitty terminal.

Value

Returns TRUE if the current terminal supports the Sixel and FALSE otherwise. Will also return FALSE when not running in a terminal.

Examples

if (has_sixel_support()) {
  cat("Yeeh, your terminal supports the sixel!")
}

Determine if terminal supports Terminal Graphics Protocol

Description

Determine if terminal supports Terminal Graphics Protocol

Usage

has_tgp_support(warn = FALSE, throw = FALSE)

Arguments

warn

show warnings when the protocol is not supported.

throw

throw an error when we are running in a kitty terminal.

Value

Returns TRUE if the current terminal supports the Terminal Graphics Protocol and FALSE otherwise. Will also return FALSE when not running in a terminal.

Examples

if (has_tgp_support()) {
  cat("Yeeh, your terminal supports the terminal graphics protocol!")
}

Determine if we are running in a kitty terminal

Description

Determine if we are running in a kitty terminal

Usage

is_kitty()

Value

Returns TRUE if R is running in a kitty terminal and FALSE otherwise.

Examples

if (is_kitty()) {
  cat("Yeeh, you are running kitty!")
}

Get the colors used in the kitty terminal

Description

Get the colors used in the kitty terminal

Usage

kitty_colors()

kitty_background()

kitty_foreground()

kitty_palette()

Details

To get the background and foreground colors, kitten query-terminal is called. To get all colors and the palette kitty @get-colors is called using system. However, for the last to work allow_remote_control needs to be set to true in the config file for kitty.

Value

kitty_colors returns a data.frame with the colors from the theme used by kitty. kitty_background returns the background color (character vector with the hex-code). kitty_foreground returns the foreground color. kitty_palette returns a vector with the 9 main accent colors from the theme.

See Also

term_background, term_foreground, term_palette for functions that try to return the colors used in any terminal. When running in kitty, these will call kitty_background etc.

Examples

if (is_kitty()) {
  cat("The background color is '", kitty_background(), "'.")
}

Dump a PNG image to the terminal in Sixel format

Description

Dump a PNG image to the terminal in Sixel format

Usage

png2sixel(filename)

Arguments

filename

filename of the PNG image

Value

Called for it's side effect of writing the image to the terminal (standard out). Returns NULL invisibly.

Dump a PNG image to the terminal

Description

Dump a PNG image to the terminal

Usage

png2terminal(filename, method = c("auto", "tgp", "sixel"))

Arguments

filename

filename of the PNG image

method

method with which the graphical output is written to the terminal. In case of 'auto', it is first checked if the Terminal Graphics Protocol is supported and if so, this is used. Otherwise, Sixel is used.

Value

Called for it's side effect of writing the image to the terminal (standard out). Returns NULL invisibly.

See Also

See png2tgp for output in Terminal Graphics Protocol. See png2sixel for output in Sixel format.

Dump a PNG image to the terminal using the Terminal Graphics Protocol

Description

Dump a PNG image to the terminal using the Terminal Graphics Protocol

Usage

png2tgp(filename)

Arguments

filename

filename of the PNG image

Details

The Terminal Graphics Protocol is not supported by many Terminal Emulators. The most notable terminal emulator supporting the protocol is Kitty.

Value

Called for it's side effect of writing the image to the terminal (standard out). Returns NULL invisibly.

Dump an image raster to the terminal in Sixel format

Description

Dump an image raster to the terminal in Sixel format

Usage

raster2sixel(raster)

Arguments

raster

the image 'raster' e.g. the output of as.raster.

Details

Sixel is a bitmap format supported by some terminals. See, for example, https://en.wikipedia.org/wiki/Sixel.

Value

Called for it's side effect of writing the image to the terminal (standard out). Returns NULL invisibly.

See Also

See raster2tgp for output using Terminal Graphics Protocol.

Dump an image raster to the terminal

Description

Dump an image raster to the terminal

Usage

raster2terminal(raster, method = c("auto", "tgp", "sixel"), ...)

Arguments

raster

the image 'raster' e.g. the output of as.raster.

method

method with which the graphical output is written to the terminal. In case of 'auto', it is first checked if the Terminal Graphics Protocol is supported and if so, this is used. Otherwise, Sixel is used.

...

passed on to the underlying method such as raster2tgp and raster2sixel.

Value

Called for it's side effect of writing the image to the terminal (standard out). Returns NULL invisibly.

See Also

See raster2tgp for output in Terminal Graphics Protocol. See raster2sixel for output in Sixel format.

Dump an image raster to the terminal using the Terminal Graphics Protocol

Description

Dump an image raster to the terminal using the Terminal Graphics Protocol

Usage

raster2tgp(raster, compress = TRUE)

Arguments

raster

the image 'raster' e.g. the output of as.raster.

compress

compress the data before sending to the terminal.

Details

The Terminal Graphics Protocol is not supported by many Terminal Emulators. The most notable terminal emulator supporting the protocol is Kitty.

Value

Called for it's side effect of writing the image to the terminal (standard out). Returns NULL invisibly.

See Also

See raster2sixel for output in Sixel format. See png2terminal for writing a PNG image to the terminal.

Terminal Graphics Protocol Device

Description

Terminal Graphics Protocol Device

Usage

sixel(
  width = getOption("term_width", max(480, min(1200, term_width(), term_height()/0.8))),
  height = getOption("term_height", 0.8 * width),
  units = "px",
  res = getOption("term_res", NA),
  ...,
  term_col = getOption("term_col", FALSE),
  term_bg = term_col,
  term_fg = term_col
)

Arguments

width

The width of the image. Passed on to agg_capture.

height

The height of the image. Passed on to agg_capture.

units

The units in which 'height' and 'width' are given. Passed on to agg_capture.

res

The resulution of the image. Passed on to agg_capture.

...

passed on to the underlying agg_capture device.

term_col

Logical value indicating that the foreground and background colors used in the plot should be set to that of the terminal.

term_bg

Logical value indicating that the background color used in the plot should be set to that of the terminal.

term_fg

Logical value indicating that the foreground color used in the plot should be set to that of the terminal.

Details

The function tries to detect whether the terminal supports Sixel. If not, it will issue a warning but still output the image to the terminal. Terminals that to not support Sixel will ignore the output. The warning is shown only once. Please file an issue when the terminal does support Sixel while has_sixel_support returns FALSE. The warning can be disabled using options(warned_sixel_support = TRUE).

Value

sixel is called for its side effect of opening a graphics device. Invisibly returns an list with two functions: plot will plot the current contents of the device in the terminal and update will plot the current contents of the device in the terminal if the contents have changed since the last plot.

term_replot will redraw the content of the device in the terminal. In principle term_replot is called automatically when the contents of the device changed. This function can be used to force plotting.

When term_bg = TRUE the background color of the graphics device ('bg') will be set using par. When term_fg = TRUE the foreground color ('fg', 'col', 'col.axis', 'col.lab', 'col.main', and 'sub') will be set using par.

Examples


if (has_sixel_support()) {
  sixel()
  plot(rnorm(100))
  abline(h = 0, lwd = 2, col = term_palette()[1])
}

Get the colors used in the terminal

Description

Get the colors used in the terminal

Usage

term_background()

term_foreground()

term_palette()

Details

Getting the color palette used in the terminal is terminal specific. Currently only the kitty terminal is supported. For other terminals default colors are returned.

Value

term_background and term_foreground will return a length 1 vector with a color. term_palette will return a vector of colors.

See Also

kitty_colors for the functions returning the specific colors used in the kitty terminal.

Examples

term_background()

Get the dimensions of the terminal window in pixels

Description

Get the dimensions of the terminal window in pixels

Usage

term_dim()

Value

An integer vector with the width and height of the terminal in pixels (x_pixels and y_pixels) and the number of text columns and rows in the terminal window (columns and rows).

These values can be zero when the terminal does not support querying the size. Some terminals only support querying the number of columns and rows. Under windows the return value will always be zero as querying the size depends on POSIX support.

See Also

term_width and term_height for only obtaining the width and height in pixels respectively.

Get the height of the terminal window in pixels

Description

Get the height of the terminal window in pixels

Usage

term_height()

Value

An integer with the number of pixels the terminal is high. This value can be zero when the terminal does not support querying the size.

See Also

term_width for the terminal width and term_dim for all dimensions including the dimensions in rows and columns.

Replot the current device in the terminal.

Description

Replot the current device in the terminal.

Usage

term_replot()

Value

Called for outputting the current contents of a sixel or tgp device into the terminal.

Get the with of the terminal window in pixels

Description

Get the with of the terminal window in pixels

Usage

term_width()

Value

An integer with the number of pixels the terminal is wide This value can be zero when the terminal does not support querying the size. Under windows the return value will always be zero as querying the size depends on POSIX support.

See Also

term_height for the terminal height and term_dim for all dimensions including the dimensions in rows and columns.

Terminal Graphics Protocol Device

Description

Terminal Graphics Protocol Device

Usage

tgp(
  width = getOption("term_width", max(480, min(1200, term_width(), term_height()/0.8))),
  height = getOption("term_height", 0.8 * width),
  units = "px",
  res = getOption("term_res", NA),
  ...,
  term_col = getOption("term_col", FALSE),
  term_bg = term_col,
  term_fg = term_col
)

Arguments

width

The width of the image. Passed on to agg_capture.

height

The height of the image. Passed on to agg_capture.

units

The units in which 'height' and 'width' are given. Passed on to agg_capture.

res

The resolution of the image. Passed on to agg_capture.

...

passed on to the underlying agg_capture device.

term_col

Logical value indicating that the foreground and background colors used in the plot should be set to that of the terminal.

term_bg

Logical value indicating that the background color used in the plot should be set to that of the terminal.

term_fg

Logical value indicating that the foreground color used in the plot should be set to that of the terminal.

Details

The function tries to detect whether the terminal supports Terminal Graphics Protocol. If not, it will issue a warning but still output the image to the terminal. Terminals that to not support Terminal Graphics Protocol will ignore the output. The warning is shown only once. Please file an issue when the terminal does support Terminal Graphics Protocol while has_tgp_support returns FALSE. The warning can be disabled using options(warned_tgp_support = TRUE).

Value

tgp is called for its side effect of opening a graphics device. Invisibly returns an list with two functions: plot will plot the current contents of the device in the terminal and update will plot the current contents of the device in the terminal if the contents have changed since the last plot.

term_replot will redraw the content of the device in the terminal. In principle term_replot is called automatically when the contents of the device changed. This function can be used to force plotting.

When term_bg = TRUE the background color of the graphics device ('bg') will be set using par. When term_fg = TRUE the foreground color ('fg', 'col', 'col.axis', 'col.lab', 'col.main', and 'sub') will be set using par.

Examples

if (has_tgp_support()) {
  # Open device
  tgp()
  plot(rnorm(100))
  abline(h = 0, lwd = 2, col = term_palette()[1])
}

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.