How to add photos with aRboretum

Introduction

The aRboretum package allows you to enrich your HTML species labels with personal photos, such as herbarium specimens, field photographs, botanical garden shots, or other curated images. This vignette shows how to:

create the required folder structure using arboretum_photos();
place image files in the correct species folders; and
generate labels that automatically include a photo slideshow.

Prerequisites

Before adding photos, you should have aRboretum installed (see the installation section of the quickstart article) and a species dataset generated with arboretum_data(). The phrases generated by arboretum_phrases() are only needed later, to create the labels.

You should also have one or more image files for the species you want to illustrate.

Step 1. Prepare the species data

If you have not yet created your dataset, start with arboretum_data():

library(aRboretum)

spp_list <- c("Luetzelburgia bahiensis", "Paubrasilia echinata")

arboretum_data(
  spp_list = spp_list,
  save = TRUE,
  format = "csv",
  dir = "arboretum_data"
)

This creates a folder such as arboretum_data/ containing the exported species dataset and a data reviewing guide (__data_reviewing_guide.html) in which the data can be checked and corrected.

Step 2. Create the photo folder structure

Run arboretum_photos() with the path to your species data file:

arboretum_photos(
  data_path = "arboretum_data/arboretum_data.csv",
  verbose = TRUE
)

This creates a directory named arboretum_photos/ in your working directory. Inside, you will find one subfolder per species, named like this (if arboretum_photos/ already exists, only the missing species folders are added and existing ones are left untouched):

arboretum_photos/
├── FABACEAE_Luetzelburgia_bahiensis_photos/
└── FABACEAE_Paubrasilia_echinata_photos/

Step 3. Add your photo files

Place your image files inside the corresponding species folder.

Supported formats include:

.jpg
.jpeg
.png
.gif
.webp
.bmp
.svg

For example, for Paubrasilia echinata you might place:

arboretum_photos/FABACEAE_Paubrasilia_echinata_photos/
├── whole_paubrasilia.jpg
└── paubrasilia_fruit.png

There is no required file naming convention. All supported image files found in the folder are detected automatically.

When the labels are generated, photos larger than 1 MB are automatically compressed in the copy placed in the output folder, so the labels remain fast to load. Your original files are not modified.

Step 4. Generate the species phrases

The labels display the species phrases stored in the data file, so generate them first (and review or edit them in arboretum_data/__phrase_generating_guide.html if needed):

arboretum_phrases(
  data_path = "arboretum_data/arboretum_data.csv",
  printed_lang = c("pt", "en", "fr", "es")
)

Step 5. Generate labels with photos

Now run arboretum_labels() and indicate the photo folder with the photo_dir argument:

arboretum_labels(
  data_path = "arboretum_data/arboretum_data.csv",
  photo_dir = "arboretum_photos",
  dir = "arboretum_species_labels"
)

The function will:

copy the full arboretum_photos/ folder into the output directory;
rename the copied folder with a leading __ to avoid conflicts; and
compress the copied photos larger than 1 MB; and
embed the available species photos as a slideshow in each HTML label.

Step 6. View the labels

Open one of the generated HTML files in your browser, for example:

arboretum_species_labels/FABACEAE_Paubrasilia_echinata_label.html

If photos were found for that species, the label will include a slideshow section with:

image navigation arrows;
progress indicators; and
automatic cycling across the available photos.

How the output is organized

When arboretum_labels() is run with photo_dir = "arboretum_photos", the output directory typically looks like this:

arboretum_species_labels/
├── __arboretum_photos/
│   ├── FABACEAE_Luetzelburgia_bahiensis_photos/
│   │   └── ...
│   └── FABACEAE_Paubrasilia_echinata_photos/
│       ├── whole_paubrasilia.jpg
│       └── paubrasilia_fruit.png
├── FABACEAE_Luetzelburgia_bahiensis_label.html
└── FABACEAE_Paubrasilia_echinata_label.html

This keeps the photo assets associated with the generated labels while preserving portability of the output folder.

Next steps

To add personal recordings to the same labels, see the howto_audios article.

To build a quick end-to-end workflow from species list to final labels and minisite, see the quickstart article.

Adding personal photos to your species labels

Martin Boucknooghe & Domingos Cardoso

2026-10-05