droplets.image_analysis module

Functions for analyzing phase field images of emulsions.

`locate_droplets`	Locates droplets in the phase field
`refine_droplets`	Refines many droplets by fitting to phase field
`refine_droplet`	Refines droplet parameters by fitting to phase field
`get_structure_factor`	Calculates the structure factor associated with a field
`get_length_scale`	Calculates a length scale associated with a phase field
`threshold_otsu`	Find the threshold value for a bimodal histogram using the Otsu method.

get_length_scale(scalar_field, method='structure_factor_maximum', **kwargs)[source]

Calculates a length scale associated with a phase field

Parameters:

scalar_field (ScalarField) – The scalar field to analyze
method (str) – A string determining which method is used to calculate the length scale. Valid options are structure_factor_maximum (numerically determine the maximum in the structure factor), structure_factor_mean (calculate the mean of the structure factor), and droplet_detection (determine the number of droplets and estimate average separation).

Return type:

float | tuple[float, Any]

Additional supported keyword arguments depend on the chosen method. For instance, the methods involving the structure factor allow for a boolean flag full_output, which also returns the actual structure factor. The method structure_factor_maximum also allows for some smoothing of the radially averaged structure factor. If the parameter smoothing is set to None the amount of smoothing is determined automatically from the typical discretization of the underlying grid. For the method droplet_detection, additional arguments are forwarded to locate_droplets().

Returns:

The determine length scale

Return type:

float

Parameters:

scalar_field (ScalarField) –
method (Literal['structure_factor_mean', 'structure_factor_maximum', 'droplet_detection']) –

See also

LengthScaleTracker: Tracker measuring length scales

get_structure_factor(scalar_field, smoothing='auto', wave_numbers='auto', add_zero=False)[source]

Calculates the structure factor associated with a field

Here, the structure factor is basically the power spectral density of the field scalar_field normalized so that re-gridding or rescaling the field does not change the result.

Parameters:

scalar_field (ScalarField) – The scalar_field being analyzed
smoothing (float, optional) – Length scale that determines the smoothing of the radially averaged structure factor. If omitted, the full data about the discretized structure factor is returned. The special value auto calculates a value automatically.
wave_numbers (list of floats, optional) – The magnitude of the wave vectors at which the structure factor is evaluated. This only applies when smoothing is used. If auto, the wave numbers are determined automatically.
add_zero (bool) – Determines whether the value at k=0 (defined to be 1) should also be returned.

Returns:

Two arrays giving the wave numbers and the associated structure factor. Wave numbers \(k\) are related to distances by \(2\pi/k\).

Return type:

(numpy.ndarray, numpy.ndarray)

locate_droplets(phase_field, threshold=0.5, *, minimal_radius=0, modes=0, interface_width=None, refine=False, refine_args=None, num_processes=1)[source]

Locates droplets in the phase field

This uses a binarized image to locate clusters of large concentration in the phase field, which are interpreted as droplets. Basic quantities, like position and size, are determined for these clusters.

Example

To determine the position, radius, and interfacial width of an arbitrary droplet, the following call can be used

emulsion = droplets.locate_droplets(
    field,
    threshold="auto",
    refine=True,
    refine_args={'vmin': None, 'vmax': None},
)

field is the scalar field, in which the droplets are located. The refine_args set flexibel boundaries for the intensities inside and outside the droplet.

Parameters:

phase_field (ScalarField) – Scalar field that describes the concentration field of droplets
threshold (float or str) –
The threshold for binarizing the image. If a value is given it is used directly. Otherwise, the following algorithms are supported:
- extrema: take mean between the minimum and the maximum of the data
- mean: take the mean over the entire data
- otsu: use Otsu’s method implemented in threshold_otsu()
The special value auto currently defaults to the extrema method.
minimal_radius (float) – The smallest radius of droplets to include in the list. This can be used to filter out fluctuations in noisy simulations.
modes (int) – The number of perturbation modes that should be included. If modes=0, droplets are assumed to be spherical. Note that the mode amplitudes are only determined when refine=True.
interface_width (float, optional) – Interface width of the located droplets, which is also used as a starting value for the fitting if droplets are refined.
refine (bool) – Flag determining whether the droplet properties should be refined using fitting. This is a potentially slow procedure.
refine_args (dict) – Additional keyword arguments passed on to refine_droplet(). Only has an effect if refine=True.
num_processes (int) – Number of processes used for the refinement. If set to “auto”, the number of processes is choosen automatically.

Returns:

All detected droplets

Return type:

Emulsion

refine_droplet(phase_field, droplet, *, vmin=0.0, vmax=1.0, adjust_values=False, tolerance=None, least_squares_params=None)[source]

Refines droplet parameters by fitting to phase field

This function varies droplet parameters, like position, size, interface width, and potential perturbation amplitudes until the overlap with the respective phase field region is maximized. Here, we use a constraint fitting routine.

Parameters:

phase_field (ScalarField) – Phase_field that is being used to refine the droplet
droplet (SphericalDroplet) – Droplet that should be refined. This could also be a subclass of SphericalDroplet
vmin (float) – The intensity value of the dilute phase surrounding the droplet. If None, the value will be determined automatically.
vmax (float) – The intensity value inside the droplet. If None, the value will be determined automatically.
adjust_value (bool) – Flag determining whether the intensity values will be included in the fitting procedure. The default value False implies that the intensity values are regarded fixed.
tolerance (float, optional) – Sets the three tolerance values ftol, xtol, and gtol of the scipy.optimize.least_squares(), unless they are specified in detail by the least_squares_params argument.
least_squares_params (dict) – Dictionary of parameters that influence the fitting; see the documentation of scipy.optimize.least_squares().
adjust_values (bool) –

Returns:

The refined droplet as an instance of the argument droplet

Return type:

DiffuseDroplet

threshold_otsu(data, nbins=256)[source]

Find the threshold value for a bimodal histogram using the Otsu method.

If you have a distribution that is bimodal, i.e., with two peaks and a valley between them, then you can use this to find the location of that valley, which splits the distribution into two.

Parameters:

data (ndarray) – The data to be analyzed
nbins (int) – The number of bins in the histogram, which defines the accuracy of the determined threshold.

Return type:

float

Modified from https://stackoverflow.com/a/71345917/932593, which is based on the the SciKit Image threshold_otsu implementation: https://github.com/scikit-image/scikit-image/blob/70fa904eee9ef370c824427798302551df57afa1/skimage/filters/thresholding.py#L312