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..hex and .yaff files
will need to manually install their own version of monobit using pip3 install monobit.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).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.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.
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.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):
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:
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().bg and fg arguments of format.bm_bitmap() and print.bm_bitmap()
now accept lists of {cli} ANSI style functions in addition to color strings.print.bm_bitmap() no longer silently ignores its compress argument.bittermelon.px is now px_auto().
This means if cli::is_utf8_output() is FALSE we now default to px_ascii instead of px_unicode.write_monobit(), write_yaff(), and the unit tests
if any of the options bittermelon.fg, bittermelon.bg, or bittermelon.compress
are set away from their defaults.read_yaff() now correctly handles octal codepoint and (single) character labels.write_yaff() now encloses "tag" labels with double quotes.hex2ucp() now also calls base::toupper() on the input value.bm_bitmap() objects now also have the class "bm_matrix" (as does the new bm_pixmap() objects).format.bm_bitmap(x) no longer throws an error when x has zero columns (#68).bm_flip() now has a value argument to set the background padding value to use
if in_place is TRUE.is_combining_character() so it will continue to work after a breaking change
in Unicode::u_char_property()'s behavior introduced in {Unicode} v15.1.0-1 (#55).read_hex() has new argument ucp.NULL (default) read every glyph in the font (#52).block2ucp() and str2ucp() are now vectorized in their first argument.This update has no user-facing changes (at the request of CRAN we re-built our package man pages with an updated version of the {roxygen2} package to avoid a deprecated html image alignment warning).
bm_compose() simplifies bm_list() object
by applying combining marks to preceding glpyhs (composing new graphemes) (#42).as_bm_bitmap.character() has new arguments compose and pua_combining
to compose graphemes using combining characters.as_bm_bitmap.character() direction argument now supports combining
in combinations of horizontal/vertical directions such as
left-to-right, top-to-bottom (#47).is_combining_character() has new argument pua_combining
which is character vector of additional Unicode code points
to be considered "combining" characters (such as those
in the Private Use Area of a font). Defaults to character(0).read_monobit() and write_monobit() take new argument monobit_path indicating
the directory path containing monobit to use.file.path(rappdirs::user_config_dir("bittermelon"), "monobit"),
file.path(rappdirs::site_config_dir("bittermelon"), "monobit"), and
system.file("monobit", package = "bittermelon") (in that order).
New package option bittermelon.monobit_path can be used to set a new default. (#48)update_monobit() which downloads the most up to date (upstream) version of
monobit.
Although we continue to embed an older, more compact version of monobit in this package
the newest versions of monobit are too large to embed within this package and
must be downloaded separately.monobit should now better handle Amiga, AngelCode BMFont, X11/Adobe BDF, and C/C++ source code bitmap fonts and be able to natively read/write
bzip2, gzip, or lzma compressed fonts.is_combining_character().bm_expand() for bitmaps with zero columns/rows.bm_bitmap() creates a S3 object representing bitmaps (#1).
Intended to represent bitmap font glyphs but can be used
to represent more complicated bitmaps.
Non-binary bitmaps are allowed
(but we are unlikely to ever support exporting color bitmap fonts).
It supports the following S3 methods:
[.bm_bitmap() and [<-.bm_bitmap() (#38)
as.matrix.bm_bitmap()
cbind.bm_bitmap() and rbind.bm_bitmap()
format.bm_bitmap() and print.bm_bitmap() (#2)
which.bm_bitmap() (with which() redefined as a S3 generic that defaults to base::which())
as_bm_bitmap() is a S3 method that coerces objects to bm_bitmap() objects
as_bm_bitmap.default()as_bm_bitmap.grob() (#10)as_bm_bitmap.matrix()is_bm_bitmap() returns TRUE for bm_bitmap() objects (or subclasses)
and FALSE for all other objects.
bm_list() creates a S3 object representing a list of bm_bitmap() objects.
It supports the following S3 methods:
The "min()", "max()", and "range()" functions from the "Summary" group generic methods
as.list.bm_list()
"slicing" with [] returns bm_list() objects.
as_bm_list() is a S3 method that coerces objects to bm_list() objects
as_bm_list.character() (#28)as_bm_list.default()as_bm_list.list()is_bm_list() returns TRUE for bm_list() objects (or subclasses)
and FALSE for all other objects.
bm_font() creates a S3 object representing bitmap fonts (#5).
it is a subclass of the bm_list() class.
as_bm_font() is a S3 method that coerces objects to bm_font() objects
as_bm_font.default()as_bm_font.list()is_bm_font() returns TRUE for bm_font() objects (or subclasses)
and FALSE for all other objects.
The following functions can modify bm_bitmap() objects
as well as all the bitmaps in bm_list() objects (including bm_font()):
!.bm_bold() creates a basic "bold" effect (#16)bm_clamp() clamps integer values between a lower and upper value.
By default coerces the bitmap to binary values.bm_compress() shrinks bitmaps by a factor of two using a "block elements" scheme (#31).bm_distort() resizes bitmaps via distortion.bm_expand() expands bitmap(s) by repeating each row and/or column (#19).bm_extend() extends the bitmap by a specified value in specified directions (#11).bm_flip() flips (reflects) bitmaps (or just their glyphs in place)
vertically, horizontally, or both.bm_glow() adds a basic "glow" effect (#17)bm_mask() uses a mask bitmap to set certain pixels in a base bitmap to zero (#21).bm_outline() computes a "outline" bitmap from a bitmap.bm_overlay() merges bitmaps by overlaying one over another (#18).bm_pad() adjusts bitmap padding lengths (#40).bm_resize() resizes the bitmap to a desired width and/or height via extending/trimming (#34).bm_rotate() losslessly rotates bitmaps 0, 90, 180, or 270 degrees (#15).bm_shadow() adds a "shadow effect" (#17)bm_shift() shifts elements within a bitmap in a specified direction
while preserving original width and height (#13).bm_trim() trims the bitmap in specified directions (#12).Support for reading and writing bitmap fonts
read_hex() reads in a "hex" font as a bm_font() object (#8)write_hex() writes out a "hex" font of a bm_font() object (#9)read_yaff() reads in a "yaff" font as a bm_font() object (#6)write_yaff() writes out a "yaff" font of a bm_font() object (#7)read_monobit() reads in a bitmap font as a bm_font() object using monobit.
Supports multiple bitmap font formats. Requires Python to be available. (#26)write_monobit() writes out a bitmap font of a bm_font() object using monobit.
Supports multiple bitmap font formats. Requires Python to be available. (#27)Other utility functions
c() S3 methods combine bitmap objects. In particular when using it to combine fonts the later fonts "update" the glyphs in the earlier fonts.bm_call() executes a function on bitmap objects. It places the bitmap object
as the first argument so it is a bit friendlier to use in pipes than base::do.call()
and allows specifying additional arguments to the function.bm_edit() allows editing a bm_bitmap() object via text editor
indicating zeroes with a . and ones with a @ (as in yaff font format).bm_lapply() applies a function to each element in a bm_list() or bm_font() object.
It returns another bm_list() or bm_font() object with the same metadata as
the original object.bm_widths() and bm_heights() calculates the widths and heights of the bitmaps
in bm_list() or bm_font() objects.bm_padding_lengths() computes the padding lengths of a
target value for the top, right, bottom, and left sides of the bitmap.block2ucp(), hex2ucp(), int2ucp(), name2ucp(), range2ucp(), and str2ucp()
return Unicode code points as character vectors.ucp2label() returns Unicode code labels as character vectors.is_combining_character() returns TRUE or FALSE if Unicode
code point refers to a combining character.ucp_sort() sorts Unicode code points