slmsuite.holography.analysis.image_moment#

image_moment(images, moment=(1, 0), centers=(0, 0), grid=None, normalize=True, nansum=False)[source]#

Computes the given moment \(M_{m_xm_y}\) for a stack of images. This involves discretely integrating each image against polynomial trial functions:

\[M_{m_xm_y} = \frac{ \int_{-w_x/2}^{+w_x/2} dx \, (x-c_x)^{m_x} \int_{-w_y/2}^{+w_y/2} dy \, (y-c_y)^{m_y} P(x, y) }{ \int_{-w_x/2}^{+w_x/2} dx \, \int_{-w_y/2}^{+w_y/2} dy \, P(x, y)},\]

where \(P(x, y)\) is a given 2D image of size \(w_x \times w_y\), and \((c_x, c_y)\) is a shift in the center of the trial functions.

Caution

This function does not check for or correct for negative values in images. Negative values may produce unusual results.

Warning

Higher order even moments (e.g. 2) will potentially yield unexpected results if the images are not background-subtracted. For instance, a calculation on an image with large background will yield the moment of the window, rather than say anything about the image. Consider using image_remove_field() to background-subtract.

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.

  • moment ((int, int)) –

    The moments in the \(x\) and \(y\) directions: \((m_x, m_y)\). For instance,

    • \(M_{m_xm_y} = M_{10}\) corresponds to the \(x\) moment or the position in the \(x\) dimension.

    • \(M_{m_xm_y} = M_{11}\) corresponds to \(xy\) shear.

    • \(M_{m_xm_y} = M_{02}\) corresponds to the \(y^2\) moment, or the variance (squared width for a Gaussian) in the \(y\) direction, given a zero or zeroed (via centers) \(M_{01}\) moment.

  • centers ((float, float) or array_like) – Perturbations to the center of the trial function, \((c_x, c_y)\). Of shape (2, image_count) if there is a custom center for each image.

  • 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. If the user pre-allocates and reuses these lists, this case has best performance.

    • Providing two full grids of shape (h, w), one for 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(). numpy.nansum() treats nan values as zeros. This is useful in the case where clip=True is passed to take() (out of range is set to nan).

Returns:

The moment \(M_{m_xm_y}\) evaluated for every image. This is of size (image_count,) for provided images data of shape (image_count, h, w).

Return type:

numpy.ndarray

On this page