Crate deconvolution

Expand description

Rust image deconvolution and restoration library.

Recovering images from blur depends on a point-spread function, stable frequency-domain utilities, and careful regularization. deconvolution provides known-PSF restoration, blind workflows, PSF/OTF conversion, preprocessing helpers, simulation fixtures, and ndarray APIs.

§Overview

Image API: Top-level functions use image::DynamicImage and return images ready to save.
Known PSF methods: Inverse filters, Wiener, Richardson-Lucy, constrained, proximal, Krylov, and MLE-style restoration.
Blind methods: Blind Richardson-Lucy, blind maximum likelihood, and parametric PSF estimation.
PSF and OTF types: Kernel2D, Kernel3D, Transfer2D, Transfer3D, and psf::Blur2D/psf::Blur3D.
PSF tools: Gaussian, motion, defocus, microscopy models, support utilities, and PSF/OTF conversion.
Preprocessing: Edge tapering, apodization, range normalization, and NSR estimation.
Simulation: Deterministic blur, noise, and synthetic fixture generation.
ndarray support: 2D image arrays and 3D volume workflows.
Feature flags: rayon by default; optional f16 support.

§Quick Start

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input = image::open("before_deconvolution.png")?;
    let psf = gaussian2d((15, 15), 2.15)?;

    let restored = wiener_with(&input, &psf, &Wiener::new().nsr(2.5e-4))?;
    restored.save("after_deconvolution.png")?;

    Ok(())
}

§Image API

Supported image::DynamicImage variants:

ImageLuma8
ImageLumaA8
ImageRgb8
ImageRgba8
ImageLuma16
ImageLumaA16
ImageRgb16
ImageRgba16
ImageRgb32F
ImageRgba32F

Configuration enums are shared across algorithm families:

Boundary: Zero, Replicate, Reflect, Symmetric, Periodic
Padding: None, Same, Minimal, NextFastLen, Explicit2, Explicit3
ChannelMode: Independent, LumaOnly, IgnoreAlpha, PremultipliedAlpha
RangePolicy: PreserveInput, Clamp01, ClampNegPos1, Unbounded

Use ChannelMode::Independent for per-channel color restoration, ChannelMode::LumaOnly when the blur should primarily affect luminance, and RangePolicy::PreserveInput when working in normal image sample ranges.

§PSF and OTF API

Kernel and transfer types:

Basic PSF generators:

Blind initialization helpers:

Support utilities:

Transfer conversion utilities:

Optical and microscopy models:

§Algorithm Families

Spectral and inverse filters: Frequency-domain restoration.

Richardson-Lucy and iterative restoration: Poisson-style and residual-update restoration.

Constrained, proximal, Krylov, and MLE-style solvers: Bound-aware, sparse, scientific-imaging, and microscopy-oriented restoration.

Custom configs: Use _with variants and configuration types such as Wiener, RichardsonLucy, spectral::InverseFilter, iterative::Landweber, optimization::Fista, or optimization::Qmle.

Blind workflows estimate both the restored image and the PSF. Image-facing blind workflows support Gray and GrayAlpha image::DynamicImage variants for u8 and u16 samples.

blind::maximum_likelihood shares the same Poisson EM restoration core as blind Richardson-Lucy.

Configuration and output types:

Parametric PSF families:

Gaussian { sigma }
MotionLinear { length, angle_deg }
Defocus { radius }
OrientedGaussian { sigma_major, sigma_minor, angle_deg }

§ndarray Workflows

The public nd module exposes array-first workflows for users who already work in ndarray or need 3D volumes. Enable the optional f16 feature to pass half::f16 arrays into the 2D ndarray API while keeping computation in f32.

2D known-PSF methods in nd::known_psf:

Blind methods in nd::blind:

3D and microscopy methods in nd::microscopy:

§Preprocessing

Preprocessing utilities help reduce ringing and prepare numerical inputs.

Use preprocess::edgetaper() or apodization before frequency-domain deconvolution when strong edge discontinuities create ringing artifacts.

§Simulation and Fixtures

Deterministic: Same input and seed produce the same simulated output.

Fixtures: Synthetic images and volumes for tests, examples, and benchmarks.

§Optional rayon Integration

rayon is enabled by default. The optional f16 feature adds half::f16 input/output support for the 2D ndarray API; computation remains in f32.

[features]
default = ["rayon"]
rayon = ["dep:rayon", "ndarray/rayon", "image/rayon"]
f16 = ["dep:half"]

Disable default features for serial builds:

cargo test --no-default-features

§Reports, Errors, and Prelude

Error handling:

Solver reports:

Prelude:

prelude

Runnable examples: See examples/ and the repository README.

Re-exports§

pub use crate::error::Error;
pub use crate::error::Result;
pub use crate::iterative::RichardsonLucy;
pub use crate::iterative::richardson_lucy;
pub use crate::otf::Transfer2D;
pub use crate::otf::Transfer3D;
pub use crate::psf::Kernel2D;
pub use crate::psf::Kernel3D;
pub use crate::spectral::Wiener;
pub use crate::spectral::wiener;
pub use crate::traits::Boundary;
pub use crate::traits::ChannelMode;
pub use crate::traits::Padding;
pub use crate::traits::RangePolicy;

Modules§

blind: Blind deconvolution solvers that estimate both the latent image and PSF.
error: Crate error and result types.
iterative: Iterative image deconvolution algorithms for known 2D PSFs.
nd: ndarray convenience APIs for 2D images and 3D microscopy volumes.
optimization: Constrained, Krylov, MLE, and proximal restoration algorithms.
otf: Optical transfer functions and PSF/OTF conversion utilities.
prelude: Common imports for simple deconvolution workflows.
preprocess: Image preprocessing helpers used before restoration.
psf: Point-spread function types, generators, constraints, and support helpers.
simulate: Synthetic blur, noise, and phantom generation utilities.
spectral: Frequency-domain deconvolution algorithms.
traits: Shared configuration enums used across image and ndarray solvers.

Structs§

SolveReport: Iteration diagnostics returned by iterative solvers.

Enums§

StopReason: Reason an iterative solver stopped.