ringDetect {measuRing}

Single Detection of TRWs

Description

This function assists in the detection of TRW (mm) in a scanned image (.tif or .png) or gray matrix, evaluating other required functions and plotting the outputs in graphics devices. The function can be combined with ringSelect to visually detected TRWs. Nevertheless, the complete measurement procedure of TRW with the package can be performed by multiDetect.

Usage

ringDetect(image, ...)

Arguments

image

character or matrix. Vector of path to the image section or a gray matrix such as that produced by imageTogray.

...

arguments to be passed to other functions, see section of Details.

Details

The scanned sample should correspond to a horizontal window of wood with the bark side located towards the left area of the image, and the pit side towards the right. The image section may not necessarily contain both bark and pit, see images of the Examples. The image should contain Red, Gren, and Blue channels (rgb) and be compressed in any of two file formats: tif or png. These are easily obtained by scanning wood samples with a conventional scanner and extracting a horizontal image section. Five functions are internally implemented: plotSegments, dataSegments, ringWidths, ringBorders, and/orimageTogray. These are controlled using the following arguments:

• ppi = NULL: image resolution in points per inch. If NULL the ppi is extracted from the image attributes. If the ppi is not embedded in the image, then thos argument should be provided;

• rgb = c(0.3,0.6,0.1): vector of three fractions, all of them adding to one, to combine the rgb into a gray matrix. Defaults correspond to the rgb-standard in the luminosity function (Russ, 2006): green light contributes the most to the intensity perceived by humans, and blue light the least;

• p.row = 1: Proportion of rows in the central portion of the gray matrix to be processed;

• last.yr = NULL: NULL or integer. Year of formation of the newest ring. If NULL then the rings are numbered from one (right) to the number of detected rings (left);

• auto.det = TRUE: logical. If TRUE then an algorithm for automatic detection is implemented, see linearDetect;

• darker = TRUE: logical. If TRUE then the algorithm uses the negative extremes on smoothed grays to detect the ring borders. If FALSE the positive extremes are used instead;

• origin = 0: An origin along central portion of the smoothed gray to find the ring borders. This value could help to avoid noisy areas during the visual detection process;

• inclu = NULL: NULL or vector with column numbers in the gray matrix, other than those automatically detected, to be considered as ring borders. If NULL no column numbers are included;

• exclu = NULL: NULL or vector with column numbers in gray matrix of those ring borders to be excluded from the analysis. If NULL, no ring borders are excluded;

• plot = TRUE: logical. If TRUE then a plot is produced;

• segs = 1: Number of image segments to be plotted;

• ratio = NULL: NULL or numeric vector of two values representing the aspect ratio of the plots (height, and width). If NULL default in par is used;

• marker = NULL: NULL or integer vector with any value from 1 to 10. The rings are averaged with those rings on either side of it and the averages are scaled from ten (the narrowest possible ring) to one (the broadest ring). The narrow rings with averages larger than marker as well as other chronological markers (decades, centuries, and millennia), are highlighted with red pinpricks;

• col.marker = 'red': color of the markers;

• tit = TRUE: logical or character. A title for the plots. If TRUE the main title is the image name. For more than 1 segment the main title ends with the segment number. This argument does not work in multiDetect.

If users run R from Interactive Development Environments (IDE) aiming to segment the image section (segs > 1), they should be sure that such environments support multiple graphics devices. If the argument image is a gray matrix, then other arguments passed to imageTogray will be ignored. The function can be combined with ringSelect to visually include/exclude ring borders in the plot output, see examples in the ringSelect function. See multiDetect for recursive implementation of this function.

references<<

• Lara W., F. Bravo, and S. Carlos. 2015. measuRing: An R package to measure tree-ring widths from scanned images. Dendrochronologia, 34: 43-50;

• Russ, J.C., 2006. The Image Processing Handbook, Fifth Edition. CRC Press, Boca Raton, 817 pp.

Value

list of data frames with ring widths and ring borders such as these produced by ringWidths, and ringBorders.

Author(s)

Wilson Lara, Carlos Sierra, Felipe Bravo

Examples

image1 <- system.file("P105_a.tif", package="measuRing")
## (not run) Initial diagnostic:
detect1 <- ringDetect(image1,segs=3)
## (not run) Updating ringDetect to chage arguments;
## and flagged rings
detect1 <- update(detect1,marker=8) 
## (not run) Some noise in smoothed gray can be avoided
## by moving the origin: 
detect1 <- update(detect1,origin = -0.03)
## (not run) columns 21 and 130 are not considered now.
##
## (not run) Choose other columns in gray matrix (see ringSelect);
## (not run) graphical devices from ringDetect should be active!
## (not run) Including columns:
## (uncomment and run):
## detect1 <- update(detect1)
## Toinc <- ringSelect(detect1)
## detect1 <- update(detect1, inclu = Toinc)
## or, include the next columns: 
Toinc <- c(202,387,1564) 
detect1 <- update(detect1,inclu = Toinc)        
## (not run) Object detec1 is updated with Toinc;
##
## (not run)  ring borders to be excluded:
## (uncomment and run):
## detect1 <- update(detect1)
## Toexc <- ringSelect(detect1,any.col = FALSE)
## detect1 <- update(detect1,exclu=Toexc)
## or, exclude the nex columns: 
Toexc <- c(208,1444,1484)
detect1 <- update(detect1,exclu = Toexc)        
##
## (not run) Final arguments:
detect2 <- update(detect1,last.yr=2011,marker = 8)
str(detect2)
##
## (not run) kill previous plot:
graphics.off()
##
## (not run) Tree-ring widths and attributes:
rings <- detect2$'ringWidths'
##
## (not run) Plot of the tree-ring witdths:        
maint <- 'Hello ring widths!'
plot(rings,ylab = 'width (mm)',type='l',col = 'red',main=maint)