Skip to content

Commit fa47153

Browse files
casperdclcasperdcl
committed
tidy readme
1 parent 0a29045 commit fa47153

File tree

1 file changed

+42
-43
lines changed

1 file changed

+42
-43
lines changed

‎Readme.md

+42-43
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,25 @@
11
# CCPi-Regularisation Toolkit ([Software X paper](https://www.sciencedirect.com/science/article/pii/S2352711018301912))
22

3-
| Master | Development | Anaconda binaries |
4-
|--------|-------------|-------------------|
5-
| [![Build Status](https://anvil.softeng-support.ac.uk/jenkins/buildStatus/icon?job=CILsingle/CCPi-Regularisation-Toolkit)](https://anvil.softeng-support.ac.uk/jenkins/job/CILsingle/job/CCPi-Regularisation-Toolkit/) | [![Build Status](https://anvil.softeng-support.ac.uk/jenkins/buildStatus/icon?job=CILsingle/CCPi-Regularisation-Toolkit-dev)](https://anvil.softeng-support.ac.uk/jenkins/job/CILsingle/job/CCPi-Regularisation-Toolkit-dev/) | ![conda version](https://anaconda.org/ccpi/ccpi-regulariser/badges/version.svg) ![conda last release](https://anaconda.org/ccpi/ccpi-regulariser/badges/latest_release_date.svg) [![conda platforms](https://anaconda.org/ccpi/ccpi-regulariser/badges/platforms.svg) ![conda dowloads](https://anaconda.org/ccpi/ccpi-regulariser/badges/downloads.svg)](https://anaconda.org/ccpi/ccpi-regulariser) |
6-
7-
**Iterative image reconstruction (IIR) methods frequently require regularisation to ensure convergence and make inverse problem well-posed. The CCPi-Regularisation Toolkit (CCPi-RGL) toolkit provides a set of 2D/3D regularisation strategies to guarantee a better performance of IIR methods (higher SNR and resolution). The regularisation modules for scalar and vectorial datasets are based on the [proximal operator](https://en.wikipedia.org/wiki/Proximal_operator) framework and can be used with [proximal splitting algorithms](https://en.wikipedia.org/wiki/Proximal_gradient_method), such as PDHG, Douglas-Rachford, ADMM, FISTA and [others](https://arxiv.org/abs/0912.3522). While the main target for CCPi-RGL is [tomographic image reconstruction](https://github.com/dkazanc/ToMoBAR), the toolkit can be used for image denoising problems. The core modules are written in C-OMP and CUDA languages and wrappers for Matlab and Python are provided. With [CuPy](https://docs.cupy.dev/en/stable/index.html) dependency installed for Python, one can use regularisers directly without the need for explicit compilation. We recommend this option as the simplest to start with if you've got a GPU. This software can also be used by running in parallel across multiple GPU devices on a PC or a cluster compute node.**
3+
[![CI status](https://anvil.softeng-support.ac.uk/jenkins/buildStatus/icon?subject=master&job=CILsingle/CCPi-Regularisation-Toolkit)](https://anvil.softeng-support.ac.uk/jenkins/job/CILsingle/job/CCPi-Regularisation-Toolkit/lastBuild)
4+
[![conda version](https://anaconda.org/ccpi/ccpi-regulariser/badges/version.svg) ![conda date](https://anaconda.org/ccpi/ccpi-regulariser/badges/latest_release_date.svg) ![conda platforms](https://anaconda.org/ccpi/ccpi-regulariser/badges/platforms.svg) ![conda downloads](https://anaconda.org/ccpi/ccpi-regulariser/badges/downloads.svg)](https://anaconda.org/ccpi/ccpi-regulariser)
85

6+
Iterative image reconstruction (IIR) methods frequently require regularisation to ensure convergence and make inverse problem well-posed. The CCPi-Regularisation Toolkit (CCPi-RGL) toolkit provides a set of 2D/3D regularisation strategies to guarantee a better performance of IIR methods (higher SNR and resolution). The regularisation modules for scalar and vectorial datasets are based on the [proximal operator](https://en.wikipedia.org/wiki/Proximal_operator) framework and can be used with [proximal splitting algorithms](https://en.wikipedia.org/wiki/Proximal_gradient_method), such as PDHG, Douglas-Rachford, ADMM, FISTA and [others](https://arxiv.org/abs/0912.3522). While the main target for CCPi-RGL is [tomographic image reconstruction](https://github.com/dkazanc/ToMoBAR), the toolkit can be used for image denoising problems. The core modules are written in C-OMP and CUDA languages and wrappers for Matlab and Python are provided. With [CuPy](https://docs.cupy.dev/en/stable/index.html) dependency installed for Python, one can use regularisers directly without the need for explicit compilation. We recommend this option as the simplest to start with if you've got a GPU. This software can also be used by running in parallel across multiple GPU devices on a PC or a cluster compute node.
97

108
<div align="center">
11-
<img src="demos/images/CCPiRGL_sm.jpg" height="400"><br>
9+
<img src="demos/images/CCPiRGL_sm.jpg" height="400"><br>
1210
</div>
1311

14-
## Prerequisites:
12+
## Prerequisites
13+
14+
- Python (3.7+) and/or [MATLAB](https://www.mathworks.com/products/matlab)
15+
- C compilers
16+
- `nvcc` (CUDA SDK) compilers
17+
- [CuPy](https://docs.cupy.dev) for the GPU-enabled methods
1518

16-
* [MATLAB](www.mathworks.com/products/matlab/) OR
17-
* Python (tested ver. 3.5/2.7); Cython
18-
* C compilers
19-
* nvcc (CUDA SDK) compilers
20-
* [CuPy](https://docs.cupy.dev/en/stable/index.html) for the GPU-enabled methods
19+
## Package modules
2120

22-
## Package modules:
21+
### Single-channel (scalar)
2322

24-
### Single-channel (scalar):
2523
1. Rudin-Osher-Fatemi (ROF) Total Variation (explicit PDE minimisation scheme) **2D/3D CPU/GPU + CuPy** (Ref. *1*)
2624
2. Fast-Gradient-Projection (FGP) Total Variation **2D/3D CPU/GPU** (Ref. *2*)
2725
3. Split-Bregman (SB) Total Variation **2D/3D CPU/GPU** (Ref. *5*)
@@ -32,65 +30,66 @@
3230
8. A joint ROF-LLT (Lysaker-Lundervold-Tai) model for higher-order regularisation **2D/3D CPU/GPU** (Ref. *10,11*)
3331
9. Nonlocal Total Variation regularisation (GS fixed point iteration) **2D CPU/GPU** (Ref. *12*)
3432

35-
### Multi-channel (vectorial):
33+
### Multi-channel (vectorial)
34+
3635
1. Fast-Gradient-Projection (FGP) Directional Total Variation **2D/3D CPU/GPU** (Ref. *3,4,2*)
3736
2. Total Nuclear Variation (TNV) penalty **2D+channels CPU** (Ref. *7*)
3837

39-
## Installation:
38+
## Installation
39+
4040
The package comes as a [CMake](https://cmake.org) project and additional wrappers for Python and Matlab. Please see more detailed [Installation](https://github.com/vais-ral/CCPi-Regularisation-Toolkit/blob/master/Installation.md) information.
4141

4242
### Python binaries
43+
4344
To install precompiled binaries, you need `conda` and install from the `ccpi` channel using :
44-
```
45+
46+
```sh
4547
conda install ccpi-regulariser -c ccpi -c conda-forge
4648
```
4749

4850
### Python (GPU-CuPy)
49-
One can also use some of the GPU modules with the provided [CuPy](https://docs.cupy.dev/en/stable/index.html) interfaces. The functions in `ccpi-regularisation-cupy` package work with CuPy arrays as an input and return a CuPy array for output.
50-
```
51+
52+
One can also use some of the GPU modules with the provided [CuPy](https://docs.cupy.dev/en/stable/index.html) interfaces. The functions in `ccpi-regularisation-cupy` package work with CuPy arrays as an input and return a CuPy array for output.
53+
54+
```sh
5155
conda install -c httomo ccpi-regularisation-cupy
52-
```
53-
Once installed please see [Demos](https://github.com/vais-ral/CCPi-Regularisation-Toolkit/blob/master/demos/demo_gpu_regularisers3D_CuPy.py). Please note that not all modules are yet supported as this is an ongoing development. One can install both CuPy-driven and the `ccpi-regulariser` packge in one environment, but please be aware that the functions carry the identical names.
56+
```
5457

58+
Once installed please see [Demos](https://github.com/vais-ral/CCPi-Regularisation-Toolkit/blob/master/demos/demo_gpu_regularisers3D_CuPy.py). Please note that not all modules are yet supported as this is an ongoing development. One can install both CuPy-driven and the `ccpi-regulariser` packge in one environment, but please be aware that the functions carry the identical names.
5559

56-
### References to implemented methods:
57-
1. [Rudin, L.I., Osher, S. and Fatemi, E., 1992. Nonlinear total variation based noise removal algorithms. Physica D: nonlinear phenomena, 60(1-4)](https://www.sciencedirect.com/science/article/pii/016727899290242F)
60+
## References
5861

59-
2. [Beck, A. and Teboulle, M., 2009. Fast gradient-based algorithms for constrained total variation image denoising and deblurring problems. IEEE Transactions on Image Processing, 18(11)](https://doi.org/10.1109/TIP.2009.2028250)
62+
### Implemented methods
6063

64+
1. [Rudin, L.I., Osher, S. and Fatemi, E., 1992. Nonlinear total variation based noise removal algorithms. Physica D: nonlinear phenomena, 60(1-4)](https://www.sciencedirect.com/science/article/pii/016727899290242F)
65+
2. [Beck, A. and Teboulle, M., 2009. Fast gradient-based algorithms for constrained total variation image denoising and deblurring problems. IEEE Transactions on Image Processing, 18(11)](https://doi.org/10.1109/TIP.2009.2028250)
6166
3. [Ehrhardt, M.J. and Betcke, M.M., 2016. Multicontrast MRI reconstruction with structure-guided total variation. SIAM Journal on Imaging Sciences, 9(3)](https://doi.org/10.1137/15M1047325)
62-
6367
4. [Kazantsev, D., Jørgensen, J.S., Andersen, M., Lionheart, W.R., Lee, P.D. and Withers, P.J., 2018. Joint image reconstruction method with correlative multi-channel prior for X-ray spectral computed tomography. Inverse Problems, 34(6)](https://doi.org/10.1088/1361-6420/aaba86) **Results can be reproduced using the following** [SOFTWARE](https://github.com/dkazanc/multi-channel-X-ray-CT)
64-
6568
5. [Goldstein, T. and Osher, S., 2009. The split Bregman method for L1-regularized problems. SIAM journal on imaging sciences, 2(2)](https://doi.org/10.1137/080725891)
66-
6769
6. [Bredies, K., Kunisch, K. and Pock, T., 2010. Total generalized variation. SIAM Journal on Imaging Sciences, 3(3)](https://doi.org/10.1137/090769521)
68-
6970
7. [Duran, J., Moeller, M., Sbert, C. and Cremers, D., 2016. Collaborative total variation: a general framework for vectorial TV models. SIAM Journal on Imaging Sciences, 9(1)](https://doi.org/10.1137/15M102873X)
70-
7171
8. [Black, M.J., Sapiro, G., Marimont, D.H. and Heeger, D., 1998. Robust anisotropic diffusion. IEEE Transactions on image processing, 7(3)](https://doi.org/10.1109/83.661192)
72-
7372
9. [Hajiaboli, M.R., 2011. An anisotropic fourth-order diffusion filter for image noise removal. International Journal of Computer Vision, 92(2)](https://doi.org/10.1007/s11263-010-0330-1)
74-
7573
10. [Lysaker, M., Lundervold, A. and Tai, X.C., 2003. Noise removal using fourth-order partial differential equation with applications to medical magnetic resonance images in space and time. IEEE Transactions on image processing, 12(12)](https://doi.org/10.1109/TIP.2003.819229)
76-
7774
11. [Kazantsev, D., Guo, E., Phillion, A.B., Withers, P.J. and Lee, P.D., 2017. Model-based iterative reconstruction using higher-order regularization of dynamic synchrotron data. Measurement Science and Technology, 28(9)](https://doi.org/10.1088/1361-6501/aa7fa8)
78-
7975
12. [Abderrahim E., Lezoray O. and Bougleux S. 2008. Nonlocal discrete regularization on weighted graphs: a framework for image and manifold processing. IEEE Trans. Image Processing 17(7), pp. 1047-1060.](https://ieeexplore.ieee.org/document/4526700)
80-
8176
13. [Chambolle, A. and Pock, T., 2010. A first-order primal-dual algorithm for convex problems with applications to imaging. Journal of mathematical imaging and vision 40(1)](https://doi.org/10.1007/s10851-010-0251-1)
8277

78+
### Software (please cite if used)
8379

84-
### References to software (please cite if used):
85-
* [Kazantsev, D., Pasca, E., Turner, M.J. and Withers, P.J., 2019. CCPi-Regularisation toolkit for computed tomographic image reconstruction with proximal splitting algorithms. SoftwareX, 9, pp.317-323.](https://www.sciencedirect.com/science/article/pii/S2352711018301912)
80+
- [Kazantsev, D., Pasca, E., Turner, M.J. and Withers, P.J., 2019. CCPi-Regularisation toolkit for computed tomographic image reconstruction with proximal splitting algorithms. SoftwareX, 9, pp.317-323.](https://www.sciencedirect.com/science/article/pii/S2352711018301912)
8681

87-
### Applications:
88-
* [The Core Imaging Library](https://github.com/TomographicImaging/CIL) by [CCPi](https://ccpi.ac.uk/cil/)
89-
* [TOmographic MOdel-BAsed Reconstruction (ToMoBAR)](https://github.com/dkazanc/ToMoBAR)
90-
* [Joint image reconstruction method with correlative multi-channel prior for X-ray spectral computed tomography (MATLAB code)](https://github.com/dkazanc/multi-channel-X-ray-CT)
82+
### Applications
83+
84+
- [The Core Imaging Library](https://github.com/TomographicImaging/CIL) by [CCPi](https://ccpi.ac.uk/cil/)
85+
- [TOmographic MOdel-BAsed Reconstruction (ToMoBAR)](https://github.com/dkazanc/ToMoBAR)
86+
- [Joint image reconstruction method with correlative multi-channel prior for X-ray spectral computed tomography (MATLAB code)](https://github.com/dkazanc/multi-channel-X-ray-CT)
87+
88+
### License
9189

92-
### License:
9390
[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
9491

95-
### Acknowledgments:
96-
CCPi-RGL software is a product of the [CCPi](https://www.ccpi.ac.uk/) group and STFC SCD software developers. Any relevant questions/comments can be e-mailed to Daniil Kazantsev at dkazanc@hotmail.com
92+
### Acknowledgments
93+
94+
CCPi-RGL software is a product of the [CCPi](https://www.ccpi.ac.uk) group and STFC SCD software developers.
95+
Any relevant questions/comments can be e-mailed to [Daniil Kazantsev](mailto:dkazanc@hotmail.com).

0 commit comments

Comments
 (0)