imageproc Rust Library

Functions in imageproc implicitly assume that pixel colors are stored in a linear color space (e.g., RGB) rather than a non-linear color space (e.g., sRGB).

If you perform operations on non-linear sRGB images without first converting them to a linear space, you may encounter color artifacts. Ensure your input images are in a linear color space before applying processing functions.

The library provides both single-threaded and multi-threaded variations of several functions using the rayon crate.

Note on Performance: Parallel versions are not guaranteed to be faster for all scenarios. The performance benefit depends on the image size and the computational workload per pixel. It is recommended to benchmark your specific use case to decide whether to use parallel or single-threaded functions.

If you enable the display-window feature, you must install the SDL2 development libraries on your system before building.

Ubuntu/Debian:

sudo apt install libsdl2-dev

macOS:

brew install sdl2

Windows: Install SDL2 manually and ensure:

1. The library directory is available to the linker.
2. The DLL directory is included in your PATH.

# Ubuntu/Debian
sudo apt install libsdl2-dev

# macOS
brew install sdl2

The Region<T> trait is a geometrical abstraction representing a set of 2D points with a coordinate type T. It is used to provide a uniform interface for checking point containment across different geometric shapes.

Rect is a primary implementation of this trait, supporting both integer (i32) and floating-point (f32) coordinates.

You can enable or disable specific functionality in imageproc using Cargo features.

Default Features

By default, the following features are enabled:

• rayon: Enables multi-threaded versions of several functions.
• text: Enables text drawing capabilities.
• fft: Enables phash and other functions that depend on the rustfft crate.

Optional Features

• display-window: Enables displaying images using imageproc::window via the sdl2 crate.

You can specify different radii for the X and Y axes to create non-square kernels. For example, setting x_radius to 2 and y_radius to 1 results in a $5 \times 3$ kernel.

use imageproc::filter::median_filter;

let image = gray_image!(
    1, 2, 3, 4, 5;
    255, 200, 4, 11, 7;
    42, 17, 3, 2, 1;
    9, 100, 11, 13, 14;
    15, 87, 99, 21, 45
);

// Uses a 5x3 kernel
let filtered = median_filter(&image, 2, 1);

The median_filter works on multi-channel images (like RGB) by processing each channel independently.

use imageproc::filter::median_filter;

let image = rgb_image!(
    [  1,   9, 10], [  2, 100,  10], [  3,  11,  10];
    [200, 200, 10], [  6,   6,  10], [  7,   7,  10];
    [  9,   1, 10], [100,   2,  10], [ 11,   3,  10]
);

let filtered = median_filter(&image, 1, 1);

Dilation sets all pixels within a specified distance k of a foreground pixel (non-zero intensity) to white (255). This operation expands the foreground regions.

You can use dilate to return a new image or dilate_mut to modify an existing GrayImage in place. The shape of the expansion is determined by the Norm provided (e.g., Norm::L1, Norm::L2, or Norm::LInf).

use image::GrayImage;
use imageproc::morphology::dilate;
use imageproc::distance_transform::Norm;

let image = gray_image!(
    0,   0,   0,   0,   0;
    0,   0,   0,   0,   0;
    0,   0, 255,   0,   0;
    0,   0,   0,   0,   0;
    0,   0,   0,   0,   0
);

// L1 norm dilation
let l1_dilated = dilate(&image, Norm::L1, 1);

To define a rectangular region, use Rect::at(x, y) to specify the top-left corner, followed by .of_size(width, height) to set the dimensions. Note that width and height must be strictly positive (> 0); otherwise, the code will panic.

use imageproc::rect::Rect;

// Construct a rectangle with top-left corner at (4, 5), width 6 and height 7.
let rect = Rect::at(4, 5).of_size(6, 7);

Quick functions to compute the magnitude of gradients for grayscale images using standard filters:

• sobel_gradients(image: &GrayImage) -> Image<Luma<u16>>: Uses Sobel kernels.
• prewitt_gradients(image: &GrayImage) -> Image<Luma<u16>>: Uses Prewitt kernels.

use imageproc::gradients::{sobel_gradients, prewitt_gradients};

let sobel_mag = sobel_gradients(&gray_image);
let prewitt_mag = prewitt_gradients(&gray_image);