analyze_objects {pliman}R Documentation

Analyzes objects in an image

Description

Usage

analyze_objects(
  img,
  foreground = NULL,
  background = NULL,
  pattern = NULL,
  parallel = FALSE,
  workers = NULL,
  watershed = TRUE,
  resize = FALSE,
  trim = FALSE,
  fill_hull = FALSE,
  filter = FALSE,
  invert = FALSE,
  object_size = "medium",
  index = "NB",
  my_index = NULL,
  object_index = NULL,
  threshold = "Otsu",
  tolerance = NULL,
  extension = 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 = 2000,
  show_image = TRUE,
  show_original = TRUE,
  show_chull = FALSE,
  show_contour = TRUE,
  contour_col = "red",
  contour_size = 1,
  show_background = TRUE,
  show_segmentation = FALSE,
  col_foreground = NULL,
  col_background = NULL,
  marker = FALSE,
  marker_col = NULL,
  marker_size = NULL,
  save_image = FALSE,
  prefix = "proc_",
  dir_original = NULL,
  dir_processed = NULL,
  verbose = TRUE
)

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

Arguments

img

The image to be analyzed.

foreground

A color palette of the foreground (optional).

background

A color palette of the background (optional).

pattern

A pattern of file name used to identify images to be imported. For example, if pattern = "im" all images in the current working directory that the name matches the pattern (e.g., img1.-, image1.-, im2.-) will be imported as a list. Providing any number as pattern (e.g., pattern = "1") will select images that are named as 1.-, 2.-, and so on. An error will be returned if the pattern matches any file that is not supported (e.g., img1.pdf).

parallel

If TRUE processes the images asynchronously (in parallel) in separate R sessions running in the background on the same machine. It may speed up the processing time, especially when pattern is used is informed. When object_index is informed, multiple sections will be used to extract the RGB values for each object in the image. This may significantly speed up processing time when an image has lots of objects (say >1000).

workers

A positive numeric scalar or a function specifying the number of parallel processes that can be active at the same time. By default, the number of sections is set up to 50% of available cores.

watershed

If TRUE (default) performs watershed-based object detection. This will detect objects even when they are touching one other. If FALSE, all pixels for each connected set of foreground pixels are set to a unique object. This is faster but is not able to segment touching objects.

resize

Resize the image before processing? Defaults to FALSE. Use a numeric value of range 0-100 (proportion of the size of the original image).

trim

Number of pixels removed from edges in the analysis. The edges of images are often shaded, which can affect image analysis. The edges of images can be removed by specifying the number of pixels. Defaults to FALSE (no trimmed edges).

fill_hull

Fill holes in the binary image? Defaults to FALSE. This is useful to fill holes in objects that have portions with a color similar to the background. IMPORTANT: Objects touching each other can be combined into one single object, which may underestimate the number of objects in an image.

filter

Performs median filtering after image processing? defaults to FALSE. See more at image_filter().

invert

Inverts the binary image, if desired. This is useful to process images with black background. Defaults to FALSE.

object_size

The size of the object. Used to automatically set up tolerance and extension parameters. One of the following. "small" (e.g, wheat grains), "medium" (e.g, soybean grains), "large"(e.g, peanut grains), and "elarge" (e.g, soybean pods)'.

index, my_index

A character value specifying the target mode for conversion to binary image when foreground and background are not declared. Defaults to "NB" (normalized blue). See image_index() for more details.

object_index

Defaults to FALSE. If an index is informed, the average value for each object is returned. It can be the R, G, and B values or any operation involving them, e.g., object_index = "R/B". In this case, it will return for each object in the image, the average value of the R/B ratio. Use pliman_indexes_eq() to see the equations of available indexes.

threshold

By default (threshold = "Otsu"), a threshold value based on Otsu's method is used to reduce the grayscale image to a binary image. If a numeric value is informed, this value will be used as a threshold. Inform any non-numeric value different than "Otsu" to iteratively chosen the threshold based on a raster plot showing pixel intensity of the index.

tolerance

The minimum height of the object in the units of image intensity between its highest point (seed) and the point where it contacts another object (checked for every contact pixel). If the height is smaller than the tolerance, the object will be combined with one of its neighbors, which is the highest.

extension

Radius of the neighborhood in pixels for the detection of neighboring objects. Higher value smooths out small objects.

lower_size, upper_size

Lower and upper limits for size for the image analysis. Plant images often contain dirt and dust. To prevent dust from affecting the image analysis, objects with lesser than 10% of the mean of all objects are removed. Upper limit is set to NULL, i.e., no upper limit used. One can set a known area or use lower_limit = 0 to select all objects (not advised). Objects that matches the size of a given range of sizes can be selected by setting up the two arguments. For example, if lower_size = 120 and upper_size = 140, objects with size greater than or equal 120 and less than or equal 140 will be considered.

topn_lower, topn_upper

Select the top n objects based on its area. topn_lower selects the n elements with the smallest area whereas topn_upper selects the n objects with the largest area.

lower_eccent, upper_eccent, lower_circ, upper_circ

Lower and upper limit for object eccentricity/circularity for the image analysis. Users may use these arguments to remove objects such as square papers for scale (low eccentricity) or cut petioles (high eccentricity) from the images. Defaults to NULL (i.e., no lower and upper limits).

randomize

Randomize the lines before training the model?

nrows

The number of lines to be used in training step. Defaults to 2000.

show_image

Show image after processing?

show_original

Show the count objects in the original image?

show_chull

Show the convex hull around the objects? Defaults to FALSE.

show_contour

Show a contour line around the objects? Defaults to TRUE.

contour_col, contour_size

The color and size for the contour line around objects. Defaults to contour_col = "red" and contour_size = 1.

show_background

Show the background? Defaults to TRUE. A white background is shown by default when show_original = FALSE.

show_segmentation

Shows the object segmentation colored with random permutations. Defaults to FALSE.

col_foreground, col_background

Foreground and background color after image processing. Defaults to NULL, in which "black", and "white" are used, respectively.

marker, marker_col, marker_size

The type, color and size of the object marker. Defaults to NULL, which plots the object id. Use marker = "point" to show a point in each object or marker = FALSE to omit object marker.

save_image

Save the image after processing? The image is saved in the current working directory named as ⁠proc_*⁠ where * is the image name given in img.

prefix

The prefix to be included in the processed images. Defaults to "proc_".

dir_original, dir_processed

The directory containing the original and processed images. Defaults to NULL. In this case, the function will search for the image img in the current working directory. After processing, when save_image = TRUE, the processed image will be also saved in such a directory. It can be either a full path, e.g., "C:/Desktop/imgs", or a subfolder within the current working directory, e.g., "/imgs".

verbose

If TRUE (default) a summary is shown in the console.

x

An object of class anal_obj.

which

Which to plot. Either 'measure' (object measures) or 'index' (object index). Defaults to "measure".

measure

The measure to plot. Defaults to "area".

type

The type of plot. Either "hist" or "density". Partial matches are recognized.

facet

Create a facet plot for each object when which = "index" is used?. Defaults to FALSE.

...

Further argument passed on to lattice::histogram() or lattice::densityplot()

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). Then, the number of objects in the foreground is counted. By setting up arguments such as lower_size, upper_size it is possible to set a threshold for lower and upper sizes of the objects, respectively. The argument object_size 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 to 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 (specially for a large number of objects) but is not able to segment touching objects.

If color palettes samples are provided, a general linear model (binomial family) fitted to the RGB values is used to segment fore- and background.

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.

Value

analyze_objects() returns a list with the following objects:

plot.anal_obj() returns a trellis object containing the distribution of the pixels, optionally for each object when facet = TRUE is used.

Author(s)

Tiago Olivoto tiagoolivoto@gmail.com

References

Gupta, S., Rosenthal, D. M., Stinchcombe, J. R., & Baucom, R. S. (2020). The remarkable morphological diversity of leaf shape in sweet potato (Ipomoea batatas): the influence of genetics, environment, and G×E. New Phytologist, 225(5), 2183–2195. doi: 10.1111/NPH.16286

Lee, Y., & Lim, W. (2017). Shoelace Formula: Connecting the Area of a Polygon and the Vector Cross Product. The Mathematics Teacher, 110(8), 631–636. doi: 10.5951/mathteacher.110.8.0631

Examples


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

# Enumerate the objects in the original image
# Return the top-5 grains with the largest area

top <-
 analyze_objects(img,
                 marker = "id",
                 topn_upper = 5)
top$results



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(img,
                   marker = "id",
                   object_index = "B")
# density of area
plot(rgb)

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

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


[Package pliman version 1.1.0 Index]