plenpy.utilities package

Submodules

plenpy.utilities.colors module

Module defining color conversion and representation.

class plenpy.utilities.colors.Converter(cmf, illuminant)[source]

Bases: abc.ABC

Abstract conversion class.

This class is a base class for wavelength or spectrum conversion using CIE standard observer and illuminants.

Converter base class initialization.

Parameters

  • cmf (str) – Name of the color matching function. See get_avail_cmfs() for a list of available color matching functions. Default: CIE 1931 standard observer sampled at 1nm.

  • illuminant (str) – Name of the illuminant. See get_avail_illuminants() for a list of available illuminants. Default: CIE D65 midday light illuminant.

abstract to_rgb(**kwargs)[source]
Return type

ndarray

abstract to_xyz(**kwargs)[source]
Return type

ndarray

class plenpy.utilities.colors.SpectrumConverter(wavelengths, cmf='CIE_1931_1NM', illuminant='CIE_D65')[source]

Bases: plenpy.utilities.colors.Converter

Spectrum conversion class.

This class is used to compute XYC or RGB values from an EM spectrum. The conversion can be done with different standard observers. For a list of available color matching functions, see get_avail_cfs(). To calculate XYZ or RGB values for reflectance spectra, an illuminant is needed. For a list of available illuminants, see get_avail_illuminants().

Variables

~SpectrumConverter.wavelengths – Wavelengths basis of the spectra in nanometers.

SpectrumConverter class initialization.

Parameters

  • wavelengths (Union[ndarray, List[float]]) – Wavelengths basis of the spectra in nanometers. For example [400, 450, 500, 550, 600, 650, 700].

  • cmf (str) – Name of the color matching function. See get_avail_cmfs() for a list of available color matching functions. Default: CIE 1931 standard observer sampled at 1nm.

  • illuminant (str) – Name of the illuminant. See get_avail_illuminants() for a list of available illuminants. Default: CIE D65 midday light illuminant.

to_rgb(spectrum)[source]

Convert spectrum to RBG values.

This functions converts the spectra to CIE XYZ values and then converts to RGB via the sRGB standard.

Passing multiple spectra is possible.

Parameters

spectrum (Union[ndarray, List[float]]) – Spectrum or vertically stacked collection of spectra. The length of the spectra have to match the length of the converter’s wavelength basis.

Return type

ndarray

Returns

RGB values of the spectrum according to sRGB standard.

Note

If multiple spectra are specified, they must be vertically stacked, i.e. xyz = [[spectrum1], [spectrum2]]. Then the result will be the vertically stacked XZY values [[x1, y1, z1], [x2, y2, z2]].

to_xyz(spectrum)[source]

Convert spectrum to CIE XYZ values.

Passing multiple spectra is possible.

Parameters

spectrum (Union[ndarray, List[float]]) – Spectrum or vertically stacked collection of spectra. The length of the spectra have to match the length of the converter’s wavelength basis.

Return type

ndarray

Returns

CIE XYZ values of the spectrum.

Note

If multiple spectra are specified, they must be vertically stacked, i.e. xyz = [[spectrum1], [spectrum2]]. Then the result will be the vertically stacked XZY values [[x1, y1, z1], [x2, y2, z2]].

class plenpy.utilities.colors.WavelengthConverter(cmf='CIE_1931_1NM', illuminant='CIE_D65')[source]

Bases: plenpy.utilities.colors.SpectrumConverter

WavelengthConverter class initialization.

Parameters

  • cmf (str) – Name of the color matching function. See get_avail_cmfs() for a list of available color matching functions. Default: CIE 1931 standard observer sampled at 1nm.

  • illuminant (str) – Name of the illuminant. See get_avail_illuminants() for a list of available illuminants. Default: CIE D65 midday light illuminant.

to_rgb(wavelength, var=1500)[source]

Convert a wavelength to an approximate RGB value.

Converting is done by calculating a Gaussian shaped spectrum with central wavelength of the passed wavelength and converting the spectrum to XYZ value via CIE standard observer and illuminant, and conversion to RGB via the sRGB standard, see also SpectrumConverter.

Parameters

  • wavelength (Union[float, List[float]]) – Central wavelength.

  • var (float) – Variance of the Gaussian used to calculate the spectrum. Note: Spectra that are too small, e.g. “monochromatic” light, will result in a near to black RGB value. Therefore, the default value is chosen rather large.

Returns

Approximate RGB value of the wavelength.

Note

If multiple wavelengths are specified as a list, i.e. [400, 467, 555], then the result will be the vertically stacked XZY values [[r1, g1, b1], [r2, g2, b2]].

to_xyz(wavelength, var=1500)[source]

Convert a wavelength to an approximate CIE XYZ value.

Converting is done by calculating a Gaussian shaped spectrum with central wavelength of the passed wavelength and converting the spectrum to XYZ value via CIE standard observer and illuminant, see also SpectrumConverter.

Parameters

  • wavelength (Union[float, List[float]]) – Central wavelength.

  • var (float) – Variance of the Gaussian used to calculate the spectrum. Note: Spectra that are too small, e.g. “monochromatic” light, will result in a near to black XYZ value. Therefore, the default value is chosen rather large.

Returns

Approximate XYZ value of the wavelength.

Note

If multiple wavelengths are specified as a list, i.e. [400, 467, 555], then the result will be the vertically stacked XZY values [[x1, y1, z1], [x2, y2, z2]].

plenpy.utilities.colors.get_avail_cmfs()[source]

Get a list of available color matching functions.

Return type

List[str]

plenpy.utilities.colors.get_avail_illuminants()[source]

Get a list of available illuminants.

Return type

List[str]

plenpy.utilities.colors.get_cmf(cmf='CIE_1931_1NM')[source]

Get a color matching function.

Parameters

cmf (str) – Name of the color matching function. See get_avail_cmfs() For a list of available color matching functions. Default: CIE 1931 standard observer sampled at 1nm.

Return type

ndarray

Returns

Color matching function of shape (num_wavelengths, 4) in format [wavelength, x, y, z].

plenpy.utilities.colors.get_illuminant(illuminant='CIE_D65')[source]

Get an illuminant.

Parameters

illuminant (str) – Name of the illuminant. See get_avail_illuminants() For a list of available illuminants. Default: CIE D65 midday light illuminant.

Return type

ndarray

Returns

Illuminant of shape (num_wavelengths, 4) in format [wavelength, x, y, z].

plenpy.utilities.colors.rgb_to_xyz(rgb)[source]

Convert RGB value to XYZ.

The conversion of RGB values to CIE XYZ is done using the sRGB standard. RGB values are bound by [0, 1] while XYZ values are bound by [0, 100].

Parameters

rgb (Union[ndarray, List[float]]) – Color values [r, g, b].

Notes

If multiple values are specified, they must be vertically stacked, i.e. xyz = [[r1, g1, b1], [r2, g2, b2]]

Return type

ndarray

plenpy.utilities.colors.show_beautiful_rainbow(lambda_start=350, lambda_end=800, size=1000)[source]

Plots a nice rainbow gradient picture.

This visualizes the wavelength to spectrum to RGB conversion as implemented by WavelengthConverter and SpectrumConverter.

Parameters

  • lambda_start (int) – Start wavelength.

  • lambda_end (int) – End wavelength.

  • size (int) – Size of the picture in pixels.

plenpy.utilities.colors.xyz_to_rgb(xyz)[source]

Convert XYZ value to RGB.

The conversion of CIE XYZ values to RGB is done using the sRGB standard. RGB values are bound by [0, 1] while XYZ values are bound by [0, 100].

Parameters

xyz (Union[ndarray, List[float]]) – Color values [x, y, z].

Notes

If multiple values are specified, they must be vertically stacked, i.e. xyz = [[x1, y1, z1], [x2, y2, z2]]

Return type

ndarray

plenpy.utilities.core module

Module defining the core SpectralArray class. This is the base class for the light field and spectral image classes.

class plenpy.utilities.core.BandInfo(num_channels, centers, unit, bandwidths=None, centers_std=None, bandwidths_std=None, type=None)[source]

Bases: object

A class holding the band information of a spectral image.

The band information characterizes the spectral properties of every color channel of the image.

Every list attribute has the be of length N = _num_ch

Variables

  • ~BandInfo._numChannels (int) – Number of spectral channels.

  • ~BandInfo._centers (Union[List[float], ndarray]) – List of central wavelengths of each channel.

  • ~BandInfo._unit (str) – Unit of the wavelenghts, e.g. nm.

  • ~BandInfo._bandwidths (Union[List[float], ndarray]) – List of bandwidths of each channel. Optional.

  • ~BandInfo._centers_std (Union[List[float], ndarray]) – List of standard deviation of band centers. Optional.

  • ~BandInfo._bandwidths_std (Union[List[float], ndarray]) – List of standard deviation of bandwidths. Optional.

  • ~BandInfo._type (str) – Imgae type, e.g. reflectance. Optional.

__eq__(other)[source]

Equality operator for BandInfo class.

Parameters

other (BandInfo) – BandInfo object to test equality with.

Return type

bool

Returns

True, if BandInfo’s are equal, False otherwise.

property bandwidths
property bandwidths_std
property centers
property centers_std
copy()[source]

Get copy of the object.

Return type

BandInfo

Returns

Copy of BandInfo object.

classmethod from_envi_header(hdr)[source]

Initialize a BandInfo object from a ENVI header dictionary.

Parameters

hdr (dict) – Input dictionary from ENVI header file.

classmethod from_equidistant(num_channels, lambda_start, lambda_end, bandwidth=None, center_std=None, bandwidth_std=None, type=None)[source]

Initialize a BandInfo object with equidistant wavlength samples.

Parameters

  • num_channels (int) – Number of wavelength channels.

  • lambda_start (int) – Wavelength range start in nanometers.

  • lambda_end (int) – Wavelength range end in nanometers.

  • bandwidth (Optional[float]) – Bandwith of channels. Optional.

  • center_std (Optional[float]) – Standard deviation of centers. Optional.

  • bandwidth_std (Optional[float]) – Standard deviation of bandwiths. Optional.

  • type (Optional[str]) – Imgae type, e.g. reflectance. Optional.

get_downsampled(num)[source]

Get a copy of the BandInfo object corresponding to the downsampled spectral array.

Note that equidistant sampling is assumed. For irregularly sampled SpectralArrays, the downsampled BandInfo will be incorrect.

Parameters

num (int) – Number of samples in the downsampled object.

Returns

BandInfo object of the downsampled SpectralArray.

get_subband(start, stop)[source]

Get a spectral subband of the BandInfo object.

The subband is specified by a start index and stop index which is not included as is usual for Python array indexing x[start:stop].

Parameters

  • start (int) – Index of the start wavelength.

  • stop (int) – Index of the stop wavelength (not included).

Returns

BandInfo object of the subband SpectralArray.

property num_channels
property type
property unit
exception plenpy.utilities.core.DimensionError(exp, found)[source]

Bases: Exception

Error can be raised by inherited classes when expected dimension does not match the dimension of the passed array.

class plenpy.utilities.core.SpectralArray(array: numpy.ndarray, dtype: Optional[Type[Union[numpy.float64, numpy.float32, numpy.float16]]] = None, copy: bool = True, meta: Optional[dict] = None, band_info: Optional[plenpy.utilities.core.BandInfo] = None, ndim_exp: Optional[int] = None)[source]

Bases: numpy.ndarray

A subclass of np.ndarray that has a meta and a bandInfo attribute. This defines the class that the LightField and SpectralImage class are derived from.

A SpectralArray can be a 1D spectrum, 3D multi- (or hyper-) spectral image as well as regular RGB image or a 4D monochromatic or 5D color light field. Basically, all these concrete images are wavelength dependent arrays for which this base class provides the common architecture and methods. The shape of the arrays is (…, num_ch), i.e. (x, y, num_ch) for a “regular” or multispectral image or (u, v, s, t, num_ch) for a light field. That is, we are throughout using a “Color channel last” ordering.

This class only allows dtypes np.float64, np.float32 and np.float16 which are normalized to a range (0, 1). Float input must be in range (0, 1) already.

Create a SpectralArray from a numpy ndarray and metadata.

Parameters

  • array – Input data array as numpy ndarray.

  • dtype – Target datatype. Only numpy floats allowed: np.float16, np.float32, np.float64. Default: np.float32

  • copy – By default, a copy of the input array is forced. If ‘False’, will try to only use a view of the input array. This might not work in some cases and also depends on the Python interpreter.

  • meta – Meta data dictionary.

  • band_info – BandInfo object holding the the spectral band properties.

  • ndim_exp – Number of dimension expected of the array. This is used by inherited classes.

Raises

  • DimensionError(ndim_exp, array.ndim) –

  • If number of dimensions of input array does not match the specified –

  • ndim_exp option. –

Returns

SpectralArray

__array_finalize__(ob)[source]

Contain num_channels, meta and BandInfo on array operations.

It is not checked if the array leaves the (0, 1) range as it would be too heavy on perfomance.

static __new__(cls, array, dtype=None, copy=True, meta=None, band_info=None, ndim_exp=None)[source]

Create a SpectralArray from a numpy ndarray and metadata.

Parameters

  • array (ndarray) – Input data array as numpy ndarray.

  • dtype (Optional[Type[Union[float64, float32, float16]]]) – Target datatype. Only numpy floats allowed: np.float16, np.float32, np.float64. Default: np.float32

  • copy (bool) – By default, a copy of the input array is forced. If ‘False’, will try to only use a view of the input array. This might not work in some cases and also depends on the Python interpreter.

  • meta (Optional[dict]) – Meta data dictionary.

  • band_info (Optional[BandInfo]) – BandInfo object holding the the spectral band properties.

  • ndim_exp (Optional[int]) – Number of dimension expected of the array. This is used by inherited classes.

Raises

  • DimensionError(ndim_exp, array.ndim) –

  • If number of dimensions of input array does not match the specified –

  • ndim_exp option. –

Returns

SpectralArray

_get_filters_gauss(num_filters, fwhm=5)[source]

Calculate gaussian bandpass with the given color channels.

The filters are spread out equidistantly across the spectral range of the SpectralArray. The filters are normalized to a peak of one.

Parameters

  • num_filters – Number of returned spectral filters.

  • fwhm – Full width half maximum of the filters in units of channels indices.

Return type

ndarray

Returns

A 2D numpy array containing the filters. The first axis of the array corresponds to the filter index. The filters themselves are defined along the second array axis.

_get_filters_ideal(num_filters)[source]

Calculate ideal bandpass with the given color channels.

The filters are spread out equidistantly across the spectral range of the SpectralArray. The filters are normalized to a peak of one.

Parameters

num_filters – Number of returned spectral filters.

Return type

ndarray

Returns

A 2D numpy array containing the filters. The first axis of the array corresponds to the filter index. The filters themselves are defined along the second array axis.

property band_info
copy(order='C')[source]

Copy SpectralArray

get_decimated_spectrum(q, **kwargs)[source]

Downsample the spectrum after applying an anti-aliasing filter in the spectral domain.

Note that for large SpectralArrays, this consumes a lot of RAM. In this case, patching in the spatial domain can be applied.

The BandInfo and metadata are updated accordingly. Note, that it is implied, that the spectrum is sampled in an equidistant fashion. If the spectrum is irregularly sampled, the downsampling will yield incorrect results.

The routine mainly uses scipy.signal.decimate() for the downsampling.

Parameters
Return type

SpectralArray

Returns

The spectrally downsampled SpectralArray.

get_gray(weighted=True)[source]

Calculate monochromatic from SpectralArray values. Uses to_rgb() conversion and then performs an RGB to grey conversion.

Parameters

weighted (bool) – Flag indicating whether to use weighted conversion according to CIE 1931 standard (default) or non weighted.

Return type

ndarray

Returns

Monochromatic data of shape (…, 1), where the shape in the non-color axes remains the same.

get_grey(weighted=True)[source]

Calculate monochromatic from SpectralArray values. Uses to_rgb() conversion and then performs an RGB to grey conversion.

Parameters

weighted (bool) – Flag indicating whether to use weighted conversion according to CIE 1931 standard (default) or non weighted.

Return type

ndarray

Returns

Monochromatic data of shape (…, 1), where the shape in the non-color axes remains the same.

get_msi(num_ch, method='gauss', normalize='area', use_compl=False)[source]

Get multispectral array from hyperspectral array using a Gaussian or ideal filter. Only the spectral axis will be altered.

Parameters

  • num_ch (int) – Number of spectral channels of downsampled image.

  • method (str) – Method used for downsampling. If gauss is specified, use gaussian filters, if ideal is specified, use ideal, rectangular filters.

  • normalize (str) – Method used to normalize the filters. By default, the filters are normlized by area, i.e. each filter sums to one. This guarantees that the output image is still bounded by 1. If peak is specified, the filters are normlized to peak 1. This results in the output image not being bound by 1. The output has to be down-amplified afterwards. But it comes in handy when looking at actual filters to be applied to a camera.

  • use_compl (bool) – Boolean flag indicating whether to use complementary filters.

Returns: SpectralArray

Downsampled image.

Return type

SpectralArray

get_resampled_spectrum(num, **kwargs)[source]

Resample the spectrum using FFT.

Note that for large SpectralArrays, this consumes a lot of RAM. In this case, patching in the spatial domain can be applied.

The BandInfo and metadata are updated accordingly. Note, that it is implied, that the spectrum is sampled in an equidistant fashion. If the spectrum is irregularly sampled, the downsampling will yield incorrect results.

The routine mainly uses scipy.signal.resample() for the downsampling.

Parameters
Return type

SpectralArray

Returns

The downsampled SpectralArray.

get_rescaled(scale, **kwargs)[source]

Rescale the array spatially after applying an anti-aliasing filter.

This has to be implemented by the derived class.

Parameters

  • scale (Union[float, Tuple[float]]) – Scale factors. Separate scale factors per axis can be defined. If one value is given, the same factor is applied along all axes.

  • **kwargs – Options passed to scipy.signal.decimate().

Return type

SpectralArray

Returns

The spatially downsampled SpectralArray.

get_resized(output_shape, **kwargs)[source]

Resize the array spatially to a defined output shape.

This has to be implemented by the derived class.

Parameters
Return type

SpectralArray

Returns

The spatially resized SpectralArray.

get_rgb(cmf='CIE_1931_1NM', illuminant='CIE_D65')[source]

Calculate RGB representation of the SpectralArray

For example, RGB values of a spectrum, a multispectral image or a multispectral light field.

Parameters
Return type

ndarray

Returns

RGB data of shape (…, 3), where the shape in the non-color axes remains the same.

get_subband(start, stop)[source]

Get a spectral subband of the SpectralArray.

The subband is specified by a start index and stop index which is not included as is usual for Python array indexing x[…, start:stop].

Parameters

  • start (int) – Index of the start wavelength.

  • stop (int) – Index of the stop wavelength (not included).

Return type

SpectralArray

Returns

SpectralArray corresponding to a subband of the input SpectralArray.

property meta
normalize(by='peak')[source]

Normalize a SpectralArray in place.

Parameters

by –

Used normalization method. Available methods are:

  • ’area’: normalize to sum one

  • ’peak’: normalize to maximum value

  • ’l2’: normalize by L2 norm of the array

See also

Based on plenpy.utilities.images.normalize_in_place().

property num_channels
numpy(copy=False)[source]

Convert array to Numpy ndarray base class.

Parameters

copy (bool) – Whether to copy the corresponding array. Otherwise, memory may be shared.

Return type

ndarray

Returns

A Numpy ndarray equivalent of the array.

static read_envi_header(file)[source]

Read ENVI header file.

This function is mostly analogous to the ENVI I/O of the SpectralPython library by Thomas Boggs releases under GNU GPGv2. See: https://github.com/spectralpython/spectral/blob/master/spectral/io/envi.py

Parameters

file – Input ENVI header file (.hdr).

Returns

Dictionary of header file values.

save(path, create_dir, dtype)[source]

Implementation of save method depends on array shape.

Is overwritten in the SpectralImage, resp. LightField class.

save_rgb(path)[source]

Implementation of save method depends on array shape.

Is overwritten in the SpectralImage, resp. LightField class.

plenpy.utilities.core.read_mat(path, key)[source]

Read array data from a Matlab mat file from a specific key.

This function wraps both scipy.io.loadmat() and hdf5 to cover all possible file versions.

Parameters

  • path (Path) – Path to mat file.

  • key (str) –

    Key name of the data in .mat file. If only one variable is contained, option is ignored and key is found automatically. If more than one key is contained, the key option must be

    specified.

Return type

ndarray

Returns

Data.

plenpy.utilities.demosaic module

Module defining image demosaicing methods.

This module is basically a wrapper of the color_demosaicing package, see also the project’s GitHub page: https://github.com/colour-science/colour-demosaicing .

plenpy.utilities.demosaic.bilinear(sen_im, spec_filter, num_ch)[source]
Parameters

  • sen_im – Sensor image.

  • spec_filter – Spectral filter array.

  • num_ch – Number of spectral channels of sensor image.

Returns

Simple bilinear separately interpolated images.

plenpy.utilities.demosaic.bilinear_correlation(sen_im, spec_filter, num_ch)[source]
Parameters

  • sen_im – Sensor image.

  • spec_filter – Spectral filter array.

  • num_ch – Number of spectral channels of sensor image.

Returns

Bilinear interpolated images using values of all channels.

plenpy.utilities.demosaic.get_demosaiced(img, pattern='GRBG', method='bilinear')[source]

Get a demosaiced RGB image from a raw image.

This function is a wrapper of the demosaicing functions supplied by the color_demosaicing package.

Parameters

  • img (ndarray) – Input image, greyscale, of shape (x,y).

  • pattern (str) –

    Bayer filter pattern that the input image is modulated with. Patterns are: ‘RGGB’, ‘BGGR’, ‘GRBG’, ‘GBRG’.

    Default: ‘GRBG’

  • method (str) –

    Algorithm used to calculate the demosaiced image.

    • ’bilinear’: Simple bilinear interpolation of color values

    • ’malvar2004’: Algorithm introduced by Malvar et. al. [R3]

    • ’menon2007’: Algorithm introduced by Menon et. al. [R4],

Return type

ndarray

Returns

Demosaiced RGB-color image of shape (x,y,3) of dtype numpy.float64.

References

R3

H.S. Malvar, Li-wei He, and R. Cutler (2004). High-quality linear interpolation for demosaicing of Bayer-patterned color images. IEEE International Conference on Acoustics, Speech, and Signal Processing, Proceedings. (ICASSP ‘04). DOI: 10.1109/ICASSP.2004.1326587

R4

D. Menon, S. Andriani, G. Calvagno (2007). Demosaicing With Directional Filtering and a posteriori Decision. IEEE Transactions on Image Processing (Volume: 16, Issue: 1) DOI: 10.1109/TIP.2006.884928

plenpy.utilities.demosaic.get_interpolation_kernel(num_ch)[source]
Parameters

num_ch – Number of spectral channels of sensor image.

Returns

Filter kernel

plenpy.utilities.demosaic.hsi_demosaiced(img, pattern, method='bilinear')[source]

Demosaicking method for hyperspectral images.

Parameters

  • img (ndarray) – Input image,greyscale, of shape (x,y).

  • pattern (ndarray) – Spectral filter array. Usually the size of the pattern needs to be the same as the size of img. But for a uniform filter, a filter block is also feasible.

  • method (str) –

    Algorithm used to calculate the demosaiced image.

    • ’bilinear’: Simple bilinear interpolation of color values separately.

    • ’bilinear_correlation’: Bilinear interpolation of color values in one channel correlated with values in all channels.

Return type

SpectralImage

Returns

Demosaiced hyperspectral images of shape (x, y, channel) of as class:’HyperSpectralImage’

plenpy.utilities.demosaic.mask_chan(image, spec_filter, chan)[source]
Parameters

  • image – 2d Image.

  • spec_filter – Spectral filter array.

  • chan – Channel number.

Returns

Updated image. Only this channel related values in image will be remained. Others will become zero.

plenpy.utilities.denoise module

Module defining various image denoising algorithms

plenpy.utilities.denoise._nabla(img_in)[source]

Calculates gradient of input image.

Parameters

img_in (ndarray) – Input image (h,w).

Return type

ndarray

Returns

Gradient of input image (h,w,2).

plenpy.utilities.denoise._nablaT(img_in)[source]

‘Inverse’ to _nabla. Calculates divergence of image. Input is gradient image.

Parameters

img_in (ndarray) – Input gradient image (h,w,2).

Return type

ndarray

Returns

Divergence of image (h,w).

plenpy.utilities.denoise._prox_l1(u, u_ref, lt)[source]

Proximity operator for l1-norm. Pixel-wise “shrinking”.

Parameters

  • u (ndarray) – Image to optimize.

  • u_ref (ndarray) – Original image.

  • lt (float) – lambda*tau from primal-dual algorithm.

Return type

ndarray

Returns

Optimized image.

plenpy.utilities.denoise._prox_l2(u, u_ref, lt)[source]

Proximity operator for l2-norm.

Parameters

  • u (ndarray) – Image to optimize.

  • u_ref (ndarray) – Original image.

  • lt (float) – lambda*tau from primal-dual algorithm.

Return type

ndarray

Returns

Optimized image.

plenpy.utilities.denoise._prox_tv(y, r=1.0)[source]

Proximity operator for total variation. Pixel-wise “projection onto r-balls”.

Parameters

  • y (ndarray) – Dual variable from primal-dual algorithm.

  • r (float) – Radius of ball.

Return type

ndarray

Returns

Optimized variable.

plenpy.utilities.denoise.denoise_image_huber(img, n_iter, w_lambda=0.5)[source]

Primal-dual algorithm for minimization of TV-Huber-norm-L1-functional. Algotirhm is based on [R1].

Discrete functional:

  • TV_Huber-L1: min_x( ||_nabla x||_h + lambda*||x - f||_1 )

Parameters

  • img (ndarray) – Input image.

  • n_iter (int) – Number of iterations

  • w_lambda (Union[ndarray, float]) – Weight factor of data term. Pixel-wise weight is possible.

Return type

ndarray

Returns

The filtered image of the same shape as the input image.

plenpy.utilities.denoise.denoise_image_rof(img, n_iter, w_lambda=5)[source]

Primal-dual algorithm for minimization of ROF-functional (TV-L2). Fast form of primal-dual algorithm (faster than standard). Algotirhm is based on [R1].

Discrete functional:

  • ROF: min_x( ||_nabla x||_1 + 0.5*lambda*(||x - f||_1)**2 )

Parameters

  • img (ndarray) – Input image.

  • n_iter (int) – Number of iterations

  • w_lambda (Union[ndarray, float]) – Weight factor of data term. Pixel-wise weight is possible.

Return type

ndarray

Returns

The filtered image of the same shape as the input image.

References

R1(1,2,3,4)

Chambolle, Antonin; Pock, Thomas (2011): A First-Order Primal-Dual Algorithm for Convex Problems with Applications to Imaging. In: Journal of Mathematical Imaging and Vision 40 (1)

plenpy.utilities.denoise.denoise_image_tvl1(img, n_iter, w_lambda=0.5)[source]

Primal-dual algorithm for minimization of TV-L1-functional. Algotirhm is based on [R1].

Discrete functional:

  • TV-L1: min_x( ||_nabla x||_1 + lambda*||x - f||_1 )

Parameters

  • img (ndarray) – Input image.

  • n_iter (int) – Number of iterations

  • w_lambda (Union[ndarray, float]) – Weight factor of data term. Pixel-wise weight is possible.

Return type

ndarray

Returns

The filtered image of the same shape as the input image.

plenpy.utilities.denoise.denoise_multi_images_tvl1(imgs, n_iter, w_lambdas=0.5)[source]

Primal-dual algorithm for minimization of TV-L1 functional with huber norm in variational term and several weights for fusion of multiple measurements. Algotirhm is based on [R1].

Discrete functional:

  • min_x( ||_nabla x||_h + sum_i{ lambda_i*||x - f_i||_1 } )

Parameters

  • imgs (Union[ndarray, list]) – Stack of input images.

  • n_iter (int) – Number of iterations

  • w_lambdas (Union[ndarray, float]) – Weight factor of the multiple data terms. Pixel-wise weight is possible.

Return type

ndarray

Returns

The filtered image of the same shape as the input image.

plenpy.utilities.denoise.remove_outliers(img, confidence, threshold=0.5)[source]

Filter an image by removing outliers with confidence below a threshold.

Pixel with confidence below the threshold are discarded and are recalculated by interpolation from the surrounding pixels.

..todo: what happens on image borders?

Parameters

  • img (ndarray) – Input image. Has to be of the shape (x,y) with a single color channel.

  • confidence (ndarray) – Confidence measure of image pixels. Needs to have same shape as input image.

  • threshold (float) – Pixel with confidence below threshold are discarded.

Return type

ndarray

Returns

The filtered image of the same shape as the input image.

plenpy.utilities.grids module

Module defining GridParameters and different grid classes.

The grid parameter class and the grid classes model regular and slightly irregular grids.

class plenpy.utilities.grids.GridParameters(size, spacing=14, rotation=0.0, offset=0)[source]

Bases: object

Class to save grid parameters of a grid.

The grid parameters are an abstract representation of a grid and store all necessary geometrical information of a grid, except its layout, i.e. hexagonal or rectangular for example.

Variables

  • ~GridParameters._size – Size [x, y] of the grid in pixels.

  • ~GridParameters._spacing – Spacing vector [x_spacing, y_spacing] between grid points in pixels.

  • ~GridParameters._rotation – Rotation of the grid in radians.

  • ~GridParameters._offset – Offset vector [x_offset, y_offset] of the first grid point in pixels.

GridParameters base class initialization.

Parameters

  • size (Union[int, List[int], ndarray]) – Size of the grid in pixels. That is, the region [0, size_x] x [0, size_y] where the grid coordinates will reside. This does not correspond to the actual number of grid points. If size is of type int` a quadratic size is assumed.

  • spacing (Union[float, List[float], ndarray]) – Spacing vector [x_spacing, y_spacing] of the grid. If float is given, a symmetric spacing is assumed.

  • rotation (float) – Rotation of the grid in radians.

  • offset (Union[float, List[float], ndarray]) – Offset vector [x_offset, y_offset] of the first grid point in pixels. If float is given, a symmetric offset is assumed. Default: [0, 0]

property offset
property rotation
property size
property spacing
class plenpy.utilities.grids.HexGrid(grid_parameters, **kwargs)[source]

Bases: plenpy.utilities.grids.AbstractGrid

Hexagonal grid.

HexGrid class initialization.

Parameters

grid_parameters (GridParameters) – Grid parameters of the grid.

_calc_grid_points()[source]

Calculate the grid points of a hexagonal grid defined by grid_parameters.

_calc_grid_points_num()[source]

Calculate the number of grid points of a hexagonal grid defined by grid_parameters.

class plenpy.utilities.grids.RectGrid(grid_parameters, **kwargs)[source]

Bases: plenpy.utilities.grids.AbstractGrid

Rectangular grid.

RectGrid class initialization.

Parameters

grid_parameters (GridParameters) – Grid parameters of the grid.

_calc_grid_points()[source]

Calculate the grid points of a rectangular grid defined by grid_parameters.

_calc_grid_points_num()[source]

Calculate the number of grid points of a rectangular grid defined by grid_parameters.

plenpy.utilities.images module

Module defining useful image related methods.

plenpy.utilities.images.crop_center(img, crop_x, crop_y=None)[source]

Utility function to crop an image around its center.

Parameters

  • img (ndarray) – Input image.

  • crop_x (int) – Size of the cropped image in x-direction

  • crop_y (Optional[int]) – Size of the cropped image in y-direction. If None, a quadratic crop is returned.

Return type

ndarray

Returns

Cropped Image of shape (cropped_x, cropped_y, num_channels).

Notes

No interpolation is done at any point. That means in particular: if you pass an image of even dimensions and crop to odd dimensions, the returned image is not the exact center (this would need interpolation) but rather an image one pixel off the original image’s center. Analogously, if you crop an image of odd dimension to an image of even dimensions, the same holds. The returned image will only be the true center of the original image if the crop sizes in both direction matches the original size dimensions in the modulo 2 sense (i.e. even/odd).

plenpy.utilities.images.fourier(img, shift=True, window=None, pad=None, implementation='scipy')[source]

Calculates the fourier transform of an image. Image will be downsampled to greyscale if necessary.

Additionally to the basic fast fourier transformations (FFT), such as numpy or scipy, this function implements proper windowing prior to the transformation, as well as a proper shift of the zero frequency component for even-sized images. Different implementations are supported. For plotting, see func:plenpy.utilities.plots.plot_fft.

Note, that color channels will be converted to greyscale prior to FFT calculation.

Parameters

  • img (ndarray) – Input image.

  • shift (bool) – If True, shift spectrum, i.e. zero frequency component is shifted to the center. If image is even-sized, zero padding will be performed.

  • window (Optional[str]) – Specify 2D window used to reduce spectral leakage. See plenpy.utilities.kernels.get_avail_names() for a list of available windows kernels. If None is specified, no windowing is performed.

  • pad (Union[int, List[int], ndarray, None]) – Zero padding applied in all directions in pixel. If int is given, padding will be identical in all directions. If list/ndarray ist given, padding will be performed independently in x- and y-direction.

  • implementation (str) – The implementation used to calculate the Fourier transform. Available implementations are ‘scipy’, ‘numpy’, ‘fftw’. See also: scipy.fftpack.fft2() and numpy.fft.fft2(). For ‘fftw’, pyFFTW has to be installed on the system, see https://github.com/hgomersall/pyFFTW . Default: ‘scipy’.

Return type

ndarray

Returns

The (complex valued) fourier transform of the input image.

plenpy.utilities.images.get_edges(im, method='sobel', **kwargs)[source]

Get the gradients of a 2D-image using different methods.

Parameters

  • im (ndarray) – Input image of shape (x, y). Only monochromatic images are supported here.

  • method – Used method for gradient calculation. Possible values are: * ‘scharr’: Scharr filter. * ‘sobel’: Sobel filter. * ‘dog’: Difference of Gaussians. * ‘gradient’: Numpy’s gradient() method

Return type

ndarray

Returns

Tuple (gx, gy). Gradient gx, gy in x- and y-direction, respectively.

plenpy.utilities.images.get_gradients(im, method='sobel', **kwargs)[source]

Get the gradients of a 2D-image using different methods.

Parameters

  • im (ndarray) – Input image of shape (x, y). Only monochromatic images are supported here.

  • method – Used method for gradient calculation. Possible values are: * ‘scharr’: Scharr filter. * ‘sobel’: Sobel filter. * ‘dog’: Difference of Gaussians. * ‘gradient’: Numpy’s gradient() method

Return type

Tuple[ndarray, ndarray]

Returns

Tuple (gx, gy). Gradient gx, gy in x- and y-direction, respectively.

plenpy.utilities.images.normalize(img, by='area', dtype=<class 'numpy.float64'>)[source]

Get a normalized copy of an ndarray, e.g. an image or kernel. The returned array will be a float.

Parameters

  • img (ndarray) – Input ndarray.

  • by –

    Used normalization method. Available methods are:

    • ’area’: normalize to sum one

    • ’peak’: normalize to maximum value

    • ’l2’: normalize by L2 norm of the array

  • dtype – Output dtype. Either np.float16, np.float32 or np.float64. If input is float, output will be of same word size.

Return type

ndarray

Returns

Normalized array of same shape as input array.

See also

Based on normalize_in_place().

plenpy.utilities.images.normalize_in_place(img, by='area')[source]

Normalize a ndarray in place. Only for float type arrays.

Parameters

  • img (ndarray) – Input ndarray.

  • by –

    Used normalization method. Available methods are:

    • ’area’: normalize to sum one

    • ’peak’: normalize to maximum value

    • ’l2’: normalize by L2 norm of the array

plenpy.utilities.images.overlay_images(img1, img2)[source]

Overlay two images in grayscale mode for comparison.

The used color scheme is magenta-green by default. That is, it shows img1 in green and img2 in magenta. The overlay is grey in areas where the two images have similar intensity. The images have to be of same shape. Color images will be converted to grayscale.

Parameters
Return type

ndarray

Returns

Overlay of img1 and img2 of shape (x, y, 3).

Raises

ValueError – Images img1 and img2 must be of same shape. Found shapes img1.shape and img2.shape .

plenpy.utilities.images.shear(im, k, order=1)[source]

Shear a 2D image. If k=1, vertical lines are at 45° after shearing.

Parameters

  • im (ndarray) – 2D image to shear.

  • k (float) – Shearing factor.

  • order (int) – Interpolation order. Default: 1 (bilinear)

Returns

Sheared image. Output shape is same as input.

plenpy.utilities.kernels module

Module defining different 2D kernels.

Feel free to add more kernels. To get list of all available kernels use get_avail_names().

plenpy.utilities.kernels.get_avail_names()[source]

List all available kernel names.

Return type

List[str]

Returns

A list of all available kernel names that can for example be passed to get_kernel().

plenpy.utilities.kernels.get_kernel(name, size, size_y=None, option=None, option_y=None, normalize='area')[source]

Get a predefined 2D matrix kernel

Parameters

  • name (str) – Name of the kernel. For a list of available kernel names, use get_avail_names().

  • size (int) – Size of the kernel in pixels.

  • option (Optional[float]) – Option of the kernel. If disk is specified, corresponds to radius, if gauss is specified, corresponds to sigma, if kaiser is specified, corresponds to shape parameter beta.

  • size_y (Optional[int]) – Size of the kernel in y-direction in pixels. If no size_y has been specified, a quadratic kernel is calculated.

  • option_y (Optional[float]) – Option of the kernel in y-direcion.. If disk is specified, corresponds to radius_y, if gauss is specified, corresponds to sigma_y, if kaiser is specified, corresponds to shape parameter beta_y. If no option_y has been specified, a symmetric kernel is calculated.

  • normalize (str) – Normalize the kernel by given method, see plenpy.utilities.images.normalize() for available types. Default: Normalize to sum one.

Returns

A predefined 2D kernel of specified type.

plenpy.utilities.kernels.get_kernel_disk(size, radius=None, size_y=None, radius_y=None, normalize='area')[source]

Get a normalized 2D disk kernel.

Parameters

  • size (int) – Size of the kernel in pixels.

  • radius (Optional[float]) – Radius of the disk.

  • size_y (Optional[int]) – Size of the kernel in y direction. If no value is specified, a quadratic kernel is calculated

  • radius_y (Optional[int]) – Radius of the disk in y-direction. If no value is specified, a circular disc is calculated.

  • normalize (str) – Normalize the kernel by given method, see plenpy.utilities.images.normalize() for available types. Default: Normalize to sum one.

Return type

ndarray

Returns

A disk kernel of shape (size, size_y) with radii (radius, radius_y).

plenpy.utilities.kernels.get_kernel_gauss(size, sigma=None, size_y=None, sigma_y=None, normalize='area')[source]

Get a normalized 2D Gauss kernel.

This kernel is not a tensor product kernel, i.e. it is rotationally symmetric if the sigma values in x- and y-direction are equal.

Parameters

  • size (int) – Size of the kernel in pixels.

  • sigma (Optional[float]) – Standard deviation of the Gauss kernel. Default: size/5.0.

  • size_y (Optional[int]) – Size of the kernel in y direction. If no value is specified, a quadratic kernel is calculated

  • sigma_y (Optional[float]) – Standard deviation of the Gauss kernel in v-direction. If no sigma_y has been specified, a symmetric kernel is calculated.

  • normalize (str) – Normalize the kernel by given method, see plenpy.utilities.images.normalize() for available types. Default: Normalize to sum one.

Return type

ndarray

Returns

A gauss kernel of shape (size, size_y) with radii standard deviations (sigma, sigma_y).

plenpy.utilities.kernels.get_kernel_hamming(size, size_y=None, normalize='area')[source]

Get a normalized 2D Hamming kernel.

Parameters

  • size – Size of the kernel in pixels.

  • size_y (Optional[int]) – Size of the kernel in y direction. If no value is specified, a quadratic kernel is calculated

  • normalize (str) – Normalize the kernel by given method, see plenpy.utilities.images.normalize() for available types. Default: Normalize to sum one.

Return type

ndarray

Returns

A Hamming kernel of shape (size, size_y).

plenpy.utilities.kernels.get_kernel_hann(size, size_y=None, normalize='area')[source]

Get a normalized 2D Hann kernel.

Parameters

  • size (int) – Size of the kernel in pixels.

  • size_y (Optional[int]) – Size of the kernel in y direction. If no value is specified, a quadratic kernel is calculated

  • normalize (str) – Normalize the kernel by given method, see plenpy.utilities.images.normalize() for available types. Default: Normalize to sum one.

Return type

ndarray

Returns

A Hann kernel of shape (size, size_y).

plenpy.utilities.kernels.get_kernel_hann_rotational(size, size_y=None, normalize='area')[source]

Get a normalized, rotationally symmetric 2D Hann kernel.

This kernel is rotationally symmetric and not a tensor product kernel.

Parameters

  • size (int) – Size of the kernel in pixels.

  • size_y (Optional[int]) – Size of the kernel in y direction. If no value is specified, a quadratic kernel is calculated

  • normalize (str) – Normalize the kernel by given method, see plenpy.utilities.images.normalize() for available types. Default: Normalize to sum one.

Return type

ndarray

Returns

A rotationally symmetric Hann kernel of shape (size, size_y).

plenpy.utilities.kernels.get_kernel_kaiser(size, beta=3.5, size_y=None, beta_y=None, normalize='area')[source]

Get a normalized 2D Kaiser kernel.

Parameters

  • size (int) – Size of the kernel in pixels.

  • beta (float) – Shape parameter. Default: 3.5

  • size_y (Optional[int]) – Size of the kernel in y direction. If no value is specified, a quadratic kernel is calculated

  • beta_y (Optional[float]) – Shape parameter in y-direction. If no value is specified, a symmetric shape array is calculated

  • normalize (str) – Normalize the kernel by given method, see plenpy.utilities.images.normalize() for available types. Default: Normalize to sum one.

Return type

ndarray

Returns

A Kaiser kernel of shape (size, size_y).

plenpy.utilities.kernels.get_kernel_kaiser_rotational(size, beta=None, size_y=None, normalize='area')[source]

Get a normalized, rotationally symmetric 2D Kaiser kernel.

This kernel is rotationally symmetric and not a tensor product kernel. Since the definition relies on the (recursively defined) modified bessel functions, this implementation is much slower than the tensor product implementation.

Parameters

  • size (int) – Size of the kernel in pixels.

  • beta (Optional[float]) – Shape parameter. Default: 3.5

  • size_y (Optional[int]) – Size of the kernel in y direction. If no value is specified, a quadratic kernel is calculated

  • normalize (str) – Normalize the kernel by given method, see plenpy.utilities.images.normalize() for available types. Default: Normalize to sum one.

Return type

ndarray

Returns

A rotationally symmetric Kaiser kernel of shape (size, size_y).

plenpy.utilities.kernels.is_symmetric(m, symmetry=None)[source]

Utility function to check for symmetries for a NxN array.

Parameters

m (ndarray) – Input ndarray to check.

symmetrySymmetry to check. Available symmetries are ‘all’, ‘rotational’

and ‘axial’. If None is specified, all symmetries are checked.

Return type

bool

Returns

bool

True if input is symmetric with the specified symmetry. False otherwise.

plenpy.utilities.misc module

Module defining miscellaneous methods used in the plenpy package.

plenpy.utilities.misc.get_avail_extensions()[source]

List all available extensions/suffixes that can be read as images.

Return type

List[str]

Returns

List of all image extensions that can be read as sensor images. See also imageio.help().

plenpy.utilities.misc.rot_matrix(angle, unit='radians')[source]

Get 2D rotation matrix using angle alpha.

Parameters

  • angle (float) – Angle to rotate in the specified unit.

  • unit (str) –

    Specify if alpha is passed in radians or degrees. Available are ‘rad’, ‘radian’, ‘radians’, ‘deg’, ‘degree’, ‘degrees’.

    Default: ‘radians’

Return type

ndarray

Returns

Rotation matrix.

plenpy.utilities.plots module

Module defining plotting methods.

This module is a collection of different plotting functions that are regularly needed in development or research. The plots are made to be of publish quality.

TODO: Implement PGF or TikZ export options.

plenpy.utilities.plots.plot_fft(img, angle=False, shift=True, window=None, pad=None, implementation='scipy', interpolation=None, cmap='jet', vmin=1e-06, vmax=1, norm=True, rescale=True, plt_show=True)[source]

Utility function to plot the absolute value of the 2D fourier transform of an image.

Parameters

  • img (ndarray) – Input image.

  • angle – Boolean flag indicating whether to also, seperately, plot the angle part of FFT.

  • interpolation (Optional[str]) – Specify interpolation mode of the plotted image. Available interpolations are ‘bilinear’ and ‘bicubic’. If None, default to rc image.inerpolation of matplotlib (i.e., usually no interpolation).

  • cmap (str) – Color map used for plotting.

  • vmin (float) – Minimum value to plot.

  • vmax (Optional[float]) – Maximum value to plot.

  • norm (bool) – Whether to normalize the FFT by its size.

  • rescale (bool) – Specify whether to rescale the axis from pixel to frequency domain.

  • plt_show (bool) – Flag indicating whether to call matplotlib.pyplot.show() at the end.

For the remaining arguments, see plenpy.images.fourier().

Module contents

The utility package of plenpy.

The package provides several useful models which are needed throughout the plenpy package but can also come in handy in different projects.