| Table of Contents |
|---|
Summary
| TomopyRecon | |||||
| Process category | Brief description | Computational demand for typical tomography data (low, medium, high) | Comment(s) | Reference(s) | Common alternative process(es) |
|---|---|---|---|---|---|
| reconstructor | TOmographic MOdel-BAsed Reconstruction (ToMoBAR) software. | medium-high. Note that there is 2D and 3D version of the plugin. 3D is more computationally demanding and doesn't exploit the MPI fully. | ToMoBAR is a library of direct and model-based regularised iterative reconstruction algorithms with a plug-and-play capability. Current Savu wrapper uses the regularised FISTA algorithm | ToMoBAR |
|
Parameters
Brief description |
|---|
| Code Block | ||
|---|---|---|
| ||
>>> disp -avv
-------------------------------------------------------------------------------------
TomobarRecon3d(savu.plugins.reconstructions.tomobar_recon_3D)
A wrapper around TOmographic MOdel-BAsed Reconstruction (ToMoBAR) software for
advanced iterative image reconstruction using _3D_ capabilities of regularisation.
The plugin will run on one cluster node, i.e. it can be slow.
1) init_vol : None
Dataset to use as volume initialiser (doesn't currently work with preview).
2) preview : []
A slice list of required frames.
3) log : True
Take the log of the data before reconstruction (True or False).
4) centre_of_rotation : 0.0
Centre of rotation to use for the reconstruction.
5) in_datasets : []
Create a list of the dataset(s) to process.
6) ring_accelerator : 50.0
Acceleration constant for ring removal (use with care).
7) output_size : auto
The dimension of the reconstructed volume (only X-Y dimension).
8) nonnegativity : ENABLE
Nonnegativity constraint, choose Enable or None.
9) regularisation : ROF_TV
To regularise choose methods ROF_TV, FGP_TV, SB_TV, LLT_ROF, NDF, Diff4th.
10) iterations : 15
Number of outer iterations for FISTA method.
11) edge_param : 0.01
Edge (noise) related parameter, relevant for NDF and Diff4th.
12) ratio : 0.95
Ratio of the m2asks diameter in pixels to the smallest edge size along given
axis.
13) log_func : np.nan_to_num(-np.log(sino))
Override the default log function.
14) regularisation_parameter2 : 0.005
Regularisation (smoothing) value for LLT_ROF method.
15) NDF_penalty : Huber
NDF specific penalty type Huber, Perona, Tukey.
16) tolerance : 1e-10
Tolerance to stop outer iterations earlier.
17) ordersubsets : 6
The number of ordered-subsets to accelerate reconstruction.
18) out_datasets : []
Create a list of the dataset(s) to create.
19) centre_pad : False
Pad the sinogram to centre it in order to fill the reconstructed volume ROI for
asthetic purposes. NB: Only available for selected algorithms and will be ignored
otherwise. WARNING: This will significantly increase the size of the data and the
time to compute the reconstruction).
20) regularisation_iterations : 400
The number of regularisation iterations.
21) regularisation_parameter : 0.0002
Regularisation (smoothing) value, higher the value stronger the smoothing effect.
22) force_zero : [None, None]
Set any values in the reconstructed image outside of this range to zero.
23) vol_shape : fixed
Override the size of the reconstuction volume with an integer value.
24) converg_const : power
Lipschitz constant, can be set to a scalar value or automatic calculation using
power methods.
25) time_marching_parameter : 0.002
Time marching parameter, relevant for (ROF_TV, LLT_ROF, NDF, Diff4th) penalties.
26) datafidelity : LS
Data fidelity, Least Squares (LS) or PWLS.
27) outer_pad : False
Pad the sinogram width to fill the reconstructed volume for asthetic purposes.
Choose from True (defaults to sqrt(2)), False or float <= 2.1. NB: Only available
for selected algorithms and will be ignored otherwise. WARNING: This will
increase the size of the data and the time to compute the reconstruction).
28) ring_variable : 0.0
Regularisation variable for ring removal.
-------------------------------------------------------------------------------------
>>> |
Additional notes |
|---|
For basic information on this process, please use the disp -av (or disp -avv or disp-v[v] <process index>) command in Savu Configurator (see above). The table below is intended to provide some additional notes on a number of selected topics:
| Item | Parameter name | Parameter format | Example(s) | Comment(s) | |
|---|---|---|---|---|---|
| Parameter value | Effect | ||||
| 1 | regularisation_parameter | float | 0.0002 | Should be chosen for a specific dataset. Higher the value stronger the smoothing effect. | The value depends on the data. If zero is passed, no regularisation will be applied (reconstruction without filtering). |
| 2 | regularisation | string | ROF_TV, FGP_TV, SB_TV, LLT_ROF, NDF, Diff4th, TGV | ROF_TV, FGP_TV, SB_TV, NDF - deliver piecewise-constant recovery (regions with uniform intensity) LLT_ROF, Diff4th, TGV - piecewise-smooth recovery. | The plugin uses the CCPi-Regularisation toolkit which is available here: https://github.com/vais-ral/CCPi-Regularisation-Toolkit and based on this paper: https://www.sciencedirect.com/science/article/pii/S2352711018301912 |
| 3 | iterations | integer | 15-20 | Less than 10 iterations for the iterative method (FISTA) can deliver a blurry reconstruction | The suggested value is 15 iterations, however the algorithm can stop prematurely based on the tolerance value (see bellow) |
| 4 | tolerance | float | 1e-10 | can stop iterations prematurely when the solution is changing "slowly" | |
| 5 | regularisation_iterations | integer | 400 for OS methods, 70 for non-OS | Less iterations - less effect of filtering. | One needs to iterate "long enough" in order to get to the filtered solution. The number of iterations for regularisation (filtering) method is set to 400/OS number or 400 for non-OS method. It is not harmful to over-iterate, this, however will effect the speed of the algorithm. |
| 6 | centre_of_rotation | The default value of the centre_of_rotation parameter is 0.0, which normally needs to be manually modified to a more appropriate value or, if VoCentering is used beforehand in the process chain, then this parameter is automatically set to a value determined by this auto-centring process. | |||
| 7 | ordersubsets | integer | 6 | effects the final solution by accelerating reconstruction process. | This directly effect the number of iterations to run. The high value (> 12), however, can result in the algorithm to diverge. |
| 8 | ratio | ||||
| 9 | out_datasets | ||||
| 10 | centre_pad | ||||
| 11 | outer_pad | ||||
| 12 | n_iterations | ||||
| 13 | force_zero | ||||
Usage
There are 2D versions of the tomobar plugin - for 2D and 3D reconstruction. 2D version is fully MPI-ed while 3D work on a single GPU provided. Although 3D version can be significantly slower than 2D, the results are normally much better using 3D versus slice-by-slice 2D. Note, however, the passed data dimensions and the available GPU memory before running tomobar3D, the memory overflow can be easily reached.