slmsuite.holography.analysis.image_variances#

image_variances(images, centers=None, grid=None, normalize=True, nansum=False, exclude_shear=False)[source]#

Computes the three second order central moments, equivalent to variance, for a stack of images. Specifically, this function returns a stack of the moments \(M_{20}\) and \(M_{02}\), along with \(M_{11}\), which are the variance in the \(x\) and \(y\) directions, along with the so-called shear variance. Recall that variance defined as

\[(\Delta x)^2 = \left<(x - \left<x\right>)^2\right>.\]

This equation is made central by subtraction of \(\left<x\right>\). The user can of course use take_moment() directly to access the non-central moments; this function is a helper to access useful quantities for analysis of spot size and skewness.

Note

The moment \(M_{20} = (\Delta x)^2\) is the variance in the \(x\) direction, or the square of the standard deviation \(\Delta x\). The standard deviation \(\Delta x\) is equal to the \(1/e\) amplitude radius (\(1/e^2\) power radius) of a Gaussian beam.

Parameters:

  • images (numpy.ndarray) – A matrix in the style of the output of take(), with shape (image_count, h, w), where (h, w) is the width and height of the 2D images and image_count is the number of images. A single image is interpreted correctly as (1, h, w) even if (h, w) is passed.

  • centers (numpy.ndarray OR None) – If the user has already computed \(\left<x\right>\), for example via image_positions(), then this can be passed though centers. The default None computes centers internally.

  • grid (float OR (float, float) OR (array_like, array_like) OR None) –

    If None (the default), the moment is reported in pixels of the image. However, the user may specify other units:

    • Providing the scaling factor between pixels and the desired units as a float or an anisotropic (float, float). This corresponds to the pixel’s \(\Delta x\), \(\Delta y\).

    • Providing lists of length w and h as a tuple as the grid dimension.

    • Providing full grids of shape (w, h) in each direction. Note that this case is the most general, and can lead to a rotated grid if a transformed grid is provided.

  • normalize (bool) – Whether to normalize images. If False, normalization is assumed to have been precomputed.

  • nansum (bool) – Whether to use numpy.nansum() in place of numpy.sum().

  • exclude_shear (bool) – Whether to exclude calculation of the shear variance. The user can choose this for speed.

Returns:

Stack of \(M_{20}\), \(M_{02}\), and \(M_{11}\) in an array of shape (3, image_count). If exclude_shear, Stack of \(M_{20}\) and \(M_{02}\) in an array of shape (2, image_count).

Return type:

numpy.ndarray

On this page