library(imagine)

IMAGing engINE: Tools for Application of Image Filters to Data Matrices

The imagine package streamlines the application of image-filtering algorithms to numeric data matrices. It implements efficient median-filtering and 2D convolution routines in C++ via Rcpp, enabling fast processing of large datasets.

Installation

For installing imagine, as follows:

install.packages("imagine")

Engines

The imagine package relies on C++-based algorithms, referred to as engines, implemented using the Rcpp and RcppArmadillo packages to accelerate filtering operations. These engines provide substantial performance improvements when working with large matrices.

As of version 2.1.0, the following engines are available:

• Engine 1: Standard 2D convolution (kernel applied to each cell neighborhood and summed).
• Engine 2: Same as Engine 1, but returns a quantile defined by the probs argument.
• Engine 3: Computes the mean over a square neighborhood defined by radius argument.
• Engine 4: Same as Engine 3, but returns a quantile defined by probs argument.
• Engine 5: Contextual Median Filter described in Belkin and O’Reilly (2009).
• Engines 6 and 7: Gradient filters described in Agenbag et al. (2003).

Since version 2.0.0, the radius argument can accept two values, allowing rectangular (non-square) neighborhoods.

Main functions

The package provides five main functions and two wrappers.

Convolution functions

# Build kernels
# Kernel 1: For bottom edge recognition
kernel1 <- matrix(
  data = c(-1, -2, -1, 
            0,  0,  0,
            1,  2,  1), 
  nrow = 3
)

# Kernel 2: Diagonal weighting
kernel2 <- matrix(
  data = c(-2, 0, 0,
            0, 1, 0,
            0, 0, 2), 
  nrow = 3
)

# Apply filters
convolutionExample  <- convolution2D(X = wbImage, kernel = kernel1)
convQuantileExample <- convolutionQuantile(X = wbImage, kernel = kernel2, probs = 0.1)

To compare results, we plot the filtered outputs using the image function (Figure 1).

Original vs filtered outputs

Median-filter asociated functions

# Add some noise (NA) to the image (matrix)
set.seed(7)
naIndex <- sample(
  x = seq(prod(dim(myMatrix))), 
  size = as.integer(0.4*prod(dim(myMatrix))), 
  replace = FALSE
)
myMatrix[naIndex] <- NA

# Build kernel
radius <- 3

# Apply filters
meanfilterExample     <- meanFilter(X = myMatrix, radius = radius)
quantilefilterExample <- quantileFilter(X = myMatrix, radius = radius, probs = 0.1)
medianfilterExample   <- medianFilter(X = myMatrix, radius = radius)

We now compare the original and filtered matrices (Figure 2).

Original and Filtered

Kernel application

In image processing, convolution is one of the most widely used operations. It consists of combining two arrays: the image (a matrix) and a kernel (a smaller matrix), which weights each pixel based on its neighborhood. Different kernels produce different effects, such as smoothing, shifting, or edge detection. Users should be cautious with kernel size, as larger neighborhoods reduce the number of valid pixels near the edges. All functions in imagine support recursive application through the times argument (Figure 3).

medianFilter(X = wbImage, radius = 5, times = 50)

Filters based on published articles

Since version 2.1.0, imagine includes implementations of algorithms from the literature for detecting oceanographic gradients:

• contextualMF: Based on Belkin and O’Reilly (2009).
• agenbagFilters: Based on Agenbag et al. (2003).

Although both functions are available directly in imagine, their use is recommended through the grec package for more specialized workflows.