AcuityView:
an R package that provides a simple method for representing a visual scene as it may be seen by an animal with less acute vision
Acuity (the ability of an animal to perceive detail) varies dramatically across species. Humans have some of the highest acuity in the animal kingdom, meaning that we perceive a great deal more spatial detail than the majority of animals. As a result, researchers may develop hypotheses about the potential function of a spatial pattern or signaling trait without first testing that it is resolvable by the relevant animal viewer. For example, the images below show the results of using AcuityView to portray a reef scene from a viewing distance of 1m, incorporating the acuity of (left) a human viewer, (center) the reef triggerfish Rinecanthus aculeatus, and (right) the reef-dwelling cleaner shrimp Ancylomenes pedersoni. Thus, three viewers in the same habitat may view the same scene in very different ways.
How does AcuityView Work? AcuityView provides a simple and powerful method for eliminating all of the spatial information from a scene that should not be resolvable by a viewer with a given acuity from a given distance. Importantly, AcuityView does NOT tell us what the animal perceives--no theoretical or experimental treatment can do that! Rather, it allows us to examine what visual information is and is not available to a given viewer. Details are available in Caves and Johnsen (2017).
In brief, AcuityView uses Fourier methods to eliminate spatial information from an image that is below the acuity of a given viewer from a specified viewing distance. As shown below in this visual schematic of the image conversion process, an original image (upper left) is Fourier-transformed (FFT). The transform is a representation of the original image in frequency space. This transform is then multiplied (element by element) with the modulation transfer function (MTF) of the viewer. The product is then inverse-Fourier-transformed (iFFT) to create the converted image, which has now lost all detail finer than what can be perceived by a visual system with a chosen acuity.
In brief, AcuityView uses Fourier methods to eliminate spatial information from an image that is below the acuity of a given viewer from a specified viewing distance. As shown below in this visual schematic of the image conversion process, an original image (upper left) is Fourier-transformed (FFT). The transform is a representation of the original image in frequency space. This transform is then multiplied (element by element) with the modulation transfer function (MTF) of the viewer. The product is then inverse-Fourier-transformed (iFFT) to create the converted image, which has now lost all detail finer than what can be perceived by a visual system with a chosen acuity.
AcuityView User Guide
The AcuityView Code:
1. Downloading and opening R and RStudio
2. Installing AcuityView
3. Preparing Your Image File
4. Running the AcuityView Program
A note for Linux users:
You may need to install the fftw library in order for the dependent R package "fftwtools" to install and perform correctly. The FFTW website and install information can be found here: http://www.fftw.org/. This library can easily be installed on Ubuntu with: apt-get install fftw3-dev
Example line of command code:
AcuityView(photo = NULL, distance = 0.5, realWidth = 3, eyeResolutionX = 0.2, eyeResolutionY = NULL, plot = T, output="Acuity_image.jpeg")
The AcuityView Code:
- Authors: Eleanor Caves and Sönke Johnsen
- E-mail: [email protected]
- Date: Packaged May 8, 2017
- Version: 0.1
- Copyright (C) 2017 Eleanor Caves and Sönke Johnsen
- The AcuityView package is freely available using the R software and can be downloaded from the CRAN. The source code for AcuityView has been archived using GitHub and is freely available from the Zenodo repository (https://doi.org/10.5281/zenodo.998916).
- When using AcuityView, please cite the original publication: Caves EM, Johnsen S. AcuityView: An r package for portraying the effects of visual acuity on scenes observed by an animal. Methods Ecol Evol. 2017;00:1–5. https://doi.org/10.1111/2041-210X.12911
1. Downloading and opening R and RStudio
- AcuityView is a package that runs using R, which is a free software environment for statistical computing and graphics. R is available for free download at https://www.r-project.org/. Please follow the instructions provided on the R website for downloading the program.
- We highly recommend using RStudio, which provides a graphical user interface for many R commands, and which is available for free download at https://www.rstudio.com/. Please follow the instructions provided on the R website for downloading the program. To operate R Studio, you must also download R.
2. Installing AcuityView
- The AcuityView package is available for download from the R CRAN.
- To install AcuityView, you can use the “install.packages” command in R, after which you must also run the library(AcuityView) command.
- An example photo is automatically supplied in the AcuityView download; the same example photo is used at the end of this guide.
3. Preparing Your Image File
- Image Size:
- AcuityView has several requirements for the image file in order for it to be correctly processed. First, the image must be square and must have pixel dimensions that are a power of two (meaning that the pixel size of each side must be 2n, where n is any positive integer). For example, pixel sizes of 512x512, 1024x1024, 2048x2048, etc. will work. If you have started with an image that is non-square, you can resize it easily using the software ImageJ, which is a free image-editing software available for download at https://imagej.nih.gov/ij/download.html. Note that AcuityView runs most efficiently with smaller file sizes, such as 512x512 and 1024x1024; it takes much longer with images that are 2048x2048.
- File Format:
- AcuityView requires that image files be either .bmp, .jpeg, or .png (note that AcuityView v0.1 requires files to be .jpeg, not .jpg. If file names include the extension .jpg, an error will result). ImageJ software (above) can also export images to these formats. AcuityView version 0.1 requires that files must be three-channel images; if you wish to examine only one channel, we recommend running AcuityView on a three-channel image and then using a software like ImageJ to extract the color channel of interest. Note that some png files contain a 4th channel (the alpha-channel). A 4-channel png will result in an error. ImageJ exports png images as 3 channels. If you are experiencing an error using a png, try saving it as a png in ImageJ and retrying.
- You may use any file format; no specific format (i.e. RAW) is required. The image you use should, however, be sharp and in focus.
4. Running the AcuityView Program
- After installing the AcuityView package and library, the function can be run using one line of code. The parameters necessary are:
- photo: using NULL will cause a prompt to appear whereby you can navigate to your image; alternatively, you can enter the file name for your photo, but the photo must be located in your working directory.
- distance: distance is the distance from the viewer to the object of interest in the image; distance can be in any units as long as it is the same units as realWidth.
- realWidth: realWidth is the real width of the entire image, calibrated using the object of interest or by using a size standard placed in the plane of the object of interest in the photograph; realWidth can be in any units as long as it is the same units as distance.
- eyeResolutionX: the minimum resolvable angle of the viewer, in units of degrees (*note that acuity is often reported in the literature in cycles/degree, which is the inverse of degrees)
- eyeResolutionY: NULL will be the standard choice here; very rarely, eyes have different acuities in the X and Y directions, in which case you may specify a different Y acuity than X acuity using this option.
- plot: T will produce a plot of your final image, in addition to saving the final image to your working directory; F will not plot the image, though the image will still be saved to your working directory.
- output: enter the file name for your output file, which will be placed in your working directory; use the format “filename.filetype”. Output filetype can be .bmp, .png, or .jpeg.
A note for Linux users:
You may need to install the fftw library in order for the dependent R package "fftwtools" to install and perform correctly. The FFTW website and install information can be found here: http://www.fftw.org/. This library can easily be installed on Ubuntu with: apt-get install fftw3-dev
Example line of command code:
AcuityView(photo = NULL, distance = 0.5, realWidth = 3, eyeResolutionX = 0.2, eyeResolutionY = NULL, plot = T, output="Acuity_image.jpeg")
