Home

Awesome

Numerical Solver Library

The Numerical Solver Library (NSoL) is a Python-based open-source toolkit for research developed within the GIFT-Surg project and contains several implementations of denoising and deconvolution algorithms.

The algorithm and software were developed by Michael Ebner at the Wellcome/EPSRC Centre for Interventional and Surgical Sciences, University College London (UCL) (2015 -- 2019), and the Department of Surgical and Interventional Sciences, King's College London (KCL) (since 2019).

If you have any questions or comments, please drop an email to michael.ebner@kcl.ac.uk.

Features

Implemented solvers include

to solve

<!--https://www.url-encode-decode.com/--> <!--```math--> <!--\vec{x}^*:=\text{argmin}_{\vec{x}}\Big[\Vert\vec{x}-\vec{x}_0\Vert_{\ell^p}^p+\alpha\,\text{Reg}(\vec{x})\Big],\quad\text{for}{\quad}p\in\{1,\,2\},--> <!--```--> <p align="center"> <img src="http://latex.codecogs.com/svg.latex?%5Cvec%7Bx%7D%5E%2A%3A%3D%5Ctext%7Bargmin%7D_%7B%5Cvec%7Bx%7D%7D%5CBig%5B%5CVert%5Cvec%7Bx%7D-%5Cvec%7Bx%7D_0%5CVert_%7B%5Cell%5Ep%7D%5Ep%2B%5Calpha%5C%2C%5Ctext%7BReg%7D%28%5Cvec%7Bx%7D%29%5CBig%5D%2C%5Cquad%5Ctext%7Bfor%7D%7B%5Cquad%7Dp%5Cin%5C%7B1%2C%5C%2C2%5C%7D%2C"> </p> and <!--https://www.url-encode-decode.com/--> <!--```math--> <!--\vec{x}^*:=\text{argmin}_{\vec{x}}\Big[\sum_{i=1}^N\varrho\big((A\vec{x}-\vec{b})_i^2)+\alpha\,\text{Reg}(\vec{x})\Big],--> <!--```--> <p align="center"> <img src="http://latex.codecogs.com/svg.latex?%5Cvec%7Bx%7D%5E%2A%3A%3D%5Ctext%7Bargmin%7D_%7B%5Cvec%7Bx%7D%7D%5CBig%5B%5Csum_%7Bi%3D1%7D%5EN%5Cvarrho%5Cbig%28%28A%5Cvec%7Bx%7D-%5Cvec%7Bb%7D%29_i%5E2%29%2B%5Calpha%5C%2C%5Ctext%7BReg%7D%28%5Cvec%7Bx%7D%29%5CBig%5D%2C"> </p>

in 1D, 2D or 3D for a variety of regularizers img and data loss functions img.

The available regularizers, depending on the minimization problem, include

<!-- * Zeroth-order Tikhonov (TK0): $`\text{Reg}(\vec{x}) = \frac{1}{2}\Vert \vec{x} \Vert_{\ell^2}^2`$ --> <!-- * First-order Tikhonov (TK1): $`\text{Reg}(\vec{x}) = \frac{1}{2}\Vert \nabla \vec{x} \Vert_{\ell^2}^2`$ --> <!-- * Isotropic Total Variation (TV): $`\text{Reg}(\vec{x}) = \text{TV}_\text{iso}(\vec{x}) = \big\Vert |\nabla \vec{x}| \big\Vert_{\ell^1}`$ --> <!-- * Huber Function: $`\text{Reg}(\vec{x}) = \frac{1}{2\gamma} \big| |\nabla \vec{x}| \big|_{\gamma}`$ -->

Data loss functions img are motivated by SciPy and allow for robust outlier rejection. Implemented data loss functions are:

<!--$`\varrho(e)=e`$--> <!--$`\varrho(e)=2(\sqrt{1+e}-1)`$ --> <!--$`\varrho(e)=|e|_\gamma=\begin{cases}e,&e<\gamma^2\\2\gamma\sqrt{e}-\gamma^2,&e\ge\gamma^2\end{cases}`$--> <!--$`\varrho(e)=\arctan(e)`$--> <!--$`\varrho(e)=\ln(1 + e)`$-->

Additionally, the choice of finding optimal reconstruction parameters is facilitated by providing several evaluation methods including

in the course of parameter studies. Implemented similarity measures are

Installation

NSoL was developed in

and tested for Python 2.7.12 and 3.5.2.

In case NSoL is used in conjuction with any of the toolkits of NiftyMIC, Volumetric Reconstruction From Printed Films or SimpleReg, please

If NSoL is used standalone, please run instead

Afterwards, clone this repository via

where all remaining dependencies can be installed using pip:

Usage

Denoising

TVL1/TVL2/HuberL2/HuberL1 Denoising can be run via

nsol_run_denoising \
--observation path-to-observation-png-nii-mat \
--result path-to-denoised-result-png-nii-mat \
--reconstruction-type TVL1 \
--alpha 0.05 \
--iterations 50

nsol_run_denoising \
--observation path-to-observation-png-nii-mat \
--reference path-to-reference-png-nii-mat \
--result path-to-denoised-result-png-nii-mat \
--reconstruction-type TVL1 \
--alpha 0.05 \
--iterations 50

Deconvolution

Examples for TK0L2/TK1L2/TVL2/HuberL2 deconvolution calls are

nsol_run_deconvolution \
--observation path-to-observation-png-nii-mat \
--result path-to-denoised-result-png-nii-mat \
--reconstruction-type HuberL2 \
--blur 1.2 \
--alpha 0.05 \
--iterations 50

nsol_run_deconvolution \
--observation path-to-observation-png-nii-mat \
--reference path-to-reference-png-nii-mat \
--result path-to-denoised-result-png-nii-mat \
--reconstruction-type HuberL2 \
--alpha 0.05 \
--blur 1.2 \
--iterations 50 \
--data-loss soft_l1 \
--minimizer L-BFGS-B

Parameter Studies

Parameter studies for the denoising problem (and, similarly, for deconvolution problem) can be performed by, e.g.,

nsol_run_denoising_study \
--observation path-to-observation-png-nii-mat \
--dir-output path-to-parameter-study \
--reference path-to-reference-png-nii-mat \
--reconstruction-type TVL2 \
--study-name TVL2-Denoising \
--measures RMSE PSNR NCC NMI SSIM \
--alpha-range 0.001 0.05 20

The results can be visualized by

nsol_show_parameter_study \
--dir-input path-to-parameter-study \
--study-name TVL2-Denoising \
--dir-output-figures dir-to-figures

Licensing and Copyright

Copyright (c) 2020 Michael Ebner and contributors. This framework is made available as free open-source software under the BSD-3-Clause License. Other licenses may apply for dependencies.

Funding

This work is partially funded by the UCL Engineering and Physical Sciences Research Council (EPSRC) Centre for Doctoral Training in Medical Imaging (EP/L016478/1), the Innovative Engineering for Health award (Wellcome Trust [WT101957] and EPSRC [NS/A000027/1]), and supported by researchers at the National Institute for Health Research University College London Hospitals (UCLH) Biomedical Research Centre.

References

Associated publications are