pyepri.utils

This module contains simple and relatively standard functions, like operators usually involved in signal or image processing.

Functions

`grad1d`(u[, backend, notest])	Gradient (= forward finite differences) of a mono-dimensional array with Neumann boundary condition.
`div1d`(P[, backend, notest])	Discrete divergence of a mono-dimensional array (opposite adjoint of grad1d).
`compute_2d_gradient_masks`(mask[, backend, notest])	Compute 2D gradient masks from a 2D binary mask.
`grad2d`(u[, masks, backend, notest])	Gradient (= forward finite differences) of a 2-dimensional array with Neumann boundary condition.
`div2d`(P[, masks, backend, notest])	Discrete divergence of a 2D field vector (opposite adjoint of grad2d).
`compute_3d_gradient_masks`(mask[, backend, notest])	Compute 3D gradient masks from a 3D binary mask.
`grad3d`(u[, masks, backend, notest])	Gradient (= forward finite differences) of a 3-dimensional array with Neumann boundary condition.
`div3d`(P[, masks, backend, notest])	Discrete divergence of a 3D field vector (opposite adjoint of grad3d).
`powerit`(x0, A[, backend, tol, verbose, nitermax, notest])	Estimation of the largest eigen value of a symmetric linear
`otsu_threshold`(u[, bins])	Compute Otsu's threshold for a (N-D) signal.
`_relerr_`(u, v[, backend, nrm, notest])	Compute relative error between two arrays.
`_check_nd_inputs_`(ndims, backend[, u, P, mask, masks])	Factorized consistency checks for functions in the `pyepri.utils` submodule.

Module Contents

pyepri.utils.grad1d(u, backend=None, notest=False)[source]

Gradient (= forward finite differences) of a mono-dimensional array with Neumann boundary condition.

Parameters:

u (array_like (with type backend.cls)) – Mono-dimensional array.
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array u.
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

G – Output array same shape as u corresponding to the forward finite differences of u.

Return type:

array_like (with type backend.cls)

See also

div1d

pyepri.utils.div1d(P, backend=None, notest=False)[source]

Discrete divergence of a mono-dimensional array (opposite adjoint of grad1d).

Parameters:

P (array_like (with type backend.cls)) – Mono-dimensional input array.
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array P.
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

div – Mono-dimensional array with same shape as u corresponding to the discrete divergence (or opposite adjoint of the grad1d operator) of the input array P.

Return type:

array_like (with type backend.cls)

See also

grad1d

pyepri.utils.compute_2d_gradient_masks(mask, backend=None, notest=False)[source]

Compute 2D gradient masks from a 2D binary mask.

Parameters:

mask (array_like (with type backend.cls)) – A two-dimensional array (expected to contains booleans or values in [0, 1]).
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array mask.
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

masks – Output array with shape (2,) + mask.shape and same datatype as mask. This array is such that each masks[j] (for j=0 or j=1) takes the value True (or 1) at locations where the the j-th output of the grad2d() (evaluated on any signal u with same shape as mask) involves differences of two pixels both falling inside the input mask (meaning that mask is True (or 1) for those two pixels).

Return type:

array_like (with type backend.cls)

Note

When input mask is None, the output is also None.

pyepri.utils.grad2d(u, masks=None, backend=None, notest=False)[source]

Gradient (= forward finite differences) of a 2-dimensional array with Neumann boundary condition.

Parameters:

u (array_like (with type backend.cls)) – Two-dimensional array.
masks (array_like (with type backend.cls) or None, optional) – When given, the output array G is multiplied by masks on return.
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array u.
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

G – Output array with shape (2,) + u.shape such that G[j] correspond to the forward finite differences of u along its j-th dimension (for j in range(1)).

Return type:

array_like (with type backend.cls)

See also

div2d, compute_2d_gradient_masks

pyepri.utils.div2d(P, masks=None, backend=None, notest=False)[source]

Discrete divergence of a 2D field vector (opposite adjoint of grad2d).

Parameters:

P (array_like (with type backend.cls)) – Two-dimensional vector field array with shape (2, Ny, Nx).
masks (array_like (with type backend.cls) or None, optional) – When given, the divergence of masks * P is returned.
backend (<class 'pyepri.backends.Backend'>or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array P.
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

div – Two dimensional array with shape (Ny, Nx) corresponding to the discrete divergence (or opposite adjoint of the grad2d operator) of the input field vector array P.

Return type:

array_like (with type backend.cls)

See also

grad2d, compute_2d_gradient_masks

pyepri.utils.compute_3d_gradient_masks(mask, backend=None, notest=False)[source]

Compute 3D gradient masks from a 3D binary mask.

Parameters:

mask (array_like (with type backend.cls)) – A three-dimensional array (expected to contains booleans or values in [0, 1]).
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array mask.
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

masks – Output array with shape (3,) + mask.shape and same datatype as mask. This array is such that each masks[j] (for 0 <= j <= 2) takes the value True (or 1) at locations where the the j-th output of the grad3d() (evaluated on any signal u with same shape as mask) involves differences of two pixels both falling inside the input mask (meaning that mask is True (or 1) for those two pixels).

Return type:

array_like (with type backend.cls)

Note

When input mask is None, the output is also None.

pyepri.utils.grad3d(u, masks=None, backend=None, notest=False)[source]

Gradient (= forward finite differences) of a 3-dimensional array with Neumann boundary condition.

Parameters:

u (array_like (with type backend.cls)) – Three-dimensional array.
masks (array_like (with type backend.cls) or None, optional) – When given, the output array G is multiplied by masks on return.
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array u.
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

G – Output array with shape (3,) + u.shape such that G[j] correspond to the forward finite differences of u along its j-th dimension (for j in range(3)).

Return type:

array_like (with type backend.cls)

See also

div3d, compute_3d_gradient_masks

pyepri.utils.div3d(P, masks=None, backend=None, notest=False)[source]

Discrete divergence of a 3D field vector (opposite adjoint of grad3d).

Parameters:

P (array_like (with type backend.cls)) – Three-dimensional vector field array with shape (3, Ny, Nx, Nz).
masks (array_like (with type backend.cls) or None, optional) – When given, the divergence of masks * P is returned.
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array P.
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

div – Three dimensional array with shape (Ny, Nx, Nz) corresponding to the discrete divergence (or opposite adjoint of the grad3d operator) of the input field vector array P.

Return type:

array_like (with type backend.cls)

See also

grad3d, compute_3d_gradient_masks

pyepri.utils.powerit(x0, A, backend=None, tol=1e-07, verbose=False, nitermax=None, notest=False)[source]

Estimation of the largest eigen value of a symmetric linear operator using the power iteration method

Parameters:

x0 (array_like or sequence or array_like) – Initializer for the power iteration scheme
A (<class 'function'>) – Function with prototype y = A(x) corresponding to a symmetric linear operator
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input array x0.
tol (float, optional) – Tolerance parameter used to stop the power iteration scheme (see below)
verbose (boolean, optional) – Set verbose = True to display the current largest eigen value estimate at each iteration
nitermax (integer, optional) – Maximal number of iterations (setting nitermax to None is equivalent to setting nitermax equal to infinity)
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

x (array_like or sequence or array_like) – Output eigen vector estimate.
l (float) – Output estimate of the maximal eigen value of A.

pyepri.utils.otsu_threshold(u, bins=256)[source]

Compute Otsu’s threshold for a (N-D) signal.

This function computes the optimal threshold that maximizes the inter-class variance between background and foreground, following Otsu’s method. It works for arbitrary intensity ranges by using histogram bin centers instead of assuming 8-bit data.

Parameters:

u (np.ndarray) – Input N-D array. The function will flatten it to compute the histogram. Must contain numeric intensity values.
bins (int, optional) – Number of histogram bins. Default is 256. Increase this value if your data has a large dynamic range.

Returns:

The optimal threshold value according to Otsu’s criterion, based on the intensity distribution of the input volume.

Return type:

float

Notes

This implementation works for arbitrary intensity ranges (integer or floating-point).
The threshold corresponds to the histogram bin center that maximizes the inter-class variance.

Examples

>>> import numpy as np
>>> vol = np.random.rand(50, 50, 50)  # example data
>>> t = otsu_threshold(vol)
>>> print(t)

pyepri.utils._relerr_(u, v, backend=None, nrm=None, notest=False)[source]

Compute relative error between two arrays.

Parameters:

u (array_like (with type backend.cls)) – First input array.
v (array_like (with type backend.cls)) – Second input array.
backend (<class 'pyepri.backends.Backend'> or None, optional) –
A numpy, cupy or torch backend (see pyepri.backends module).

When backend is None, a default backend is inferred from the input arrays u and v.
nrm (float, optional) – A normalization factor to be applied to both input array (useful to avoid underflow or overflow issues in the computation of the relative error). If not given, nrm will be taken equal to one over the infinite norm of u, i.e., nrm = 1. / max(||u||_inf, ||v||_inf).
notest (bool, optional) – Set notest=True to disable consistency checks.

Returns:

rel – The relative error ||nrm * u - nrm * v|| / ||nrm * u|| (where ||.|| denotes the l2 norm), or 0 when u and v are full of 0.

Return type:

float

pyepri.utils._check_nd_inputs_(ndims, backend, u=None, P=None, mask=None, masks=None)[source]: Factorized consistency checks for functions in the pyepri.utils submodule.