gdtools

gdtools addresses four practical problems when working with fonts in R:

Problem	gdtools solution
Measure text without a device: layout calculations (column widths, text wrapping) need reliable metrics independent of the rendering device	strings_sizes(), from the font files
Register non-system fonts: Google Fonts, Liberation fonts or the math font STIX Two Math (bundled) must be made visible to ‘systemfonts’	font_set_liberation(), font_set_auto(), font_set(), register_stixmath()
Embed fonts in HTML: Shiny, R Markdown and girafe need htmlDependency objects so the browser loads the right fonts	font_set()$dependencies, gfontHtmlDependency(), liberation*HtmlDependency()
Check font availability: detect missing fonts before rendering, to avoid silent fallbacks	font_family_exists(), sys_fonts()

How font metric calculation works

gdtools was originally designed to compute font metrics for R graphic devices via C-level interfaces. With the arrival of the ‘systemfonts’ package, font discovery and matching became much simpler and the C interface was no longer needed by other packages.

The package has since been refocused. Font metric calculation follows two steps:

1. Font lookup: ‘systemfonts’ resolves the family name to a font file. Any font registered via systemfonts::register_font(), register_gfont(), or font_set() is found.
2. Metric computation: FreeType reads the metrics stored in the font file, without scaling or hinting: the glyph advances give the width, plus, on request, the kerning read from the tables of the font; the ink boxes of the glyphs give the ascent and the descent.

The metrics are independent of any graphic device and only depend on the font file: the same file gives the same values on every platform. Whether they match the final rendering depends on how the device resolves fonts on its side, this is a device concern.

Installation

You can install the released version of gdtools from CRAN with:

install.packages("gdtools")

And the development version from GitHub with:

# install.packages("remotes")
remotes::install_github("davidgohel/gdtools")

Font metrics

The main function for text measurement is strings_sizes(). It returns width, ascent and descent in inches. The measurements are accurate for devices that use ‘systemfonts’ for font resolution (ragg, svglite, ggiraph) and for cairo_pdf() when the font is also installed at the system level; for devices with their own font engine (pdf(), png(), …) the metrics may not match the rendering.

library(gdtools)
strings_sizes(
  c("a string", "a longer string"),
  fontsize = 24, 
  bold = TRUE, 
  italic = TRUE
)
#>      width    ascent    descent
#> 1 1.203939 0.2413737 0.07259115
#> 2 2.315104 0.2413737 0.07259115

All arguments are vectorized:

strings_sizes(
  c("normal", "bold", "italic", "bold-italic"),
  fontsize = 12,
  bold = c(FALSE, TRUE, FALSE, TRUE),
  italic = c(FALSE, FALSE, TRUE, TRUE)
)
#>       width    ascent     descent
#> 1 0.5094401 0.1195475 0.003173828
#> 2 0.3517253 0.1199544 0.003092448
#> 3 0.3334147 0.1195475 0.002929688
#> 4 0.7870280 0.1206868 0.003092448

Kerning

Kerning adjusts the space between some pairs of letters, such as “AV” or “To”. With kerning = TRUE, the width includes the kerning stored in the font file:

invisible(register_liberationsans())
strings_sizes("AVATAR", fontname = "Liberation Sans", fontsize = 12)$width
#> [1] 0.6668294
strings_sizes("AVATAR", fontname = "Liberation Sans", fontsize = 12, kerning = TRUE)$width
#> [1] 0.6173503

Use it when the text is drawn by a device that kerns (‘ragg’, ‘svglite’, ‘ggiraph’, cairo_pdf()), for example to place words or align text in ‘grid’ graphics. The default, kerning = FALSE, is the sum of the glyph advances. Ligatures and contextual kerning are not applied: see the section “Kerning” of ?strings_sizes.

Font management

font_set_auto() detects the best available system fonts and falls back to Liberation fonts when needed. It returns a font_set object ready to use with ggplot2, ggiraph, or any ‘systemfonts’-based device:

library(gdtools)

fonts <- font_set_auto()
fonts
#> Font set
#>   sans:    Arial [system]
#>   serif:   Times New Roman [system]
#>   mono:    Courier New [system]
#>   symbol:  Symbol [system]
#>   4 HTML dependencies

For explicit control, font_set() lets you pick each role with font_google(), font_liberation(), or a plain family name:

fonts <- font_set(
  sans  = font_google("Open Sans"),
  mono  = font_liberation("mono")
)

fonts$sans          # "Open Sans"
fonts$dsvg_fonts    # named list for dsvg() / girafe()
fonts$dependencies  # list of htmlDependency objects

For an offline-only setup, font_set_liberation() uses Liberation fonts for all four roles:

fonts <- font_set_liberation()
fonts

Going further

Google Fonts

A set of lower-level functions is provided to download and cache fonts from ‘Google Fonts’. They can be used in ‘R Markdown’ documents and ‘Shiny’ applications, as well as with graphic outputs generated by ‘ggiraph’, ‘ragg’ and ‘svglite’, or tabular outputs from ‘flextable’.

# Download and register with systemfonts (cached for future use)
register_gfont(family = "Open Sans")

Use addGFontHtmlDependency() to embed a Google Font in an HTML document, and gfontHtmlDependency() to create an htmltools dependency object.

To install a Google Font at the system level (e.g. in a Dockerfile), use install_gfont_script():

This is the beginning of the README. Read the rest at the original. Read the full README ↗