centroid_quadratic

photutils.centroids.centroid_quadratic(data, xpeak=None, ypeak=None, fit_boxsize=5, search_boxsize=None, mask=None)[source]

Calculate the centroid of an n-dimensional array by fitting a 2D quadratic polynomial.

A second degree 2D polynomial is fit within a small region of the data defined by fit_boxsize to calculate the centroid position. The initial center of the fitting box can specified using the xpeak and ypeak keywords. If both xpeak and ypeak are None, then the box will be centered at the position of the maximum value in the input data.

If xpeak and ypeak are specified, the search_boxsize optional keyword can be used to further refine the initial center of the fitting box by searching for the position of the maximum pixel within a box of size search_boxsize.

Vakili & Hogg (2016) demonstrate that 2D quadratic centroiding comes very close to saturating the Cramér-Rao lower bound in a wide range of conditions.

Parameters:
data2D ndarray

The 2D image data. The image should be a background-subtracted cutout image containing a single source.

xpeak, ypeakfloat or None, optional

The initial guess of the position of the centroid. If either xpeak or ypeak is None then the position of the maximum value in the input data will be used as the initial guess.

fit_boxsizeint or tuple of int, optional

The size (in pixels) of the box used to define the fitting region. If fit_boxsize has two elements, they must be in (ny, nx) order. If fit_boxsize is a scalar then a square box of size fit_boxsize will be used. fit_boxsize must have odd values for both axes.

search_boxsizeint or tuple of int, optional

The size (in pixels) of the box used to search for the maximum pixel value if xpeak and ypeak are both specified. If fit_boxsize has two elements, they must be in (ny, nx) order. If search_boxsize is a scalar then a square box of size search_boxsize will be used. search_boxsize must have odd values for both axes. This parameter is ignored if either xpeak or ypeak is None. In that case, the entire array is searched for the maximum value.

maskbool ndarray, optional

A boolean mask, with the same shape as data, where a True value indicates the corresponding element of data is masked. Masked data are excluded from calculations.

Returns:
centroidndarray

The x, y coordinates of the centroid.

Notes

Use fit_boxsize = (3, 3) to match the work of Vakili & Hogg (2016) for their 2D second-order polynomial centroiding method.

Because this centroid is based on fitting data, it can fail for many reasons, returning (np.nan, np.nan):

  • quadratic fit failed

  • quadratic fit does not have a maximum

  • quadratic fit maximum falls outside image

  • not enough unmasked data points (6 are required)

Also note that a fit is not performed if the maximum data value is at the edge of the data. In this case, the position of the maximum pixel will be returned.

References

[1]

Vakili and Hogg 2016; arXiv:1610.05873 (https://arxiv.org/abs/1610.05873)