slmsuite.holography.analysis.image_moment

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

Computes the given moment \(M_{m_xm_y}\) for a stack of images. This involves 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+x_0, y+y_0) }{ \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, \((x_0, y_0)\) is the center of a window of size \(w_x \times w_y\), and \((c_x, c_y)\) is a shift in the center of the trial functions.

Warning

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 (tuple or numpy.ndarray) – Perturbations to the center of the trial function, \((c_x, c_y)\).

  • 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