pbkx/deconvolution

来源：https://github.com/pbkx/deconvolution

deconvolution

crates.io (https://crates.io/crates/deconvolution)
docs.rs (https://docs.rs/deconvolution)
许可证

左侧为运动模糊样本；右侧使用 wiener_with 恢复后的结果。

Rust 图像去卷积与恢复库。从模糊中恢复图像依赖于点扩散函数、稳定的频域工具以及细致的正则化。deconvolution 提供已知 PSF 复原、盲法工作流、PSF/OTF 转换、预处理辅助函数、仿真测试工具以及 ndarray API。

概述

• 图像 API：顶层函数使用 image::DynamicImage 并返回可直接保存的图像。
• 已知 PSF 方法：逆滤波器、维纳滤波、理查森-露西、约束、近端梯度、Krylov 及 MLE 式复原。
• 盲法方法：盲理查森-露西、盲最大似然估计以及参数化 PSF 估计。
• PSF 和 OTF 类型：Kernel2D、Kernel3D、Transfer2D、Transfer3D、Blur2D/Blur3D。
• PSF 工具：高斯、运动、离焦、显微模型、支撑工具及 PSF/OTF 转换。
• 预处理：边缘渐变、切趾、范围归一化及 NSR 估计。
• 仿真：确定性模糊、噪声及合成测试数据生成。
• ndarray 支持：2D 图像数组及 3D 体数据工作流。
• 特性标志：默认启用 rayon；可选择 f16 支持。

安装

cargo add deconvolution

[dependencies]
deconvolution = "0.2.0"

图像加载：当你的应用需要打开或保存图像文件时，添加 image。

cargo add image

串行构建：禁用默认特性以关闭 rayon。

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

快速入门

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(())
}

图像 API

支持的 DynamicImage 变体：

• ImageLuma8
• ImageLumaA8
• ImageRgb8
• ImageRgba8
• ImageLuma16
• ImageLumaA16
• ImageRgb16
• ImageRgba16
• ImageRgb32F
• ImageRgba32F

配置枚举在不同算法族间共享：

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

使用 ChannelMode::Independent 进行逐通道色彩恢复，ChannelMode::LumaOnly 当模糊主要影响亮度时，RangePolicy::PreserveInput 在普通图像样本范围内工作时使用。

PSF 和 OTF API

基本 PSF 生成器：

• delta2d、delta3d
• gaussian2d、gaussian3d
• motion_linear
• disk、pillbox、defocus
• box2d、box3d
• oriented_gaussian

盲法初始化辅助函数：

• psf::init::uniform
• psf::init::gaussian_guess
• psf::init::motion_guess
• psf::init::from_support

支撑工具：

• normalize、normalize_3d
• center、center_3d
• pad_to、pad_to_3d
• crop_to、crop_to_3d
• flip、flip_3d
• validate、validate_3d
• support_mask、support_mask_3d

传递函数转换工具：

• otf::convert::psf2otf
• otf::convert::psf2otf_3d
• otf::convert::otf2psf
• otf::convert::otf2psf_3d

光学与显微模型：

• BornWolfParams / born_wolf
• GibsonLanniParams / gibson_lanni
• VariableRiGibsonLanniParams / variable_ri_gibson_lanni
• RichardsWolfParams / richards_wolf
• lorentz2d
• astigmatic
• double_helix
• otf::spectra::koehler_otf
• otf::spectra::defocus_otf

已知 PSF 方法

谱与逆滤波器

频域复原。

• naive_inverse_filter
• inverse_filter
• truncated_inverse_filter
• regularized_inverse_filter
• tikhonov_inverse_filter
• wiener
• unsupervised_wiener

配置类型：

• InverseFilter
• RegularizedInverseFilter
• TikhonovInverseFilter
• Wiener
• UnsupervisedWiener

自定义配置：使用 _with 变体。

理查森-露西及正则化 RL

泊松型乘法复原。

• richardson_lucy
• damped_richardson_lucy
• richardson_lucy_tv

配置类型：

• RichardsonLucy
• RichardsonLucyTv

迭代最小二乘法

残差更新复原。

• landweber
• van_cittert
• tikhonov_miller
• ictm

配置类型：

• Landweber
• VanCittert
• TikhonovMiller
• Ictm

约束求解器

边界感知复原。

• nnls
• bvls

配置类型：

• Nnls
• Bvls

稀疏与近端方法

近端梯度复原。

• ista
• fista

配置与模型类型：

• Ista
• Fista
• SparseBasis

Krylov 与高级迭代方法

科学成像求解器。

• mrnsd
• cgls
• wpl
• hybr

配置类型：

• Mrnsd
• Cgls
• Wpl
• Hybr

最大似然族

面向显微的 MLE 式复原。

• cmle
• gmle
• qmle

配置类型：

• Cmle
• Gmle
• Qmle

盲去卷积

盲法工作流同时估计复原图像和 PSF。面向图像的盲法工作流支持 u8 和 u16 样本的 Gray 与 GrayAlpha DynamicImage 变体。

• blind::richardson_lucy
• blind::maximum_likelihood
• blind::parametric

blind::maximum_likelihood 与盲理查森-露西共享相同的泊松 EM 复原核心。

配置与输出类型：

• BlindRichardsonLucy
• BlindMaximumLikelihood
• BlindParametric
• BlindOutput
• BlindReport
• ParametricPsf
• PsfConstraint

PSF 约束：

• Nonnegative
• NormalizeSum
• SupportMask(...)

参数化 PSF 族：

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

ndarray 工作流

公开的 nd 模块为已在 ndarray 中工作或需要 3D 体数据的用户提供数组优先的工作流。启用可选的 f16 特性，可以将 half::f16 数组传入 2D ndarray API，同时计算仍在 f32 中进行。

nd::known_psf 中的 2D 已知 PSF 方法：

• wiener、unsupervised_wiener
• richardson_lucy、richardson_lucy_tv
• landweber、van_cittert、tikhonov_miller、ictm
• nnls、bvls
• ista、fista
• mrnsd、cgls、wpl、hybr

nd::blind 中的盲法方法：

• richardson_lucy
• maximum_likelihood

nd::microscopy 中的 3D 与显微方法：

• wiener
• richardson_lucy
• richardson_lucy_tv
• cmle
• gmle
• qmle

预处理

预处理工具有助于减少振铃效应并准备数值输入。

• preprocess::apodize
• preprocess::apodize::window_edges
• preprocess::edgetaper
• preprocess::estimate_nsr
• preprocess::normalize_range

在频域去卷积前，当强烈的边缘不连续产生振铃伪影时，使用 edgetaper 或切趾处理。

仿真与测试数据

确定性：相同的输入和种子会产生相同的仿真输出。
测试数据：用于测试、示例和基准测试的合成图像和体数据。

模糊与退化：

• simulate::blur::blur
• simulate::blur::blur_otf
• simulate::blur::blur_3d
• simulate::blur::blur_otf_3d
• simulate::blur::degrade

噪声模型：

• simulate::noise::add_gaussian_noise
• simulate::noise::add_poisson_noise
• simulate::noise::add_readout_noise

合成测试数据：

• simulate::phantom::checkerboard_2d
• simulate::phantom::gaussian_blob_2d
• simulate::phantom::rgb_edges_2d
• simulate::phantom::phantom_3d

可选的 rayon 集成

rayon 默认启用。可选的 f16 特性为 2D ndarray API 增加了 half::f16 输入/输出支持；计算仍保持在 f32。

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

禁用默认特性以进行串行构建：

cargo test --no-default-features

示例程序

面向图像的工作流：

cargo run --example wiener -- input.png output.png
cargo run --example richardson_lucy
cargo run --example blind_motion
cargo run --example edgetaper
cargo run --example custom_regularizer

体数据工作流：

cargo run --example microscopy_volume

基准测试与开发

基准测试：基于 Criterion 的基准测试族。

• spectral
• rl
• blind
• volume

cargo bench --no-run
cargo bench --bench spectral
cargo bench --bench rl
cargo bench --bench blind
cargo bench --bench volume

检查：

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo check --all-features
cargo test --workspace --all-targets --all-features
cargo doc --workspace --no-deps --all-features

限制与范围

• 面向图像的已知 PSF 算法支持 u8/u16 的 Gray、GrayAlpha、Rgb 和 Rgba DynamicImage 变体，以及 32 位浮点 Rgb 和 Rgba 图像。
• 面向图像的盲法算法支持 u8/u16 的 Gray 和 GrayAlpha DynamicImage 变体。

许可证

deconvolution 基于 MIT 许可证 发布，版权所有 (c) 2026 pbkx。