bittermelon v2.0.2

Breaking changes

• We no longer embed an increasingly outdated version of monobit.

  • monobit has now grown too large to embed within {bittermelon} and stay within CRAN package size limits.
  • Users interested in reading/writing bitmap fonts formats other than .hex and .yaff files
    will need to manually install their own version of monobit using pip3 install monobit.
  • The interpretation of the argument monobit_path in read_monobit() and write_monobit()
    and the global option bittermelon.monobit_path has been changed and now means the path
    to pass to base::Sys.which() (if the new default name "monobit-convert" is not good enough).
  • Any previously installed versions of monobit to rappdirs::site_config_dir("bittermelon", "monobit") or rappdirs::user_config_dir("bittermelon", "monobit") will now be ignored.
    Please consider deleting them or update the bittermelon.monobit_path option to point to them.
  • The function update_monobit() has been removed.

• The default col argument to as.raster.bm_bitmap() and plot.bm_bitmap() is now
  getOption("bittermelon.col", col_bitmap) where the newly exported
  col_bitmap = c("transparent", "black", "grey50", "grey25").
  In particular by default 0L values will now be cast to "transparent" instead of "grey80".
  To get the old behaviour set options("bittermelon.col" = c("grey80", "black", "grey40")).

• We no longer export a generic S3 which() method which by default calls base::which()
  and remove the special which.bm_bitmap() method that first cast to a logical.
  Instead now use which(as.logical(x)) for bm_bitmap() objects.

• Many functions were upgraded to S3 generics that support more bitmap objects.
  The first argument of these functions are now usually x instead of bm_object.
  If specifying the first argument by name instead of positionally you'll now
  need to use x instead.

• bm_distort() is now a wrapper around magick::image_resize().
  x, width, and height are now the only supported positional arguments
  and the interpolate, vp, and png_device arguments are no longer supported.
  It now requires the suggested package {magick}.

• The default for height in bm_expand() is now the value of width i.e.
  bm_expand(x, 2L) will now double the size of x in both directions.
  To get the previous behaviour you may now need to explicitly set height = 1L.

New features

• bm_pixmap() creates a S3 object representing raster image pixmaps (#60).
  Intended to represent pixel art / sprites but can be used
  to represent more complicated raster images.
  It supports the following S3 methods:

  • as.matrix.bm_pixmap() and as.array.bm_pixmap()

  • as.raster.bm_pixmap() and plot.bm_pixmap()

  • cbind.bm_pixmap() and rbind.bm_pixmap()

  • format.bm_pixmap() and print.bm_pixmap()

  • as_bm_pixmap() is a S3 method that coerces objects to bm_pixmap() objects

    • as_bm_pixmap.array() (e.g. from {png}, {jpeg}, and {webp})
    • as_bm_pixmap.bm_bitmap()
    • as_bm_pixmap.default()
    • as_bm_pixmap.glyph_bitmap() (from {fontr})
    • as_bm_pixmap.grob()
    • as_bm_pixmap.magick-image() (from {magick})
    • as_bm_pixmap.matrix()
    • as_bm_pixmap.maze() (from {mazing})
    • as_bm_pixmap.nativeRaster()
    • as_bm_pixmap.pattern_square() (from {gridpattern})
    • as_bm_pixmap.pattern_weave() (from {gridpattern})
    • as_bm_pixmap.pixeltrix() (from {pixeltrix})
    • as_bm_pixmap.pixmapGrey() (from {pixmap})
    • as_bm_pixmap.pixmapIndexed() (from {pixmap})
    • as_bm_pixmap.pixmapRGB() (from {pixmap})
    • as_bm_pixmap.raster()

  • is_bm_pixmap() returns TRUE for bm_pixmap() objects (or subclasses)
    and FALSE for all other objects.

  • Some of the "Ops" group generic operators such as == and !=.

• The following functions are now S3 generics that have methods that support (at least) bm_bitmap() / bm_pixmap(), bm_font() / bm_list(), "magick-image", and "raster" / "nativeRaster" objects:

  • bm_bold()
  • bm_clamp()
  • bm_compress()
  • bm_distort()
  • bm_expand()
  • bm_extend()
  • bm_flip()
  • bm_glow()
  • bm_heights()
  • bm_mask()
  • bm_outline()
  • bm_overlay()
  • bm_pad()
  • bm_padding_lengths()
  • bm_resize()
  • bm_rotate()
  • bm_shadow()
  • bm_shift()
  • bm_trim()
  • bm_widths()

• New bitmap/pixmap manipulation function:

  • bm_downscale()
  • bm_gray() with alias bm_grey()
  • bm_invert()
  • bm_replace()

• Other new functions:

  • bm_print() and bm_format() can be used to pretty print bitmap objects to the terminal.
  • farming_crops_16x16() returns a named list of lists
    of twenty farming crops in five stages of growth plus a portrait as bm_pixmap() objects.
  • bm_options() returns a list of (current or default) bittermelon options values.
  • px_auto() determines which character vector to use for "pixels" based on
    whether cli::is_utf8_output() is TRUE or not.

• New as_bm_bitmap() class methods:

  • as_bm_bitmap.array() (e.g. from {png}, {jpeg}, and {webp})
  • as_bm_bitmap.bm_pixmap()
  • as_bm_pixmap.glyph_bitmap() (from {fontr})
  • as_bm_bitmap.magick-image() (from {magick})
  • as_bm_bitmap.maze() coerces (from {mazing})
  • as_bm_bitmap.nativeRaster()
  • as_bm_bitmap.pattern_square() (from {gridpattern})
  • as_bm_bitmap.pattern_weave() (from {gridpattern})
  • as_bm_bitmap.pixeltrix() (from {pixeltrix})
  • as_bm_bitmap.pixmapGrey() (from {pixmap})
  • as_bm_bitmap.pixmapIndexed() (from {pixmap})
  • as_bm_bitmap.pixmapRGB() (from {pixmap})
  • as_bm_bitmap.raster()

• New "bm_bitmap" class S3 generics features:

  • format.bm_bitmap() and print.bm_bitmap() gain a downscale argument to downscale the image
    to getOption("width") (if necessary to fit in terminal).
  • as.raster.bm_bitmap() now has a native argument to cast to "nativeRaster" objects.
  • as.matrix.bm_bitmap() now has a first_row_is_top argument to flip the rows
    so that the first row represents the top of the bitmap instead of the bottom.
  • New as.array.bm_bitmap() function for writing bitmaps with png::writePNG() and friends.

• New color utilities:

  • col2hex() standardize color strings into a unique hex color string.
  • col2int() and int2col() convert back and forth to (native) color integers.

• Following bm_list() upgrades (#69):

  • Can now contain bm_bitmap(), bm_pixmap(), "magick-image", "nativeRaster", or "raster" bitmaps.
  • as_bm_list.list() now supports FUN for a function which can be applied to each element of the list
    such as identity(), as_bm_bitmap(), and as_bm_pixmap().

• New package options:

  • The bittermelon.downscale option can be used to change the default for
    the downscale argument in format.bm_bitmap(), print.bm_bitmap(),
    format.bm_pixmap(), and print.bm_pixmap().