Skip to content

nabu.preproc.flatfield

source module nabu.preproc.flatfield

Classes

  • FlatFieldArrays — A class for flat-field normalization

  • FlatFieldDataUrls — Initialize a flat-field normalization process with DataUrls.

  • PCAFlatsNormalizer — This class implement a flatfield normalization based on a PCA of a series of acquired flatfields. The PCA decomposition is handled by a PCAFlatsDecomposer object.

  • PCAFlatsDecomposer — This class implements a PCA decomposition of a serie of acquired flatfields. The PCA decomposition is used to normalize the projections through a PCAFLatNormalizer object.

source class FlatFieldArrays(radios_shape: tuple, flats, darks, radios_indices=None, interpolation: str = 'linear', distortion_correction=None, nan_value=1.0, radios_srcurrent=None, flats_srcurrent=None, n_threads=None)

A class for flat-field normalization

Initialize a flat-field normalization process.

Parameters

  • radios_shape : tuple — A tuple describing the shape of the radios stack, in the form (n_radios, n_z, n_x).

  • flats : dict — Dictionary where each key is the flat index, and the value is a numpy.ndarray of the flat image.

  • darks : dict — Dictionary where each key is the dark index, and the value is a numpy.ndarray of the dark image.

  • radios_indices : array of int, optional — Array containing the radios indices in the scan. radios_indices[0] is the index of the first radio, and so on.

  • interpolation : str, optional — Interpolation method for flat-field. See below for more details.

  • distortion_correction : DistortionCorrection, optional — A DistortionCorrection object. If provided, it is used to correct flat distortions based on each radio.

  • nan_value : float, optional — Which float value is used to replace nan/inf after flat-field.

  • radios_srcurrent : array, optional — Array with the same shape as radios_indices. Each item contains the synchrotron electric current. If not None, normalization with current is applied. Please refer to "Notes" for more information on this normalization.

  • flats_srcurrent : array, optional — Array with the same length as "flats". Each item is a measurement of the synchrotron electric current for the corresponding flat. The items must be ordered in the same order as the flats indices (flats.keys()). This parameter must be used along with 'radios_srcurrent'. Please refer to "Notes" for more information on this normalization.

  • n_threads : int or None, optional — Number of threads to use for flat-field correction. Default is to use half the threads.

Important

flats and darks are expected to be a dictionary with integer keys (the flats/darks indices) and numpy array values. You can use the following helper functions: nabu.io.reader.load_images_from_dataurl_dict and nabu.io.utils.create_dict_of_indices

Notes

Usually, when doing a scan, only one or a few darks/flats are acquired. However, the flat-field normalization has to be performed on each radio, although incoming beam can fluctuate between projections. The usual way to overcome this is to interpolate between flats. If interpolation="nearest", the first flat is used for the first radios subset, the second flat is used for the second radios subset, and so on. If interpolation="linear", the normalization is done as a linear function of the radio index.

The normalization with synchrotron electric current is done as follows. Let s = sr/sr_max denote the ratio between current and maximum current, D be the dark-current frame, and X' be the normalized frame. Then: srcurrent_normalization(X) = X' = (X - D)/s + D flatfield_normalization(X') = (X' - D)/(F' - D) = (X - D) / (F - D) * sF/sX So current normalization boils down to a scalar multiplication after flat-field.

Methods

source staticmethod FlatFieldArrays.get_previous_next_indices(arr, idx)

source staticmethod FlatFieldArrays.get_nearest_index(arr, idx)

source staticmethod FlatFieldArrays.interp(pos, indices, weights, array, slice_y=slice(None, None), slice_x=slice(None, None))

Interpolate between two values. The interpolator consists in pre-computed arrays such that

prev, next = indices[pos] w1, w2 = weights[pos] interpolated_value = w1 * array[prev] + w2 * array[next]

source method FlatFieldArrays.get_flat(pos, dtype=np.float32, slice_y=slice(None, None), slice_x=slice(None, None))

source method FlatFieldArrays.get_dark()

source method FlatFieldArrays.remove_invalid_values(img)

source method FlatFieldArrays.normalize_radios(radios)

Apply a flat-field normalization, with the current parameters, to a stack of radios. The processing is done in-place, meaning that the radios content is overwritten.

Parameters

  • radios : numpy.ndarray — Radios chunk

source method FlatFieldArrays.normalize_single_radio(radio, radio_idx, dtype=np.float32, slice_y=slice(None, None), slice_x=slice(None, None))

Apply a flat-field normalization to a single projection image.

source class FlatFieldDataUrls(radios_shape: tuple, flats: dict, darks: dict, radios_indices=None, interpolation: str = 'linear', distortion_correction=None, nan_value=1.0, radios_srcurrent=None, flats_srcurrent=None, **chunk_reader_kwargs)

Bases : FlatField

Initialize a flat-field normalization process with DataUrls.

Parameters

  • radios_shape : tuple — A tuple describing the shape of the radios stack, in the form (n_radios, n_z, n_x).

  • flats : dict — Dictionary where the key is the flat index, and the value is a silx.io.DataUrl pointing to the flat.

  • darks : dict — Dictionary where the key is the dark index, and the value is a silx.io.DataUrl pointing to the dark.

  • radios_indices : array, optional — Array containing the radios indices. radios_indices[0] is the index of the first radio, and so on.

  • interpolation : str, optional — Interpolation method for flat-field. See below for more details.

  • distortion_correction : DistortionCorrection, optional — A DistortionCorrection object. If provided, it is used to correct flat distortions based on each radio.

  • nan_value : float, optional — Which float value is used to replace nan/inf after flat-field.

Other Parameters

The other named parameters are passed to the reading function (sub_region, binning, etc). Please read its documentation for more information.

Notes

Usually, when doing a scan, only one or a few darks/flats are acquired. However, the flat-field normalization has to be performed on each radio, although incoming beam can fluctuate between projections. The usual way to overcome this is to interpolate between flats. If interpolation="nearest", the first flat is used for the first radios subset, the second flat is used for the second radios subset, and so on. If interpolation="linear", the normalization is done as a linear function of the radio index.

source class PCAFlatsNormalizer(components, dark, mean)

This class implement a flatfield normalization based on a PCA of a series of acquired flatfields. The PCA decomposition is handled by a PCAFlatsDecomposer object.

This implementation was proposed by Jailin C. et al in https://journals.iucr.org/s/issues/2017/01/00/fv5055/

Code initially written by ID11 @ ESRF staff. Jonathan Wright - Implementation based on research paper Pedro D. Resende - Added saving and loading from file capabilities

Jerome Lesaint - Integrated the solution in Nabu.

Initializes all variables needed to perform the flatfield normalization.

Parameters

  • components : ndarray — The components of the PCA decomposition.

  • dark : ndarray — The dark image. Should be one single 2D image.

  • mean : ndarray — The mean image of the series of flats.

Methods

  • update_mask — Method to update the mask with a custom mask in the form of a boolean 2+D array.

  • normalize_radios — This is to keep the flatfield API in the pipeline.

  • correct_stack — This functions normalizes the stack of projections.

  • correctproj — Performs the correction on one projection of the stack.

  • fit — Fit the (masked) projection to the (masked) components of the PCA decomposition.

source method PCAFlatsNormalizer.update_mask(mask: np.ndarray)

Method to update the mask with a custom mask in the form of a boolean 2+D array.

Paramters

mask: np.ndarray of Boolean; The array of boolean allows the selection of the region of the image that will be used to fit against the components.

It will set the mask, replacing the standard mask created with setmask().

Raises

  • TypeError

source method PCAFlatsNormalizer.normalize_radios(projections, mask=None, prop=0.125)

This is to keep the flatfield API in the pipeline.

source method PCAFlatsNormalizer.correct_stack(projections: np.ndarray, mask: np.ndarray = None, prop: float = 0.125)

This functions normalizes the stack of projections.

Performs correction on a stack of projections based on the calculated decomposition. The normalizations is done in-place. The previous projections before normalization are lost.

Parameters

  • projections : ndarray — Stack of projections to normalize.

  • prop : float (default: {0.125}) — Fraction to mask on the horizontal field of view, assuming vertical rotation axis

  • mask : np.ndarray (default: None) — Custom mask if your data requires it.

Returns

  • corrected projections : np.ndarray — Flat field corrected images. Note that the returned projections are exp-transformed to fit the pipeline (e.g. to allow for phase retrieval).

source method PCAFlatsNormalizer.correctproj(projection)

Performs the correction on one projection of the stack.

Parameters

  • projection : np.ndarray, float — Radiograph from the acquisition stack.

Returns

  • The fitted projection.

source method PCAFlatsNormalizer.fit(corr)

Fit the (masked) projection to the (masked) components of the PCA decomposition.

This is for each projection, so worth optimising ...

source class PCAFlatsDecomposer(flats: np.ndarray, darks: np.ndarray, nsigma=3)

This class implements a PCA decomposition of a serie of acquired flatfields. The PCA decomposition is used to normalize the projections through a PCAFLatNormalizer object.

This implementation was proposed by Jailin C. et al in https://journals.iucr.org/s/issues/2017/01/00/fv5055/

Code initially written by ID11 @ ESRF staff. Jonathan Wright - Implementation based on research paper Pedro D. Resende - Added saving and loading from file capabilities

Jerome Lesaint - Integrated the solution in Nabu.

Parameters

flats: np.ndarray A stack of darks corrected flat field images darks: np.ndarray An image or stack of images of the dark current images of the camera.

Does the log scaling. Subtracts mean and does eigenvector decomposition.

Methods

  • ccij — Compute the covariance (img[i]*img[j]).sum() / npixels It is a wrapper for threading. args == i, j, npixels, imgs

  • compute_correlation_matrix — Computes an (nflats x nflats) correlation matrix

  • compute_pca — Gets eigenvectors and eigenvalues and sorts them into order

  • generate_pca_flats — Projects the eigenvectors back into image space.

  • save_decomposition — Saves the basic information of a PCA decomposition in view of the normalization of projections.

source staticmethod PCAFlatsDecomposer.ccij(args)

Compute the covariance (img[i]*img[j]).sum() / npixels It is a wrapper for threading. args == i, j, npixels, imgs

source method PCAFlatsDecomposer.compute_correlation_matrix()

Computes an (nflats x nflats) correlation matrix

source method PCAFlatsDecomposer.compute_pca()

Gets eigenvectors and eigenvalues and sorts them into order

source method PCAFlatsDecomposer.generate_pca_flats(nsigma=3)

Projects the eigenvectors back into image space.

Parameters

  • nsigma : int (default: 3)

source method PCAFlatsDecomposer.save_decomposition(path='PCA_flats.h5', overwrite=True, entry='entry0000')

Saves the basic information of a PCA decomposition in view of the normalization of projections.

Parameters

  • path : str (default: "PCA_flats.h5") — Full path to the h5 file you want to save your results. It will overwrite!! Be careful.

Raises

  • OSError