Print bitmap objects

print.bm_bitmap() prints a representation of bitmap objects to the terminal. It is a wrapper around format.bm_bitmap() which converts bitmap objects to a character vector. px_unicode and px_ascii are builtin character vectors intended for use with the px argument (the former contains Unicode “Block Elements” while the latter is purely ASCII). px_auto() chooses which character vector to use based on whether cli::is_utf8_output() is TRUE or not.

Usage

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

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

px_unicode

px_ascii

px_auto(unicode = px_unicode, ascii = px_ascii)

Format

An object of class character of length 20.

Arguments

x: A bm_bitmap() object
...: Further arguments passed to or from other methods.
px: Character vector of the pixel to use for each integer value i.e. The first character for integer 0L, the second character for integer 1L, and so on. Will be recycled.
fg: R color strings of foreground colors to use and/or cli ANSI style functions of class cli_ansi_style. FALSE (default) for no foreground colors. Will be recycled and passed to cli::make_ansi_style().
bg: R color strings of background colors to use and/or cli ANSI style functions of class cli_ansi_style. FALSE (default) for no background colors. Will be recycled and passed to cli::make_ansi_style() with bg = TRUE.
compress: If "none" (default) or "n" don't compress first with bm_compress(). Otherwise compress first with bm_compress() passing the value of compress as its direction argument (i.e. either "vertical" or "v", "horizontal" or "h", OR "both" or "b").
downscale: If TRUE and the printed bitmap will be wider than getOption("width") then shrink the image to fit getOption("width") using bm_downscale().
unicode: Character vector to use if cli::is_utf8_output() is TRUE.
ascii: Character vector to use if cli::is_utf8_output() is FALSE.

Value

A character vector of the string representation (print.bm_bitmap() does this invisibly). As a side effect print.bm_bitmap() 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 cli::num_ansi_colors() equals 16777216 then your terminal supports 24-bit ANSI 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