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:
data

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:
centroid`ndarray`

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 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)