box_centroider
Purpose:
Calculates centroids for a source using a simple 1st moment box centroider. Designed to work with IRAC bcds and uncertainty images. It should work with other data but has not been tested with such.
Date Contributed: 24 Feb 2021
System Requirements: IDL with Astro Lib
Information and Download
Download box_centroider.pro (12 KB)
Category
Photometry, Centering, Centroiding
Calling Sequence
IDL> box_centroider, input_image, sigma2, xmax, ymax, halfboxwidth, $
backboxwidth, boxborder, x0, y0, f0, b, xs, ys, fs, bs, $
c, cb, np, xfwhm, yfwhm, xys, xycov $
[, /TWOPASS] [, /MMM]
Inputs
INPUT_IMAGE:  2d float/double array containing input image. INPUT_IMAGE is presumed to be have bad pixels NaNed out 
SIGMA2:  2d float/double array containing estimate of square of per pixel
image uncertainty. Presumed to have the same number of elements as INPUT_IMAGE. If uncertainties are unavailable, an array of 1's produced using MAKE_ARRAY(SIZE=SIZE(INPUT_IMAGE),VALUE=1d) is sufficient. 
XMAX:  float/double scalar containing x position of peak pixel to
centroid around. Pixels are measured such that the bottom left of an image is defined to have coordinates [0.0,0.0] at its center. 
YMAX:  float/double scalar containing y position of peak pixel to
centroid around. 
HALFBOXWIDTH:  integer scalar, giving approximately 1/2 the size of the square centroiding box. The centroiding box size will be set to 2*HALFBOXWIDTH+1, ensuring an odd number of pixels so the aperture is centered exactly on the center of the peak pixel. 
BACKBOXWIDTH:  integer scalar, giving the width of the (square) annulus that measures the background. 
BOXBORDER:  integer scalar, giving the offset of the (square)background annulus in pixels from the box aperture. 
Optional Inputs
None.
Keyword Parameters
/TWOPASS:  if set run the centroider once to find the pixel that holds the centroid, then rerun using that pixel as the initial guess. It is recommended that you always use /TWOPASS. 
/MMM:  if set, then the backround estimate will be calculated using MMM.pro from the IDL Astronomy User's Library. 
Outputs
X0:  double scalar X position of calculated centroid. 
Y0:  double scalar Y position of calculated centroid. 
F0:  double scalar flux of source as summed in box after background removal. 
B:  double scalar background level. 
XS:  double scalar variance in X centroid position. 
YS:  double scalar variance in Y centroid position. 
FS:  double scalar variance in measured flux accounting for variance in background. 
BS:  double scalar variance in background. 
C:  fixed scalar number of good pixels in aperture. 
CB:  fixed scalar number of good pixels in background aperture. 
NP:  fixed scalar number of noise pixels. 
XFWHM:  full width at half maximum source size in X (second moment of light). 
YFWHM:  full width at half maximum source size in Y (second moment of light). 
XYS:  double scalar covariance in X wrt Y centroid position (and vice versa) (Propagated uncertainty). 
XYCOV:  xy covariance of input image (second crosscorrelated moment of light). 
Algorithm
The centroid position in units of pixels on the image is calculated
using fluxweighted 1st moments in x and y pixel position.
x0 = sum(I(i) * x(i)) / sum(I(i))
y0 = sum(I(i) * y(i)) / sum(I(i))
where the sum is conducted over all pixels i in the source aperture,
a square box of size 2*HALFBOXWIDTH+1 pixels centered on pixel (XMAX,YMAX).
Before calculating the moments, an estimate of the background is determined from a square background region which is a specified width
(BACKBOXWIDTH) and offset (BOXBORDER) from the source aperture used to
calculate the moments. By default, a sigmaclipped median is used for the
background value.
The uncertainties and covariance for the centroid position are calculated
from the supplied perpixel uncertainty by propagating the perpixel
uncertainties:
xs^2 = sum((x(i)x0)^2 * sigma(i)^2)
ys^2 = sum((y(i)y0)^2 * sigma(i)^2)
xycov = sum((x(i)x0) * (y(i)y0) * sigma(i)^2)
where the sums are again over all pixels i in the source aperture
Source FWHM is calculated from the 2nd moment of light:
xfwhm = 2.D * sqrt(2.D * alog(2.D)) *
[sum(x(i)x0)^2 * I(i)) / sum(I(i))]^0.5
yfwhm = 2.D * sqrt(2.D * alog(2.D)) *
[sum(y(i)y0)^2 * I(i)) / sum(I(i))]^0.5
and a measure of the size of the source in terms of noise pixels is
calculated:
noise pixels = sum(I(i))^2 / sum(I(i)^2)
Notes
 First moment centroiding provides a robust measurement of source position
for undersampled data where more complex models fail due to lack of
sampling or inadequate knowledge of the point response function.
 Any centroiding method does have inherent biases which should be
understood when interpreting the positions, particularly if the measured
flux depends on the location of the source relative to a pixel center
due to the effects of intrapixel gain variations.
 The flux returned by this program is a more crude estimate than achieved with
circular/elliptical aperture photometry that uses fractional pixels and is
only provided here for reference and sanity checking.
Example
Assuming you have an image IMG but no uncertainty, and that you think the source should be somewhere on pixel (15.0,15.0). A good set of aperture parameters for measuring a centroid on an IRAC PSF is HALFBOXWIDTH=3, BACKBOXWIDTH=6, and BOXBORDER=3.
IDL> box_centroider, IMG, MAKE_ARRAY(SIZE=size(IMG), VALUE=1d), 15.0, 15.0, 3, 6, 3, X0, Y0, /TWOPASS
For this example, the calculated centroid will be at (X0,Y0).
