Deconvolution: A Rust Library for Image Restoration

The deconvolution crate is a specialized Rust toolkit designed for the restoration of images affected by blur.

To successfully recover an image from a blurred state, one requires a precise point-spread function (PSF), robust utilities for operating in the frequency domain, and a strategic approach to regularization.

This library provides a comprehensive suite of tools, including restoration for known PSFs, blind deconvolution workflows, conversion between PSFs and OTFs, preprocessing utilities, simulation tools, and integration with ndarray APIs.

🛠️ Conceptual Workflow

The process of image degradation can be represented mathematically as: $g = (f * h) + n$ Where:

• $g$ is the observed blurred image.
• $f$ is the original latent image.
• $h$ is the Point Spread Function (PSF).
• $*$ denotes the convolution operator.
• $n$ is additive noise.

The goal of this crate is to solve for $f$.

---

🚀 Getting Started

Installation

To add the library to your project, run: cargo add deconvolution

Alternatively, edit your Cargo.toml:

[dependencies]
deconvolution = "0.2.0"
# Required for loading/saving image files
image = "0.24" 

Optimization Tip: To disable rayon and perform a serial build, use:

deconvolution = { version = "0.2.0", default-features = false }

Setup Checklist

• Add deconvolution to dependencies.
• Add image crate for file I/O.
• Define or estimate your PSF.
• Select a restoration algorithm (e.g., Wiener).

Quick Start Example

use deconvolution::psf::basic::gaussian2d;
use deconvolution::spectral::{wiener_with, Wiener};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load the blurred source
    let input = image::open("before_deconvolution.png")?;
    
    // Generate a Gaussian PSF
    let psf = gaussian2d(5.0, 1.0); 
    
    // Apply Wiener restoration
    let restored = wiener_with(input, psf, Wiener::new());
    
    Ok(())
}

---

📖 API Reference

Image API

The top-level functions are designed to work with image::DynamicImage, ensuring the output is ready for immediate saving.

Supported Image Formats:

Color Space	8-bit	16-bit	32-bit Float
Luma	ImageLuma8	ImageLuma16	ImageRgb32F
Luma + Alpha	ImageLumaA8	ImageLumaA16	ImageRgba32F
RGB	ImageRgb8	ImageRgb16	—
RGBA	ImageRgba8	ImageRgba16	—

Configuration Enums:

• Boundary: Zero, Replicate, Reflect, Symmetric, Periodic
• Padding: None, Same, Minimal, NextFastLen, Explicit2, Explicit3
• ChannelMode: Independent (per-channel), LumaOnly (luminance focus), IgnoreAlpha, PremultipliedAlpha
• RangePolicy: PreserveInput, Clamp01, ClampNegPos1, Unbounded

---

PSF and OTF API

The library provides extensive tools for managing Point Spread Functions (PSF) and Optical Transfer Functions (OTF).

1. Generators & Initialization

• Basic PSFs: delta2d, delta3d, gaussian2d, gaussian3d, motion_linear, disk, pillbox, defocus, box2d, box3d, and oriented_gaussian.
• Blind Init Helpers: psf::init::uniform, psf::init::gaussian_guess, psf::init::motion_guess, and psf::init::from_support.

2. Utility Functions

• Support: normalize, center, pad_to, crop_to, flip, validate, and support_mask (available in 2D and 3D).
• Conversion: otf::convert::psf2otf and otf::convert::otf2psf (available in 2D and 3D).

3. Specialized Optical Models

For scientific and microscopy applications:

• BornWolfParams $\rightarrow$ born_wolf
• GibsonLanniParams $\rightarrow$ gibson_lanni
• VariableRiGibsonLanniParams $\rightarrow$ variable_ri_gibson_lanni
• RichardsWolfParams $\rightarrow$ richards_wolf
• Others: lorentz2d, astigmatic, double_helix, koehler_otf, and defocus_otf.

---

🧪 Restoration Methods

Known PSF Methods

When the PSF is already known, use these frequency-domain or iterative solvers:

• Spectral/Inverse Filters:
  • naive_inverse_filter, inverse_filter, truncated_inverse_filter, regularized_inverse_filter, tikhonov_inverse_filter, wiener, unsupervised_wiener.
  • Configs: InverseFilter, RegularizedInverseFilter, TikhonovInverseFilter, Wiener, UnsupervisedWiener.
• Richardson-Lucy (RL):
  • richardson_lucy, damped_richardson_lucy, richardson_lucy_tv.
  • Configs: RichardsonLucy, RichardsonLucyTv.
• Iterative Least-Squares:
  • landweber, van_cittert, tikhonov_miller, ictm.
  • Configs: Landweber, VanCittert, TikhonovMiller, Ictm.
• Constrained Solvers:
  • nnls, bvls.
  • Configs: Nnls, Bvls.
• Proximal Methods:
  • ista, fista.
  • Configs: Ista, Fista, SparseBasis.
• Krylov/Advanced Iterative:
  • mrnsd, cgls, wpl, hybr.
  • Configs: Mrnsd, Cgls, Wpl, Hybr.
• Maximum-Likelihood (MLE):
  • cmle, gmle, qmle.
  • Configs: Cmle, Gmle, Qmle.

Blind Deconvolution

If the PSF is unknown, the library can estimate both the image and the PSF simultaneously.

• Supported Workflows: blind::richardson_lucy and blind::maximum_li.
• Compatibility: Supports Gray and GrayAlpha DynamicImage variants for both u8 and u16 samples.

---

🛠️ Additional Features

• Preprocessing: Includes edge tapering, apodization, range normalization, and NSR estimation.
• Simulation: Tools for creating synthetic fixtures via deterministic blur and noise injection.

Example Result: Before (left): Motion-blurred sample. After (right): Restored using wiener_with.