SolverDatabase¶
SolverDatabase
¶
A star pattern database for plate solving.
Generate from the Hipparcos catalog, or load a previously saved database.
Supports pickle serialization.
Example::
db = tetra3rs.SolverDatabase.generate_from_hipparcos("data/hip2.dat")
db.save_to_file("my_db.bin")
db = tetra3rs.SolverDatabase.load_from_file("my_db.bin")
num_stars
property
¶
Number of stars in the catalog.
num_patterns
property
¶
Number of patterns in the database.
max_fov_deg
property
¶
Maximum FOV the database was built for (degrees).
min_fov_deg
property
¶
Minimum FOV the database was built for (degrees).
generate_from_hipparcos(catalog_path, max_fov_deg=30.0, min_fov_deg=None, star_max_magnitude=None, pattern_max_error=0.001, lattice_field_oversampling=100, patterns_per_lattice_field=50, verification_stars_per_fov=150, multiscale_step=1.5, epoch_proper_motion_year=2025.0, catalog_nside=16)
staticmethod
¶
Generate a database from the Hipparcos catalog file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
catalog_path
|
str
|
Path to the hip2.dat file. |
required |
max_fov_deg
|
float
|
Maximum field of view in degrees. |
30.0
|
min_fov_deg
|
Optional[float]
|
Minimum field of view in degrees. None means same as max_fov_deg (single-scale). |
None
|
star_max_magnitude
|
Optional[float]
|
Faintest star to include. None = auto. |
None
|
pattern_max_error
|
float
|
Maximum edge-ratio error. |
0.001
|
lattice_field_oversampling
|
int
|
Lattice field oversampling factor. |
100
|
patterns_per_lattice_field
|
int
|
Patterns per lattice field. |
50
|
verification_stars_per_fov
|
int
|
Verification stars per FOV. |
150
|
multiscale_step
|
float
|
Multiscale step factor. |
1.5
|
epoch_proper_motion_year
|
Optional[float]
|
Year for proper motion propagation. |
2025.0
|
catalog_nside
|
int
|
HEALPix nside for catalog spatial indexing. |
16
|
Returns:
| Type | Description |
|---|---|
SolverDatabase
|
A new SolverDatabase instance. |
save_to_file(path)
¶
Save the database to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Output file path. |
required |
load_from_file(path)
staticmethod
¶
Load a database from a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to a previously saved database file. |
required |
Returns:
| Type | Description |
|---|---|
SolverDatabase
|
A SolverDatabase loaded from disk. |
solve_from_centroids(centroids, fov_estimate_deg=None, fov_estimate_rad=None, image_width=None, image_height=None, image_shape=None, fov_max_error_deg=None, fov_max_error_rad=None, match_radius=0.01, match_threshold=1e-05, solve_timeout_ms=5000, match_max_error=None, refine_iterations=2, camera_model=None, observer_velocity_km_s=None)
¶
Solve for camera attitude given star centroids.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
centroids
|
Union[list[Centroid], NDArray[float64]]
|
Either a list of Centroid objects (from extract_centroids), or an Nx2/Nx3 numpy array of centroid positions in pixels. Columns are (x, y) or (x, y, brightness). Origin is at the image center, +X right, +Y down. |
required |
fov_estimate_deg
|
Optional[float]
|
Estimated horizontal field of view in degrees. |
None
|
fov_estimate_rad
|
Optional[float]
|
Estimated horizontal field of view in radians. Exactly one of fov_estimate_deg or fov_estimate_rad must be provided. |
None
|
image_width
|
Optional[int]
|
Image width in pixels. |
None
|
image_height
|
Optional[int]
|
Image height in pixels. |
None
|
image_shape
|
Optional[tuple[int, int]]
|
Image shape as (height, width) tuple (numpy convention). Can be used instead of image_width/image_height. |
None
|
fov_max_error_deg
|
Optional[float]
|
Maximum FOV error in degrees. None = no limit. |
None
|
fov_max_error_rad
|
Optional[float]
|
Maximum FOV error in radians. None = no limit. At most one of fov_max_error_deg or fov_max_error_rad can be provided. |
None
|
match_radius
|
float
|
Match distance as fraction of FOV. |
0.01
|
match_threshold
|
float
|
False-positive probability threshold. |
1e-05
|
solve_timeout_ms
|
Optional[int]
|
Timeout in milliseconds. None = no timeout. |
5000
|
match_max_error
|
Optional[float]
|
Maximum edge-ratio error. None = use database value. |
None
|
refine_iterations
|
int
|
Number of iterative SVD refinement passes. Each pass re-projects catalog stars and re-matches centroids using the refined rotation. Default 2. |
2
|
camera_model
|
Optional[CameraModel]
|
A CameraModel specifying optical center, distortion, and parity. None = simple pinhole model with no distortion. |
None
|
observer_velocity_km_s
|
Optional[list[float]]
|
Observer's barycentric velocity as [vx, vy, vz] in km/s (ICRS/GCRF frame). When set, catalog positions are aberration-corrected to apparent positions, removing the ~20" bias from Earth's orbital velocity. None = no correction (default). |
None
|
Returns:
| Type | Description |
|---|---|
Optional[SolveResult]
|
A SolveResult on success, or None if no match was found. |
get_star(index)
¶
Get a catalog star by its internal index (0-based, brightness order).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
index
|
int
|
Star index in [0, num_stars). |
required |
Returns:
| Type | Description |
|---|---|
CatalogStar
|
CatalogStar at that index. |
Raises:
| Type | Description |
|---|---|
IndexError
|
If index is out of range. |
get_star_by_id(catalog_id)
¶
Get a catalog star by its catalog ID (e.g. Hipparcos number).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
catalog_id
|
int
|
The catalog identifier to search for. |
required |
Returns:
| Type | Description |
|---|---|
Optional[CatalogStar]
|
CatalogStar with that ID, or None if not found. |
cone_search(ra_deg, dec_deg, radius_deg)
¶
Query catalog stars within an angular radius of a sky position.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ra_deg
|
float
|
Right ascension of cone center in degrees. |
required |
dec_deg
|
float
|
Declination of cone center in degrees. |
required |
radius_deg
|
float
|
Search radius in degrees. |
required |
Returns:
| Type | Description |
|---|---|
list[CatalogStar]
|
List of CatalogStar objects within the cone, sorted by brightness. |
calibrate_camera(solve_results, centroids, image_width=None, image_height=None, image_shape=None, order=4, max_iterations=10, sigma_clip=3.0, convergence_threshold_px=0.01)
¶
Calibrate a camera model from one or more plate-solve results.
Fits a global CameraModel (focal length, optical center, polynomial distortion) by alternating per-image constrained WCS refinement with a global linear least-squares fit. Distortion terms start at order 2 (SIP convention).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solve_results
|
Union[SolveResult, list[SolveResult]]
|
A SolveResult or list of SolveResult objects. |
required |
centroids
|
Union[list[Centroid], NDArray[float64], list[Union[list[Centroid], NDArray[float64]]]]
|
Matching centroids (list of Centroid lists, or single list). |
required |
image_width
|
Optional[int]
|
Image width in pixels. |
None
|
image_height
|
Optional[int]
|
Image height in pixels. |
None
|
image_shape
|
Optional[tuple[int, int]]
|
Image shape as (height, width) tuple (numpy convention). Can be used instead of image_width/image_height. |
None
|
order
|
int
|
Polynomial distortion order (2-6). Default 4. |
4
|
max_iterations
|
int
|
Maximum outer iterations. Default 10. |
10
|
sigma_clip
|
float
|
Sigma threshold for outlier rejection. Default 3.0. |
3.0
|
convergence_threshold_px
|
float
|
Stop when RMSE change < this (pixels). Default 0.01. |
0.01
|
Returns:
| Type | Description |
|---|---|
CalibrateResult
|
CalibrateResult with camera_model, rmse_before_px, rmse_after_px, |
CalibrateResult
|
n_inliers, n_outliers, and iterations. |
fit_radial_distortion(solve_results, centroids, image_width, sigma_clip=3.0, max_iterations=20, stage2_threshold_px=5.0)
¶
Fit a radial distortion model (k1, k2, k3) from solve results.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solve_results
|
Union[SolveResult, list[SolveResult]]
|
A SolveResult or list of SolveResult objects. |
required |
centroids
|
Union[list[Centroid], NDArray[float64], list[Union[list[Centroid], NDArray[float64]]]]
|
Matching centroids. |
required |
image_width
|
int
|
Image width in pixels. |
required |
sigma_clip
|
float
|
Sigma threshold for outlier rejection. |
3.0
|
max_iterations
|
int
|
Maximum sigma-clip iterations. |
20
|
stage2_threshold_px
|
Optional[float]
|
Loose pixel threshold for second-stage recovery. None to disable. |
5.0
|
Returns:
| Type | Description |
|---|---|
DistortionFitResult
|
DistortionFitResult with the fitted radial model and statistics. |
fit_polynomial_distortion(solve_results, centroids, image_width, order=4, sigma_clip=3.0, max_iterations=20, stage2_threshold_px=5.0)
¶
Fit a polynomial (SIP-like) distortion model from solve results.
This model captures arbitrary 2D distortion including radial, tangential, and cross-terms — suitable for wide-field cameras like TESS where the optical center is offset from the CCD center.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
solve_results
|
Union[SolveResult, list[SolveResult]]
|
A SolveResult or list of SolveResult objects. |
required |
centroids
|
Union[list[Centroid], NDArray[float64], list[Union[list[Centroid], NDArray[float64]]]]
|
Matching centroids. |
required |
image_width
|
int
|
Image width in pixels. |
required |
order
|
int
|
Polynomial order (2-6). Default 4. |
4
|
sigma_clip
|
float
|
Sigma threshold for outlier rejection. |
3.0
|
max_iterations
|
int
|
Maximum sigma-clip iterations. |
20
|
stage2_threshold_px
|
Optional[float]
|
Loose pixel threshold for second-stage recovery. None to disable. |
5.0
|
Returns:
| Type | Description |
|---|---|
DistortionFitResult
|
DistortionFitResult with the fitted polynomial model and statistics. |