Crate ndarray_conv

ndarray-conv provides N-dimensional convolution operations for ndarray arrays.

This crate extends the ndarray library with both standard and FFT-accelerated convolution methods.

Getting Started

To start performing convolutions, you’ll interact with the following:

1. Input Arrays: Use ndarray’s Array or ArrayView as your input data and convolution kernel.
2. Convolution Methods: Call array.conv(...) or array.conv_fft(...). These methods are added to ArrayBase types via the traits ConvExt::conv and ConvFFTExt::conv_fft.
3. Convolution Mode: ConvMode specifies the size of the output.
4. Padding Mode: PaddingMode specifies how to handle array boundaries.

Basic Example:

Here’s a simple example of how to perform a 2D convolution using ndarray-conv:

use ndarray::prelude::*;
use ndarray_conv::{ConvExt, ConvFFTExt, ConvMode, PaddingMode};

// Input data
let input = array![[1, 2, 3], [4, 5, 6], [7, 8, 9]];

// Convolution kernel
let kernel = array![[1, 1], [1, 1]];

// Perform standard convolution with "same" output size and zero padding
let output = input.conv(
    &kernel,
    ConvMode::Same,
    PaddingMode::Zeros,
).unwrap();

println!("Standard Convolution Output:\n{:?}", output);

// Perform FFT-accelerated convolution with "same" output size and zero padding
let output_fft = input.map(|&x| x as f32).conv_fft(
    &kernel.map(|&x| x as f32),
    ConvMode::Same,
    PaddingMode::Zeros,
).unwrap();

println!("FFT Convolution Output:\n{:?}", output_fft);

Choosing a convolution method

• Use ConvExt::conv for standard convolution
• Use ConvFFTExt::conv_fft for FFT accelerated convolution. FFT accelerated convolution is generally faster for larger kernels, but standard convolution may be faster for smaller kernels.

Key Structs, Enums and Traits

• ConvMode: Specifies how to determine the size of the convolution output (e.g., Full, Same, Valid).
• PaddingMode: Specifies how to handle array boundaries (e.g., Zeros, Reflect, Replicate). You can also use PaddingMode::Custom or PaddingMode::Explicit to combine different BorderType strategies for each dimension or for each side of each dimension.
• BorderType: Used with PaddingMode for Custom and Explicit, specifies the padding strategy (e.g., Zeros, Reflect, Replicate, Circular).
• ConvExt: The trait that adds the conv method, extending ndarray arrays with standard convolution functionality.
• ConvFFTExt: The trait that adds the conv_fft method, extending ndarray arrays with FFT-accelerated convolution functionality.

Structs

FftProcessor

Manages FFT planning and execution for convolution operations.

Enums

BorderType

Used with PaddingMode. Specifies the padding mode for a single dimension or a single side of a dimension.

ConvMode

Specifies the convolution mode, which determines the output size.

Error

Error type for convolution operations.

PaddingMode

Specifies the padding mode, which determines how to handle borders.

Traits

ConvExt

Extends ndarray’s ArrayBase with convolution operations.

ConvFFTExt

Extends ndarray’s ArrayBase with FFT-accelerated convolution operations.

WithDilation

Trait for adding dilation information to a kernel.