hemispheR: an R package for fisheye canopy image analysis

A couple of months ago, I wrote a post where I illustrated the open-access tools available for digital canopy image analysis (you can find it here). For the purpose, I reviewed both the existing software and language-programming tools to create a list of all existing free canopy image processing solutions. I have been very surprised to find that very few R solutions were available for processing canopy images. This was quite surprising, as the digital image format is suitable for being handled by R.

After that post, I decided to create my own R packages. The first one I created was coveR, which is tailored for restricted-view canopy photography (digital cover photography). I described it in another post in the blog here. Thanks to the post I made my acquaintance with Martin Macek and together decided to create our own R package for canopy hemispherical images.

The challenges of making a package for fisheye image analysis had been twofold:

1) firstly, the available R packages dealing with hemispherical images focused on specific processing steps, such as thresholding (package ‘caiman’; Díaz et al., 2021), gap fraction inversion (‘hemiphoto2LAI’; Zhao et al., 2019), canopy openness retrieval (‘Sky’; Bachelot, 2016). Therefore, a ‘new’ R package should provide all the steps required for processing digital hemispherical images in a single package, from importing images up to retrieve canopy attributes. This lead to the second issue…

2) compared with other canopy image method, the processing of fisheye image is rather complex, as many specific steps like setting a circular mask, perform gamma correction, correct for lens distortion, divide the hemisphere in zenith and azimuth bins, among others, are required. Such complexity of image processing needs to comply with the requisite of having a simple and flexible R tool, to make a package simple and ready-to-use.

The results of mine & Martin’s joined efforts is hemispheR. The hemispheR package uses the functionality of ‘raster’ package (Hijmans, 2021), which ensures faster processing of images not otherwise possible when dealing with other image formats in the R environment. The ‘raster’ package also has the strong advantage of importing any kind of raster graphic image formats (i.e, pixel matrix), including raw imagery. The package allows analysis of both circular and full-frame fisheye images. In addition, it can import either single channel images or mixing channel (including greenness indices), to allow using them for either upward-facing (forest canopies) and downward-facing (short canopies and crops) images.

Left: Circular fisheye image. Right: Full-frame fisheye image.

The package features the following functions, which are ordered sequentially, following the fundamental image processing steps:

1. import_fisheye(): imports an image channel (or a mixing channel) and applies a circular mask (in case of circular images);
2. binarize_fisheye(): thresholds the selected image channel and returns a binary image;
3. gapfrac_fisheye(): calculate the gap fraction for defined zenith and azimuth bins;
4. canopy_fisheye(): infer canopy attributes from the angular distribution of gap fraction

To complement the package, additional features allows to import circular mask parameters for a known set of camera & lens equipment (using the function camera_fisheye()), and provide a long list of fisheye lenses available to correct for lens distortion (available as list.lenses).

The package allows inspecting all the steps of the processing such as:

Importing images:

Example of an imported circular fisheye image using import_fisheye() function

Classify images:

Example of a classified image using the binarize_fisheye() function

Extract angular gap fraction:

Example of circular image classified by setting 5 rings and 8 azimuth segments, and zenith range 0-75°

The package can be installed from CRAN by typing:

install.packages(“hemispheR”)

The development version package can be installed by typing :

devtools::install_git(“https://gitlab.com/fchianucci/hemispheR“)

The article describing the package is available here: https://doi.org/10.1016/j.agrformet.2023.109470

      By providing a simple, transparent, and flexible image processing procedure, hemispheR supported the use of DHP for routine measurements and monitoring of forest canopy attributes. Hosting the package in a Git repository will further support development of the package, through either collaborative coding or forking projects.

Chianucci, F. and Macek, M., 2023. hemispheR: an R package for fisheye canopy image analysis. Agricultural and Forest Meteorology, 336, p.109470.