CCPi-Regularisation Toolkit (CCPi-RGL)

Iterative image reconstruction (IIR) methods normally require regularisation to stabilise the convergence and make the reconstruction problem more well-posed. CCPi-RGL software consists of 2D/3D regularisation modules for single-channel and multi-channel reconstruction problems. The regularisation modules are well-suited to use with splitting algorithms, such as ADMM and FISTA. Furthermore, the toolkit can be used independently to solve image denoising and inpaiting tasks. The core modules are written in C-OMP and CUDA languages, wrappers for Matlab and Python are provided.

Prerequisites:

MATLAB OR
Python (tested ver. 3.5/2.7); Cython
C compilers
nvcc (CUDA SDK) compilers

Package modules:

Single-channel (denoising):

Rudin-Osher-Fatemi (ROF) Total Variation (explicit PDE minimisation scheme) 2D/3D CPU/GPU (Ref. 1)
Fast-Gradient-Projection (FGP) Total Variation 2D/3D CPU/GPU (Ref. 2)
Split-Bregman (SB) Total Variation 2D/3D CPU/GPU (Ref. 5)
Total Generalised Variation (TGV) model for higher-order regularisation 2D CPU/GPU (Ref. 6)
Linear and nonlinear diffusion (explicit PDE minimisation scheme) 2D/3D CPU/GPU (Ref. 8)
Anisotropic Fourth-Order Diffusion (explicit PDE minimisation) 2D/3D CPU/GPU (Ref. 9)
A joint ROF-LLT (Lysaker-Lundervold-Tai) model for higher-order regularisation 2D/3D CPU/GPU (Ref. 10,11)

Multi-channel (denoising):

Fast-Gradient-Projection (FGP) Directional Total Variation 2D/3D CPU/GPU (Ref. 3,4,2)
Total Nuclear Variation (TNV) penalty 2D+channels CPU (Ref. 7)

Inpainting:

Linear and nonlinear diffusion (explicit PDE minimisation scheme) 2D/3D CPU (Ref. 8)
Iterative nonlocal vertical marching method 2D CPU

Installation:

The package comes as a CMake project so you will need CMake (v.>=3) to configure it. Additionally you will need a C compiler, make (on linux) and CUDA SDK where available. The toolkit may be used directly from C/C++ as it is compiled as a shared library (check-out the include files in Core for this). We provide wrappers for Python and Matlab.

Clone this repository to a directory, i.e. CCPi-Regularisation-Toolkit,
create a build directory.
Issue cmake to configure (or cmake-gui, or ccmake, or cmake3). Use additional flags to fine tune the configuration.

CMake flags

Flags used during configuration

CMake flag	type	meaning
`BUILD_PYTHON_WRAPPER`	bool	`ON\|OFF` whether to build the Python wrapper
`BUILD_MATLAB_WRAPPER`	bool	`ON\|OFF` whether to build the Matlab wrapper
`CMAKE_INSTALL_PREFIX`	path	your favourite install directory
`PYTHON_DEST_DIR`	path	python modules install directory (default `${CMAKE_INSTALL_PREFIX}/python`)
`MATLAB_DEST_DIR`	path	Matlab modules install directory (default `${CMAKE_INSTALL_PREFIX}/matlab`)
`BUILD_CUDA`	bool	`ON\|OFF` whether to build the CUDA regularisers
`CONDA_BUILD`	bool	`ON\|OFF` whether it is installed with `setup.py install`
`Matlab_ROOT_DIR`	path	Matlab directory
`PYTHON_EXECUTABLE`	path	/path/to/python/executable

Here an example of build on Linux:

git clone https://github.com/vais-ral/CCPi-Regularisation-Toolkit.git
mkdir build
cd build
cmake ../CCPi-Regularisation-Toolkit -DCONDA_BUILD=OFF -DBUILD_MATLAB_WRAPPER=ON -DBUILD_PYTHON_WRAPPER=ON -DBUILD_CUDA=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=<your favourite install directory>
make install

Python

Python binaries

Python binaries are distributed via the ccpi conda channel. Currently we produce packages for Linux64, Python 2.7, 3.5 and 3.6, NumPy 1.12 and 1.13.

conda install ccpi-regulariser -c ccpi -c conda-forge

Python (conda-build)

	export CIL_VERSION=0.10.1
	conda build Wrappers/Python/conda-recipe --numpy 1.12 --python 3.5 
	conda install ccpi-regulariser=${CIL_VERSION} --use-local --force
	cd demos/
	python demo_cpu_regularisers.py # to run CPU demo
	python demo_gpu_regularisers.py # to run GPU demo

Python build

If passed CONDA_BUILD=ON the software will be installed by issuing python setup.py install which will install in the system python (or whichever other python it's been picked up by CMake at configuration time.) If passed CONDA_BUILD=OFF the software will be installed in the directory pointed by ${PYTHON_DEST_DIR} which defaults to ${CMAKE_INSTALL_PREFIX}/python. Therefore this directory should be added to the PYTHONPATH.

If Python is not picked by CMake you can provide the additional flag to CMake -DPYTHON_EXECUTABLE=/path/to/python/executable.

Matlab

Matlab wrapper will install in the ${MATLAB_DEST_DIR} directory, which defaults to ${CMAKE_INSTALL_PREFIX}/matlab

If Matlab is not picked by CMake, you could add -DMatlab_ROOT_DIR=<Matlab directory>.

Linux

Because you've installed the modules in <your favourite install directory> you need to instruct Matlab to look in those directories:

PATH="/path/to/mex/:$PATH" LD_LIBRARY_PATH="/path/to/library:$LD_LIBRARY_PATH" matlab

By default /path/to/mex is ${CMAKE_INSTALL_PREFIX}/bin and /path/to/library/ is ${CMAKE_INSTALL_PREFIX}/lib

Windows

On Windows the dll and the mex modules must reside in the same directory. It is sufficient to add the directory at the beginning of the m-file.

addpath(/path/to/library);

Legacy Matlab installation

	
	cd /Wrappers/Matlab/mex_compile
	compileCPU_mex.m % to compile CPU modules
	compileGPU_mex.m % to compile GPU modules (see instructions in the file)

References to implemented methods:

References to Software:

If software is used, please refer to [11], however, the supporting publication is in progress.

Applications:

License:

Apache License, Version 2.0

Acknowledgments:

CCPi-RGL software is a product of the CCPi group and STFC SCD software developers. Any relevant questions/comments can be e-mailed to Daniil Kazantsev at dkazanc@hotmail.com

epapoutsellis/CCPi-Regularisation-Toolkit