bm_mask {bittermelon}

Modify bitmaps via masking with a 'mask' bitmap

Description

bm_mask() modifies bitmaps by using a binary bitmap “mask” to set certain elements to zero.

Usage

bm_mask(
  bm_object,
  mask = NULL,
  base = NULL,
  mode = c("luminance", "alpha"),
  hjust = "center-left",
  vjust = "center-top"
)

Arguments

bm_object

Either a bm_bitmap(), bm_list(), or bm_font() object.

mask

A 'bm_bitmap()' object to use as a “mask”. Only one of mask or base may be set.

base

A 'bm_bitmap()' object which will be “masked” by mask. Only one of mask or base may be set.

mode

Either "luminance" (default) or "alpha".

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".

Details

If necessary bitmaps will be extended by bm_extend() such that they are the same size. If necessary the mask will be coerced into a “binary” mask. If mode is "luminance" then where the mask is 1L the corresponding pixel in base will be coerced to 0L. If mode is "alpha" then where the mask is 0L the corresponding pixel in base will be coerced to 0L

Value

Either a bm_bitmap(), bm_list(), or bm_font() object.

Examples

 if (require("grid") && capabilities("png")) {
   font_file <- system.file("fonts/spleen/spleen-8x16.hex.gz", package = "bittermelon")
   font <- read_hex(font_file)
   one <- font[[str2ucp("1")]]
   circle_large <- as_bm_bitmap(circleGrob(r = 0.50), width = 16L, height = 16L)
   circle_small <- as_bm_bitmap(circleGrob(r = 0.40), width = 16L, height = 16L)

   circle_outline <- bm_mask(circle_large, circle_small)
   print(circle_outline, px = px_ascii)

   # U+2776 "Dingbat Negative Circled Digit One"
   circle_minus_one <- bm_mask(circle_large, one)
   print(circle_minus_one, px = px_ascii)

   # Can also do "alpha" mask
   square_full <- bm_bitmap(matrix(1L, nrow = 16L, ncol = 16L))
   square_minus_lower_left <- square_full
   square_minus_lower_left[1:8, 1:8] <- 0L
   print(square_minus_lower_left, px = px_ascii)

   circle_minus_lower_left <- bm_mask(circle_large, square_minus_lower_left, mode = "alpha")
   print(circle_minus_lower_left, px = px_ascii)
 }