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



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