piecepackr v1.13.10

• Bumps version of {rayvertex} in the DESCRIPTION to v0.10.4 to avoid a bug
  introduced in v0.10.3 that affected piece_mesh() (#339).

piecepackr v1.13.8

• Wraps get_embedded_font() example with try() and skips test on CRAN.

  • This prevents R CMD check ERRORS on CRAN machines with buggy versions of cairo installed (#333).
  • In particular cairo versions 1.17.4 to 1.17.8 may be buggy (#334).
    We'll now also raise a warning if a user tries to use get_embedded_font() with these cairo versions.
    These warnings have class "piecepackr_buggy_cairo" and can also be suppressed by setting
    options(piecepackr.check.cairo = FALSE).

piecepackr v1.13.6

• Tweak documentation examples to make CRAN happy (#332).

piecepackr v1.13.3

Bug fixes and minor improvements

• is_color_invisible() now accepts col values of length greater than one.
• basicPieceGrob() no longer shrinks its background and gridlines grobs if
  they would overlap with a transparent mat.

piecepackr v1.13.1

Breaking changes

• pp_shape("kite") with default theta and radius arguments now returns a slightly different "kite" shape.
  Explicitly set radius = 0.25 i.e. pp_shape("kite", radius = 0.25) to get the old "kite" shape
  (previously the "kite" shape couldn't be altered at all by the theta and radius arguments but with this release it can).

• The suggested package {xmpdf} is now required to embed bookmarks and XMP/documentation info metadata into
  the pdf files generated by save_print_and_play().
  Please install the suggested R package {xmpdf} and depending on what you metadata you want to embed
  either the ghostscript, pdftk-java, and/or exiftool command-line tools.
  If you use save_print_and_play() to create a pdf file and don't have these suggested software installed
  you'll get message informing you that {piecepackr} was unable to embed certain metadata.
  These messages have class "piecepackr_embed_metadata" and can also be suppressed by setting
  options(piecepackr.metadata.inform = FALSE).

• Some features which were deprecated by v1.10.3 (2022-03-23) have been removed:

  • The use_pictureGrob argument of grid.piece() / pieceGrob() which was deprecated in v1.8.1 (2021-08-11) has been removed.
    Use type = "picture" instead of use_pictureGrob = TRUE.
    The ... has also been moved sooner to where use_pictureGrob used to be in the argument order so
    the arguments width, height, depth, op_scale, op_angle, default.units, envir,
    name, gp, and vp must now always be named arguments (instead of positional arguments).
  • The pp_cfg() R6 class public method get_shadow_fn() which was deprecated in v1.10.1 (2022-02-22)
    has been removed. The public method get_op_grob() returns the complete oblique projection grob.
  • animate_pieces()'s annotate argument must now always be set as a named argument
    (or rely on its default value).
    Setting it positionally was deprecated in v1.10.3 (2022-03-23).

Deprecated features

• The use of the command-line utility pdffonts (usually found in poppler-utils)
  in get_embedded_font() is now deprecated.
  Please install the suggested R package {pdftools}
  (we now preferably use its pdf_fonts() function instead).

New features

• The following enhancements to the configurations returned by game_systems():

  • New configuration dice_d4 which provide four-sided dice in six color schemes (color controlled by their suit).
    Tetrahedrons with the rank as a numeral at the top point (#286).
  • New configuration dice_numeral which provide six-sided dice with numerals instead of pips in six color schemes (#311).
  • New configuration dice_d8 which provide eight-sided dice in six color schemes (color controlled by their suit).
    Octahedrons with the rank as a numeral at the top face (#312).
  • New configuration dice_d10 which provide ten-sided dice in six color schemes (color controlled by their suit).
    Pentagonal trapezohedrons with the rank as a numeral at the top face.
    The rank of ten is represented by a zero (#315).
  • New configuration dice_d10_percentile which provide ten-sided dice in six color schemes (color controlled by their suit).
    Pentagonal trapezohedrons with the rank as a numeral followed by a zero at the top face.
    The rank of ten is represented by a zero (#322).
  • New configuration dice_d12 which provide twelve-sided dice in six color schemes (color controlled by their suit).
    Dodecahedrons with the rank as a numeral at the top face (#316).
  • New configuration dice_d20 which provide twenty-sided dice in six color schemes (color controlled by their suit).
    Icosahedrons with the rank as a numeral at the top face (#317).
  • New configurations dominoes_chinese and dominoes_chinese_black which provide Chinese dominoes and Asian-style dice.
    dominoes_chinese has a white background with black and red pips while dominoes_chinese_black has a black background with white and red pips (#308).

• save_print_and_play() now uses {xmpdf} to embed bookmarks, documentation info, and XMP metadata into
  the pdf files generated by save_print_and_play().

  • The suggested package {xmpdf} is now required to embed metadata.
  • If available it will continue to use ghostscript to embed bookmarks and documentation info but
    can now also fallback to using pdftk to embed bookmarks and documentation info.
  • Can now use exiftool to embed XMP metadata including document license information.
  • save_print_and_play() will now inform users if unable to embed metadata into the generated pdf file.
    These messages have class "piecepackr_embed_metadata" and can also be surpressed by setting
    options(piecepackr.metadata.inform = FALSE).

Bug fixes and minor improvements

• Fixes a mis-rendering bug when using the new affine transformation feature that affected a small subset of game piece faces (#309).

• Border lines in oblique projected pyramids are now correctly made thicker/thinner when scale is different from 1 (#310).

• pp_shape()'s gridlines() and shape() methods takes new argument mat_width which can be used to shrink them
  (to not overlap/extend past a target "mat" effect) for most shapes that support a "mat" effect
  (but not "halma" or "roundrect" shapes which will quietly ignore the mat_width argument).
  This is now used in the default grob functions.

• The "kite" shape returned by pp_shape("kite") can now be adjusted by its theta and radius arguments.

• The following enhancements to the configurations returned by game_systems():

  • The dice in chess1 and chess2 now have larger chess symbols (#318).

  • In dual_piecepacks_expansion:

    • The border color for "Moons" dice and pawns is now "black" instead of "grey40".
    • The "Moons" suit color is now "black" instead of "grey30" for "board_face" pieces.

  • In piecepack

    • The "Moons" suit color is now "black" instead of "grey30" except for "bit" and "matchstick" pieces.
    • The "Moons" suit color is now "grey30" instead of "black" for "bit" pieces.

  • In piecepack_inverted:

    • Pieces no longer have a "mat" effect except for the "tile_back"
    • The edges of "coin" and "tile" pieces are now "white".
    • The "coin_face" and "card_back" backgrounds are now "grey30" instead of "black".
    • The "Moons" "board_face" and "matchstick" suit colors are now "black" instead of "grey30".

  • In playing_cards_expansion:

    • The "Clubs" suit color is now "grey30" for "matchstick" pieces.
    • The "Clubs" and "Spades" suit color is now "grey30" for "bit" pieces.

piecepacker v1.12.2

Bug fixes and minor improvements

• In save_print_and_play() we fix rotation of pawn layout
  when bleed = FALSE and size is not "4x6".
• The default function used to create game pieces for use with the {rayrender}
  graphics system (via the piece() function) has been updated to handle
  some breaking changes in the arguments for rayrender::obj_model() (#304).
• piece_mesh() has been updated to handle some breaking changes in {rayvertex} (#307).

piecepacker v1.12.0

New features

• save_print_and_play() now supports new argument size_bleed to add an additional "bleed zone" to
  the edges of the print-and-play output size:

  • A list with names "top", "right", "bottom", "left"
    containing numeric values indicating the inches "bleed" to add to
    the size of the print-and-play layout.
  • The default NULL means no such bleed added to "letter", "A4", and "A5"
    size layouts and a small bleed added to "4x6" size layouts
    (1/16" to top/bottom and 3/32" to left/right).
    Light prototyping at my local photo print service indicates adding such a bleed delivers
    better results for 4x6 photo prints but your results my vary.
  • Multiply millimeters by 0.0393700787 to convert to inches.
  • We currently don't support an asymmetric left/right bleed combined with arrangement = "double-sided".
  • Not to be confused with the bleed argument which if TRUE switches to an alternative layout
    which adds a bleed zone and crop marks around the game pieces.

Bug fixes and minor improvements

• Default resolution when generating bitmap images with save_print_and_play() is now 300 pixels per inch.
• Fixes the "hexpack" configuration returned by game_systems().

piecepackr v1.11.1

Breaking changes

• Some tweaks to the "bleed" zone feature introduced in v1.10.1:

  • In grid.piece() / pieceGrob() if bleed = TRUE and width or height is not NA
    then width / height is now interpreted as the size of the piece before "bleed" zone is added.
  • A non-unitary scale factor will now be applied to piece dimensions before "bleed" zone is added.
  • If one of the "named slots" of the {grid} "grob" returned by a custom
    grob_with_bleed_fn function is bleed then pieceGrob() / grid.piece()
    will adjust that grob's bleed slot to the requested "bleed" zone margins.

• There were some tweaks on how custom function style elements
  (i.e. grob_fn, op_grob_fn, grob_with_bleed_fn,
  obj_fn, rayrender_fn, rayvertex_fn, rgl_fn)
  in configurations lists are internally called by {piecepackr}.
  If you use custom function style elements it is possible you may be affected:

  • The arguments of custom functions are now called by name (via do.call())
    instead of positionally.
    If your custom function uses the same argument names
    as any of {piecepackr}'s internal custom functions then there should be no problem.
    The order of arguments no longer matters but the names must match the
    names {piecepackr} expects.

  • If one of the "named slots" of the {grid} "grob" returned by a custom
    grob_fn function is border then pieceGrob() / grid.piece() will
    adjust that named slot to FALSE
    and manually draw new border lines whenever distorting the grob via the
    affine transformation feature (#277).

  • If one of the "named slots" of the {grid} "grob" returned by a custom
    grob_fn function is flip then pieceGrob() / grid.piece() will
    adjust that named slot to TRUE and draw it horizontally flipped
    (via affine transformation feature) when drawing the "flip" side.
    Currently most relevant when drawing on-their-side pyramids viewed from their bottom.

  • If one of the "named slots" of the {grid} "grob" returned by a custom
    grob_fn, op_grob_fn, or grob_with_bleed_fn function is scale then
    pieceGrob() / grid.piece() will adjust that named slot rather than
    adjusting that grob's gp slot's cex and lex values when scale != 1.
    If your "grob" doesn't have a named slot scale you shouldn't be affected.

• A couple pp_cfg() R6 class active bindings which were deprecated in v1.7.1 (2021-03-25)
  have been removed:

  • cache_shadow. Use the new cache_op_fn instead.
  • i_unsuit. Add one to the n_suits field instead.

New features

• cropmarkGrob() / grid.cropmark() create/draw "crop mark" grobs (#262).
  Intended for use in creating print-and-play layouts.

• save_print_and_play() supports new argument bleed (#259).
  If bleed = TRUE we provide a new print-and-play layout with
  1/8" bleed zones and "crop marks" indicating where to cut the pieces.
  Currently this feature only supports pieces = "piecepack", does
  not support size = "4x6", and requires more paper than the
  more compact legacy bleed = FALSE layout.

• geom_piece(), grid.piece(), pieceGrob(),
  pp_cfg()$get_grob(), and pp_cfg()$get_op_grob() now support
  argument type = "transformation" which uses
  the new affine transformation feature introduced in R 4.2.

  This should be a faster alternative to the existing "picture" and "raster" types when
  wishing to "faithfully" draw game pieces outside their "normal" (viewport) sizes
  and/or dilate them in x/y directions
  but will only work in select graphic devices in R 4.2 (or later).
  You can tell if the active graphic device supports the affine transformation feature
  with isTRUE(dev.capabilities()$transformations).

• grid.piece() / pieceGrob() now has support for
  drawing two-sided tokens stood up on one of their sides
  i.e. ("top", "left", "right", or "base") in an oblique projection (#272).

  grid.piece() / pieceGrob()` now also draws more sides of
  die and pyramid pieces when drawn in an oblique projection (#173, #257).

  Fully rendering the visible sides of the pieces requires the new "affine transformation" feature
  which is only supported in select graphic devices in R 4.2 (most notably the "cairo" family of devices).
  If this feature is not detected
  we will output an inform() message() of class "piecepackr_affine_transformation"
  and fall back to either a grImport2::pictureGrob() or grid::polygonGrob() alternative.
  These messages may be suppressed by setting options(piecepackr.at.inform = FALSE).

• pp_cfg()'s die_arrangement "style" now supports comma-separated strings
  of six integers optionally followed by a ^, <, v, > which can be
  used to completely customize the arrangement of faces on six-sided dice (#175).
  The die_arrangement "style" continues to also support the values "counter_up",
  "opposites_sum_to_5", and "counter_down" (default) which provide aliases
  for three popular arrangements.

• The following enhancements to the configurations returned by game_systems():

  • New configuration dice_fudge which provide Fudge dice
    in six color schemes (#287).

Bug fixes and minor improvements

• The op_angle, op_scale, alpha, and scale arguments of
  pieceGrob() / grid.piece() are now vectorized.
• The op_scale threshold when pieceGrob() / grid.piece() switches from "oblique projection"
  mode to "orthographic projection" mode has been lowered from 0.01 to 0.0001.
• If isTRUE(capabilities("cairo")) then pp_cfg()$get_raster()
  now always uses png(type = "cairo").
• grid::grobCoords() now returns slightly better values for dice, pyramids, and convex
  two-sided tokens when projected in an oblique projection by pieceGrob() / grid.piece() (#285).
• save_print_and_play()'s pieces argument now defaults to NULL. If the size / bleed
  arguments support the "matchsticks" and "pyramids" pieces it defaults to
  c("piecepack", "pyramids", "matchsticks") (as before) and if they
  do not suport those pieces it defaults to just "piecepack".
  We are now more selective of which piecepack credits to include based on
  which components are in the pieces argument.
• save_print_and_play() now shuffles tile back directions (#103).
  If a user makes tiles by double-sided printing or folding over the "gutter" and the tile
  backs are not perfectly symmetric then the tile backs will now leak less information
  about the "direction" of the tile faces.
• The default "bleed" function (as used by pp_cfg()$get_grob_with_bleed() and pieceGrob(bleed=TRUE))
  now better extends "mat" and "gridlines" from the default "grob" function (#288).
• animate_piece() now correctly handles n_pauses != 1.
• If the file argument of animate_piece() ends in ".bmp", ".jpg", ".jpeg", ".png", or ".tiff"
  we will now save individual images of the animation frames.
  file must have a "C integer format" in the filename.
• Fixes bug generating textures in save_piece_obj() if options("piecepackr.op_scale") was
  set to a positive number (#293).

piecepackr v1.10.3

Breaking changes

• Upcoming breaking changes in R 4.2 for grid::grobCoords() and grid::grobPoints()
  required changes being made in {piecepackr} as well.
  However {piecepackr} users probably won't need to update any of their code due to these changes (#270).:

  • {piecepackr} exports new S3 grobCoords() / grobPoints() methods that
    works for grob objects returned by pieceGrob() and pp_cfg()$get_grob() (for type = "normal")
    as well as grob objects returned by pmap_piece().
    They return lists of lists with (x,y) coordinates of the polygons that bound the game pieces
    in the format expected for grid::grobCoords() methods according to the R version number.
  • Instead of grobPoints.piece() we now export the S3 method grobPoints.pp_grobCoords() and
    the grob objects returned by pieceGrob() and pp_cfg()$get_grob() (for type = "normal") now
    inherit the additional class "pp_grobCoords".

Bug fixes

• Final page in "4x6" size layout produced by save_print_and_play()
  is no longer incorrectly rotated from landscape to portrait mode (#269).

Deprecated features

• Using animate_piece()'s annotate argument unnamed is now deprecated.
  Instead either use its annotate argument named e.g. annotate = "cartesian"
  or instead don't provide this argument (and let it use its default TRUE value).
  In a future version this argument will be moved behind the ....

piecepackr v1.10.1

Breaking changes

• save_print_and_play() no longer automatically assumes that the
  generated print-and-play file should automatically be released under the CC BY-SA 4.0 license.
  To continue to release under the CC BY-SA 4.0 license you should set the cfg argument's
  spdx_id style/binding to "CC-BY-SA-4.0" (i.e. cfg$spdx_id = "CC-BY-SA-4.0") before calling save_print_and_play()`.

• Several features that were deprecated in 2020 have been removed:

  • The following utility functions have been removed:

    • checkersGrob(c, s, t, n), use pp_shape(s, t)$checkers(n, gp=gpar(fill=c)) instead.
    • concaveGrobFn(n, t, r), use pp_shape(paste0("concave", n), t, r)$shape instead.
    • convexGrobFn(n, t), use pp_shape(paste0("convex", n), t)$shape instead.
    • get_shape_grob_fn(s, t, r, b), use pp_shape(s, t, r, b)$shape instead.
    • gridlinesGrob(c, s, t, l, n), use pp_shape(s, t)$gridlines(n, gp=gpar(col=c, lex=l)) instead.
    • halmaGrob(...), use pp_shape("halma")$shape(...) instead.
    • hexlinesGrob(c, s, n), use pp_shape(s)$hexlines(n, gp=gpar(col=c)) instead.
    • kiteGrob(...), use pp_shape("kite")$shape(...) instead.
    • matGrob(c, s, t, mw, n), use pp_shape(s, t)$mat(mw, n, gp=gpar(fill=c)) instead.
    • pyramidGrob(...), use pp_shape("pyramid")$shape(...) instead.

  • The following pp_cfg() R6 class public method has been removed:

    • get_pictureGrob(), use get_grob(piece_type, suit, rank, type="picture") instead.

  • The following pp_cfg() "style" has been removed:

    • shadow_fn, use op_grob_fn to indicate a custom function for drawing in an oblique projection.

New features

• animate_piece() can be used to create board game animations
  using either the suggested package {animation} or {gifski} (#251).
  Adding transition effects between moves (i.e. n_transitions > 0)
  requires the suggested package {tweenr}.

• scale_x_piece() and scale_y_piece() are wrappers around
  ggplot2::scale_x_continuous() and ggplot2::scale_y_continuous()
  with better defaults for board game diagrams.
  The functions returned by label_letter() labels with letters,
  label_counting() labels with counting numbers,
  and breaks_counting() generates breaks at the counting numbers
  to more easily generate (i.e. chess) algebraic notation coordinates
  as commonly used in board game diagrams (#252).

• The following enhancements to the configurations returned by game_systems():

  • New piecepack_inverted configuration (#256).
    The standard piecepack with its color scheme inverted.
    Intended to aid in highlighting special pieces in diagrams.

  • New reversi configuration (#258).
    "board_face" provides lined boards with colored backgrounds.
    "board_back" provides checkered boards.
    "bit_face" / "bit_back" provides circular game tokens with differently colored sides:
    red paired with green, black paired with white, and blue paired with yellow.

• Improvements to save_print_and_play():

  • Now supports a dev argument and dev.args argument
    that allows one to customize which graphic device (and its arguments) is
    used to generate the print-and-play files.

  • Now natively supports bitmap file formats "bmp", "jpeg", "png", and "tiff".
    but output_filename will need to have a "C integer format" in the string
    (e.g. "piecepack%02d.png") so it can generate multiple "pages".

  • Now supports size "4x6" to create a piecepack print-and-play layout for
    4x6 (photo print) size documents (#162).

    • Currently only supports pieces = "piecepack".
      Will throw an error if you try to create
      (piecepack) "pyramids", "matchsticks", or "subpack" print-and-play layouts.
    • For 4x6 photo prints will probably want to use a bitmap file format e.g. set
      output_filename = "piecepack%02d.png".

  • The license of the generated print-and-play file is now customized by
    the cfg argument's spdx_id style/binding (#235).
    save_print_and_play() will then create a license section with
    that license's "full name", a URL, and in case of a Creative Commons license
    add a "button mark" badge.
    If left NULL we will now omit the license section but print a message
    saying we omitted it (unless quietly = TRUE).

  • New argument quietly.
    Unless quietly = FALSE will now message() about missing metadata.

  • The "title" page was tweaked and improved. In particular it should
    now be able to handle any license with a SPDX Identifier.

• Improvements to support adding a "bleed" zone around pieces:

  • pieceGrob() and grid.piece() now support a bleed argument.

    • If bleed = TRUE we add a "bleed" zone around the piece.
    • width and height should be the width and height of the piece plus bleed zone.
      If width or height is NA we will add 1/8 inch bleeds (about 3.18 mm).
    • bleed = TRUE is incompatible with op_scale > 0.

  • pp_cfg() now supports a grob_with_bleed_fn style that can be
    used to set a custom function for drawing the piece with bleed.
    The default grob_with_bleed_fn function tries to guess a
    good solid bleed color and draws it around the base piece.

• pp_cfg() supports a new spdx_id "style" and an associated active binding to update it.
  This is meant to refer to the SPDX Identifier for
  the graphical design license.
  save_print_and_play() can now use this field to customize the License info
  for the generated print-and-play layout (#235).

• spdx_license_list is a dataset for the SPDX License List.
  It is intended as an aid for developers writing print-and-play layout generators
  or board game ruleset generators.

Bug fixes and minor improvements

• render_piece() should now handle its dev.args argument properly.
• pmap_piece() now simply returns list() if its .l argument has zero length
  or number of rows (instead of throwing an error).
• The "saucer" pieces in game_systems()'s piecepack configurations have been improved.
  The suit text on the backs are better sized and the suit text has been removed from the faces.
• The "joystick" or "peg-doll" pawns now have support for piece_side = "pawn_base" with pieceGrob().

Deprecated features

The following pp_cfg() R6 class public method has been deprecated:

• get_shadow_fn(), use get_op_grob() to get complete oblique projection grob.