Commit 51447555 authored by Pierre Paleo's avatar Pierre Paleo
Browse files

doc: add features

parent 5f007fac
Pipeline #24638 passed with stage
in 54 seconds
# Features overview
Nabu is a tomography processing software. The term "processing" stands for various things: pre-processing the radios/sinograms, reconstruction, and image/volume post-processing.
## Pre-processing
Pre-processing means steps done before reconstruction.
API : [nabu.preproc](apidoc/nabu.preproc)
### Flat-field normalization
This is usually the first step done on the radios. Each radio is normalized by the incoming beam intensity and CCD dark current as `radio = (radio - dark)/(flat - dark)`.
Usually, several "flats" images are acquired. Nabu automatically determines which flat image to use depending on the radio angle.
Configuration file: section `[preproc]`: `flatfield_enabled = 1`.
API: [FlatField](apidoc/nabu.preproc.ccd_cuda.rst#nabu.preproc.ccd_cuda.CudaFlatField) and [CudaFlatField](apidoc/nabu.preproc.ccd_cuda.rst#nabu.preproc.ccd_cuda.CudaFlatField)
### CCD hotspots removal
Some pixels might have unusually high values. These are called "hotspots". A simple an efficient way to remove them is to apply a thresholded median filter: a pixel is replaced by the median of its neighborhood if its values exceeds a certain relative threshold.
Configuration file: section `[preproc]`: `ccd_filter_enabled = 1` and `ccd_filter_threshold = 0.04`.
API: [CCDCorrection](apidoc/nabu.preproc.ccd.rst#nabu.preproc.ccd.CCDCorrection) and [CudaCCDCorrection](apidoc/nabu.preproc.ccd_cuda.rst#nabu.preproc.ccd_cuda.CudaCCDCorrection)
### Double flat-field
This is a projections-based rings artefacts removal.
Some defects might remain in the projections even after flat-fielding. These defects are visible as structured noise in the projections or sinograms.
By doing the average of all projections, the genuine features are canceled out and only the defects remain. This "average image" is used to remove the defects from the radios. Schematically, this method does `radio = radio / mean(radios)` (or other operations if the logarithm of radios was already taken).
Be aware that by doing so, you might lose the quantitativeness of the reconstructed data.
This method assumes that when averaging all the radios, the genuine feature will cancel and only spurious artefacts will remain. This assumption can fail if genuine features are (more or less) independent from the projection angle, ex. ring-shaped.
Configuration file key: section `[preproc]`: `double_flatfield_enabled = 1`.
API: [DoubleFlatField](apidoc/nabu.preproc.double_flat_field.rst#nabu.preproc.double_flat_field.DoubleFlatField)
### Logarithm
When doing an end-to-end volume reconstruction, the `-log()` step has to be explicitly specified.
This step enables the conversion of the projections to the usual linear model setting, assuming a Beer–Lambert–Bouguer transmission law: `I = I_0 exp(-mu(x, y))` to `mu(x, y) = -log(I/I_0)`
Numerical issues might occur when performing this step. For this reason, the projections values can be "clipped" to a certain range before applying the logarithm.
Configuration file: section `[preproc]`: `take_logarithm = 1`, `log_min_clip = 1e-6`, `log_max_clip = 10.0`.
API: [CCDProcessing.take_logarithm](apidoc/nabu.preproc.ccd.rst#nabu.preproc.ccd.CCDProcessing.take_logarithm) and [CudaLog](apidoc/nabu.preproc.ccd_cuda.rst#nabu.preproc.ccd_cuda.CudaLog)
## Phase retrieval
Phase retrieval is still part of the "pre-processing", although it has a dedicated section in the [configuration file](nabu_config_file).
This step enables to retrieve the image phase information from intensity. After that, reconstruction consists in obtaining the (deviation from unity of the real part of the) refractive index from the phase (instead of absorption coefficient from the attenuation).
In general, phase retrieval is a non-trivial problem. Nabu currently implements a simple phase retrieval method (single-distance Paganin method). More methods are planned to be integrated in the future.
See also: [Phase retrieval](
### Paganin phase retrieval
The Paganin method consists in applying a band-pass filter on the radios.
It depends on the δ/β ratio (assumed to be constant in all the image) and the incoming beam energy.
Configuration file: section `[phase]`: `method = Paganin`, `delta_beta = 1000.0`
API : [PaganinPhaseRetrieval](apidoc/nabu.preproc.phase.rst#nabu.preproc.phase.PaganinPhaseRetrieval) and [CudaPaganinPhaseRetrieval](apidoc/nabu.preproc.phase_cuda.rst#nabu.preproc.phase_cuda.CudaPaganinPhaseRetrieval)
### Unsharp Mask
Although it is a general-purpose image processing utility, unsharp mask is often used after Paganin phase retrieval as a mean to sharpen the image (high pass filter).
Each radio is processed as `UnsharpedImage = (1 + coeff)*Image - coeff * ConvolvedImage` where `ConvolvedImage` is the result of a Gaussian blur applied on the image.
Configuration file: section `[phase]`: `unsharp_coeff = 1.` and `unsharp_sigma = 1.`
Setting `coeff` to zero (default) disables unsharp masking.
## Reconstruction
Tomographic reconstruction is the process of reconstructing the volume from projections/sinograms.
Configuration file: section `[reconstruction]`.
Related keys: `angles_file`, `angle_offset`, `rotation_axis_position`, `enable_halftomo`
`start_x`, `end_x`, `start_y`, `end_y`, `start_z`, `end_z`.
### FBP
Configuration file: section `[reconstruction]`: `method = FBP`, `padding_type = edges`, `fbp_filter_type = ramlak`
This is the Filtered Back Projection reconstruction method.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment