I12 JEEP SAVU tips

Created by Nghia Vo

1.  Using zinger removal plugins:

1. If use the Dezinger plugin, it should be used before the DarkFlatFieldCorrection plugin.
2. If use the DezingerSinogram, it should be used after the DarkFlatFieldCorrection plugin.

2.  Using the plugin of converting 360-degree sinogram to 180-degree sinogram:

1. Change the parameter "centre_of_rotation" of the reconstruction plugin (TomopyRecon, AstraReconGpu...) to "cor"
2. Change the parameter "in_datasets" of a plugin (such as a ring removal plugin or the Fresnel filter) going right after this plugin from "[]" to "[tomo]"

3.  Using distortion correction plugins:

1. For correcting the distortion, these plugins use few adjacent slices (>10 depending on how strong the distortion is), so users need to add more slices in "preview" of the NXtomoLoader plugin such as [:, mid-10:mid+10,:]
2. It's normal that few slices on top and bottom are non-reconstructable (output black or nan images) due to the distortion effect.
3. As these plugins slightly blur the image which may affect the cleaning performance of ring removal plugins, it should be used after ring removal plugins. This is, however, not a strict requirement with latest ring removal plugins. 
4. Since version 2.4 users can set the "file_path" to a txt file containing the distortion coefficients. This is more convenient than inputting manually coefficients.
5. Center of distortions are referred to the original size of the projections (assuming that it has the same size as the dot pattern). This means that users don't have to worry about offsetting the values of center of distortions in the case of data cropped.

4. Using VoCentering:

1. It must be used after the DarkFlatFieldCorrection plugin.
2. It must be used after the distortion correction plugins.
3. It must be used before any plugin may blur the image (PaganinFilter, FresnelFilter,..). 
4. It should be used after ring removal plugins, but not strictly. 
5. By default the "preview" is set at "[]". This means that the center of rotation will be calculated for every slice passed to this plugin. This is time consuming. In most of the case we can calculate the CoR using the middle slice only by changing the "preview" to [:,mid,:] (for 3D data) or [:,mid,:,0] (for 4D data).
6. If the images (sinograms) are at very low contrast and VoCentering doesn't work well:
   • Increase the "average_radius" to ~ 10. This means that the "preview" in the NxtomoLoader need to be increased correspondingly  (~ +/- 10).
7. If the results of Vocentering are unstable between scans or slices:
   • Increase the "preview" slices of the VoCentering. Note that users have to increase the "preview" in the NxtomoLoader equivalently. By doing these, VoCentering will calculate center of rotation (CoR) of every previewing slices. Then the final CoR will be the median, mean, or fitted value of those calculated which users can specify in the "broadcast_method".
8. If the sample is too big compared with the field of view of the camera and VoCentering doesn't work well:
   • Increase the "ratio" to something ~ larger 2.
   • Use the tip of increase the "preview"  in 4.6. If this doesn't work, combine with the tip 4.5.
9. If the data was collected using 360-degree scanning (but not off-setting CoR for doubling the field of view):
   • Change the "preview" to [0:mid, <user-choice>,:]. Because the VoCentering only works on 180-degree sinogram, by doing that we make sure the plugin only get data in the range of 180 degree.
10. If none of the above tips work:

• make sure that:
  • There's no motion artifacts.
  • Data was collected in the range of [0;180] degree (not limited-angle tomography).
  • The sample is inside the field of view the previewing slices.
  • Dark and flat are collected properly: shutter was completely closed when collecting dark; there's no sample in the flat image.
  • There's no non-rotating part in the image, e.g the image of some experiment components such as window of a furnace.
• otherwise:
  • Users have to find CoR manually by doing parameter turning in the reconstruction plugins.
  • Send e-mail and a sinogram (or location of the data) to Nghia (nghia.vo@diamond.ac.uk).

5. Using DarkFlatFieldCorrection:

1. If dark and flat are collected separately, in the NxtomoLoader, users need to change these parameters:
   • Change "flat" from [None, None, 1] to [<path-to-the-flat>,<hdf-key-path>, ratio]
   • Do the same with "dark".
   • If flats are collected using different exposure time compared with projections → Change the "ratio" above to the ratio of <projection-exposure-time>/<flat-exposure-time>

6. Using Paganin filter:

1. There are many parameters in the Paganin filter. This causes confusion and it is time wasting to play around all of them while only the "Ratio" parameter is most significant. Users can use FresnelFilter as a replacement.

7. Using NXTomoLoader:

1. Specify angles:
   • User can pass a list of angles (in degree) to the parameter of "angles" using python and numpy commands (use np as an alias pointing to numpy). For example:
     • np.linspace(0.0, 180, 1801)            :   This command generates 1801 number of angles evenly distributed in the range of [0;180 degree] 
     • 30 + np.linspace(0.0, 180, 1801)    : Same as above but angles are offset 30 degree. This is useful if users want to rotate reconstructed images.
     • np.arange(1801)*180.0/1800         : Different way of doing the same as the first example. 
     • np.ndarray.flatten(np.asarray([np.linspace(0.0, 180.0, 1801) if i%2==0 else np.linspace(180.0, 0.0, 1801) for i in range(10)])) : A one-line command used for 4D time-series tomography in which the rotation stage was moved backward and forward between 0 and 180 degree ten times.

8. Save output data as 8-bit or 16-bit tiff images:

      Very often users would like to convert reconstructed images from 32-bit data to 8-bit or 16-bit tiff images. To do that users need to add two plugins: MinAndMax and ImageSaver, right after the reconstruction plugins (AstraReconGpu...).

      The MinAndMax plugin returns global min and global max of a 3D dataset which will be used to rescale the 3D dataset before saving them to lower-bit images.

      ImageSaver allows users to input global min and global max manually. This is useful for post-processing where users can do segmentation using a global threshold across multiple datasets.

      ImageSaver also allows to slice a 3D data at different orientations such as VOLUME_XZ, VOLUME_YZ, or VOLUME_XY; or to save data at various formats such as jpg, png,...

      ImageSaver can be used to save results of a plugin (Dezinger, DarkFlatCorrection, RemoveAllRings...) to imaging format. Users need to change the "pattern" to PROJECTION or SINOGRAM depending on the output pattern of the plugin.

      The latest version of ImageSaver is available in Savu pre-release "module load savu/pre-release"

9. Denoising using CCPi lib:

     CCPi-regularisation toolkit has been added to Savu, this is very useful for smoothing reconstructed images from small number-of-projection data. Example of use:

1) NxtomoLoader

-------------------------------------------------------------------------------------

2) DarkFlatFieldCorrection

-------------------------------------------------------------------------------------

3) VoCentering

-------------------------------------------------------------------------------------

4) RingRemovalFiltering

-------------------------------------------------------------------------------------

5) TomopyRecon

-------------------------------------------------------------------------------------

6) CcpiDenoisingGpu

-------------------------------------------------------------------------------------

7) MinAndMax

-------------------------------------------------------------------------------------

8) ImageSaver

With parameters for CcpiDenoisingGpu:

6) CcpiDenoisingGpu

           1) in_datasets : []

           2) reg_par : 0.0005

           3) alpha0 : 2.0

           4) alpha1 : 1.0

           5) out_datasets : []

           6) pattern : VOLUME_XZ

           7) edge_par : 0.01

           8) penalty_type : huber

           9) lipshitz_constant : 12

          10) time_step : 0.001

          11) reg_parLLT : 0.05

          12) method : FGP_TV

          13) tolerance_constant : 0.0

          14) max_iterations : 300

Example:

Reconstructed image using tomopy with 600 number of projections:

and after using above denoising plugin:

Contact Daniil if you would like to know more about how to use these tools.