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, matched_filter_sigma=1.5, max_sharpness=0.9, saturation_level=None, deblend='off', border_margin=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
|
matched_filter_sigma
|
Optional[float]
|
Apply a Gaussian matched filter of this sigma (in pixels) before thresholding (~2x point-source SNR for a sigma~1.5 px PSF). Used only to form the detection mask, so photometry is unaffected, and the threshold is automatically scaled for the filtered noise level — no retuning needed. None = disabled. Default 1.5. |
1.5
|
max_sharpness
|
Optional[float]
|
Reject blobs whose peak sharpness
|
0.9
|
saturation_level
|
Optional[float]
|
Pixel value at or above which the sensor is saturated; such blobs skip sub-pixel peak refinement (a flat top has no meaningful maximum) and keep the center-of-mass position. None = disabled. |
None
|
deblend
|
str
|
Policy for blobs with more than one distinct intensity peak (blended pairs centroid to a wrong midpoint position). "off" keeps them merged; "reject" drops them — the safe choice for plate solving. Saturated blobs are exempt. |
'off'
|
border_margin
|
int
|
Drop blobs whose bounding box comes within this many pixels of an image edge (truncated PSFs bias the center-of-mass inward). |
0
|
Returns:
| Type | Description |
|---|---|
ExtractionResult
|
ExtractionResult with centroids and image statistics. |
extract_centroids_fast(image, sigma_threshold=5.0, bg_grid=64, min_pixels=2, max_centroids=None, max_sharpness=0.9, saturation_level=None, max_pixels=10000, max_elongation=None, border_margin=0)
¶
Fast single-pass centroid extraction — the "adequate star tracker" path.
Reads each pixel once (coarse-grid background + run-length connected-
component moments), so it is several times faster than
:func:extract_centroids — at the cost of faint-star sensitivity and
sub-pixel accuracy (~0.1 px on bright stars). Use :func:extract_centroids
for calibration or faint-star work. Returns the same ExtractionResult,
so it is a drop-in for solve_from_centroids.
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 noise sigmas above the local background. |
5.0
|
bg_grid
|
int
|
Coarse background-grid block size in pixels (tracks gradients such as vignetting / Milky Way). |
64
|
min_pixels
|
int
|
Minimum pixels in a region; rejects hot pixels. |
2
|
max_centroids
|
Optional[int]
|
Maximum number of centroids to return, brightest first. None = all. |
None
|
max_sharpness
|
Optional[float]
|
Reject regions whose peak sharpness
|
0.9
|
saturation_level
|
Optional[float]
|
Pixel value at or above which the sensor is saturated; such regions skip sub-pixel peak refinement and keep the center-of-mass position. None = disabled. |
None
|
max_pixels
|
int
|
Maximum region size in pixels — without it a satellite trail or horizon glow becomes the brightest centroid handed to the solver. |
10000
|
max_elongation
|
Optional[float]
|
Maximum elongation ratio (major/minor axis) from intensity-weighted second moments — rejects streaks too small for max_pixels. Off by default (noisy for few-pixel regions); enable (3.0-5.0) with min_pixels raised to ~5+. None = disabled. |
None
|
border_margin
|
int
|
Drop regions whose bounding box comes within this many pixels of an image edge (truncated PSFs bias the center-of-mass inward). |
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.
__new__(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.