Package 'pliman'

Description

Subsetting method for image objects

Usage

## S3 method for class 'image'
x[i, j, k, ..., drop = FALSE]

Arguments

Description

High-performance C++ implementation of Enhanced Correlation Coefficient (ECC) maximization with multi-scale Gaussian pyramids for sub-pixel image alignment.

Usage

align_stack_cpp(
  images,
  ref_idx = 0L,
  method = "ecc",
  crop = TRUE,
  levels = 3L,
  max_iter = 50L,
  eps = 1e-04,
  verbose = TRUE
)

Arguments

Value

A named list containing aligned, matrices, statuses, and crop_box.

Description

• analyze_objects() provides tools for counting and extracting object features (e.g., area, perimeter, radius, pixel intensity, Haralick texture, veins, and Fourier descriptors) in an image using an ultra-fast, cache-optimized C++ computer vision engine. See more at the Details section.

• analyze_objects_iter() provides an iterative section to measure object features using an object with a known area.

• plot.anal_obj() produces a histogram or density plot for object measures or R, G, and B values when argument object_index is used in analyze_objects().

• analyze_objects2() is maintained as an exact alias for analyze_objects().

Usage

analyze_objects(
  img,
  foreground = NULL,
  background = NULL,
  pick_palettes = FALSE,
  segment_objects = TRUE,
  viewer = get_pliman_viewer(),
  reference = FALSE,
  reference_area = NULL,
  back_fore_index = "R/(G/B)",
  fore_ref_index = "B-R",
  reference_img = NULL,
  reference_larger = FALSE,
  reference_smaller = FALSE,
  pattern = NULL,
  parallel = FALSE,
  workers = NULL,
  watershed = TRUE,
  veins = FALSE,
  sigma_veins = 1,
  veins_thinning = FALSE,
  veins_rel_erode = 0.005,
  ab_angles = FALSE,
  ab_angles_percentiles = c(0.25, 0.75),
  width_at = FALSE,
  width_at_percentiles = c(0.05, 0.25, 0.5, 0.75, 0.95),
  haralick = FALSE,
  har_nbins = 32,
  har_scales = 1,
  har_band = 1,
  smooth = FALSE,
  pcv = FALSE,
  pcv_niter = 100,
  resize = FALSE,
  trim = FALSE,
  fill_hull = FALSE,
  erode = FALSE,
  dilate = FALSE,
  opening = FALSE,
  closing = FALSE,
  filter = FALSE,
  return_exact = FALSE,
  filter_order = c("erode", "dilate", "opening", "closing", "filter", "fill_hull"),
  invert = FALSE,
  object_size = "medium",
  sensitivity = "medium",
  area_mode = c("contour", "pixel"),
  index = "NB",
  r = 1,
  g = 2,
  b = 3,
  re = 4,
  nir = 5,
  swir = 6,
  object_index = NULL,
  pixel_level_index = FALSE,
  return_mask = FALSE,
  efourier = FALSE,
  nharm = 10,
  threshold = "Otsu",
  k = 0.1,
  windowsize = NULL,
  tolerance = NULL,
  extension = NULL,
  lower_noise = 0.1,
  rel_size = NULL,
  lower_size = NULL,
  upper_size = NULL,
  topn_lower = NULL,
  topn_upper = NULL,
  lower_eccent = NULL,
  upper_eccent = NULL,
  lower_circ = NULL,
  upper_circ = NULL,
  randomize = TRUE,
  nrows = 1000,
  plot = TRUE,
  show_original = TRUE,
  show_chull = FALSE,
  show_contour = FALSE,
  show_bbox = FALSE,
  contour_col = "red",
  contour_size = 1,
  show_lw = FALSE,
  show_background = TRUE,
  show_segmentation = FALSE,
  col_foreground = NULL,
  col_background = NULL,
  marker = "point",
  marker_col = "red",
  marker_size = NULL,
  save_image = FALSE,
  max_pixels = 2e+06,
  prefix = "proc_",
  dir_original = NULL,
  dir_processed = NULL,
  verbose = TRUE
)

analyze_objects2(
  img,
  foreground = NULL,
  background = NULL,
  pick_palettes = FALSE,
  segment_objects = TRUE,
  viewer = get_pliman_viewer(),
  reference = FALSE,
  reference_area = NULL,
  back_fore_index = "R/(G/B)",
  fore_ref_index = "B-R",
  reference_img = NULL,
  reference_larger = FALSE,
  reference_smaller = FALSE,
  pattern = NULL,
  parallel = FALSE,
  workers = NULL,
  watershed = TRUE,
  veins = FALSE,
  sigma_veins = 1,
  veins_thinning = FALSE,
  veins_rel_erode = 0.005,
  ab_angles = FALSE,
  ab_angles_percentiles = c(0.25, 0.75),
  width_at = FALSE,
  width_at_percentiles = c(0.05, 0.25, 0.5, 0.75, 0.95),
  haralick = FALSE,
  har_nbins = 32,
  har_scales = 1,
  har_band = 1,
  smooth = FALSE,
  pcv = FALSE,
  pcv_niter = 100,
  resize = FALSE,
  trim = FALSE,
  fill_hull = FALSE,
  erode = FALSE,
  dilate = FALSE,
  opening = FALSE,
  closing = FALSE,
  filter = FALSE,
  return_exact = FALSE,
  filter_order = c("erode", "dilate", "opening", "closing", "filter", "fill_hull"),
  invert = FALSE,
  object_size = "medium",
  sensitivity = "medium",
  area_mode = c("contour", "pixel"),
  index = "NB",
  r = 1,
  g = 2,
  b = 3,
  re = 4,
  nir = 5,
  swir = 6,
  object_index = NULL,
  pixel_level_index = FALSE,
  return_mask = FALSE,
  efourier = FALSE,
  nharm = 10,
  threshold = "Otsu",
  k = 0.1,
  windowsize = NULL,
  tolerance = NULL,
  extension = NULL,
  lower_noise = 0.1,
  rel_size = NULL,
  lower_size = NULL,
  upper_size = NULL,
  topn_lower = NULL,
  topn_upper = NULL,
  lower_eccent = NULL,
  upper_eccent = NULL,
  lower_circ = NULL,
  upper_circ = NULL,
  randomize = TRUE,
  nrows = 1000,
  plot = TRUE,
  show_original = TRUE,
  show_chull = FALSE,
  show_contour = FALSE,
  show_bbox = FALSE,
  contour_col = "red",
  contour_size = 1,
  show_lw = FALSE,
  show_background = TRUE,
  show_segmentation = FALSE,
  col_foreground = NULL,
  col_background = NULL,
  marker = "point",
  marker_col = "red",
  marker_size = NULL,
  save_image = FALSE,
  max_pixels = 2e+06,
  prefix = "proc_",
  dir_original = NULL,
  dir_processed = NULL,
  verbose = TRUE
)

## S3 method for class 'anal_obj'
plot(
  x,
  which = "measure",
  measure = "area",
  type = c("density", "histogram"),
  ...
)

## S3 method for class 'anal_obj_ls'
plot(
  x,
  which = "measure",
  measure = "area",
  type = c("density", "histogram"),
  ...
)

analyze_objects_iter(pattern, known_area, verbose = TRUE, ...)

Arguments

Details

A binary image is first generated to segment the foreground and background. The argument index is useful to choose a proper index to segment the image (see image_binary() for more details). It is also possible to provide color palettes for background and foreground (arguments background and foreground, respectively). When this is used, a general linear model (binomial family) is fitted to the RGB values to segment fore- and background.

Then, the number of objects in the foreground is counted. By setting up arguments such as lower_size and upper_size, it is possible to set a threshold for lower and upper sizes of the objects, respectively. The argument object_size or sensitivity can be used to set up pre-defined values of tolerance and extension depending on the image resolution. This will influence the watershed-based object segmentation. Users can also tune up tolerance and extension explicitly for a better precision of watershed segmentation.

If watershed = FALSE is used, all pixels for each connected set of foreground pixels in img are set to a unique object. This is faster, especially for a large number of objects, but it is not able to segment touching objects.

There are some ways to correct the measures based on a reference object. If a reference object with a known area (reference_area) is used in the image and reference = TRUE is used, the measures of the objects will be corrected, considering the unit of measure informed in reference_area. There are two main ways to work with reference objects: * The first is to provide a reference object that has a contrasting color with both the background and object of interest. In this case, the arguments back_fore_index and fore_ref_index can be used to define an index to first segment the reference object and objects to be measured from the background, then the reference object from objects to be measured.

* The second one is to use a reference object that has a similar color to the

objects to be measured, but has a contrasting size. For example, if we are counting small brown grains, we can use a brown reference template that has an area larger (says 3 times the area of the grains) and then uses reference_larger = TRUE. With this, the larger object in the image will be used as the reference object. This is particularly useful when images are captured with background light. The argument reference_smaller can be used in the same way.

By using pattern, it is possible to process several images with common pattern names that are stored in the current working directory or in the subdirectory informed in dir_original. To speed up the computation time, one can set parallel = TRUE.

analyze_objects_iter() can be used to process several images using an object with a known area as a template. In this case, all the images in the current working directory that match the pattern will be processed.

• Additional measures:

  • If haralick = TRUE, the function computes 13 Haralick texture features for each object based on a gray-level co-occurrence matrix (Haralick et al. 1973).

  • If efourier = TRUE is used, an Elliptical Fourier Analysis (Kuhl and Giardina, 1982) is computed for each object contour using efourier().

  • If veins = TRUE, vein features are computed for each object using Difference of Gaussians (DoG) bandpass filtering.

  • If ab_angles = TRUE, the apex and base angles of each object are computed with poly_apex_base_angle().

  • If width_at = TRUE, the widths at given percentiles of object height are computed.

  • If pcv = TRUE, the Perimeter Complexity Value is computed.

Value

An object of class anal_obj (single image) or anal_obj_ls (batch).

Author(s)

Tiago Olivoto [email protected]

References

Haralick, R.M., K. Shanmugam, and I. Dinstein. 1973. Textural Features for Image Classification. IEEE Transactions on Systems, Man, and Cybernetics SMC-3(6): 610–621. doi:10.1109/TSMC.1973.4309314

Kuhl, F. P., and Giardina, C. R. (1982). Elliptic Fourier features of a closed contour. Computer Graphics and Image Processing 18, 236-258.

Examples

if (interactive()) {
library(pliman)
img <- image_pliman("soybean_touch.jpg")
obj <- analyze_objects(img)
obj$statistics

# Top-5 grains with largest area
top <- analyze_objects(img, marker = "id", topn_upper = 5)
top$results

# Reference object correction
img <- image_pliman("flax_grains.jpg")
res <- analyze_objects(img,
                       index = "GRAY",
                       reference = TRUE,
                       reference_area = 6,
                       reference_larger = TRUE,
                       lower_noise = 0.3)
}

if (interactive()) {
library(pliman)

img <- image_pliman("soy_green.jpg")
rgb <- analyze_objects(img,
                       marker = "id",
                       object_index = "B",
                       pixel_level_index = TRUE)
# density of area
plot(rgb)

# histogram of perimeter
plot(rgb, measure = "perimeter", type = "histogram")

# density of the blue (B) index
plot(rgb, which = "index")
}

Description

A lighter option to analyze_objects()

Usage

analyze_objects_minimal(
  img,
  segment_objects = TRUE,
  reference = FALSE,
  reference_area = NULL,
  back_fore_index = "R/(G/B)",
  fore_ref_index = "B-R",
  reference_larger = FALSE,
  reference_smaller = FALSE,
  pattern = NULL,
  parallel = FALSE,
  workers = NULL,
  watershed = TRUE,
  fill_hull = FALSE,
  opening = FALSE,
  closing = FALSE,
  filter = FALSE,
  erode = FALSE,
  dilate = FALSE,
  invert = FALSE,
  object_size = "medium",
  index = "NB",
  r = 1,
  g = 2,
  b = 3,
  re = 4,
  nir = 5,
  threshold = "Otsu",
  tolerance = NULL,
  extension = NULL,
  lower_noise = 0.1,
  lower_size = NULL,
  upper_size = NULL,
  topn_lower = NULL,
  topn_upper = NULL,
  lower_eccent = NULL,
  upper_eccent = NULL,
  lower_circ = NULL,
  upper_circ = NULL,
  plot = TRUE,
  show_original = TRUE,
  show_contour = TRUE,
  contour_col = "red",
  contour_size = 1,
  col_foreground = NULL,
  col_background = NULL,
  marker = FALSE,
  marker_col = NULL,
  marker_size = NULL,
  save_image = FALSE,
  max_pixels = 4e+06,
  prefix = "proc_",
  dir_original = NULL,
  dir_processed = NULL,
  verbose = TRUE
)

## S3 method for class 'anal_obj_minimal'
plot(
  x,
  which = "measure",
  measure = "area",
  type = c("density", "histogram"),
  ...
)

## S3 method for class 'anal_obj_ls_minimal'
plot(
  x,
  which = "measure",
  measure = "area",
  type = c("density", "histogram"),
  ...
)

Arguments

Author(s)

Tiago Olivoto [email protected]

Examples

if (interactive()) {
library(pliman)
img <- image_pliman("soybean_touch.jpg")
obj <- analyze_objects(img)
obj$statistics

}

if (interactive()) {
library(pliman)

img <- image_pliman("soy_green.jpg")
# Segment the foreground (grains) using the normalized blue index (NB, default)
# Shows the average value of the blue index in each object

rgb <- analyze_objects_minimal(img)
# density of area
plot(rgb)

# histogram of area
plot(rgb, type = "histogram") # or 'hist'
}

Description

Analyzes objects using shapefiles

Usage

analyze_objects_shp(
  img,
  nrow = 1,
  ncol = 1,
  buffer_x = 0,
  buffer_y = 0,
  prepare = FALSE,
  segment_objects = TRUE,
  viewer = get_pliman_viewer(),
  index = "R",
  r = 1,
  g = 2,
  b = 3,
  re = 4,
  nir = 5,
  shapefile = NULL,
  interactive = FALSE,
  plot = FALSE,
  parallel = FALSE,
  workers = NULL,
  watershed = TRUE,
  opening = FALSE,
  closing = FALSE,
  filter = FALSE,
  erode = FALSE,
  dilate = FALSE,
  object_size = "medium",
  efourier = FALSE,
  object_index = NULL,
  veins = FALSE,
  width_at = FALSE,
  verbose = TRUE,
  invert = FALSE,
  ...
)

Arguments

Details

The analyze_objects_shp function performs object analysis on an image and generates shapefiles representing the analyzed objects. The function first prepares the image for analysis using the image_prepare() function if the prepare argument is set to TRUE. If a shapefile object is provided, the number of rows and columns for splitting the image is obtained from the shapefile. Otherwise, the image is split into multiple sub-images based on the specified number of rows and columns using the object_split_shp() function. The objects in each sub-image are analyzed using the analyze_objects() function, and the results are stored in a list. If parallel processing is enabled, the analysis is performed in parallel using multiple workers.

The output object provides access to various components of the analysis results, such as the analyzed object coordinates and properties. Additionally, the shapefiles representing the analyzed objects are included in the output object for further analysis or visualization.

Value

An object of class anal_obj. See more details in the Value section of analyze_objects().

Examples

if (interactive()) {
library(pliman)

# Computes the DGCI index for each flax leaf
flax <- image_pliman("flax_leaves.jpg", plot =TRUE)
res <-
   analyze_objects_shp(flax,
                       nrow = 3,
                       ncol = 5,
                       plot = FALSE,
                       object_index = "DGCI")
plot(flax)
plot(res$shapefiles)
plot_measures(res, measure = "DGCI")
}

Description

Most of the functions in pliman can be applied to a list of images, but this can be not ideal to deal with lots of images, mainly if they have a high resolution. For curiosity, a 6000 x 4000 image use nearly 570 Megabytes of RAM. So, it would be impossible to deal with lots of images within R. apply_fun_to_img() applies a function to images stored in a given directory as follows:

• Create a vector of image names that contain a given pattern of name.

• Import each image of such a list.

• Apply a function to the imported image.

• Export the mutated image to the computer.

If parallel is set to FALSE (default), the images are processed sequentially, which means that one image needs to be imported, processed, and exported so that the other image can be processed. If parallel is set to TRUE, the images are processed asynchronously (in parallel) in separate R sessions (3) running in the background on the same machine. It may speed up the processing time when lots of images need to be processed.

Usage

apply_fun_to_imgs(
  pattern,
  fun,
  ...,
  dir_original = NULL,
  dir_processed = NULL,
  prefix = "",
  suffix = "",
  parallel = FALSE,
  workers = 3,
  verbose = TRUE
)

Arguments

Value

Nothing. The processed images are saved to the current working directory.

Examples

# apply_fun_to_imgs("pattern", image_resize, rel_size = 50)

Description

Coerce image pixel values to numeric vector

Usage

## S3 method for class 'image'
as.numeric(x, raw_to_scale = TRUE, ...)

Arguments

Description

Convert image to standard R raster matrix

Usage

## S3 method for class 'image'
as.raster(x, ...)

Arguments

Description

Combines multiple yolo_fewshot_model objects into a multi-class few-shot model.

Usage

## S3 method for class 'yolo_fewshot_model'
c(...)

Arguments

Value

A yolo_fewshot_multimodel object.

Description

Calibrating the actual size is possible if any interlandmark distance on the image is known. calibrate() can be used to determine the size of a known distance (cm) on the graph. I invite users to photograph the object together with a scale (e.g., ruler, micrometer...).

Usage

calibrate(img, viewer = get_pliman_viewer())

Arguments

Value

A numeric (double) scalar value indicating the scale (in pixels per unit of known distance).

References

Claude, J. (2008) Morphometrics with R, Use R! series, Springer 316 pp.

Examples

if(isTRUE(interactive())){
library(pliman)
#### compute scale (dots per unit of known distance) ####
# only works in an interactive section
# objects_300dpi.jpg has a known resolution of 300 dpi
img <- image_pliman("objects_300dpi.jpg")
# Larger square: 10 x 10 cm
# 1) Run the function calibrate()
# 2) Use the left mouse button to create a line in the larger square
# 3) Declare a known distance (10 cm)
# 4) See the computed scale (pixels per cm)
calibrate(img)

# scale ~118
# 118 * 2.54 ~300 DPI
}

Description

Computes several statistics to evaluate the agreement and accuracy between observed (real) and predicted values. It includes Lin's Concordance Correlation Coefficient (CCC), Pearson's correlation, Willmott's index of agreement, and error metrics like RMSE and Bias.

Usage

ccc(data, real, predito)

Arguments

Details

The function evaluates model performance through different lenses:

• Precision: Pearson's r and r2 measure how well the predicted values follow a linear relationship with the observed values.

• Accuracy/Agreement: ccc and d measure how close the predictions are to the 1:1 line (perfect agreement).

• Error magnitude: rmse, mae, and rrmse quantify the average deviation in absolute and relative terms.

• Directional Bias: bias indicates if the model consistently overestimates (positive) or underestimates (negative) the real values.

Lin's CCC is defined as:

$\rho_c = \frac{2 \cdot \text{Cov}(x, y)}{\text{Var}(x) + \text{Var}(y) + (\bar{x} - \bar{y})^2}$

Willmott's index of agreement (d) is defined as:

$d = 1 - \frac{\sum (y - x)^2}{\sum (|y - \bar{x}| + |x - \bar{x}|)^2}$

Value

A data frame with the following columns:

• r: Pearson correlation coefficient.

• r2: Coefficient of determination (R-squared).

• ccc: Lin's Concordance Correlation Coefficient.

• d: Willmott's Index of Agreement.

• rmse: Root Mean Squared Error.

• rrmse: Relative Root Mean Squared Error (%).

• mae: Mean Absolute Error.

• bias: Mean bias error.

Examples

library(dplyr)
library(pliman)
df <- data.frame(
  group = rep(c("A", "B"), each = 5),
  real = c(1:5, 2:6),
  predicted = c(1.1, 2, 2.9, 4.1, 5, 2.2, 3.1, 4, 4.8, 6.1)
)

# Without grouping
ccc(df, real, predicted)

# With grouping
df |>
  group_by(group) |>
  ccc(real, predicted)

Description

Deletes cached .rds files used by functions such as object_scatter(). You can either remove the entire cache directory or only files older than a given number of days.

Usage

clear_pliman_cache(all = TRUE, days = NULL)

Arguments

Value

Invisibly returns TRUE if the operation was successful.

Examples

if(interactive()){
# Clear everything
clear_pliman_cache()

# Clear only files older than 7 days
clear_pliman_cache(all = FALSE, days = 7)
}

Description

Provides the standard reference RGB values for the 24-patch ColorChecker Classic (Macbeth) chart in sRGB D65 color space.

Usage

colorchecker_ref(chart = c("colorchecker24", "macbeth"))

Arguments

Value

A data.frame with 24 rows and columns:

• id: Patch identifier (1 to 24).

• code: Patch code (No.001 to No.024).

• name: Descriptive name of the color patch.

• R, G, B: Standard reference sRGB values (0-255 scale).

• ref_R, ref_G, ref_B: Alias reference columns.

Examples

ref <- colorchecker_ref()
head(ref)

Description

Extracts the external contour of each object in a labeled matrix (e.g., from watershed segmentation). It returns a list of coordinates for each object.

Usage

contour(labels)

Arguments

Value

A list where each element is a matrix of (x, y) coordinates for the contour of the respective object.

Examples

library(pliman)
# generate a binary image
img <- image_pliman("soybean_touch.jpg")
bin <- image_binary(img, "B")[[1]]
# watershed segmentation
wat <- image_watershed(bin)
# extract contours
cont <- contour(wat)
plot(img)
plot_contour(cont, col = "red", lwd = 2)

Description

A list of contour outlines from five leaves. It may be used as example in some functions such as efourier()

Format

A list with five objects

• leaf_1

• leaf_2

• leaf_3

• leaf_4

• leaf_5

Each object is a data.frame with the coordinates for the outline perimeter

Author(s)

Tiago Olivoto [email protected]

Source

Personal data. The images were obtained in the Flavia data set downlodable at https://flavia.sourceforge.net/

Description

Fast C++ raster extraction engine without GDAL

Usage

cpp_extract_raster(
  values,
  n_row,
  n_col,
  n_lyr,
  bbox_raster,
  geoms_r,
  fun = as.character(c("none")),
  exact = FALSE,
  return_coverage_area = FALSE,
  subdiv = 10L,
  summarize_quantiles = as.numeric(c(0.05, 0.975))
)

Arguments

Description

This function generates a custom color palette using the specified colors and number of colors.

Usage

custom_palette(
  colors = c("yellow", "#53CC67", "#009B95", "#00588B", "#4B0055"),
  n = 5
)

Arguments

Value

A vector of colors representing the custom color palette.

Examples

# Generate a custom color palette with default colors and 10 colors
custom_palette()

# Generate a custom color palette with specified colors and 20 colors
custom_palette(colors = c("blue", "red"), n = 20)

# example code
library(pliman)
custom_palette(n = 5)

Description

Fast morphological dilation

Usage

dilate_cpp(img, raio = 3L, forma = "disc")

Arguments

Description

Computes the distance map transform of a binary image. The distance map is a matrix which contains for each pixel the distance to its nearest background pixel.

Usage

dist_transform(binary, normalize = FALSE)

Arguments

Value

An image object or an array, with pixels containing the distances to the nearest background points

Examples

if (interactive()) {
library(pliman)
img <- image_pliman("soybean_touch.jpg")
binary <- image_binary(img, "B")[[1]]
wts <- dist_transform(binary)
range(wts)
}

Description

dl_extract_phenotypes() bridges deep learning inference with botanical, agronomic, and biological measurement. It extracts granular phenotypes for every detected instance (seeds, fruits, leaves, lesions, roots) predicted by image_detect_dl(), image_segment_dl(), or image_detect_sahi().

Extracted traits include:

• Morphometry: Area (pixels and physical units like cm^2), perimeter, circularity, solidity, eccentricity, aspect ratio, and major/minor axes.

• Spectral Color Profiles: Mean R, G, B channels and user-selected vegetation/color indices (e.g., VARI, NGRDI, GLI, BGI).

• Texture Features: Haralick contrast, entropy, correlation, and homogeneity.

• Phytopathology & Severity: Automated disease severity percentage ((Lesion Area / Host Area) * 100) grouped per leaf.

Usage

dl_extract_phenotypes(
  data,
  img = NULL,
  pixel_size = NULL,
  extract_indexes = c("R", "G", "B", "VARI", "NGRDI"),
  haralick = FALSE,
  severity = FALSE,
  host_class = "leaf",
  lesion_class = "lesion",
  verbose = TRUE
)

Arguments

Value

An S3 object of class c("dl_phenotypes", "data.frame") containing per-object phenotypic traits.

Examples

## Not run: 
library(pliman)

# Segment leaves and lesions
res <- image_segment_dl("bean_rust.jpg", model = "bean_rust_yolo_seg.onnx")

# Extract comprehensive phenotypes & disease severity
pheno <- dl_extract_phenotypes(res, pixel_size = 0.02, severity = TRUE)
head(pheno)

## End(Not run)

Description

Computes Elliptical Fourier Analysis of closed outlines based on x and y-coordinates coordinates.

Usage

efourier(x, nharm = 10, align = FALSE, center = FALSE, smooth_iter = 0)

Arguments

Details

Adapted from Claude (2008). pp. 222-223.

Value

A list of class efourier with:

• the harmonic coefficients (an, bn, cn and dn)

• the estimates of the coordinates of the centroid of the configuration (a0 and c0).

• The number of rows (points) of the perimeter outline (nr).

• The number of harmonics used (nharm).

• The original coordinates (coords).

If x is a list of perimeter coordinates, a list of efourier objects will be returned as an object of class iefourier_lst.

References

Claude, J. (2008) Morphometrics with R, Use R! series, Springer 316 pp.

Kuhl, F. P., and Giardina, C. R. (1982). Elliptic Fourier features of a closed contour. Computer Graphics and Image Processing 18, 236-258. doi: doi:10.1016/0146-664X(82)90034-X

Examples

if (interactive()) {
library(pliman)
leaf1 <- contours[[4]]
plot_polygon(leaf1)

#### default options
# 10 harmonics (default)
# without alignment

ef <- efourier(leaf1)
efourier_coefs(ef)

# object is aligned along the major caliper with `poly_align()`
# object is centered on the origin with `poly_center()`
# using a list of object coordinates
ef2 <- efourier(contours, align = TRUE, center = TRUE)
efourier_coefs(ef2)

# reconstruct the perimeter of the object
# Use only the first one for simplicity
plot_polygon(contours[[1]] |> poly_align() |> poly_center())
efourier_inv(ef2[[1]]) |> plot_contour(col = "red", lwd = 4)
}

Description

Extracts the Fourier coefficients from objects computed with efourier() and efourier_norm() returning a 'ready-to-analyze' data frame.

Usage

efourier_coefs(x)

Arguments

Value

A data.frame object

Examples

if (interactive()) {
library(pliman)

# a list of objects
efourier(contours) |> efourier_coefs()

# one object, normalized coefficients
efourier(contours[[4]]) |>
  efourier_norm() |>
  efourier_coefs()
}

Description

Computes the sum of squared distances between the original data and reconstructed outline. It allows examining reconstructed outlines with the addition of successive contributing harmonics indicated in the argument nharm.

Usage

efourier_error(
  x,
  nharm = NULL,
  type = c("error", "outline", "deviations"),
  plot = TRUE,
  ncol = NULL,
  nrow = NULL
)

Arguments

Value

A list with the objects:

• dev_points A list with the deviations (distances) from original and predicted outline for each pixel of the outline.

• data.frame object with the minimum, maximum and average deviations (based on the outline points).

If x is an object of class efourier_lst, a list will be returned.

Examples

if (interactive()) {
library(pliman)
ef <-
  contours[[1]] |>
  efourier(nharm = 30)

efourier_error(ef)

efourier_error(ef,
               nharm = 30,
               type = "outline")

efourier_error(ef,
               nharm = c(1, 4, 20),
               type = "deviations")
}

Description

Performs an inverse elliptical Fourier transformation to construct a shape, given a list with Fourier coefficients computed with efourier().

Usage

efourier_inv(x, nharm = NULL, a0 = NULL, c0 = NULL, npoints = 500)

Arguments

Details

Adapted from Claude (2008). pp. 223.

References

Claude, J. (2008) Morphometrics with R, Use R! series, Springer 316 pp.

Examples

if (interactive()) {
library(pliman)
plot_polygon(contours, aspect_ratio = 1)
# without alignment
ef <- efourier(contours, nharm = 10, align = FALSE)
ief <- efourier_inv(ef)
plot_contour(ief, col = "red", lwd = 2)
}

Description

The first harmonic defines an ellipse that best fits the outlines. One can use the parameters of the first harmonic to "normalize" the data so that they can be invariant to size, rotation, and starting position of the outline trace. This approach is referred to in the literature as the normalized elliptic Fourier. efourier_norm() calculates a new set of Fourier coefficients An, Bn, Cn, Dn that one can use for further multivariate analyses (Claude, 2008).

Usage

efourier_norm(x, start = FALSE)

Arguments

Details

Adapted from Claude (2008). pp. 226.

Value

A list with the following components:

• A, B, C, D for harmonic coefficients.

• size the magnitude of the semi-major axis of the first fitting ellipse.

• theta angle, in radians, between the starting and the semi-major axis of the first fitting ellipse.

• psi orientation of the first fitting ellipse

• a0 and c0, harmonic coefficients.

• lnef the concatenation of coefficients.

• nharm the number of harmonics used.

References

Claude, J. (2008) Morphometrics with R, Use R! series, Springer 316 pp.

Examples

if (interactive()) {
library(pliman)
leaf1 <- contours[[4]]
plot_polygon(leaf1)

# compute the Fourier coefficients
ef <- efourier(leaf1)
efourier_coefs(ef)

# Normalized Fourier coefficients

efn <- efourier_norm(ef)
efourier_coefs(efn)
}

Description

Computes an spectrum of harmonic Fourier power. The power is proportional to the harmonic amplitude and can be considered as a measure of shape information. As the rank of harmonic increases, the power decreases and adds less and less information. We can evaluate the number of harmonics that we must select, so their cumulative power gathers 99% of the total cumulative power (Claude, 2008).

Usage

efourier_power(
  x,
  first = TRUE,
  thresh = c(0.8, 0.85, 0.9, 0.95, 0.99, 0.999),
  plot = TRUE,
  ncol = NULL,
  nrow = NULL
)

Arguments

Details

Most of the shape "information" is contained in the first harmonic. This is not surprising because this is the harmonic that best fits the outline, and the size of ellipses decreases as for explaining successive residual variation. However, one may think that the first ellipse does not contain relevant shape information, especially when differences one wants to investigate concern complex outlines. By using first = FALSE it is possible to remove the first harmonic for this computation. When working on a set of outlines, high-rank-harmonics can contain information that may allow groups to be distinguished (Claude, 2008).

Adapted from Claude (2008). pp. 229.

Value

A list with the objects:

• cum_power, a data.frame object with the accumulated power depending on the number of harmonics

• min_harm The minimum number of harmonics to achieve a given power.

References

Claude, J. (2008) Morphometrics with R, Use R! series, Springer 316 pp.

Examples

if (interactive()) {
library(pliman)
pw <- efourier(contours) |> efourier_power()
}

Description

Calculates a 'Fourier elliptical shape' given Fourier coefficients

Usage

efourier_shape(
  an = NULL,
  bn = NULL,
  cn = NULL,
  dn = NULL,
  n = 1,
  nharm = NULL,
  npoints = 150,
  alpha = 4,
  plot = TRUE
)

Arguments

Details

efourier_shape can be used by specifying nharm and alpha. The coefficients are then sampled in an uniform distribution $(-\pi ; \pi)$ and this amplitude is then divided by $harmonicrank ^ alpha$. If alpha is lower than 1, consecutive coefficients will thus increase. See Claude (2008) pp.223 for the maths behind inverse ellipitical Fourier

Adapted from Claude (2008). pp. 223.

Value

A list with components:

• x vector of x-coordrdinates

• y vector of y-coordrdinates.

References

Claude, J. (2008) Morphometrics with R, Use R! series, Springer 316 pp.

Examples

if (interactive()) {
library(pliman)
# approximation of the third leaf's perimeter
# 4 harmonics
image_pliman("potato_leaves.jpg", plot = TRUE)

efourier_shape(an = c(-7.34,  1.81,  -1.32, 0.50),
               bn = c(-113.88, 21.90, -0.31, -6.14),
               cn = c(-147.51, -20.89, 0.66, -14.06),
               dn = c(-0.48, 2.36, -4.36, 3.03))
}

Description

Produces a confidence ellipse that is an iso-contour of the Gaussian distribution, allowing to visualize a 2D confidence interval.

Usage

ellipse(
  x,
  conf = 0.95,
  np = 100,
  plot = TRUE,
  fill = "green",
  alpha = 0.3,
  random_fill = TRUE
)

Arguments

Value

A matrix with coordinates of points sampled on the ellipse.

Note

Borrowed from Claude (2008), pp. 85

References

Claude, J. (2008) Morphometrics with R, Use R! series, Springer 316 pp.

Examples

if (interactive()) {
library(pliman)
ellipse(contours)
}

Description

This function calculates the Shannon entropy of a numeric vector.

Usage

entropy(x)

Arguments

Value

A numeric value representing the entropy.

Examples

library(pliman)
x <- c(1, 2, 2, 3, 3, 3, 4, 4, 4, 4)
entropy(x)

Description

Standard morphological erosion

Usage

erode_cpp(img, raio = 3L, forma = "disc")

Arguments

Description

Fast external erosion

Usage

erode_external_cpp(img, raio = 3L, forma = "disc")

Arguments

Description

Fast conservative erosion pipeline

Usage

erosao_conservativa(img, raio_erosao = 3L, raio_dilatacao = 3L, forma = "disc")

Arguments

Description

Fast internal hole filling (with optional maximum hole size and neck distance check)

Usage

fill_holes_cpp(img, max_size = -1, min_neck_dist = 0)

Arguments

Description

High-performance native tools for focus stacking in digital imaging and microscopy:

• align_stack(): Sub-pixel image alignment and registration implemented natively in C++ using multi-scale Gaussian pyramid Enhanced Correlation Coefficient (ECC) maximization (affine motion or translation) to eliminate focus breathing, translation, and rotation, with optional automatic border cropping. Zero external Python/OpenCV dependencies.

• fuse_multifocus(): Multi-Focus Image Fusion (MFIF) supporting:

  1. Deep learning ONNX models (e.g., IFCNN) with either hierarchical tournament tree (strategy = "pyramid") or linear (strategy = "sequential") fusion.

  2. Ultra-fast native C++ Modified Laplacian Extended Depth of Field (method = "laplacian"), ideal for massive stacks of 50-500 images in < 1 second.

• process_focus_stack(): Orchestrates the complete end-to-end focus stacking pipeline, taking raw images, performing alignment, keyframe subsampling (max_frames), and fusion.

Usage

align_stack(
  images,
  reference_index = NULL,
  method = c("ecc", "translation", "orb"),
  crop = TRUE,
  levels = 3,
  max_iter = 50,
  eps = 1e-04,
  max_frames = NULL,
  verbose = TRUE,
  ...
)

image_align_stack(
  images,
  reference_index = NULL,
  method = c("ecc", "translation", "orb"),
  crop = TRUE,
  levels = 3,
  max_iter = 50,
  eps = 1e-04,
  max_frames = NULL,
  verbose = TRUE,
  ...
)

fuse_multifocus(
  images,
  method = c("ifcnn", "laplacian"),
  strategy = c("pyramid", "sequential"),
  blend = c("soft", "hard"),
  radius = 3,
  power = 6,
  max_frames = NULL,
  model = "ifcnn",
  engine = c("gpu", "cpu"),
  threads = 0L,
  device_id = -1L,
  verbose = TRUE,
  ...
)

image_fuse_multifocus(
  images,
  method = c("ifcnn", "laplacian"),
  strategy = c("pyramid", "sequential"),
  blend = c("soft", "hard"),
  radius = 3,
  power = 6,
  max_frames = NULL,
  model = "ifcnn",
  engine = c("gpu", "cpu"),
  threads = 0L,
  device_id = -1L,
  verbose = TRUE,
  ...
)

process_focus_stack(
  images,
  align = TRUE,
  align_method = c("ecc", "translation", "orb"),
  reference_index = NULL,
  crop = TRUE,
  levels = 3,
  max_iter = 50,
  eps = 1e-04,
  max_frames = NULL,
  method = NULL,
  fusion_method = c("ifcnn", "laplacian"),
  strategy = c("pyramid", "sequential"),
  blend = c("soft", "hard"),
  radius = 3,
  power = 6,
  model = "ifcnn",
  engine = c("gpu", "cpu"),
  threads = 0L,
  device_id = -1L,
  return_aligned = FALSE,
  verbose = TRUE,
  ...
)

image_focus_stack(
  images,
  align = TRUE,
  align_method = c("ecc", "translation", "orb"),
  reference_index = NULL,
  crop = TRUE,
  levels = 3,
  max_iter = 50,
  eps = 1e-04,
  max_frames = NULL,
  method = NULL,
  fusion_method = c("ifcnn", "laplacian"),
  strategy = c("pyramid", "sequential"),
  blend = c("soft", "hard"),
  radius = 3,
  power = 6,
  model = "ifcnn",
  engine = c("gpu", "cpu"),
  threads = 0L,
  device_id = -1L,
  return_aligned = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

• align_stack(): A list of aligned Image objects with identical spatial dimensions.

• fuse_multifocus(): An all-in-focus Image object.

• process_focus_stack(): The fused Image object (or a list containing fused and aligned if return_aligned = TRUE).

Author(s)

Tiago Olivoto [email protected]

References

Zhang, Y., Liu, Y., Sun, P., Yan, H., Zhao, X., & Zhang, L. (2020). IFCNN: A general image fusion framework based on convolutional neural network. Information Fusion, 54, 99-118.

Evangelidis, G. D., & Psarakis, E. Z. (2008). Parametric image alignment using enhanced correlation coefficient maximization. IEEE Transactions on Pattern Analysis and Machine Intelligence, 30(10), 1858-1865.

Examples

## Not run: 
library(pliman)

# Load or read a stack of multi-focus images
imgs <- list(
  image_read("focus_frame1.jpg"),
  image_read("focus_frame2.jpg"),
  image_read("focus_frame3.jpg")
)

# Fast automated pipeline with native C++ Modified Laplacian (zero-AI, ultra-fast)
fused_lap <- process_focus_stack(imgs, fusion_method = "laplacian", blend = "soft")
plot(fused_lap)

# Deep learning IFCNN with hierarchical tournament pyramid reduction
fused_dl <- process_focus_stack(imgs, fusion_method = "ifcnn", strategy = "pyramid")
plot(fused_dl)

# Handling large stacks (e.g. 200 frames from a focus rack video)
# Automatically extract 25 key focal planes for alignment and fusion:
fused_rack <- process_focus_stack(imgs, max_frames = 25, fusion_method = "laplacian")

## End(Not run)

Description

Ultra-fast analytical multi-focus image fusion using spatial Modified Laplacian (ML) energy maps. Ideal for large image stacks (50-500 images) where deep learning networks are computationally heavy.

Usage

fuse_laplacian_cpp(images, blend = "soft", radius = 3L, power = 6)

Arguments

Value

A fused Image object.

Description

Automatically detects a ColorChecker chart in an image (or uses user-specified corners), maps each color patch using perspective-aware bilinear homography, and extracts pure nucleus color statistics using a dynamic negative buffer.

Usage

get_card_colors(
  img,
  reference = "colorchecker24",
  nrow = NULL,
  ncol = NULL,
  buffer = 0.45,
  margin_x = 0.05,
  margin_y = 0.07,
  corners = NULL,
  auto_orient = TRUE,
  index = "GRAY",
  erode = NULL,
  fill_hull = TRUE,
  stat = c("mean", "median"),
  plot = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Details

The extraction employs a bilinear interpolation mapping:

$P(u, v) = (1 - u)(1 - v)\mathbf{TL} + u(1 - v)\mathbf{TR} + uv\mathbf{BR} + (1 - u)v\mathbf{BL}$

Outer card margins (margin_x, margin_y) exclude the surrounding plastic/cardboard frame. A dynamic negative buffer (buffer, default 45%) shrinks each nominal cell inwards towards its center, ensuring pixel sampling is strictly restricted to the homogeneous nucleus of the color chip, immune to edge glare, shadows, and plastic borders.

Value

An object of class c("pliman_card_colors", "data.frame") containing:

• id: Patch identifier (1 to nrow * ncol).

• row, col: Grid row and column positions.

• center_x, center_y: Pixel center coordinates.

• R, G, B: Sampled primary RGB values (0-255 scale).

• R_med, G_med, B_med: Median RGB values.

• R_sd, G_sd, B_sd: Standard deviations per channel.

• n_pixels: Number of pixels sampled in the nucleus.

• If reference comparison is active: code, name, ref_R, ref_G, ref_B, Delta_R, Delta_G, Delta_B, Delta_E, and Delta_E_Calib.

The object also stores attributes:

• attr(res, "patches"): List of patch bounding boxes and polygon vertices.

• attr(res, "corners"): Sorted corner coordinates (⁠TL, TR, BR, BL⁠).

• attr(res, "wb_gains"): Calculated White Balance gains.

• attr(res, "ccm"): Calculated 3x3 Color Correction Matrix.

• attr(res, "avg_delta_raw"): Mean Euclidean color error ($\Delta E$) before calibration.

• attr(res, "avg_delta_calib"): Mean $\Delta E$ after CCM 3x3 calibration.

Examples

if(interactive()){
library(pliman)
img <- image_pliman("colorcheck.jpg")

# Auto-detect card, auto-orient, and extract 24 patches with 45% negative buffer
card <- get_card_colors(img)
head(card)

# View patch overlay
plot(card)
}

Description

get_free_ram() retrieves the current available physical RAM of the system in real-time using native OS system calls in C++ (GlobalMemoryStatusEx on Windows, sysconf on Linux, and Mach Kernel host_statistics on macOS). It executes in microseconds with zero memory allocation.

Usage

get_free_ram(unit = c("GB", "MB", "KB", "B"))

Arguments

Value

A numeric value representing available system physical memory in the specified unit.

Examples

## Not run: 
library(pliman)
# Get free RAM in GB
get_free_ram()

# Get free RAM in MB
get_free_ram("MB")

## End(Not run)

Description

Fast C++ retrieval of available system physical RAM in bytes (Windows, Linux, macOS)

Usage

get_free_ram_cpp()

Description

Retrieves the current value of the pliman_viewer option used in the package.

Usage

get_pliman_viewer()

Value

The current value of the pliman_viewer option.

Description

This function extracts a UUID (Universal Unique Identifier) from the filename, using a regular expression that specifically identifies the standard UUID format.

Usage

get_uuid(filename)

Arguments

Value

A character vector with extracted UUIDs (or NA if none found)

Examples

library(pliman)
file <- "Grãos - contagem_f68bca60-c8cf-4272-9448-3f28891a97cd.jpg"
file2 <- "Grãos - contagem_f68bca60-c8cf-4272-9448-3f8891a97cd.jpg"
get_uuid(file)

Description

Generate ggplot2

Usage

ggplot_color(n = 1)

Arguments

Examples

library(pliman)
ggplot_color(n = 3)

Description

Performs Generalized Procrustes Analysis (GPA) to align a set of shapes.

Usage

gpa(x, tol = 1e-05, max_iter = 100)

Arguments

Value

A list with components:

• aligned: A list of the aligned shapes.

• consensus: The consensus (mean) shape.

• centroid_sizes: The centroid sizes of the original shapes.

• iterations: The number of iterations until convergence.

Description

Computes an ultra-fast C++ pixel intensity histogram for image objects of any storage mode (raw, logical, double, integer).

Usage

## S3 method for class 'image'
hist(
  x,
  nbins = 256,
  plot = TRUE,
  col = NULL,
  main = NULL,
  xlab = "Pixel Value",
  ...
)

Arguments

Value

A histogram S3 object (or list of histogram objects for multi-channel images) invisibly.

Description

image creates or coerces objects into a memory-optimized image S3 object in pliman. Storing pixel data efficiently (using 8-bit raw vectors by default) provides up to 8x memory reduction compared to standard float64 double arrays.

Usage

image(
  data = raw(),
  colormode = NULL,
  colspace = "RGB",
  gamma = 1,
  storage = c("raw", "double", "integer", "logical"),
  ...
)

as_image(
  data,
  colormode = NULL,
  colspace = "RGB",
  gamma = 1,
  storage = c("raw", "double", "integer", "logical"),
  dim = NULL,
  ...
)

is_image(x)

Arguments

Value

An S3 object of class c("image", "array").

Examples

## Not run: 
img <- image(array(as.raw(sample(0:255, 300, replace = TRUE)), dim = c(10, 10, 3)))
print(img)
summary(img)
is_image(img)

## End(Not run)

Description

image_align() rotate an image given a line of desired aligment along the y axis that corresponds to the alignment of the objects (e.g., field plots). By default, the aligment will be to the vertical, which means that if the drawed line have an angle < 90 degrees parallel to the x axis, the rotation angle wil be negative (anticlocwise rotation).

Usage

image_align(
  img,
  align = c("vertical", "horizontal"),
  viewer = get_pliman_viewer(),
  plot = TRUE
)

Arguments

Details

The image_align function aligns an image along the vertical or horizontal axis based on user-selected points. The alignment can be performed in either the base plotting system or using the mapview package for interactive visualization. If the viewer option is set to "base", the function prompts the user to select two points on the image to define the alignment line. If the viewer option is set to "mapview", the function opens an interactive map where the user can draw a polyline to define the alignment line. The alignment angle is calculated based on the selected points, and the image is rotated accordingly using the image_rotate function. The function returns the aligned image object.

Value

The img aligned

Examples

if (interactive()) {
library(pliman)
flax <- image_pliman("flax_leaves.jpg", plot = TRUE)
aligned <- image_align(flax)
}

Description

This function adds an alpha (transparency) layer to an RGB image. The alpha layer can be specified as a single numeric value for uniform transparency or as a matrix/array matching the dimensions of the image for varying transparency.

Usage

image_alpha(img, mask)

Arguments

Value

An image object with an added alpha layer, maintaining the RGBA format.

Examples

if (interactive()) {
library(pliman)

# Load a sample RGB image
img <- image_pliman("soybean_touch.jpg")

# 50% transparency
image_alpha(img, 0.5) |> plot()

# transparent background
mask <- image_binary(img, "NB")[[1]]
img_tb <- image_alpha(img, mask)
plot(img_tb)

}

Description

This function takes an image and augments it by rotating it multiple times.

Usage

image_augment(
  img,
  pattern = NULL,
  times = 12,
  type = "export",
  dir_original = NULL,
  dir_processed = NULL,
  parallel = FALSE,
  verbose = TRUE,
  workers = NULL
)

Arguments

Value

If type is "export," augmented images are saved. If type is "return," a list of augmented images is returned.

Examples

if (interactive()) {
library(pliman)
img <- image_pliman("sev_leaf.jpg")
imgs <- image_augment(img, type = "return", times = 4)
image_combine(imgs)
}

Description

Reduce a color, color near-infrared, or grayscale images to a binary image using a given color channel (red, green blue) or even color indexes. The Otsu's thresholding method (Otsu, 1979) is used to automatically perform clustering-based image thresholding.

Usage

image_binary(
  img,
  index = "R",
  r = 1,
  g = 2,
  b = 3,
  re = 4,
  nir = 5,
  return_class = "image",
  threshold = c("Otsu", "adaptive"),
  k = 0.15,
  windowsize = NULL,
  has_white_bg = FALSE,
  resize = FALSE,
  fill_hull = FALSE,
  max_size = NULL,
  remove_reflection = FALSE,
  erode = FALSE,
  dilate = FALSE,
  opening = FALSE,
  closing = FALSE,
  filter = FALSE,
  filter_order = c("erode", "dilate", "opening", "closing", "filter", "fill_hull"),
  invert = FALSE,
  return_exact = FALSE,
  plot = TRUE,
  nrow = NULL,
  ncol = NULL,
  parallel = FALSE,
  workers = NULL,
  verbose = TRUE
)

Arguments

Value

A list containing binary images. The length will depend on the number of indexes used.

Author(s)

Tiago Olivoto [email protected]

References

Otsu, N. 1979. Threshold selection method from gray-level histograms. IEEE Trans Syst Man Cybern SMC-9(1): 62-66. doi:10.1109/tsmc.1979.4310076

Shafait, F., D. Keysers, and T.M. Breuel. 2008. Efficient implementation of local adaptive thresholding techniques using integral images. Document Recognition and Retrieval XV. SPIE. p. 317-322 doi:10.1117/12.767755

Examples

if (interactive()) {
library(pliman)
img <- image_pliman("soybean_touch.jpg")
image_binary(img, index = c("R, G"))
}

Description

Extracts a pixel-accurate binary mask (foreground = 1, background = 0) from an image using state-of-the-art Deep Learning neural networks executed in ONNX format via native C++ bindings. Supports salient object detection, dichotomous image segmentation, high-resolution boundary matting, foundation segmentation models (SAM 2.1 / SAM 3.1), zero-shot text-prompted instance segmentation (Grounded-SAM), and one-shot visual exemplar segmentation (PerSAM).

Usage

image_binary_dl(
  img,
  model = c("u2netp", "ben2", "grounded-sam", "sam2.1", "persam", "rmbg-1.4", "rmbg-2.0",
    "withoutbg", "birefnet-lite", "sam3.1", "isnet-general-use", "silueta", "u2net"),
  threshold = 0.5,
  fill_hull = TRUE,
  filter = 0,
  erode = 0,
  dilate = 0,
  opening = 0,
  closing = 0,
  min_area = 0,
  invert = FALSE,
  pick_object = FALSE,
  prompt = NULL,
  exemplar = FALSE,
  threads = 0,
  engine = c("gpu", "cpu"),
  device_id = -1,
  verbose = TRUE,
  plot = TRUE,
  dir = pliman_model_dir(),
  ...
)

Arguments

Value

A binary image object (Grayscale, values 0 and 1) or a list of binary image objects.

Examples

## Not run: 
  library(pliman)
  img <- image_import("leaf.png")

  # Fast binarization on CPU (ultra-lightweight, 4.6 MB)
  mask <- image_binary_dl(img, model = "u2netp")

  # Sub-pixel boundary segmentation for fine veins and serrations
  mask_ben <- image_binary_dl(img, model = "ben2")

  # Interactive prompt: click directly on objects of interest
  mask_interactive <- image_binary_dl(img, model = "sam2.1", pick_object = TRUE)

  # Open-vocabulary text-prompted binarization
  mask_weed <- image_binary_dl(img, model = "grounded-sam", prompt = "weed")

  # One-shot visual exemplar segmentation (PerSAM)
  mask_exemplar <- image_binary_dl(img, model = "persam", prompt = c(150, 200))

## End(Not run)

Description

This function performs Connected Component Labeling (CCL) on a binary image. It implements a highly optimized 2-pass Union-Find algorithm, providing lightning-fast execution even for massive images.

Usage

image_bwlabel(binary)

Arguments

Value

A grayscale image object containing the labels, where each isolated object is assigned a unique integer value. Background pixels are 0.

Examples

## Not run: 
  library(pliman)
  bin <- image_pliman("soybean_touch.jpg") |> image_binary(index = "B")
  labels <- image_bwlabel(bin$B)

## End(Not run)

Description

Canny Edge Detector for Images. Adapted from https://github.com/bnosac/image/tree/master/image.CannyEdges.

Usage

image_canny_edge(img, index = "GRAY", s = 5, low_thr = 10, high_thr = 20)

Arguments

Value

a list with an image object with values 0 or 255, and the number of pixels which have value 255 (pixels_nonzero).

Examples

if(interactive()){
library(pliman)
img <- image_pliman("sev_leaf.jpg")
conts <- image_canny_edge(img, index = "B")
image_combine(img, conts$edges)
}

Description

Classifies images using pre-trained YOLO26 classification models across 1,000 ImageNet categories, or open-vocabulary text candidates using OpenAI CLIP (ViT-B/32) cross-modal embeddings and cosine similarity softmax.

Usage

image_classify_dl(
  img,
  candidates = NULL,
  model = NULL,
  top_k = NULL,
  labels = NULL,
  format_prompt = TRUE,
  plot = FALSE,
  col = "#2b5c8f",
  threads = 0,
  engine = c("gpu", "cpu"),
  device_id = -1,
  verbose = TRUE,
  dir = pliman_model_dir(),
  ...
)