Skip to contents

Print pixmap objects

Source: R/print.bm_pixmap.R
print.bm_pixmap.Rd

print.bm_pixmap() prints bittermelon pixmap objects to the terminal It is a wrapper around format.bm_pixmap().

Usage

# S3 method for class 'bm_pixmap'
print(
  x,
  ...,
  bg = getOption("bittermelon.bg", FALSE),
  compress = getOption("bittermelon.compress", "none"),
  downscale = getOption("bittermelon.downscale", FALSE)
)

# S3 method for class 'bm_pixmap'
format(
  x,
  ...,
  bg = getOption("bittermelon.bg", FALSE),
  compress = getOption("bittermelon.compress", "none"),
  downscale = getOption("bittermelon.downscale", FALSE)
)

Arguments

x

A bm_pixmap() object

...

Currently ignored.

bg

R color string of background color to use and/or cli ANSI style function of class cli_ansi_style. FALSE (default) for no background color (i.e. use default terminal background).

compress

How to print the image:

  • "none" (default) or "n" use one character per pixel.

  • "vertical" or "v" use one character per two vertical pixels (makes pixels look closest to square in typical terminal).

  • "horizontal" or "h" use one character per two horizontal pixels.

  • "both" or "b" use one character per four pixels (this will be a lossy conversion whenever there are more than two colors per four pixels).

downscale

If TRUE and the printed pixmap will be wider than getOption("width") then shrink the image to fit getOption("width") using bm_downscale().

Value

A character vector of the string representation (print.bm_pixmap() does this invisibly). As a side effect print.bm_pixmap() prints out the string representation to the terminal.

Fonts and terminal settings

Printing bitmaps/pixmaps may or may not look great in your terminal depending on a variety of factors:

  • The terminal should support the Unicode - UTF-8 encoding. We use cli::is_utf8_output() to guess Unicode support which in turn looks at getOption("cli.unicode") and l10n_info().

  • The terminal should support ANSI sequences and if it does it should support many colors.

    • We use cli::num_ansi_colors() to detect number of colors supported. num_ansi_colors() detection algorithm is complicated but it first looks at getOption("cli.num_colors").

    • If using the Windows Command Prompt window you may need to enable ANSI sequences support by doing REG ADD HKCU\CONSOLE /f /v VirtualTerminalLevel /t REG_DWORD /d 1 from the command-line or running regedit (Registry Editor) and go to Computer\HKEY_CURRENT_USER\Console and set VirtualTerminalLevel to 1.

  • The font used by the terminal should be a monoscale font that supports the Block Elements Unicode block.

  • The terminal text settings should have a cell spacing around 1.00 times width and 1.00 times height. For terminals configured by CSS styles this means a line-height of around 1.0.

Examples

crops <- farming_crops_16x16()
corn <- crops$corn$portrait
if (cli::is_utf8_output() && cli::num_ansi_colors() >= 256L) {
  print(corn)
}
#>                 
#>                 
#>      ██  ██     
#>     ███████     
#>    ████████     
#>    █████████    
#>     █████████   
#>    ███████████  
#>   ████████████  
#>  █████████████  
#>  ███ █████████  
#>       ████████  
#>        ██████   
#>         ████    
#>                 
#>                 

if (cli::is_utf8_output() && cli::num_ansi_colors() >= 256L) {
  print(corn, compress = "v", bg = cli::bg_br_white)
}
#>                 
#>     ▄▀▀▄▄▀█     
#>    █▀▀▀▀█▀▀▄    
#>    ▄▀▀▀█▀█▀▀▀▄  
#>  ▄▀▀▀█▀▀▀▀████  
#>  ▀▀▀ ▀▀▀▀▀▀▀██  
#>        ▀▀▀▀▀▀   
#>                 

if (cli::is_utf8_output() &&
    cli::num_ansi_colors() > 256L &&
    getOption("width") >= 100L) {
  img <- png::readPNG(system.file("img", "Rlogo.png", package="png"))
  pm <- as_bm_pixmap(img)
  print(pm, compress = "v")
}