bm_overlay {bittermelon}

Merge bitmaps by overlaying one over another

Description

bm_overlay() merges bitmaps by overlaying a bitmap over another.

Usage

bm_overlay(
  x,
  over = NULL,
  under = NULL,
  hjust = "center-left",
  vjust = "center-top",
  ...
)

## S3 method for class 'bm_bitmap'
bm_overlay(
  x,
  over = NULL,
  under = NULL,
  hjust = "center-left",
  vjust = "center-top",
  bg = 0L,
  ...
)

## S3 method for class 'bm_list'
bm_overlay(x, ...)

## S3 method for class 'bm_pixmap'
bm_overlay(
  x,
  over = NULL,
  under = NULL,
  hjust = "center-left",
  vjust = "center-top",
  bg = col2hex("transparent"),
  ...
)

## S3 method for class ''magick-image''
bm_overlay(
  x,
  over = NULL,
  under = NULL,
  hjust = "center-left",
  vjust = "center-top",
  bg = "transparent",
  ...
)

## S3 method for class 'nativeRaster'
bm_overlay(
  x,
  over = NULL,
  under = NULL,
  hjust = "center-left",
  vjust = "center-top",
  bg = col2int("transparent"),
  ...
)

## S3 method for class 'raster'
bm_overlay(
  x,
  over = NULL,
  under = NULL,
  hjust = "center-left",
  vjust = "center-top",
  bg = "transparent",
  ...
)

Arguments

x

Either a bm_bitmap(), bm_font(), bm_list(), "magick-image", "nativeRaster", bm_pixmap(), or "raster" object.

over

A bitmap/pixmap object to overlay over the x bitmap(s). Only one of over or under may be set.

under

A bitmap/pixmap object which will be overlaid by the x bitmap(s). Only one of over or under may be set.

hjust

One of "left", "center-left", "center-right", "right". "center-left" and "center-right" will attempt to place in "center" if possible but if not possible will bias it one pixel left or right respectively. "centre", "center", and "centre-left" are aliases for "center-left". "centre-right" is an alias for "center-right".

vjust

One of "bottom", "center-bottom", "center-top", "top". "center-bottom" and "center-top" will attempt to place in "center" if possible but if not possible will bias it one pixel down or up respectively. "centre", "center", and "centre-top" are aliases for "center-top". "centre-bottom" is an alias for "center-bottom".

...

Additional arguments to be passed to or from methods.

bg

Bitmap background value.

Details

If necessary bitmaps will be extended by bm_extend() such that they are the same size. Then the non-zero pixels of the “over” bitmap will be inserted into the “under” bitmap.

Value

Depending on x either a bm_bitmap(), bm_font(), bm_list(), magick-image, "nativeRaster", bm_pixmap(), or raster object.

Examples

font_file <- system.file("fonts/spleen/spleen-8x16.hex.gz", package = "bittermelon")
font <- read_hex(font_file)
grave <- font[[str2ucp("`")]]
a <- font[[str2ucp("a")]]
a_grave <- bm_overlay(a, over = grave)
print(a_grave)

# Can also instead specify the under glyph as a named argument
a_grave2 <- bm_overlay(grave, under = a)
print(a_grave2)

crops <- farming_crops_16x16()
corn <- bm_shift(crops$corn$portrait, right = 2L, top = 2L)
grapes <- bm_shift(crops$grapes$portrait, bottom = 1L)
grapes_and_corn <- bm_overlay(corn, grapes)
if (cli::is_utf8_output() && cli::num_ansi_colors() >= 256L) {
  print(grapes_and_corn, compress = "v")
}