rescale_intensity#

VirtualBSEImage.rescale_intensity(relative: bool = False, in_range: Tuple[int, int] | Tuple[float, float] | None = None, out_range: Tuple[int, int] | Tuple[float, float] | None = None, dtype_out: str | dtype | type | Tuple[int, int] | Tuple[float, float] | None = None, percentiles: Tuple[int, int] | Tuple[float, float] | None = None, show_progressbar: bool | None = None, inplace: bool = True, lazy_output: bool | None = None) None | VirtualBSEImage | LazyVirtualBSEImage[source]#

Rescale image intensities.

Output min./max. intensity is determined from out_range or the data type range of the numpy.dtype passed to dtype_out if out_range is None.

This method is based on skimage.exposure.rescale_intensity().

Parameters:
relative

Whether to keep relative intensities between images (default is False). If True, in_range must be None, because in_range is in this case set to the global min./max. intensity. Use with care, as this requires the computation of the min./max. intensity of the signal before rescaling.

in_range

Min./max. intensity of input images. If not given, in_range is set to pattern min./max intensity. Contrast stretching is performed when in_range is set to a narrower intensity range than the input patterns. Must be None if relative=True or percentiles are passed.

out_range

Min./max. intensity of output images. If not given, out_range is set to dtype_out min./max according to skimage.util.dtype.dtype_range.

dtype_out

Data type of rescaled images, default is input images’ data type.

percentiles

Disregard intensities outside these percentiles. Calculated per image. Must be None if in_range or relative is passed. Default is None.

show_progressbar

Whether to show a progressbar. If not given, the value of hyperspy.api.preferences.General.show_progressbar is used.

inplace

Whether to operate on the current signal or return a new one. Default is True.

lazy_output

Whether the returned signal is lazy. If not given this follows from the current signal. Can only be True if inplace=False.

Returns:
s_out

Rescaled signal, returned if inplace=False. Whether it is lazy is determined from lazy_output.

Notes

Rescaling RGB images is not possible. Use RGB channel normalization when creating the image instead.

Examples

>>> import numpy as np
>>> import kikuchipy as kp
>>> s = kp.data.nickel_ebsd_small()

Image intensities are stretched to fill the available grey levels in the input images’ data type range or any data type range passed to dtype_out, either keeping relative intensities between images or not

>>> print(
...     s.data.dtype, s.data.min(), s.data.max(),
...     s.inav[0, 0].data.min(), s.inav[0, 0].data.max()
... )
uint8 23 246 26 245
>>> s2 = s.deepcopy()
>>> s.rescale_intensity(dtype_out=np.uint16)
>>> print(
...     s.data.dtype, s.data.min(), s.data.max(),
...     s.inav[0, 0].data.min(), s.inav[0, 0].data.max()
... )
uint16 0 65535 0 65535
>>> s2.rescale_intensity(relative=True)
>>> print(
...     s2.data.dtype, s2.data.min(), s2.data.max(),
...     s2.inav[0, 0].data.min(), s2.inav[0, 0].data.max()
... )
uint8 0 255 3 253

Contrast stretching can be performed by passing percentiles

>>> s.rescale_intensity(percentiles=(1, 99))

Here, the darkest and brightest pixels within the 1% percentile are set to the ends of the data type range, e.g. 0 and 255 respectively for images of uint8 data type.

Examples using VirtualBSEImage.rescale_intensity#

Extract patterns from a grid

Extract patterns from a grid