A length-one NaN value of any pattern parameter is now treated as unset
so pattern-specific (or else generic) defaults apply
(a parameter without any default is then NULL i.e. the same as if it wasn't supplied
so new {ggpattern} aesthetics and new defaults don't change what a NaN means).
This is the new {ggpattern} default for its aesthetics that should fall back to the pattern's defaults
(e.g. the "wave" frequency of 1 / spacing, the "regular_polygon" scale 0.5,
the "text" shape "X", and the "crosshatch" / "weave" pattern_fill2 of pattern_fill).
An NA value keeps its meaning (e.g. a transparent colour or a "pch" shape that draws nothing)
except for pattern_type, pattern_subtype, pattern_gravity, and pattern_res
for which a length-one NA is still also treated as unset.
A few pattern defaults were updated to match the previous {ggpattern} defaults (that are now unset) to minimize visual changes downstream:
shape of grid.pattern_regular_polygon() (and the registered default pattern_shape
of the "regular_polygon" pattern) is now "convex6" (hexagons) instead of "convex4".
Use shape = "convex4" to restore the previous appearance.fill of grid.pattern_magick() is now gp$fill %||% "grey80" (previously "grey20" ignoring gp$fill)
matching the generic default pattern_fill that patternGrob() already used for the "magick" pattern.
Use fill = "grey20" to restore the previous appearance.linewidth, size, nor gp$lwd is given) is now 0.5
instead of 1 for both patternGrob() and the grid.pattern_<name>() functions
so default lines are now half as thick.
The generic default of pattern_size is likewise now gp$lwd %||% 0.5.{ggpattern} aesthetics pattern_phase and pattern_option_1 - pattern_option_5
(which no builtin pattern uses) now have a generic default of 0
A custom pattern drawn by patternGrob() that used params$pattern_option_1 %||% my_default
(or checked is.null(params$pattern_phase)) to pick its own default when unset now always gets 0
and should instead register its defaults with register_pattern(defaults = ).The default resolution pattern_res (res argument) of array patterns, the "gradient" pattern,
and the raster fallbacks of alphaMaskGrob() and clippingPathGrob()
(if the package option ggpattern_res is unset) is now computed when drawn
from the resolution of the graphics device instead of being 72 pixels per inch:
1.14 times the device resolution (e.g. about 82 on pdf() / svg() devices and 342 on a 300 ppi png()).
This is sharper on high resolution devices but uses more memory and time.
A numeric legend key's default resolution is 1.3 * legend * pattern_key_scale_factor times the device resolution
so array patterns in legend keys resemble those in the (larger) plot panels.
These match the resolutions {ggpattern} (<= 1.3.1) computed itself.
The res argument of the grid.pattern_<name>() functions, alphaMaskGrob(), and clippingPathGrob()
now defaults to NULL (unset).
pattern_units (units argument) may no longer be "npc", "native", nor "null" (now an error, #115).
Pattern lengths (e.g. pattern_spacing, pattern_xoffset, and pattern_yoffset) were always converted
along the viewport's width so "npc" and "native" ignored the viewport's height (even for vertical offsets)
and "null" lengths are zero (which threw an obscure error).
Use "snpc" (the default) for lengths relative to the viewport or an absolute unit such as "cm" or "in".
legend argument of patternGrob() / grid.pattern() may now be a non-negative number s
to draw a legend key showing (the centre of) the pattern as it would be drawn in an area
s times the width and height of the key
(TRUE is equivalent to 1 and FALSE to 0).
The pattern is drawn in a centred viewport s times larger than the key so all relative lengths
(e.g. "snpc" spacings, offsets, and wave amplitudes, including those of custom patterns)
scale together while absolute lengths (e.g. line widths, font sizes, "cm" units, and array pixels) don't.
The pattern functions themselves are still passed a logical legend value.
{ggpattern} now uses this to scale its legend keys instead of rescaling
pattern_spacing, pattern_xoffset, and pattern_yoffset itself.legend key is now zoomed by the pattern_key_scale_factor parameter (key_scale_factor argument):
the legend viewport is legend * pattern_key_scale_factor times larger than the key
and if pattern_units isn't "snpc" then the pattern's key_scaling parameters are multiplied by
(a power of) pattern_key_scale_factor
so legend keys of patterns with absolute units (e.g. "cm") can be zoomed too.
register_pattern()'s new key_scaling argument (a named vector of powers) sets these parameters:
by default c(pattern_spacing = 1, pattern_xoffset = 1, pattern_yoffset = 1)
while the "wave" pattern also zooms pattern_amplitude (1) and pattern_frequency (-1).
This zoom is applied after all the defaults are filled in
so (function) defaults always see the parameters as drawn in the plot
e.g. a registered default for pattern_key_scale_factor may zoom out a legend key more for larger spacings
list(pattern_spacing = 0.025, pattern_key_scale_factor = function(params, gp) min(1, 0.025 / params$pattern_spacing)).
A logical legend (as passed by {ggpattern} 1.3.1 and earlier, which zoom their keys themselves)
is not zoomed by pattern_key_scale_factor.
Previously only the "magick" pattern used pattern_key_scale_factor (which it still does for any legend key).prefer_pattern()'s new must_exist argument controls what happens if a preferred pattern isn't (yet) registered:
NA (the default) warns, TRUE errors, and FALSE neither warns nor loads the pattern's package (useful in an .Rprofile).
It likewise controls what happens if the user has more than one pattern with that name
(via the legacy ggpattern_geometry_funcs / ggpattern_array_funcs options).
Previously preferring a pattern that wasn't registered was always an error.local_prefer_pattern() sets pattern preferences until the current function (or test) exits
and then restores any previous preferences (#113).local_pattern()'s new prefer argument also prefers the registered pattern
until the current function (or test) exits if TRUE.has_registered_pattern() returns whether a pattern name is taken
(even if it doesn't resolve e.g. because of a conflict)
i.e. whether registering a pattern with that name would clobber or conflict with a pre-existing pattern.as.patternGrob() creates a pattern grob whose boundary is (the area filled by) an existing grid grob (#131).with_pattern() fills each area of an object with a pattern (#131).area_boundaries() splits a grid grob into one boundary grob per such area.Resolving pattern names (e.g. by patternGrob()) and registered_patterns() / conflicting_patterns()
are faster when many patterns are registered
(e.g. both are about 20 times faster with 1000 registered patterns).
registered_patterns() and conflicting_patterns() no longer load the package of a preferred pattern
(previously the first call omitted that package's patterns
and listed no pattern with that name as active).
A qualified pattern name "pkg::name" no longer resolves to a stale registration
left behind by a {pkg} that was unloaded and can no longer be loaded (e.g. because it was removed)
so has_pattern() now returns FALSE and prefer_pattern(must_exist = TRUE) now errors for it.
The raster fallbacks of alphaMaskGrob() and clippingPathGrob()
(used by the "hatch", "line", "rose", and "text" patterns when masks / clipping paths aren't supported by the graphics device)
now only rasterise the (pixel-snapped) bounding box of the masker / clipper within the viewport
instead of the whole viewport (if it can be computed with grobCoords() in R 4.2+).
This is much faster and uses much less memory for small boundaries in large viewports,
in particular for a numeric legend (e.g. {ggpattern} legend keys).
When the png_device doesn't support clipping paths the raster fallback of clippingPathGrob()
now ignores the graphical parameters of the clipper (and its children) like native clipping paths
(previously e.g. a clipper with fill = NA clipped to the outline drawn by its stroke)
and its clip edge is now anti-aliased (if the png_device anti-aliases)
instead of keeping or dropping whole pixels (#117).
The (forced) child of alphaMaskGrob() is now always named "alpha_mask"
and the (forced) child of clippingPathGrob() is now always named "clip"
(previously the raster fallbacks drawn with native masks / clipping paths on a {ragg} or png_device device
used an automatic grid name).
If {ragg} (>= 1.2.0) isn't installed the default png_device of the raster fallbacks of
alphaMaskGrob() and clippingPathGrob() (and the patterns that use them)
is now grDevices::png(type = "cairo") if R has Cairo (#128).
Previously it was ragg::agg_png() (if an older {ragg} was installed, which lacks clipping paths and masks)
or else grDevices::png() which on Windows always uses GDI,
on macOS uses Quartz (which only supports clipping paths in R >= 4.3.0 and alpha masks in R >= 4.5.0),
and elsewhere doesn't use Cairo if R lacks Pango (getOption("bitmapType") is then "Xlib").
grid::grobCoords() of a patternGrob() is now the coordinates of its boundary
(without building the pattern).
The "hatch" pattern types drawn by other patterns
(e.g. "or" circles, "olive", "proper" waves, Goodman "steel" and "copper", and Unicode "cendree" checkers)
now pass on pattern_units, pattern_xoffset, and pattern_yoffset.
Previously their spacing was always interpreted as "snpc" units
(while their density was computed from the spacing in pattern_units units)
and their offsets were ignored.
The builtin patterns' registered defaults now agree with the defaults of their grid.pattern_<name>() functions
(so patternGrob() / {ggpattern} and grid.pattern_<name>() render the same when a parameter is unset):
pattern_subtype = "combinatorial" (previously an unset subtype was already treated as "combinatorial").pattern_shape = "X" (previously the generic 1).aspect_ratio argument of grid.pattern_gradient(), grid.pattern_image(), grid.pattern_magick(),
grid.pattern_placeholder(), and grid.pattern_plasma() now defaults to NA (use the aspect ratio of the
current viewport, as patternGrob() does) instead of 1
so their raster approximations are no longer distorted in non-square viewports.The "circle", "regular_polygon", "rose", "text", and "weave" patterns (and the patterns drawn with them e.g. "pch", "polygon_tiling", and the "cendree" hatch) are much faster when the pattern grid is dense (many points per viewport) (#119).
Patterns now draw nothing (a grid::nullGrob()) instead of throwing an error (or building a huge pattern grid)
in a viewport whose width or height is smaller than a device pixel (including zero or negative)
e.g. a {ggpattern} panel squeezed to nothing (or beyond) by a wide legend in a small plot pane (#119).
Previously the geometry patterns threw invalid '(to - from)/by' or wrong sign in 'by' argument
(their default "snpc" spacing was zero or negative) and the "plasma" pattern threw the dims contain negative values.
The patterns with a two-dimensional grid ("circle", "regular_polygon", "rose", "text", "weave",
and the hatch types they draw e.g. "cendree") now draw nothing (a grid::nullGrob())
instead of possibly exhausting memory when their grid would have more than ten million points (#119).
The geometry patterns drawn with {sf} (e.g. "circle", "crosshatch", "regular_polygon", "stripe", "wave", and "weave")
now fill every lobe of a self-intersecting boundary (e.g. a "bow tie" polygon).
Previously only one lobe was filled (the zero-width buffer that cleaned up the boundary kept only one).
The boundary is now first made valid with sf::st_make_valid()
(which needs GEOS 3.8 (2019) or newer, otherwise the previous behaviour is kept).
The "seagal" and "seagalbw" placeholder types work again
(their URLs used a nonexistent www. subdomain of stevensegallery.lucidinternets.com, #118).
Placeholder types that return greyscale images (e.g. "murray", "murraybw", "picsumbw", and "seagalbw") no longer throw an error (their single channel images weren't promoted to RGBA arrays).
An unknown placeholder type now actually falls back to the "bear" placeholder
(as its warning claims) instead of a "dummy" placeholder image.
A placeholder type that isn't length one now also falls back to "bear"
(the default type) instead of "kitten".
The "stripe", "crosshatch", and "weave" patterns now cycle multiple fill (and fill2), colour,
linewidth, linetype, and (except for "weave") density values by stripe
like the "wave" and "regular_polygon" patterns do:
the stripes of each set of values are clipped to the boundary separately
(so these patterns' grobs are now gTrees with a polygon grob child per set of values).
Previously multiple fill, colour, linewidth, and linetype values were recycled over
the pieces of the stripes clipped to the boundary (in the order of the sf::st_intersection() output)
so when the boundary was several polygons a stripe could change colour from polygon to polygon
and multiple density values were an error
("weave" still needs a single density but now says so clearly).
The stripes are counted from the stripe through the centre of the viewport
so for a single polygon they may now start with a different colour than before.
The "wave" pattern now cycles multiple density values by row like its other parameters
(previously an error since the density of each row was recycled but never used).
Its grob is now named "wave" (previously it was misnamed "regular_polygon").
A pattern of NA draws nothing in patternGrob() / grid.pattern() (like "none")
instead of being an error when the grob is drawn.
pattern_amplitude parameter
nor for the {ambient} noise parameters (pattern_fractal, pattern_octaves, etc.).
These are now pattern-specific defaults of the builtin "wave" and "ambient" patterns.
A custom pattern that reads them should now set its own defaults
with register_pattern()'s defaults argument.
The generic defaults for pattern_frequency and pattern_gravity are now the constants
0.1 and "center" (matching {ggpattern}) instead of 1 / pattern_spacing and
a function of pattern_type; the "wave", "ambient", and "image" patterns override them.
pattern_subtype now has a generic default of NA (matching {ggpattern}) and like
pattern_type and pattern_gravity an NA value is treated as unset so pattern-specific defaults apply.
An NA pattern_res is also treated as unset (previously an obscure error).register_pattern() is now the recommended way for packages to register patterns
(in their .onLoad() function, ideally wrapped in rlang::on_package_load())
instead of setting the ggpattern_geometry_funcs / ggpattern_array_funcs global options
which may clobber other registrations (#108).
register_pattern()'s defaults argument sets pattern-specific default parameter values
(constants or functions of the other parameters, named e.g. pattern_spacing or fill;
unprefixed names are an error unless declared in the unprefixed argument).
The builtin patterns now use this to register their pattern-specific defaults.patternGrob() caches the pattern resolved when the grob is created so redraws
(e.g. resizing an interactive device) still work if the pattern is later unregistered or masked."gridpattern::stripe" or "pkg::name".unregister_pattern() can be used to unregister a pattern.
prefer_pattern("owner::name") sets preferences and unprefer_pattern(name) removes them
(both are vectorized and return the previous preferences so they can be restored).
Bare pattern names resolve to the pattern preferred by prefer_pattern() (if any) and otherwise to the pattern of the only owner (the user, {gridpattern}, or a package) with that name.
If more than one owner has a pattern with that name there is a conflict and an error asks for either a qualified name or a prefer_pattern() preference (similar to the {conflicted} package).
conflicting_patterns() lists patterns whose bare names are shared by more than one pattern
has_pattern() returns whether a pattern name resolves to a pattern.
local_pattern() registers a pattern until the current function (or test) exits and then restores any previous registration (useful in tests and examples).
pattern_subtype was NA
(the {ggpattern} default) instead of NULL (#106).prefer_pattern()) instead of always throwing an error."indented" (formerly "triangle") wave type now uses a wider stroke
in order to better match the apparent stroke widths of the new wave types.
Users who relied on the previous visual appearance should reduce density
to compensate.New "hatch" pattern with corresponding grid.pattern_hatch() and names_hatch() (#97).
New "line" pattern with corresponding grid.pattern_line().
Unlike the "stripe" pattern which fills bands with solid colour,
"line" draws stroked lines using the device's native line rendering,
enabling all of R's built-in linetype values
(including "dotdash", "twodash", and custom line types specified as hex strings per ?par).
The preexisting "wave" pattern gains ten new type values, a reverse parameter, a stagger parameter, and names_wave (#100, #101).
New mix_col() that mixes colors via Munsell color space using aqp::mixMunsell().
Requires the suggested package {aqp}.
Fixes a bug where geometry-based patterns (e.g. "stripe", "crosshatch", "wave")
could silently disappear in small viewports when pattern_key_scale_factor
was a relatively large value (#95).
The following "placeholder" pattern updates (#83):
The following placeholder pattern names are now serviced by placecats.com
The following placeholder pattern names are now serviced by placehold.co
The "placeholderbw" name now provides a pure black-and-white image (i.e. no grey).
Fixes a bug where the "wavy" (aliases "sine", "undy") and "indented" (alias "triangle") wave types had an effective wavelength of (n-1)/n times the requested wavelength, where n is the number of wavelength-spaced grid positions spanning the viewport.
grid.pattern_aRtsy() with
patterns powered by the {aRtsy} package (#87).grid.pattern_weave() adds the new units parameter
that most other "geometry" pattern functions received in gridpattern v1.2.1.
The "polygon_tiling" pattern should now respect the units parameter
if set to a value different from the "snpc" default (#82).
For the "polygon_tiling" pattern type = "18.18.3*" the size of the
eighteen-sided polygons have been increased a teeny bit and
this polygon tiling should look a bit cleaner.
The following "placeholder" pattern updates (#83):
The following placeholder pattern names are now serviced by lucidinternets.com:
The following placeholder pattern names have been removed since their associated web service no longer works:
The "dummybw" name now provides a pure black-and-white image (i.e. no grey).
Fixes a regression for the "placeholderbw" name where it redirected to the "seagal" name instead of "placeholder".
type for the "placeholder" pattern
is now "bear" instead of "kitten".
Explicitly set type = "kitten" to continue to use
the "kitten" placeholder but note that although
the "kitten" placeholder website isn't completely down
it has been buggy recently (#73).patternFill() wraps patternGrob() to return a
grid::pattern() fill object (#70).
The "geometry" patterns (e.g. "circle", "stripe", etc.) now allow
the fill to be pattern fills (#67).
The "geometry" patterns (e.g. "circle", "stripe", etc.) now allow
the new units parameter to set which grid::unit() to use for the
the spacing, xoffset, and yoffset parameters
(and for the "wave" pattern also the amplitude and frequency parameters) (#58).
By default it will continue to be "snpc" units but can now be changed to "cm", "in", etc.
update_alpha() updates fill colour and/or pattern transparency.
ggplot2::fill_alpha() by @teunbrand.{ggplot2} or {scales}.usethis::use_standalone("trevorld/gridpattern", "standalone-update_alpha.R")
or simply copying standalone-update_alpha.R into your R directory and adding
grDevices, grid, and rlang to the Imports of your DESCRIPTION file.For completeness there is now a new "fill" pattern with corresponding
grid.pattern_fill() which draws a simple fill pattern.
For completeness there is now a grid.pattern_none() corresponding to the previously
supported "none" pattern which draws nothing.
wave pattern no longer quietly and incorrectly ignores the frequency parameter.
The effective wavelength of the wave pattern is now 1 / frequency instead of spacing.
However frequency will continue to default to 1 / spacing.clippingPathGrob() can now more efficiently compute a rasterGrob() approximation
via ragg::agg_capture() and for png_device functions that support
the clipping path feature such aspng(type = "cairo")(#74).alphaMaskGrob() can now more efficiently compute a rasterGrob() approximation
for png_device functions that support
the alpha mask feature such aspng(type = "cairo")(#75).alphaMaskGrob() and clippingPathGrob() now
switch back to the previously open graphics device if
they open and close any new graphics devices.pdf()
that can't handle the playing cards Unicode glyphs (#68).reset_image_cache() resets the image cache used by grid.pattern_image()
and grid.pattern_placeholder() to store images (#63).guess_has_R4.1_features() is now available as a "standalone" file.
You may copy its source under the permissive MIT No Attribution (MIT-0)
license into your own R package
by either using usethis::use_standalone("trevorld/gridpattern", "standalone-guess_has_R4.1_features.R")
or simply copying standalone-guess_has_R4.1_features.R into your R directory and
adding grDevices and utils to the Imports of your DESCRIPTION file.{vdiffr} has been updated to at least v1.0.6 (released 2023-08-25) then
guess_has_R4.1_features() should now always correctly guess R4.1 feature support for the
svglite::svglite() and vdiffr:::svglite() graphics devices.convert_polygon_sf_to_polygon_df() will now be a bit more
quiet (throw WARNINGs less often).guess_has_R4.1_features() can now also take advantage if dev.capabilities()
explicitly indicates that a feature is not supported in active graphics device.{ggplot2} one may now use the parameter linewidth to
set polygon/path line widths in
grid.pattern_circle(), grid.pattern_crosshatch(), grid.pattern_pch(),
grid.pattern_polygon_tiling(),
grid.pattern_regular_polygon(), grid.pattern_stripe(), grid.pattern_rose(),
grid.pattern_wave(), and grid.pattern_weave().
For backwards compatibility one may continue to use size as well.
Continue to use size (or gp) to set the fontsize in grid.pattern_text().
Both pattern_linewidth and pattern_size will be available
for use in custom patterns (#57).Fixes bug with grid.pattern_image() with type = "tile" (#47).
Additionally grid.pattern_image() now supports gravity argument when type = "tile".
If the active graphics device has also implemented the new R 4.2 dev.capabilities() support then
guess_has_R4.1_features() can now better guess R 4.1 graphic feature support when called within R 4.2.
guess_has_R4.1_features() can now better guess R 4.1 graphic feature support in the
{grDevices} bitmap devices (i.e. bmp(), jpeg(), png(), tiff())
when called within R 4.2 on Windows.
Previously it was not possible to easily distinguish on Windows if the device was called with
type = "windows" or type = "cairo" and hence we had to conservatively guess no such support
even if type = "cairo" had been specified (and within R 4.1 we must still conservatively do so).dev.capabilities() support then we should now be able to correctly guess such support within R 4.2
without needing to manually update guess_has_R4.1_features().guess_has_R4.1_features() now supports an argument features which allows one to
limit the guessing of R4.1 feature support to a subset of c("clippingPaths", "gradients", "masks", "patterns").
Although all known graphic devices either implements all or none of these features
this need not hold true in the future.
grid.pattern_rose() and grid.pattern_text() now "clip" their boundary using an
"alpha mask" rather than a "clipping path".
Now use the argument use_R4.1_masks, the global option ggpattern_use_R4.1_masks,
or the global option ggpattern_use_R4.1_features to toggle on/off the R 4.1 alpha mask
feature instead of using the use_R4.1_clipping argument or
the global option ggpattern_use_R4.1_clipping as before
(the latter continue to toggle on/off the R 4.1 clipping path feature in clippingPathGrob()).alphaMaskGrob() is a function that (alpha) masks one grob by using a second grob to specify the (alpha) mask.
use_R4.1_masks is TRUE we simply use the new R 4.1 (alpha) masks feature.use_R4.1_masks is FALSE we generate a grid::rasterGrob() approximation.use_R4.1_masks is NULL try to guess an appropriate choice.use_R4.1_masks can be set by options("ggpattern_use_R4.1_masks").guess_has_R4.1_features() now returns TRUE for the ragg::agg_jpeg(),
ragg::agg_ppm(), and ragg::agg_tiff() devices if packageVersion("ragg") >= '1.2.0'.
It also returns TRUE for svglite::svglite() if packageVersion("svglite") >= '2.1.0'.clippingPathGrob() will now consistently - as previously documented - use ragg::agg_png()
as the default png_device graphics device if it is available and use_R4.1_clipping is FALSE.grid.pattern_image() should no longer throw an inscrutable Error in magick_image_readpath...
error on certain platforms such as Windows (#47).guess_has_R4.1_features() is now an exported function.
It guesses whether the "active" graphic devices supports the
new R 4.1 graphics features and returns
TRUE or FALSE.grid.pattern_polygon_tiling() now supports the "elongated_triangular" type (#48).
"geometry" patterns now support a "elongated_triangle" grid value.guess_has_R4.1_features() now returns TRUE for the ragg::agg_png() and
ragg::agg_supertransparent() devices if packageVersion("ragg") >= '1.2.0'.
It now also returns TRUE for the grDevices::bmp(type = "cairo"),
grDevices::cairo_ps(), grDevices::jpeg(type = "cairo"),
and grDevices::tiff(type = "cairo") devices if getRversion() >= '4.1.0'.The package {magick} has been downgraded from "Imports" to "Suggests" (#44).
You'll need to manually install {magick} with install.packages("magick")
in order to use the following "array" patterns:
use_R4.1_gradients is FALSE)The following package option ggpattern_res can now be set by options().
It controls default "raster" image pattern resolution (pixels per inch).
Defaults to 72 (pixels per inch).
grid.pattern_polygon_tiling() now supports the following additional polygon tiling type's (#42):
"rhombille" implements a rhombille tiling of rhombi (#37)"tetrakis_square" implements a tetrakis square tiling of isosceles right triangles (#38)"2*.2**.2*.2**" implements a polygon tiling made of rhombi."2**.3**.12*" implements a polygon tiling made of rhombi, triangles, and twelve-pointed stars."3.3.3.3**" implements a polygon tiling made of triangles."3.3*.3.3**" implements a regular (star) polygon tiling made of triangles and three-pointed stars."3.3.3.12*.3.3.12*" implements a regular (star) polygon tiling made of triangles and twelve-pointed starts."3.3.8*.3.4.3.8*" implements a regular (star) polygon tiling of triangles,
squares, and eight-pointed stars."3.3.8*.4**.8*" implements a regular (star) polygon tiling made of triangles, four-pointed stars,
and eight-pointed stars."3.4.6.3.12*" implements a regular (star) polygon tiling made of triangles, squares,
hexagons, and twelve-pointed stars."3.4.8.3.8*" implements a regular (star) polygon tiling of triangles,
squares, octagons, and eight-pointed stars."3.6*.6**" implements a regular (star) polygon tiling made of triangles and six-pointed stars."4.2*.4.2**" implements a polygon tiling made of squares and rhombi."4.4*.4**" implements a regular (star) polygon tiling made of squares and four-pointed stars."4.6.4*.6" implements a regular (star) polygon tiling made of squares, hexagons, and four-pointed stars."4.6*.4.6*.4.6*" implements a regular (star) polygon of squares and six-pointed stars."4.8*.4**.8*" implements a polygon tiling of squares and eight-pointed stars."6.6*.6.6*" implements a regular (star) polygon of hexagons and six-pointed stars."8.4*.8.4*" implements a regular (star) polygon of octagons and four-pointed stars."9.3.9.3*" implements a regular (star) polygon of triangles, nonagons, and three-pointed stars."12.3*.12.3*" implements a regular (star) polygon tiling made of dodecagons and three-pointed stars."12.12.4*" implements a regular (star) polygon tiling made of dodecagons and four-pointed stars."18.18.3*" implements a regular (star) polygon tiling made of eighteen-sided polygons and three-pointed stars.grid.pattern_regular_polygon() now supports a "tetrakis_left" shape and "tetrakis_right" shape
which both draw an isosceles right triangle (one oriented left and one oriented right) as well as a
"rhombille_rhombus" shape which draws a rhombus.
These are non-regular polygons intended to help produce tetrakis square and rhombille polygon tilings.
star_angle() and star_scale() now handle the n_vertices == 2 case
(a "two-pointed star" polygon is a rhombus).grid.pattern_gradient() when use_R4.1_gradients=TRUE to better
match behavior when use_R4.1_gradients=FALSE.fill (and fill2) colour strings for
gridpattern_plasma() and gridpattern_gradient() (when use_R4.1_gradients=FALSE).pattern_square() for the "horizontal" and "vertical" types the value 1L is
now guaranteed to be in the center of the pattern (#46).grid::nullGrob()).legend = TRUE.Supports the following new patterns:
names_pattern is a new character vector of supported (builtin) patterns.
clippingPathGrob() is a function that clips one grob according to clipping path set by a second grob.
use_R4.1_clipping is TRUE we simply use the new R 4.1 clipping path featureuse_R4.1_clipping is FALSE we generate a grid::rasterGrob() approximationuse_R4.1_clipping is NULL try to guess an appropriate choice.use_R4.1_clipping can be set by options("ggpattern_use_R4.1_clipping")grid.pattern_gradient() now supports the argument use_R4.1_gradients
TRUE use the new R 4.1 gradient featureFALSE use a rasterGrob approximation (old behaviour)NULL try to guess an appropriate choice.use_R4.1_gradients can be set by options("ggpattern_use_R4.1_gradients")The following package options can now be set by options():
ggpattern_use_R4.1_clipping If TRUE use the grid clipping path feature introduced in R v4.1.0.
If FALSE do a rasterGrob approximation of the clipped pattern.
Currently used by clippingPathGrob(), grid.pattern_rose(),
grid.pattern_text(), and available for custom patterns.ggpattern_use_R4.1_features Set the default for all the other
ggpattern_use_R4.1_* options arguments.ggpattern_use_R4.1_gradients If TRUE use the grid gradient feature introduced in R v4.1.0.
If FALSE do a rasterGrob approximation of the gradient pattern.
Currently used by grid.pattern_gradient() and available for custom patterns.ggpattern_use_R4.1_masks If TRUE use the grid mask feature introduced in R v4.1.0.
Currently unused by this package but available for custom patterns.ggpattern_use_R4.1_patterns If TRUE use the grid pattern feature introduced in R v4.1.0.
Currently unused by this package but available for custom patterns.grid.pattern() now throws an error if there is a non-unique pattern name
(set by options("ggpattern_geometry_funcs") and/or options("ggpattern_array_funcs")).grid.pattern() draws a specified "pattern" to the active graphics device
while patternGrob() returns a "pattern" (grid) grob.
Supports the following original patterns:
Supports the following patterns from ggpattern:
grid.pattern_ambient()grid.pattern_circle() (#5)grid.pattern_crosshatch()(#4)grid.pattern_gradient()(#8)grid.pattern_image()(#9)grid.pattern_magick() (#6)grid::null()grid.pattern_placeholder() (#10)grid.pattern_plasma() (#7)grid.pattern_stripe() (#3)Enhancements made to the {ggpattern} patterns provided by this package:
Resolution of "array" patterns is now settable by new "pattern_res". Defaults to 72 pixels per inch but sets a minimum 12 pixel image width and/or height.
Default for "pattern_alpha" is now NA_real_ (preserve existing alpha transparency) instead of 1 (set to fully opaque).
grid.pattern_ambient() pattern supports all arguments of the six {ambient} "noise" functions.
grid.pattern_circle() has several enhancements:
xoffset and yoffset (#22)grid, type, and subtype to customize the pattern arrangement.fill colors now produces a more attractive pattern.density greater than 1 will now sometimes give an attractive result (#17).{sf} to clip circles to boundary instead of {gridGeometry}grid.pattern_crosshatch() allows using the argument fill2 to set
different fill color(s) for the "over" crosshatch lines (#14).
xoffset, yoffset, and spacing are now interpreted as "snpc" units and
grid.pattern_stripe() and grid.pattern_crosshatch() now allow using the
argument grid to tweak placement of lines so that they now match the placement
of circles from grid.pattern_circle() and polygons from grid.pattern_regular_polygon() (#24).
The center point of the geometry "grid" now matches the center of the viewport.
mean_col() is a utility function that computes an "average" color (#21)
star_scale() and star_angle() are utility functions for converting
between regular star polygon parameterizations (#39).
pattern_hex() returns an integer matrix indicating placement of multiple
colors (or other graphical elements) on a hex grid. Supports types listed in hex_names.
pattern_square() returns an integer matrix indicating placement of multiple
colors (or other graphical elements) on a rectangular grid. Supports types listed in square_names.
pattern_weave() returns a logical matrix indicating where the warp
lines should "up" for a specified weave pattern type and subtype. Supports
weaves listed in weave_names. In particular supports "irregular matt" and
"elongated twill" family of weave patterns including "zig-zag" and
"herringbone" variations.