Spitzer Documentation & Tools

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)


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]


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


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.


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: x-y covariance of input image (second cross-correlated moment of light).


The centroid position in units of pixels on the image is calculated using flux-weighted 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 sigma-clipped median is used for the background value.

The uncertainties and covariance for the centroid position are calculated from the supplied per-pixel uncertainty by propagating the per-pixel 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)


  • 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 intra-pixel 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.


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