scanarea

scanarea provides reproducible batch estimation of projected plant area from scanned images. It is designed for standardized flatbed scans of leaves, needles, and other plant material, including scans where many plant structures occur in a single image.

The package converts images to grayscale, separates plant material from the background using Otsu thresholding, optionally masks image edges and removes small objects, and converts the resulting foreground pixel count to projected area in square centimetres using the scan DPI.

The main user-facing function is process_leaf_scans(). One call processes all supported images in a scan-set folder using one common set of processing settings.

Installation

Install scanarea from GitHub with pak:

install.packages("pak")
pak::pak("lsigut/scanarea")

Then load the package with:

library(scanarea)

Quick start

A scan set is a folder containing one or more scan images and, optionally, one CSV settings file whose name starts with settings.

A typical project structure is:

project/
├── data/
│   └── my_scan_set/
│       ├── scan_001.png
│       ├── scan_002.png
│       └── settings_my_scan_set.csv
├── output/
└── figs/

Process the complete scan set with:

library(scanarea)

result <- process_leaf_scans(
  scan_dir = "./data/my_scan_set",
  output_root = "./output",
  figure_root = "./figs",
  save_plots = TRUE
)

result

Supported image extensions are jpg, jpeg, png, tif, and tiff by default. They can be restricted with the extensions argument if needed.

Bundled example

A small representative needle scan and its settings file are included with the package. The example uses a forced DPI of 800 so that the physical area conversion is reproducible and does not depend on image metadata.

library(scanarea)

scan_dir <- system.file(
  "extdata",
  "example_scan_set",
  package = "scanarea",
  mustWork = TRUE
)

output_root <- file.path(
  tempdir(),
  "scanarea-example"
)

result <- process_leaf_scans(
  scan_dir = scan_dir,
  output_root = output_root,
  save_plots = FALSE
)

result

output_dir <- file.path(
  output_root,
  basename(scan_dir)
)

# Typical output files
list.files(output_dir)

The bundled example is intentionally small and is intended for package examples and automated tests. A full example dataset containing raw and manually cleaned needle scans, processing settings, reproducible processing scripts, reference outputs, and diagnostic figures is available from Zenodo:

Full example dataset: https://doi.org/10.5281/zenodo.22729820

The example workflow was developed in the context of foliar sampling at Czech ICOS ecosystem stations and can support projected leaf or needle area determination for leaf mass per area (LMA) calculations.

How processing works

For each scan set, scanarea performs the following steps:

1. Finds the settings CSV or creates a default one if no settings file is present.
2. Finds all supported image files in the scan-set folder.
3. Obtains the DPI from image metadata, unless a known DPI is forced in the settings file.
4. Reads each image and converts RGB or RGBA images to grayscale.
5. Applies Otsu thresholding. Plant material is expected to be darker than the background.
6. Optionally masks pixels along the top, bottom, left, or right image edges.
7. Labels connected foreground objects and optionally removes objects smaller than the specified pixel threshold.
8. Counts foreground and background pixels and converts pixel counts to square centimetres using the DPI.
9. Saves scan-level results, the exact settings used, and a processing log. Diagnostic processing plots are also saved when save_plots = TRUE.

Projected plant area is calculated as:

$$ \text{area [cm}^2\text{]} = \text{number of foreground pixels} \times \left(\frac{2.54}{\mathrm{DPI}}\right)^2 $$

In the results table, plant material corresponds to the foreground pixels and is reported as num_white_pixels and white_area_cm2. The term “white” refers to its representation in the binary image, not to the colour of the original plant material.

Processing example

The example below shows processing of a scan with densely arranged needles. The needles are separated from the scanner frame and do not overlap, while small image artefacts are still present. The diagnostic output allows the effects of thresholding, edge masking, and object filtering to be visually checked.

Example of scan processing

Diagnostic output showing the input scan, the binary image after Otsu thresholding and edge masking, and the final image after small-object filtering.

Processing settings

Settings are stored in a two-column CSV with columns parameter and value. The scan-set folder may contain at most one file matching settings*.csv. If none is found, scanarea creates a default settings file in the scan folder. If more than one is found, processing stops because the intended settings are ambiguous.

Parameter	Default	Meaning
force_dpi	FALSE	Use a user-specified DPI instead of image metadata.
forced_dpi	blank	DPI used when force_dpi = TRUE.
top_rows_to_remove	0	Number of pixels masked from the top edge.
bottom_rows_to_remove	0	Number of pixels masked from the bottom edge.
left_cols_to_remove	0	Number of pixels masked from the left edge.
right_cols_to_remove	0	Number of pixels masked from the right edge.
min_object_size_px	1	Minimum connected-object size retained, in pixels.

The default min_object_size_px = 1 means that no small-object filtering is applied. Edge masking is also disabled by default.

DPI is critical for physical area

By default, DPI is obtained from image metadata. Because the conversion from pixels to square centimetres depends directly on DPI, always verify that the DPI reported by scanarea matches the original scanner settings.

If image metadata are missing, invalid, or known to be unreliable, set force_dpi = TRUE and provide the correct value in forced_dpi. Processing stops rather than silently assuming a fallback DPI when valid metadata cannot be obtained.

Diagnostic plots

Diagnostic plots are saved by default (save_plots = TRUE) and contain three views of each processed scan:

• the grayscale input image;
• the binary image after Otsu thresholding and edge masking;
• the final binary image after connected-object filtering.

Visual inspection is particularly recommended when edge masking or small-object filtering differs from the defaults. This makes it possible to confirm that valid plant material has not been removed and that unwanted scanner-edge artefacts or debris have been handled as intended.

Set save_plots = FALSE when diagnostic plots are not needed, for example if raw scans were manually cleaned beforehand by removing scanner-edge artefacts or debris. Manual cleaning can reduce reproducibility because editing steps are difficult to document and repeat consistently, so package-based edge masking and object filtering are preferable where possible. If manual editing is used, document the procedure, avoid removing plant material, and verify that the DPI still matches the original scan resolution.

Output

For a scan set named my_scan_set, the default output structure is:

output/my_scan_set/
├── scan_results.csv
├── settings*.csv
└── processing_log.txt

figs/my_scan_set/
└── *_processing.png

The figure directory is created only when save_plots = TRUE.

scan_results.csv contains one row per scan image. Important columns include:

Column	Description
scan_name	Input image file name.
dpi	DPI used for the physical area conversion.
otsu_threshold	Otsu threshold calculated for the scan.
min_object_size_px	Minimum connected-object size used.
top_removed_px, bottom_removed_px	Edge masking applied vertically.
left_removed_px, right_removed_px	Edge masking applied horizontally.
num_white_pixels	Number of foreground plant pixels retained.
num_black_pixels	Number of background pixels.
white_area_cm2	Estimated projected plant area in cm².
black_area_cm2	Estimated background area in cm².

The copied settings CSV records the exact settings used for the run. processing_log.txt records processing time, input files, DPI information, output locations, whether diagnostic plots were saved, and R session information to support reproducibility.

Important assumptions and scope

scanarea is intended for standardized scans where plant material is darker than a relatively light background. Good contrast and consistent scanning conditions improve segmentation reliability.

All images in one scan-set folder are processed using the same settings. If scan conditions require different cropping, object filtering, or DPI settings, place those images in separate scan-set folders.

The package estimates total projected plant area from foreground pixels. It is not intended to identify individual leaves or needles or to provide object-level morphological measurements such as perimeter, length, or circularity.