Skip to contents

Generate printable QR code labels for plant collection specimens

Source: R/arboretum_qrcodes.R
arboretum_qrcodes.Rd

This function generates print-ready QR code labels for living plant collection specimens using a species data file, typically produced by arboretum_data(). Labels are arranged on A4 pages and saved as PDF or PNG files. If the number of labels exceeds the page capacity, the function automatically creates multiple output files, one per page.

Four visual layouts are available:

  • "minimalist" (default): a compact label with a thin border, scientific name in italic, optional first vernacular name, and QR code. All elements scale proportionally to the chosen label size.

  • "classic": a traditional botanical label with dark-green serif typography, scientific name, authorship, bold family name, optional vernacular name, optional language-specific endemism phrase, QR code, optional specimen identifier, and optional institutional logo.

  • "modern": a contemporary label with a slate-blue colour palette, clean sans-serif fonts throughout, a lightweight border, and the same information fields as "classic".

  • "botanical": a warm parchment-background label with brown earth-tone serif typography, an ornamental double border, and the same information fields as "classic".

In all "classic", "modern", and "botanical" layouts, all font sizes scale proportionally to both the label width and height, so the text remains readable at any custom size.

QR codes can link to species pages in a published minisite, to a single shared URL, to POWO or FFB source pages from the input data, or, when no URL is available, encode the taxon name as plain text.

Usage

arboretum_qrcodes(
  data_path = NULL,
  species = NULL,
  printed_lang = c("pt", "en", "fr", "es"),
  length = NULL,
  width = NULL,
  path_to_logo = NULL,
  layout = c("minimalist", "classic", "modern", "botanical"),
  id_code = NULL,
  base_url = NULL,
  url = NULL,
  color = NULL,
  font_family = "serif",
  format = c("pdf", "png"),
  verbose = TRUE,
  dir = "arboretum_qrcodes"
)

Arguments

data_path

Required. Character string giving the path to the mined species data file. The file must be in CSV or Excel format and is typically generated by arboretum_data(). It should contain, at minimum, taxonName and family. Additional columns such as scientificNameAuthorship, FFB.vernacularName, endemism, country, POWO.url, and FFB.url are used when available.

species

Character vector or NULL. Optional subset of species names to process. Values must match entries in the taxonName column. If NULL, all species in the input file are included. Default is NULL.

printed_lang

Character vector. Language code used for the endemism phrase in detailed labels ("classic", "modern", "botanical"). Accepted values are "pt", "en", "fr", and "es". When more than one language is supplied, the first valid value selected by match.arg() is used. Ignored for "minimalist" labels. Default is c("pt", "en", "fr", "es").

length

Numeric or NULL. Label height in centimetres. If NULL, the default is 2.5 cm for "minimalist" labels and 8.0 cm for detailed layouts. All text sizes scale proportionally.

width

Numeric or NULL. Label width in centimetres. If NULL, the default is 2.5 cm for "minimalist" labels and 6.0 cm for detailed layouts. All text sizes scale proportionally.

Character string or NULL. Optional path to a PNG or JPEG logo file. The logo is shown in "classic", "modern", and "botanical" labels, near the bottom-right corner. The image aspect ratio is preserved. If the logo file is missing or unsupported, the function warns and continues without it. Default is NULL.

layout

Character string. Label layout. One of "minimalist" (default), "classic", "modern", or "botanical".

id_code

Character vector or NULL. Optional specimen or collection identifier printed on detailed labels ("classic", "modern", "botanical"). If a single value matching a column name in the input data is supplied, values are taken from that column. Otherwise, supplied values are recycled or used directly. Ignored for "minimalist" labels. Default is NULL.

base_url

Character string or NULL. Root URL of a published minisite containing species label pages. When supplied, each QR code is linked to a species-specific HTML page using the same filename convention as arboretum_labels(): base_url/FAMILY_Genus_species_label.html. This option has priority over url, POWO.url, and FFB.url. Default is NULL.

url

Character string, character vector, or NULL. URL to encode in the QR code. If a single URL is supplied, it is used for all labels. If a vector is supplied, it should match the number of selected species. Ignored when base_url is supplied. Default is NULL.

color

Character string or NULL. Hex colour used for the dark QR modules. If NULL, the default dark forest green "#1a2e1a" is used.

font_family

Character string. Font family used for the scientific name. Any font available to the active R graphics device can be used. Common values include "serif", "sans", and "mono". Default is "serif".

format

Character string. Output file format. One of "pdf" or "png". Default is "pdf".

verbose

Logical. If TRUE, progress messages are printed to the console. Default is TRUE.

dir

Character string. Output directory where the QR code pages will be saved. The directory is created if it does not exist. Default is "arboretum_qrcodes".

Value

Invisibly returns a character vector with the paths to the saved output files, one path per generated page. The function is called mainly for its side effects:

  • reads the input species data;

  • optionally filters the data to selected species;

  • generates QR codes;

  • arranges labels on one or more A4 pages;

  • saves the pages as PDF or PNG files.

Details

The function follows five main steps:

  1. Input preparation

    • Reads the species data using an internal helper function.

    • Optionally filters the data to the species supplied in species.

    • Validates the output format, layout, output directory, and label dimensions.

  2. URL selection

    • If base_url is supplied, the function builds one species-specific minisite URL per label.

    • If base_url is not supplied but url is supplied, url is encoded.

    • If neither is supplied, the function uses POWO.url when available.

    • If POWO.url is unavailable, the function uses FFB.url when available.

    • If no URL is available, the taxon name is encoded as plain text.

  3. Page layout

    • Labels are arranged on A4 pages measuring 21.0 × 29.7 cm.

    • Pages use 0.8 cm margins and 0.4 cm gaps between labels.

    • The number of rows and columns is calculated automatically from the selected label dimensions.

    • Additional pages are created automatically when needed.

  4. Minimalist labels

    • Display the scientific name in italic.

    • Display the first vernacular name when available.

    • Display a QR code with a white quiet zone for scanning reliability.

  5. Classic / Modern / Botanical labels

    • Display scientific name, authorship, family, and first vernacular name when available.

    • Display a language-specific endemism phrase when endemism is "Endemic" and a country value is available.

    • Display an optional specimen identifier from id_code.

    • Display an optional logo when path_to_logo is supplied.

    • Display a QR code with a white quiet zone for scanning reliability.

    • All font sizes are computed from a single proportional scale factor min(width / 6, height / 8), so text remains readable at any size.

Output files are named arboretum_qrcodes.pdf or arboretum_qrcodes.png when all labels fit on one page. When multiple pages are needed, files are named arboretum_qrcodes_page01.pdf, arboretum_qrcodes_page02.pdf, and so on, or with the equivalent .png extension.

Note

  • The function does not publish minisites or verify that URLs are online.

  • For base_url, trailing slashes are removed before species-specific label filenames are appended.

  • The first vernacular name is used when FFB.vernacularName contains multiple names separated by "|".

  • PNG logos are read with png. JPEG logos require the jpeg package to be installed.

  • Unsupported or unreadable logos are ignored with a warning.

  • Very small custom label dimensions may make text difficult to read or QR codes difficult to scan.

See also

arboretum_data, arboretum_labels, arboretum_minisite

Author

Domingos Cardoso

Examples

if (FALSE) { # \dontrun{
# Minimalist QR codes using POWO or FFB URLs from the mined data
arboretum_qrcodes(
data_path = "arboretum_data/arboretum_data.xlsx"
)

# QR codes linked to species pages in a published minisite
arboretum_qrcodes(
data_path = "arboretum_data/arboretum_data.xlsx",
base_url = "https://dboslab.github.io/jbrj-arboretum"
)

# Classic labels with specimen IDs and a logo
arboretum_qrcodes(
data_path = "arboretum_data/arboretum_data.xlsx",
species = c("Euterpe edulis", "Paubrasilia echinata"),
layout = "classic",
printed_lang = "pt",
base_url = "https://dboslab.github.io/jbrj-arboretum",
id_code = c("JBRJ-001", "JBRJ-002"),
path_to_logo = "path/to/institution_logo.png",
format = "pdf"
)

# Modern labels using specimen IDs stored in a data column
arboretum_qrcodes(
data_path = "arboretum_data/arboretum_data.xlsx",
layout = "modern",
id_code = "accession_id",
printed_lang = "en"
)

# Botanical labels with warm parchment style
arboretum_qrcodes(
data_path = "arboretum_data/arboretum_data.xlsx",
layout = "botanical",
printed_lang = "pt",
base_url = "https://dboslab.github.io/jbrj-arboretum",
format = "pdf"
)

# Larger minimalist PNG labels with a custom QR colour
arboretum_qrcodes(
data_path = "arboretum_data/arboretum_data.xlsx",
width = 3.5,
length = 3.5,
color = "#3b1f0a",
format = "png"
)
} # }