Developing Patterns (1) - Pattern Overview

Source: vignettes/developing-patterns-1.Rmd

Developing Patterns - overview

To develop a pattern for use with ggpattern you will need to:

  1. Decide whether this is a geometry-based pattern or an array-based pattern.
  2. Create a function with the required arguments and return value
  3. Use options() to let ggpattern know that a certain pattern name should be delegated to your function.

Pattern Classification - geometry-based and array-based

There are only 2 high-level classes of pattern supported by ggpattern - geometry-based and array-based.

Geometry-based patterns create a series of geometry objects and trim them (using sf:st_intersection(), polyclipGrob etc) to be within the boundary of the geom. For example, the ‘stripes’ pattern in ggpattern is a series of equally spaced rectangular polygons.

Array-based patterns are RGBA image arrays. Any supplied image will be processed by ggpattern to ensure it is masked to only apply to the area within the geom’s boundary.

Aesthetics - Descriptions and Defaults

Aesthetic summary - click to open/close
aesthetic description default possible values
pattern Name of the pattern to draw ‘stripe’ gridpattern::names_pattern
pattern_type Generic control option NA pattern-dependent
pattern_subtype Generic control option NA pattern-dependent
pattern_alpha Alpha 1 value in range [0, 1] or NA
pattern_linetype Stroke linetype 1 linetype
pattern_size Stroke linewidth 1 linewidth
pattern_shape Plotting shape 1 shapes
pattern_colour Stroke colour ‘grey20’ colour
pattern_fill Fill colour ‘grey80’ colour
pattern_fill2 Second fill colour ‘#4169E1’ colour
pattern_angle Rotation angle 30 angle in degrees
pattern_density Approx. fraction of area the pattern fills 0.2 value in range [0, 1]
pattern_spacing Spacing between repetitions of pattern 0.05 value in range [0, 1] (snpc units)
pattern_xoffset Shift pattern along x axis 0 value in range [0, 1] (snpc units)
pattern_yoffset Shift pattern along y axis 0 value in range [0, 1] (snpc units)
pattern_aspect_ratio Aspect ratio adjustment NA usual range [0.01, 10]
pattern_key_scale_factor Scale factor for pattern in legend 1
pattern_filename Image filename/URL ’’ Filename/URL
pattern_gravity Image placement ‘center’ magick::gravity_types
pattern_filter Image scaling filter ‘lanczos’ magick::filter_types
pattern_scale Scale 1 Multiplier
pattern_orientation Orientation ‘vertical’ ‘vertical’, ‘horizontal’, ‘radial’
pattern_phase Phase 0
pattern_frequency Frequency 0.1
pattern_option_1 - 5 Generic options for expansion 0

Aesthetics Usage by Pattern

Aesthetic Usage-by-Pattern - click to open/close
aesthetic circle pch polygon_tiling regular_polygon
pattern Y Y Y Y
pattern_type Y Y Y Y
pattern_subtype Y Y Y
pattern_alpha Y Y Y
pattern_linetype Y Y Y Y
pattern_size Y Y Y Y
pattern_shape Y Y
pattern_colour Y Y Y Y
pattern_fill Y Y Y Y
pattern_fill2
pattern_angle Y Y Y Y
pattern_density Y Y Y
pattern_spacing Y Y Y Y
pattern_xoffset Y Y Y Y
pattern_yoffset Y Y Y Y
pattern_aspect_ratio Y Y Y Y
pattern_key_scale_factor Y Y Y Y
pattern_filename
pattern_gravity
pattern_filter
pattern_scale
pattern_orientation
pattern_phase
pattern_frequency
pattern_option_1 - 5
aesthetic stripe crosshatch weave
pattern Y Y Y
pattern_type Y
pattern_subtype Y
pattern_alpha Y Y Y
pattern_linetype Y Y Y
pattern_size Y Y Y
pattern_shape
pattern_colour Y Y Y
pattern_fill Y Y Y
pattern_fill2 Y Y
pattern_angle Y Y Y
pattern_density Y Y Y
pattern_spacing Y Y Y
pattern_xoffset Y Y Y
pattern_yoffset Y Y Y
pattern_aspect_ratio Y Y Y
pattern_key_scale_factor Y Y Y
pattern_filename
pattern_gravity
pattern_filter
pattern_scale
pattern_orientation
pattern_phase
pattern_frequency
pattern_option_1 - 5
aesthetic ambient image placeholder magick gradient plasma
pattern Y Y Y Y Y Y
pattern_type Y Y Y Y
pattern_subtype
pattern_alpha Y Y Y Y Y Y
pattern_linetype
pattern_size
pattern_shape
pattern_colour
pattern_fill Y Y Y Y
pattern_fill2 Y Y
pattern_angle
pattern_density
pattern_spacing
pattern_xoffset
pattern_yoffset
pattern_aspect_ratio Y Y Y Y Y
pattern_key_scale_factor Y Y Y Y Y Y
pattern_filename Y
pattern_gravity Y
pattern_filter Y Y
pattern_scale Y Y Y
pattern_orientation Y
pattern_phase
pattern_frequency
pattern_option_1 - 5

There are a number of aesthetics which are part of the package, but not currently used in any patterns: pattern_subtype, pattern_phase, pattern_frequency and pattern_option_1 through to pattern_option_5. These may be useful for developing patterns outside of the package.

Geometry-based pattern functions - Formal Arguments and Return Values

All geometry-based pattern creation functions must:

  1. Have the exact function signature: function(params, boundary_df, aspect_ratio, legend)
    • params - parameters from the geom (the aesthetics) e.g pattern_fill
    • boundary_df - data.frame containing polygon information i.e. The polygon_df format.
    • aspect_ratio - the best guess that ggpattern is able to make as to the aspect ratio of the viewport in which this pattern is being rendered.
    • legend logical value to indicate whether or not this function is being called to render a key legend or the in-place geom fill.
  2. Return a grid grob object. This can be any valid grob including a grid::grobTree()

List of geometry-based patterns in ggpattern:

  • circle
  • crosshatch
  • pch
  • polygon_tiling
  • regular_polygon
  • stripe
  • weave

Array-based pattern functions - Formal Arguments and Return Values

All array-based pattern creation functions must:

  1. Have the exact function signature: function(width, height, params, legend)
    • width,height - dimensions of the bounding box of the geom area
    • params - parameters from the geom (the aesthetics) e.g pattern_fill
    • legend logical value to indicate whether or not this function is being called to render a key legend or the in-place geom fill.
  2. Return a 3D array of RGBA values (all values in the range [0, 1]).

List of array-based patterns in ggpattern:

  • ambient
  • gradient
  • image
  • magick
  • placeholder
  • plasma

The polygon_df data.frame format

The polygon_df is a very simple data.frame format to contain polygon values. This is used to pass the coordinates of the geom boundary from the geom to the pattern generating function.

It contains only ‘x’ and ‘y’ columns for the coordinates, and an ‘id’ column used to signify which polygon the coordinates belong to.

The following polygon_df data.frame contains 2 polygons:

#> Rows: 8 Columns: 3
#> ── Column specification ────────────────────────────────────────────────────────
#> Delimiter: ","
#> dbl (3): x, y, id
#> 
#> ℹ Use `spec()` to retrieve the full column specification for this data.
#> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
example data in ‘polygon_df’ format
x y id
0 0 1
1 0 1
1 1 1
0 1 1
0 0 2
2 0 2
2 1 2
0 1 2

Limitations of the ‘polygon_df’ format:

  • There is no support for polygons with holes.

Associating a function with ggpattern pattern name

There are two global option() values which can be set - one for geometry-based patterns, and the other for array-based patterns.

The global values should point to a named list, where the names are the pattern names you want to use within ggpattern, and the the named values are the actual functions.

options(ggpattern_array_funcs    = list(your_pattern_name = your_pattern_function))
options(ggpattern_geometry_funcs = list(your_pattern_name = your_pattern_function))

Next Steps