nabu.preproc.flatfield_variable_region module

class nabu.preproc.flatfield_variable_region.FlatFieldArraysVariableRegion(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)[source]

Bases: FlatFieldArrays

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.

class nabu.preproc.flatfield_variable_region.FlatFieldDataVariableRegionUrls(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)[source]

Bases: FlatFieldArraysVariableRegion

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.