PointOfInterestFinder

class giant.image_processing.point_source_finder.PointOfInterestFinder(options=None)

This class is responsible for finding and refining points of interest in an image.

It uses a combination of image flattening, thresholding, and point spread function fitting to identify and locate subpixel centers of points of interest.

The class is configured using the PointOfInterestFinderOptions, which allows for customization of various parameters such as the point spread function, image flattening options, centroid size, minimum and maximum blob size, threshold, and saturation rejection.

Key methods: - find_poi_in_roi: Identifies pixel-level centers of points of interest in a region of interest. - refine_locations: Estimates subpixel centers of blobs given pixel-level locations. - __call__: Combines find_poi_in_roi and refine_locations to identify subpixel locations of points of interest.

Parameters:

options (PointOfInterestFinderOptions | None) – The options configuring this class

static corners_to_roi(row_corners, column_corners)

This method provides a convenient way to convert a set of corners to a region of interest that can be passed to find_poi_in_roi() and locate_subpixel_poi_in_roi().

This method finds the minimum and maximum row and column from row_corners and column_corners, respectively, and then makes a call to meshgrid using these bounds, reversing the output so it is row, col instead of col, row.

The results from this function can be used to directly index into an image

>>> import numpy
>>> import giant.image_processing as gimp
>>> im = numpy.random.randn(500, 600)
>>> local_row_corners = [5.5, 3, 6.5, 8.9]
>>> local_column_corners = [4.3, 2.7, 3.3, 7.8]
>>> roi = im[gimp.ImageProcessing.corners_to_roi(local_row_corners, local_column_corners)]
>>> (roi == im[3:10, 2:9]).all()
True

Parameters:

• row_corners (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – a list of corner row locations

• column_corners (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – a list of corner column locations

Returns:

row, column subscripts into an image as a tuple of ndarrays of type int

Return type:

tuple[ndarray[tuple[Any, …], dtype[int64]], ndarray[tuple[Any, …], dtype[int64]]]

find_poi_in_roi(image, region=None)

This method identifies pixel level centers for all points of interest inside of some region of interest.

A point of interest is defined as any grouping of n pixels that are above threshold * standard_deviation where min_size <= n <= max_size. The standard_deviation is computed using the flatten_image_and_get_noise_level() method. Pixels are defined to be grouped if they are neighboring:

nnnnn
nyyyn
nyoyn
nyyyn
nnnnn

therefore any pixels labeled y are grouped with o whereas any pixels labeled n are not.

This method will ignore any blobs that contain saturated pixels if reject_saturation is set to True and the image object has an attribute saturation containing the saturation level for the image.

This method will also return the connected components stats (see OpenCV connectedComponentsWithStats for details) and the peak signal to noise ratio for each detection.

Parameters:

• image (ndarray) – The image being considered

• region (tuple[ndarray, ndarray] | None) – The region of the image to consider

Returns:

the pixel level locations of the points of interest in the region of interest (row, col), the connected component stats and the peak signal to noise ratio for each detection if return_stats is set to True.

Return type:

FindPPOIInROIOut

refine_locations(image, points_of_interest)

This method is used to estimate the subpixel centers of blobs in an image given the pixel level location of the blobs.

The method operates by performing a user specified centroiding algorithm on the image area surrounding the specified pixel level centers of the points of interest. The centroiding algorithm should typically be a subclass of PointSpreadFunction, however it can be any object with a fit method that inputs 3 array like parameters with the first two being pixel locations and the last being DN values and returns a object with a centroid attribute which provides the (x, y) location of the centroid. The centroiding algorithm is specified using the centroiding attribute. The size of the area considered in the centroiding algorithm can be specified in the centroid_size attribute.

This method returns both the subpixel centers of the points of interest as well as the illumination values of the pixels containing the subpixel centers of the points of interest. Optionally, stats about the blobs that the centroid was fit to and then full centroid fit can be returned if stats and snrs are not None and save_psf is set to True, respectively.

Note that if a centroid fit is unsuccessful then no information is returned for that point. Therefore the output arrays lengths will be less than or equal to the length of the input array.

This method is designed to be used in conjunction with the find_poi_in_roi() method; however, it can be used with any rough identification method so long as the input format is correct.

Parameters:

• image (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – The image to be processed

• points_of_interest (FindPPOIInROIOut) – The named tuple containing the pixel level information about the points of interest

Returns:

The subpixel centers of the points of interest (col, row), the intensity of the center of the pois, the fit PointSpreadFunction to the pois, the stats from the blobs containing the pois, and the peak SNR of the blobs containing the pois.

Return type:

POIFinderOut

Methods

find_poi_in_roi	This method identifies pixel level centers for all points of interest inside of some region of interest.
refine_locations	This method is used to estimate the subpixel centers of blobs in an image given the pixel level location of the blobs.
__call__	This method identifies the subpixel locations of points of interest in an image.
corners_to_roi	This method provides a convenient way to convert a set of corners to a region of interest that can be passed to find_poi_in_roi() and locate_subpixel_poi_in_roi().