ALL Metrics
-
Views
-
Downloads
Get PDF
Get XML
Cite
Export
Track
Software Tool Article

bwimage: A package to describe image patterns in natural structures

[version 1; peer review: 1 approved with reservations]
PUBLISHED 23 Jul 2019
Author details Author details
OPEN PEER REVIEW
REVIEWER STATUS

This article is included in the RPackage gateway.

Abstract

Currently R is the most popular software for data analyses among biologists. Here, we present bwimage, a package designed to describe patterns from black and white images. The package can be used for a wide range of applications. We implemented functions previously described in the literature to calculate parameters designed originally, but not exclusively, for vegetation structures. Additionally, we propose a new parameter: the aggregation index. We demonstrate applications for field work, providing examples that range from calculation of canopy openness, description of patterns in vertical vegetation structure, to patterns in bird nest structure. We provide advice and illustrated examples of how to produce high quality images for analyses.

Keywords

animal, ecology methods, field, image analyses, image processing, vegetation patterns

Introduction

The facility to obtain high quality digital images creates the opportunity to measure natural variables using image analyses. Black and white pictures have frequently been used to understand patterns in field ecology, especially in plant biology studies1. However, the use of plant image analyses software is not easily extended to other biological fields for several reasons. Free programs are uncommon and paid software normally has threshold algorithms that were specifically designed for vegetation pictures2. Thus, a flexible method that would allow the application of such analyses to other subjects would be welcome. For example, despite the relatively well reported descriptions of bird nests and egg morphology in Del Hoyo and collaborators3 (but see Xiao, Hu4), there are no well-established approaches to estimate nest wall openness patterns.

Currently, R software5 allows users to migrate from data processing based on combinations of different software (with the possibility of having costly licensing, software-specific files, incompatibility between operating systems and lack of updates) to a free, single cross-platform software. Here, we introduce bwimage, a package for R that can be used to analyze patterns in black and white images from natural structures. We provide data examples for applications and descriptions of routines for processing of black and white images.

Methods

Implementation

Bwimage´s analysis of images is based on the transformation from a picture (“jpeg” and “png” files are allowed) to a binary matrix (Figure 1). For each pixel, the intensity of red, green and blue is averaged and compared to a threshold. If the average intensity is less than the threshold (default is 50%) the pixel will be set as black, otherwise it will be white. Beyond RGB intensity in PNG images, the alpha channel is used to set transparent pixels, i.e. alpha channel values above the threshold (default is 50%) will set the pixel as transparent. In the data matrix, the value one represents black pixels, zero represents white pixels and NA represents transparent pixels. For high resolution files, i.e. numbers of pixels in width and height, we suggest reducing the resolution to create a smaller matrix, as this strongly reduces GPU usage and time necessary to run analyses. However, by reducing resolution, the accuracy of data description will also be lowered. Figure 2 compares different resamplings from a figure of 2500x2500 pixels. If the user is not acquainted with scale and threshold processing and/or images were captured under different light conditions, we recommend the scale and application of threshold algorithms in a native image editor software, such as GIMP6, and subsequent usage of the resulting images with the bwimage package.

352ec8da-34a3-48d9-b21b-218d29ded597_figure1.gif

Figure 1. General approach for image analysis in the bwimage package.

A) An image of a natural structure is obtained with digital photography; here we used an image from a canopy. B) The image is converted into a binary matrix, functions threshold_color (to a single image) or threshold_image_list (for two or more images). In the data matrix the value one represents black pixels, zero represents white pixels and NA represents transparent pixels.

352ec8da-34a3-48d9-b21b-218d29ded597_figure2.gif

Figure 2. Comparison of different resamplings from a figure of 2500x2500 pixels.

A) Original image. B) Black and white conversion of the original image by GIMP software, i.e. all pixels converted to either black or white in image. CI) conversion of the original image to binary matrices of 10x10, 50x50, 75x75, 100x100, 250x250, and 500x500, respectively.

Several metrics can be performed with the functions presented in Table 1. We implemented functions to calculate parameters designed originally, but not exclusively, for vegetation structures (described by Zehm et al. 2003) and propose a new parameter: the aggregation index. The aggregation index is a standardized estimation of the average proportion of same-color pixels around each image pixel. First, the proportion of same-color neighboring pixels (SCNP) is calculated (marginal lines and columns are excluded). Next, the SCNP for all pixels are averaged; then, given the proportion of black and white pixels, number of pixels in height and width, and location of transparent pixels (when present), the maximum and minimum possible aggregation indexes are calculated. Finally, the observed aggregation is standardized to a scale where the minimum possible value is set at zero and the maximum value is set at one (Figure 3).

Table 1. Main functions of the bwimage package.

FunctionsDescription
Image processes
threshold_colorConvert an image into a matrix
threshold_image_listConvert several images into a list of matrices
image_informationSummary of image information
Image analyses
denseness_totalProportion of black pixels in relation to all pixels
denseness_rowProportion of black pixels in rows subsets
denseness_columnProportion of black pixels in column subsets
hole_rowDescription of white pixel continuous sequences in rows
hole_colummDescription of white pixel continuous sequences in columns
light_gapLeft and right distances from first black pixel to image edge
heigh_maximumHigher black pixel in all image
altitudinal_profileDescription of higher black pixel in image sections
heigh_propotionHeight below which a given proportion of vegetation denseness occurs
toplineLine running along the crest of highest black pixel
aggregation_indexPixel aggregation estimator
352ec8da-34a3-48d9-b21b-218d29ded597_figure3.gif

Figure 3. Demonstration of aggregation index calculation.

Imagens represent photos of 6x6 pixel, with 50% black and 50% white pixels. For the aggregation index calculation, first, the proportion of same-color neighboring pixels (SCNP) is calculated (marginal lines and columns are excluded). Then, SCNP are averaged. In these examples, the average SCNP is 0.75 (A), 0.5 (B), 0 (C) and 0.875 (D). Next, the maximum and minimum possible aggregation indexes are calculated. In images with 50% black and white pixels, the minimum aggregation will be pixels distributed in chessboard style (C), and the highest aggregation will be the aggregation of all same color pixels on each image side (D). Thus, by scaling the aggregation by the minimum and maximum possible aggregation, the final aggregation index is: 0.857 (A), 0.571 (B), 0 (C) and 1 (D).

Operation

Bwimage is written in the R programming language5, and can be run on Windows, Mac OS X, and Linux systems. The package is available at the CRAN repository, and the development releases are available at Github (see Software availability)7. The bwimage CRAN page documents package dependencies. Input images must be in one of the following formats PNG, JPG, or JPEG.

Use cases

Canopy openness is one of the most essential ecological parameters for a field ecologist. In the bwimage package, canopy openness can be calculated based on a single picture. To illustrate, we demonstrate below how to analyze a canopy image with the bwimage package. The photo was taken with a digital camera placed in the ground, perpendicular to the ground. Canopy closure can be calculated by estimating the total amount of vegetation in the canopy. Canopy openness is equal to one minus the canopy closure. For this example, we used the original image from Figure 1. The original image file is provided as Underlying data8.

canopy_matrix<-
threshold_color("canopy.JPG",compress_method="proportional",compress_rate=0.1)

1-denseness_total(canopy_matrix)
[1] 0.1297333

Several metrics to describe vertical vegetation complexity can be performed by the bwimage package (see Table 1). Here we provide examples based on an image (Figure 2A) from a vegetation plot of 30×100cm1. The original image file is provided as Underlying data9. On the 100cm side of this plot we placed a panel of 100x100 cm, covered with white cloth, and perpendicular to the ground. A plastic canvas of 50x100cm was used to cover the vegetation along a narrow strip in front of a camera positioned on a tripod at a height of 55 cm. A photograph of the portion of standing vegetation against the white cloth was taken.

vegetation_matrix<-threshold_color(bush)

denseness_total(vegetation_matrix,height_size = 100, width_size = 100)
[1] 0.115248

topline(vegetation_matrix)
topline 
  785.6

heigh_propotion_test(vegetation_matrix,proportion=0.75,height_size=100)
Height below which 0.75 of the vegetation denseness is located
                                                                            31.2 

aggregation_index(vegetation_matrix)
     adjusted_aggregation non_adjusted_aggregation
                  0.8512586                0.9634373

Variation in eggs and nest morphology provide relevant information concerning bird life history that has frequently been used to answer ecological1012 and evolutionary questions1315. Here we analyze examples that address the quantification nest wall openness and the aggregation of nest wall holes, using a nest of the blue-black grasssquit (Volatinia jacarina) deposited in the museum collection Coleção Ornitológica Marcelo Bagno, at Universidade de Brasília (register number COMB-N682). Figure 4 describes how to produce a high-quality image to describe patterns in bird nest wall openness. The original image file used is provided as Underlying data16.

NestWall_matrix<-threshold_color("NestWall.png", 
filetype="png",compress_method="width_fixed",target_width=300)

denseness_total(NestWall_matrix)
[1] 0.7612406

aggregation_index(NestWall_matrix)
    adjusted_aggregation non_adjusted_aggregation
                 0.9007821                0.9502800

352ec8da-34a3-48d9-b21b-218d29ded597_figure4.gif

Figure 4. Description of how to produce an image to evaluate patterns in bird nest wall openness.

The following example used a blue-black grasssquit (Volatinia jacarina) nest deposited in the museum collection Coleção Ornitológica Marcelo Bagno, at Universidade de Brasília (catalog number COMB-N682). A) A photo of the nest was taken with a white styrofoam ball (50mm in diameter) placed inside the nest chamber. B) In GIMP software (version 2.10.10), we added alpha channel (to allow transparent pixels), and used the Ellipse select tool to select contrast of the white ball and nest wall, and then erased all background elements. C) To ensure that shadows from nest wall did not influence white ball detection, we also performed the threshold processing in GIMP. To preserve the transparent pixels from background elements, the final image must be saved as a PNG file.

Conclusions

The bwimage package provides accessible and simple methods for ecologists and field researchers to describe patterns from black and white digital images. It is a flexible method that allows the application of image analyses to an exceptionally broad range of research subjects. Bwimage´s analysis is based on a simple computational routine based on the transformation of a picture (“jpeg” or “png” files) into a binary matrix, followed by the analysis itself. Several metrics can be calculated by the bwimage package. We implemented functions previously described in the literature, and additionally, we proposed a new parameter: the aggregation index, which generates a standardized estimate of the average proportion of same-color pixels around each image pixel. The application of this methods is exceptionally broad.

Data availability

Underlying data

Figshare: Canopy of Royal poinciana. https://doi.org/10.6084/m9.figshare.8429117.v28

Figshare: Image from a vegetation plot of 30x100cm. https://doi.org/10.6084/m9.figshare.8429882.v29

Figshare: Blue-black grassquit (Volatinia jacarina) nest. https://doi.org/10.6084/m9.figshare.8432018.v116

Data are available under the terms of the Creative Commons Zero "No rights reserved" data waiver (CC0 1.0 Public domain dedication).

Software availability

Comments on this article Comments (0)

Version 3
VERSION 3 PUBLISHED 23 Jul 2019
Comment
Author details Author details
Competing interests
Grant information
Copyright
Download
 
Export To
metrics
Views Downloads
F1000Research - -
PubMed Central
Data from PMC are received and updated monthly.
- -
Citations
CITE
how to cite this article
Biagolini-Jr. C and Macedo RH. bwimage: A package to describe image patterns in natural structures [version 1; peer review: 1 approved with reservations]. F1000Research 2019, 8:1168 (https://doi.org/10.12688/f1000research.19801.1)
NOTE: If applicable, it is important to ensure the information in square brackets after the title is included in all citations of this article.
track
receive updates on this article
Track an article to receive email alerts on any updates to this article.

Open Peer Review

Current Reviewer Status: ?
Key to Reviewer Statuses VIEW
ApprovedThe paper is scientifically sound in its current form and only minor, if any, improvements are suggested
Approved with reservations A number of small changes, sometimes more significant revisions are required to address specific details and improve the papers academic merit.
Not approvedFundamental flaws in the paper seriously undermine the findings and conclusions
Version 1
VERSION 1
PUBLISHED 23 Jul 2019
Views
26
Cite
Reviewer Report 13 Aug 2019
Francesco Chianucci, The Council for Agricultural Research and Economics (CREA) - Research Centre for Forestry and Wood, Arezzo, Italy 
Approved with Reservations
VIEWS 26
The topic is interesting. However, I think the package makes simple things which many other similar packages do, and omit some intermediate steps required to refine the analysis.

First, the authors should provide a list of thresholding ... Continue reading
CITE
CITE
HOW TO CITE THIS REPORT
Chianucci F. Reviewer Report For: bwimage: A package to describe image patterns in natural structures [version 1; peer review: 1 approved with reservations]. F1000Research 2019, 8:1168 (https://doi.org/10.5256/f1000research.21722.r51562)
NOTE: it is important to ensure the information in square brackets after the title is included in all citations of this article.
  • Author Response 29 Oct 2019
    Carlos Biagolini-Jr., Programa de Pós-Graduação em Ecologia, Universidade de Brasília, Brasília, 70910-900, Brazil
    29 Oct 2019
    Author Response
    Dear Dr. Francesco Chianucci,

    We appreciate all of your helpful comments, and we are certain that they have improved significantly the original version of the Package. In the new version (1.2) ... Continue reading
COMMENTS ON THIS REPORT
  • Author Response 29 Oct 2019
    Carlos Biagolini-Jr., Programa de Pós-Graduação em Ecologia, Universidade de Brasília, Brasília, 70910-900, Brazil
    29 Oct 2019
    Author Response
    Dear Dr. Francesco Chianucci,

    We appreciate all of your helpful comments, and we are certain that they have improved significantly the original version of the Package. In the new version (1.2) ... Continue reading

Comments on this article Comments (0)

Version 3
VERSION 3 PUBLISHED 23 Jul 2019
Comment
Alongside their report, reviewers assign a status to the article:
Approved - the paper is scientifically sound in its current form and only minor, if any, improvements are suggested
Approved with reservations - A number of small changes, sometimes more significant revisions are required to address specific details and improve the papers academic merit.
Not approved - fundamental flaws in the paper seriously undermine the findings and conclusions
Sign In
If you've forgotten your password, please enter your email address below and we'll send you instructions on how to reset your password.

The email address should be the one you originally registered with F1000.

Email address not valid, please try again

You registered with F1000 via Google, so we cannot reset your password.

To sign in, please click here.

If you still need help with your Google account password, please click here.

You registered with F1000 via Facebook, so we cannot reset your password.

To sign in, please click here.

If you still need help with your Facebook account password, please click here.

Code not correct, please try again
Email us for further assistance.
Server error, please try again.