slmsuite.holography.analysis.take

take(images, vectors, size, centered=True, integrate=False, clip=False, return_mask=False, plot=False, mp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/slmsuite/envs/latest/lib/python3.9/site-packages/numpy/__init__.py'>)[source]

Crop integration regions around an array of vectors, yielding an array of images.

Each integration region is a rectangle of the same size. Similar to but more general than numpy.take(). Useful for gathering data from spots in spot arrays. Operates with some speed due to the vectorized nature of implemented slicing.

Parameters

  • images (array_like) – 2D image or array of 2D images.

  • vectors (array_like of floats) – 2-vector (or 2-vector array). Location(s) of integration region anchor(s) in pixels, see centered. See format_2vectors().

  • size (int or (int, int)) – Size of the rectangular integration region in (w, h) format in pixels. If a scalar is given, assume square (w, w).

  • centered (bool) – Whether to center the integration region on the vectors. If False, vectors indicates the upper-left corner of the integration region. Defaults to True.

  • integrate (bool) – If True, the spatial dimension are integrated (summed), yielding a result of the same length as the number of vectors. Defaults to False.

  • clip (bool) – Whether to allow out-of-range integration regions. True allows regions outside the valid area, setting the invalid region to np.nan (or zero if the array datatype does not support np.nan). False throws an error upon out of range. Defaults to False.

  • return_mask (bool) – If True, returns a boolean mask corresponding to the regions which are taken from. Defaults to False. The average user will ignore this.

  • plot (bool) – Calls take_plot() to visualize the images regions.

  • mp (module) – If images are cupy objects, then cupy must be passed as mp. Very useful to minimize the cost of moving data between the GPU and CPU. Defaults to numpy. Indexing variables inside :meth:`take still use numpy for speed, no matter what module is used.

Returns

If integrate is False, returns an array containing the images cropped from the regions of size (image_count, h, w). If integrate is True, instead returns an array of floats of size (image_count,) where each float corresponds to the numpy.sum() of a cropped image. If mp is cupy, then a cupy.ndarray is returned.

Return type

numpy.ndarray OR cupy.ndarray