sfn_correlator

giant.relative_opnav.estimators.sfn.sfn_correlators:

giant.relative_opnav.estimators.sfn.sfn_correlators.sfn_correlator(image, template, space_mask=None, intersects=None, search_dist=10, center_predicted=None)

This function performs normalized cross correlation in the spatial domain over a given search distance about a center between an image and a template using masks.

The correlation is performed by aligning the center of the template with various gridded points in the image centered on the predicted location of the center of the template in the image and extending to +/- search_dist in both the rows and columns. At each alignment, the Pearson Product moment correlation between the template and the overlaid portion of the image is computed and stored into a (2*search_dist+1, 2*search_dist+1) correlation surface. During the Pearson Product moment correlation computation, 2 masks are checked with a logical or to see if the pixel should be included in the computation. Anywhere that the template and the image do not overlap we also do not include in the computation of the Pearson Product moment correlation coefficient.

The first mask, space_mask should be the same size as the image and have a value of True for anywhere in the image that contains empty space, and a value of False for anywhere in the image that contains an extended body. The second mask, intersects should be the same size as the template and should have a value of True for anywhere in the template where a ray shot through the pixel intersected a surface and a value of False for anywhere in the template where no rays shot through the pixel intersected a surface. The purpose of these masks is to exclude regions of the template that were not rendered, since we normally render a few pixels around the edge of the template to ensure we capture all of it, while still including regions of the image which included empty space. This largely only affects templates that are very near the limb of the observed body.

For the correlation surface that is returned, the center pixel (np.array(surface.shape)//2) represents a shift of 0 from the predicted template center location in the image. Any location with a row/column less than the center pixel is a negative shift, a vice-versa for anywhere greater. Therefore, the shift from the nominal location can be notionally found using shift = np.unravel_index(surface.argmax(), surface.shape) - np.array(surface.shape)//2

Typically this function is only used by the SurfaceFeatureNavigation class. In fact, it should not be used as the correlator for most other classes, which assume the correlator does a global search instead of a local search.

We here provide an example

>>> import numpy as np
>>> from giant.relative_opnav.estimators.sfn.sfn_correlators import sfn_correlator
>>> example_image = np.random.randn(200, 200)
>>> example_template = example_image[30:60, 45:60]
>>> # set the intersect mask to just include part of the interior
>>> intersect_mask = np.zeros(example_template.shape, dtype=bool)
>>> intersect_mask[5:-5, 2:-3] = True
>>> set the space_mask to be all False
>>> space_mask = np.zeros(example_image.shape, dtype=bool)
>>> surface = sfn_correlator(example_image, example_template, space_mask=space_mask, intersects=intersect_mask,
...                          search_dist=20, center_predicted = [40, 35])
>>> shift = np.unravel_index(surface.argmax(), surface.shape) - np.array(surface.shape)//2
>>> # find the location of the template center in the image
>>> [35, 40] + shift
array([45, 52])
Parameters:

  • image (numpy.ndarray) – The image we are correlating with as a numpy array

  • template (numpy.ndarray) – The template we are trying to find in the image

  • space_mask (Optional[numpy.ndarray]) – A numpy boolean array specifying which portions of the image are space and thus should be included in computing the correlation score. If None then it is assumed to all be True

  • intersects (Optional[numpy.ndarray]) – A numpy boolean array specifying which portions of the template were actually intersected by rays and which were empty space. Only points intersected are included in the computation of the correlation score. If None then all points are considered.

  • search_dist (int) – The number of pixels around the predicted center of the template in the image to search.

  • center_predicted (Optional[numpy.ndarray]) – The predicted center of the template in the image. If None then it is assumed the center of the template is near the center of the image. Note that this is (x, y) or (col, row)

Returns:

A correlation surface of shape (search_dist*2+1, search_dist*2+1) as a numpy array with values between -1 and 1 where 1 indicates perfect positive correlation and -1 indicates perfect negative correlation. The center of the correlation surface corresponds to a shift of 0 between the expected template location and the found template location. Values past the center indicate a postive shift and values before the center indicate a negative shift

Return type:

numpy.ndarray