Skip to contents

Modify bitmaps via masking with a 'mask' bitmap

Source: R/bm_mask.R
bm_mask.Rd

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

Usage

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

# S3 method for class 'bm_bitmap'
bm_mask(
  x,
  mask = NULL,
  base = NULL,
  mode = c("luminance", "alpha"),
  hjust = "center-left",
  vjust = "center-top"
)

# S3 method for class 'bm_pixmap'
bm_mask(
  x,
  mask = NULL,
  base = NULL,
  mode = c("luminance", "alpha"),
  hjust = "center-left",
  vjust = "center-top"
)

# S3 method for class '`magick-image`'
bm_mask(
  x,
  mask = NULL,
  base = NULL,
  mode = c("luminance", "alpha"),
  hjust = "center-left",
  vjust = "center-top"
)

# S3 method for class 'nativeRaster'
bm_mask(
  x,
  mask = NULL,
  base = NULL,
  mode = c("luminance", "alpha"),
  hjust = "center-left",
  vjust = "center-top"
)

# S3 method for class 'raster'
bm_mask(
  x,
  mask = NULL,
  base = NULL,
  mode = c("luminance", "alpha"),
  hjust = "center-left",
  vjust = "center-top"
)

# S3 method for class 'bm_list'
bm_mask(
  x,
  mask = NULL,
  base = NULL,
  mode = c("luminance", "alpha"),
  hjust = "center-left",
  vjust = "center-top"
)

Arguments

x

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

mask

An object to use as a binary bitmap “mask”. Only one of mask or base may be set. Will be coerced to a bm_bitmap() object by as_bm_bitmap().

base

A bitmap/pixmap 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".

Value

A bitmap/pixmap object that is the same type as x (if base is NULL) or base.

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 by bm_clamp(as_bm_bitmap(mask)). If mode is "luminance" then where the mask is 1L the corresponding pixel in base will be coerced to the background value. If mode is "alpha" then where the mask is 0L the corresponding pixel in base will be coerced to the background value.

Examples

if (require("grid", quietly = TRUE) && 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)
}
#> ░░░░░██████░░░░░
#> ░░░████░░████░░░
#> ░░██░░░░░░░░██░░
#> ░██░░░░░░░░░░██░
#> ░█░░░░░░░░░░░░█░
#> ██░░░░░░░░░░░░██
#> ██░░░░░░░░░░░░██
#> █░░░░░░░░░░░░░░█
#> █░░░░░░░░░░░░░░█
#> ██░░░░░░░░░░░░██
#> ██░░░░░░░░░░░░██
#> ░█░░░░░░░░░░░░█░
#> ░██░░░░░░░░░░██░
#> ░░██░░░░░░░░██░░
#> ░░░████░░████░░░
#> ░░░░░██████░░░░░
if (capabilities("png")) {
  # U+2776 "Dingbat Negative Circled Digit One"
  circle_minus_one <- bm_mask(circle_large, one)
  print(circle_minus_one)
}
#> ░░░░░██████░░░░░
#> ░░░██████████░░░
#> ░░█████░░█████░░
#> ░█████░░░██████░
#> ░████░░░░██████░
#> █████░█░░███████
#> ███████░░███████
#> ███████░░███████
#> ███████░░███████
#> ███████░░███████
#> ███████░░███████
#> ░████░░░░░░████░
#> ░██████████████░
#> ░░████████████░░
#> ░░░██████████░░░
#> ░░░░░██████░░░░░
# 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)
#> ████████████████
#> ████████████████
#> ████████████████
#> ████████████████
#> ████████████████
#> ████████████████
#> ████████████████
#> ████████████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
if (capabilities("png")) {
  circle_minus_lower_left <- bm_mask(circle_large, square_minus_lower_left, mode = "alpha")
  print(circle_minus_lower_left)
}
#> ░░░░░██████░░░░░
#> ░░░██████████░░░
#> ░░████████████░░
#> ░██████████████░
#> ░██████████████░
#> ████████████████
#> ████████████████
#> ████████████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
#> ░░░░░░░░████████
#> ░░░░░░░░███████░
#> ░░░░░░░░███████░
#> ░░░░░░░░██████░░
#> ░░░░░░░░█████░░░
#> ░░░░░░░░███░░░░░

if (capabilities("png")) {
  m <- matrix(grDevices::rainbow(8L), byrow = TRUE, ncol = 8L, nrow = 8L)
  rainbow <- bm_expand(as_bm_pixmap(m), 2L)
  circle_rainbow <- bm_mask(rainbow, circle_large, mode = "alpha")
}
if (cli::is_utf8_output() &&
    cli::num_ansi_colors() >= 256L &&
    capabilities("png")) {
  print(circle_rainbow, compress = "v")
}
#>    ▄▄██████▄▄   
#>  ▄████████████▄ 
#> ▄██████████████▄
#> ████████████████
#> ████████████████
#> ▀██████████████▀
#>  ▀████████████▀ 
#>    ▀▀██████▀▀