neutompy.preproc.preproc

neutompy.preproc.preproc.draw_ROI(img, title, ratio=0.85)[source]

This function allows to select interactively a rectangular region of interest (ROI) over an image. The function returns the ROI coordinates.

Parameters:
  • img (2d array) – The image on which the dose roi is drawn.
  • title (str) – String defining the title of the window shown.
  • ratio (float, optional) – The filling ratio of the window respect to the screen resolution. It must be a number between 0 and 1. The default value is 0.85.
Returns:

  • rowmin (int) – The minimum row coordinate.
  • rowmax (int) – The maximum row coordinate.
  • colmin (int) – The minimum column coordinate.
  • colmax (int) – The maximum column coordinate.
neutompy.preproc.preproc.normalize_proj(proj, dark, flat, proj_180=None, out=None, dose_file='', dose_coor=(), dose_draw=True, crop_file='', crop_coor=(), crop_draw=True, scattering_bias=0.0, minus_log_lowest_val=None, min_denom=1e-06, min_ratio=1e-06, max_ratio=10.0, mode='mean', log=False, sino_order=False, show_opt='mean')[source]

This function computes the normalization of the projection data using dark and flat images. If the source intensity is not stable the images can be normalized respect to the radiation dose (see formula 2.2 in [1]). In this case, the user must specify a region (the dose ROI) where the sample never appears. If not interested in reconstructing the entire field-of-view, the normalization can be performed using only a region of interest (crop ROI) of all projections. The dose ROI and the crop ROI can be drawn interactively on the image or specified using the index coordinates or an ImageJ .roi file. A stack of dark and flat images is required and the median or the mean of the stack is used to compute the main fomula.

Parameters:
  • proj (ndarray) – A three-dimensional stack of raw projections. The 0-axis represents theta.
  • dark (ndarray) – A three-dimensional stack of dark-field images.
  • flat (ndarray) – A three-dimensional stack of flat-field images.
  • proj_180 (2d arrays, optional) – The projection at 180 degree. Specify it only if it is not already included in the stack proj. It is disabled by default (None).
  • out (ndarray, optional) – The output array returned by the function. If it is the same as proj, the computation will be done in place.
  • dose_file (str, optional) – String defining the path or the name of the Image ROI file that includes the dose ROI.
  • dose_coor (tuple, optional) – Tuple defining the indexes range for each axis of the ROI dose. Specify it in this way: (row_start, row_end, col_start, col_end)
  • dose_draw (bool, optional) – If True the dose ROI is selected interactively on the image by the user. The default is True.
  • crop_file (str, optional) – String defining the path or the name of the Image ROI file that includes the ROI to crop.
  • crop_coor (tuple, optional) – Tuple defining the indexes range, for each axis, of the ROI to crop. Specify it in this way: (row_start, row_end, col_start, col_end)
  • crop_draw (bool, optional) – If True the ROI to crop is selected interactively on the image by the user. The default is True.
  • scattering_bias (float, optional) – It allows to compensate uniform scattering by subtracting a constant value from the raw projections. Defalut value is 0.0.
  • minus_log_lowest_val (float, optional) – Minimum permitted value of the -log-transform of the normalized data. The parameter prevents values close to (or below) zero to introduce artefacts. The clipping is ignored if minus_log_lowest_val is None or the variable log is False. Default value is None.
  • min_denom (float, optional) – Minimum permitted value of the denominator. It must be a small number that prevents the division by zero. Defalut value is 1.0e-6.
  • min_ratio (float, optional) – Minimum permitted value of normalized projections. It must be a small positive number that prevents negative values normalized data. Defalut value is 1.0e-6.
  • max_ratio (float, optional) – Maximum permitted value of normalized projections. It must be a positive number. It mitigates the magnitude of the bright outliers within normalized data. Defalut value is 10.
  • log (bool, optional) – If True the log-transform of the normalized data is performed. If False, the normalized data without log-transform are returned. Default value is False.
  • mode (string, optional) – If dose_draw or crop_draw is True the user can select interactively the ROI. A window showing a representative image of the projection stack is created. This image can be the mean or the standard deviation computed pixel-wise over the projection stack. Hence, allowed values of mode are mean and std. Default value is mean.
  • sino_order (bool, optional) – If True a stack of sinograms is returned (0 axis represents the projections y-axis). If False a stack of projections is returned (0 axis represents theta). Default value is False.
Returns:

  • out (ndarray) – Three-dimensional stack of the normalized projections.
  • out_180 (2d arrays) – The normalized projection at 180 degree. It is returned only if proj_180 is an array.

References

[1]D. Micieli et al., A comparative analysis of reconstruction methods applied to Neutron Tomography, Journal of Instrumentation, Volume 13, June 2018.

Examples

Normalize dataset selecting interactively the ROI to crop and the dose ROI.

>>> import neutompy as ntp
>>> norm =  ntp.normalize_proj(proj, dark, flat, dose_draw=True, crop_draw=True)

Normalize dataset and the raw projection at 180 degree:

>>> fname  = ntp.get_image_gui('', message = 'Select raw projection at 180°...')
>>> img180 = ntp.read_image(fname)
>>> norm, norm_180 = ntp.normalize_proj(proj, dark, flat, proj_180=img180)

Normalize dataset using two ImageJ .roi file to define the ROI to crop and the dose ROI:

>>> norm = ntp.normalize_proj(proj, dark, flat, dose_file='./dose.roi', crop_file='./crop.roi'
                                                 dose_draw=False, crop_draw=False)

Normalize the dataset with the log-transform:

>>> norm = ntp.normalize_proj(proj, dark, flat, log=True)

Trivial data normalization using the whole field of view and without the dose correction:

>>> norm = ntp.normalize_proj(proj, dark, flat, dose_draw=False, crop_draw=False)
neutompy.preproc.preproc.log_transform(norm_proj, out=None)[source]

This function computes the minus log of an array. In trasmission CT the input array must be the normalized dataset after flat-fielding correction.

Parameters:
  • norm_proj (ndarray) – 3D stack of projections.
  • out (ndarray, optional) – Output array. If same as norm_proj, computation will be done in-place.
Returns:

out (ndarray) – Minus-log of the input array.
neutompy.preproc.preproc.find_COR(proj_0, proj_180, nroi=None, ref_proj=None, ystep=5, ShowResults=True)[source]

This function estimates the offset and the tilt angle of the rotation axis respect to the detector using the projections at 0 and at 180 degree. The user selects interactively different regions where the sample is visible. Once the position of the rotation axis is found the results are shown in two figures. In the first are shown the computed rotation axis and the image obtained as proj_0 - pro_180[:,::-1] (the projection at 180 is flipped horizontally) before the correction. The second figure shows the difference image proj_0 - pro_180[:,::-1] after the correction and the histogram of abs(proj_0 - pro_180[:,::-1]).

Parameters:
  • proj_0 (2d array) – The projection at 0 degrees.
  • proj_180 (2d array) – The projection at 180 degrees.
  • nroi (int, optional) – The number of the region of interest to select for the computation of the rotation axis position. Default is None, hence the value is read as input from keyboard.
  • ref_proj (2d array) – The image shown to select the region of interest. Default is None, hence proj_0 is shown.
  • ystep (int, optional) – The center of rotation position is computed every ystep. Default value is 5.
  • ShowResults (bool, optional) – If True, the the two figures that summarize the result are shown. Default is True.
Returns:

  • middle_shift (float) – The horizontal shift of the rotation axis respect to the center of the detector.
  • theta (float) – The tilt angle formed by the rotation axis and the vertical axis of the detector.
neutompy.preproc.preproc.correction_COR(norm_proj, proj_0, proj_180, show_opt='mean', shift=None, theta=None, nroi=None, ystep=5)[source]

This function corrects the misalignment of the rotation axis respect to the vertical axis of the detector. The user can choose to insert manually the offset and the tilt angle of the rotation axis respect to the detector, if known parameters, or to estimate them using the projections at 0 and at 180 degrees. In this case, the user selects interactively different regions where the sample is visible. Once the position of the rotation axis is found the results are shown in two figures. In the first are shown the estimated rotation axis and the image obtained as proj_0 - pro_180[:,::-1] (projection at 180 is flipped horizontally) before the correction. The second figure shows the difference image (proj_0 - pro_180[:,::-1]) after the correction and the histogram of abs(proj_0 - pro_180[:,::-1]).

Parameters:

  • norm_proj (ndarray) – A stack of projections. The 0-axis represents theta.

  • proj_0 (2d array) – The projection at 0 degrees.

  • proj_180 (2d array) – The projection at 180 degrees.

  • show_opt (str, optional) – A string defining the image to show for the selection of the ROIs.

    Allowed values are:

    mean -> shows the mean of norm_proj along the O-axis.

    std -> shows the standard deviation of norm_proj along the O-axis

    zero -> shows proj_0

    pi -> shows proj_180

    Default value is mean.

  • shift (int, optional) – The horizontal shift in pixel of the rotation axis respect to the vertical axis of the detector. It can be specified if known parameter. The default is None, hence this parameter is estimated from the projections.

  • theta (float, optional) – The tilt angle in degrees of the rotation axis respect to the vertical axis of the detector. It can be specified if known parameter. The default is None, hence this parameter is estimated from the projections.

  • nroi (int, optional) – The number of the region of interest to select for the computation of the rotation axis position. Default is None, hence the value is read as input from keyboard.

  • ystep (int, optional) – The center of rotation position is computed every ystep. Default value is 5.
Returns:

norm_proj (ndarray) – The stack after the correction. The computation is done in place.
neutompy.preproc.preproc.remove_outliers(img, radius, threshold, outliers='bright', k=1.0, out=None)[source]

This function removes bright and dark outliers from an image. It replaces a pixel by the median of the pixels in the neighborhood if it deviates from the median by more than a certain value (k*threshold). The threshold can be specified by the user as a global value or computed proportionally to the local standard deviation of the projection.

Parameters:
  • img (2d array) – The image to elaborate.
  • radius (int or tuple of int) – The radius of the neighborhood. The radius is defined separately for each dimension as the number of pixels that the neighborhood extends outward from the center pixel.
  • threshold (float or str) – If it is the string ‘local’ the local standard deviation map is taken into account. Conversely, if it is a float number the threshold is global.
  • outliers (str, optional) – A string defining the type of outliers to remove. Allowed values are bright and dark. Default is bright.
  • k (float, optional) – A pixel is replaced by the median of the pixels in the neighborhood if it deviates from the median by more than k*threshold. Default value is 1.0.
  • out (2d array, optional) – If same as img, then the computation is done in place. Default is None, hence this behaviour is disabled.
Returns:

out (2d array) – The image obtained by removing the outliers.
neutompy.preproc.preproc.remove_outliers_stack(arr, radius, threshold, axis=0, outliers='bright', k=1.0, out=None)[source]

This function removes bright and dark outliers from a stack of images. The algorithm elaborates 2d images and the filtering is iterated over all images in the stack. The function replaces a pixel by the median of the pixels in the 2d neighborhood if it deviates from the median by more than a certain value (k*threshold). The threshold can be specified by the user as a global value or computed proportionally to the local standard deviation of the projection.

Parameters:
  • arr (ndarray) – The stack to elaborate.
  • radius (int or tuple of int) – The radius of the 2D neighborhood. The radius is defined separately for each dimension as the number of pixels that the neighborhood extends outward from the center pixel.
  • threshold (float or str) – If it is the string ‘local’ the local standard deviation map is taken into account. Conversely, if it is a float number the threshold is global.
  • axis (int) – The axis along wich the outlier removal is iterated.
  • outliers (str, optional) – A string defining the type of outliers to remove. Allowed values are bright and dark. Default is bright.
  • k (float, optional) – A pixel is replaced by the median of the pixels in the neighborhood if it deviates from the median by more than k*threshold. Default value is 1.0.
  • out (2d array, optional) – If same as arr, then the computation is done in place. Default is None, hence this behaviour is disabled.
Returns:

out (ndarray) – The array obtained by removing the outliers.
neutompy.preproc.preproc.remove_stripe(img, level, wname='db5', sigma=1.5)[source]

Suppress horizontal stripe in a sinogram using the Fourier-Wavelet based method by Munch et al. [2].

Parameters:
  • img (2d array) – The two-dimensional array representig the image or the sinogram to de-stripe.
  • level (int) – The highest decomposition level.
  • wname (str, optional) – The wavelet type. Default value is db5
  • sigma (float, optional) – The damping factor in the Fourier space. Default value is 1.5
Returns:

out (2d array) – The resulting filtered image.

References

[2]B. Munch, P. Trtik, F. Marone, M. Stampanoni, Stripe and ring artifact removal with combined wavelet-Fourier filtering, Optics Express 17(10):8567-8591, 2009.
neutompy.preproc.preproc.remove_stripe_stack(arr, level, wname='db5', sigma=1.5, axis=1, out=None)[source]

Suppress horizontal stripe in a stack of sinograms or a stack of projections using the Fourier-Wavelet based method by Munch et al. [3] .

Parameters:
  • arr (3d array) – The tomographic data. It can be a stack of projections (theta is the 0-axis) or a stack of images (theta is the 1-axis).
  • level (int) – The highest decomposition level
  • wname (str, optional) – The wavelet type. Default value is db5
  • sigma (float, optional) – The damping factor in the Fourier space. Default value is 1.5
  • axis (int, optional) – The axis index of the theta axis. Default value is 1.
  • out (None or ndarray, optional) – The output array returned by the function. If it is the same as arr, the computation will be done in place. Default value is None, hence a new array is allocated and returned by the function.
Returns:

outarr (3d array) – The resulting filtered dataset.

References

[3]B. Munch, P. Trtik, F. Marone, M. Stampanoni, Stripe and ring artifact removal with combined wavelet-Fourier filtering, Optics Express 17(10):8567-8591, 2009.
neutompy.preproc.preproc.simple_BHC(norm, a0=0.0, a1=0.0, a2=0.02, a3=0.0, out=None)[source]

This function performs the simple beam hardening correction (BHC) corresponding to a polynomial correction, given by:

\[s'= s + a_0 s^2 + a_1 s^3 + a_2 s^4 + a_3 s^5\]

where \(s = -\ln(I/I_0)\). The user can choose 4 parameters which define the 5-th order polynomial.

Parameters:
  • norm (3d array) – Three-dimensional stack of the normalized projections
  • a0 (float, optional) – The first term of the polynomial
  • a1 (float, optional) – The second term of the polynomial
  • a2 (float, optional) – The third term of the polynomial
  • a3 (float, optional) – The fourth term of the polynomial
Returns:

out (3d array) – Beam hardening correction (BHC) of the input array.
neutompy.preproc.preproc.zero_clipping_value(norm, cl=0.01, out=None)[source]

This function clips the values in an array. Values below the threshold value cl are replaced with cl. This function prevents values close to (or below) zero to introduce new artefacts.

\[s' = \max ( s, cl)\]
Parameters:
  • norm (3d array) – Three-dimensional stack of the normalized projections
  • cl (float, optional) – Clipping value
Returns:

out (3d array) – Clipping correction of the input array.