Centroid Extraction

extract_centroids(image, sigma_threshold=5.0, min_pixels=3, max_pixels=10000, max_centroids=None, local_bg_block_size=64, max_elongation=3.0)

Extract star centroids from a 2D image array.

Parameters:

Name	Type	Description	Default
image	NDArray	2D numpy array (height x width) of pixel values. Supported dtypes: float64, float32, uint16, int16, uint8.	required
sigma_threshold	float	Detection threshold in sigma above background.	5.0
min_pixels	int	Minimum blob size in pixels.	3
max_pixels	int	Maximum blob size in pixels.	10000
max_centroids	Optional[int]	Maximum number of centroids to return. None = all.	None
local_bg_block_size	Optional[int]	Block size for local background estimation. None = global background only.	64
max_elongation	Optional[float]	Maximum blob elongation ratio. None = disabled.	3.0

Returns:

Type	Description
ExtractionResult	ExtractionResult with centroids and image statistics.

ExtractionResult

Result of centroid extraction from an image.

Returned by extract_centroids. Supports pickle serialization.

centroids property

List of detected centroids, sorted by brightness (brightest first).

image_width property

Width of the input image in pixels.

image_height property

Height of the input image in pixels.

background_mean property

Estimated background mean.

background_sigma property

Estimated background standard deviation.

threshold property

Detection threshold used.

num_blobs_raw property

Number of raw blobs before filtering.

Centroid

A detected star centroid with position, brightness, and shape.

Returned by extract_centroids. Centroids use pixel coordinates with the origin at the image center, +X right, +Y down. Supports pickle serialization.

x property

X position in pixels (origin at image center, +X right).

y property

Y position in pixels (origin at image center, +Y down).

brightness property

Integrated intensity above background.

cov property

2x2 intensity-weighted covariance matrix [[sigma_xx, sigma_xy], [sigma_xy, sigma_yy]] in pixels squared.

The eigenvalues give the squared semi-axes of the intensity profile, and the eigenvectors give the orientation.

__init__(x, y, brightness=None)

Create a new Centroid.

Parameters:

Name	Type	Description	Default
x	float	X position in pixels (origin at image center, +X right).	required
y	float	Y position in pixels (origin at image center, +Y down).	required
brightness	Optional[float]	Integrated intensity above background (optional).	None

with_offset(dx, dy)

Return a new Centroid with position shifted by (dx, dy).

Preserves brightness and covariance.

undistort(distortion)

Remove lens distortion from this centroid's position (distorted → ideal).

Returns a new Centroid at the corrected position. Brightness and covariance are preserved.

distort(distortion)

Apply lens distortion to this centroid's position (ideal → distorted).

Returns a new Centroid at the distorted position. Brightness and covariance are preserved.