SolverDatabase

SolverDatabase

A star pattern database for plate solving.

Generate from the Gaia or Hipparcos catalog, or load a previously saved database. Supports pickle serialization.

Example::

db = tetra3rs.SolverDatabase.generate_from_gaia()  # uses bundled gaia-catalog
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).

parameters property

Database generation parameters as a dict.

Returns the settings baked into this database when it was generated (stars per FOV, lattice field oversampling, pattern quantization, FOV range, magnitude limit, epochs). Read from the stored properties, so they reflect the actual database on disk -- not solve-time options.

generate_from_gaia(catalog_path=None, 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 a Gaia DR3 catalog file.

Accepts either: - A CSV file (.csv) with columns: source_id,ra,dec,phot_g_mean_mag,phot_bp_mean_mag,phot_rp_mean_mag,parallax,pmra,pmdec - A binary file (.bin) from the gaia-catalog package.

Use scripts/download_gaia_catalog.py to produce a merged Gaia + Hipparcos CSV, or pip install gaia-catalog for the pre-built binary catalog. Negative source_ids indicate Hipparcos gap-fill stars.

Parameters:

Name	Type	Description	Default
catalog_path	Optional[str]	Path to the Gaia catalog file (CSV or binary). If None, uses the bundled catalog from the gaia-catalog package.	None
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 (G-band). 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, camera_model=None, observer_velocity_km_s=None, attitude_hint=None, hint_uncertainty_deg=None, hint_uncertainty_rad=None, strict_hint=False)

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. Used (with the image dimensions) to build a pinhole camera model when camera_model is not given; ignored when it is — the model's focal length then defines the FOV estimate.	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. Values below the database's pattern quantization error are clamped up to it.	None
camera_model	Optional[CameraModel]	A CameraModel specifying focal length, image dimensions, optical center, distortion, and parity. When provided it is the single source of camera geometry (fov_estimate and image dimensions are ignored). None = simple pinhole model built from fov_estimate and the image dimensions.	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
attitude_hint	Optional[Union[list[float], NDArray[float64]]]	Optional attitude hint. Accepts either: a 4-element [w, x, y, z] quaternion (list or 1D ndarray), Hamilton / scalar-first convention — same as SolveResult.quaternion. This matches scipy.spatial.transform.Rotation.as_quat(scalar_first=True); it does not match scipy's default (scalar-last) ordering. a 3×3 rotation matrix (2D ndarray) — same as SolveResult.rotation_matrix_icrs_to_camera. Either form must rotate a vector from the ICRS frame into the camera frame. When provided, the solver skips the 4-star pattern-hash phase and instead projects nearby catalog stars via the hint, nearest-neighbor matches them to centroids, and runs the same verification + WCS refine path as lost-in-space. Typical use case: video-rate tracking where each frame's solve seeds the next. Succeeds with as few as 3 matched stars (vs. 4 for LIS). On failure, falls back to lost-in-space unless strict_hint=True.	None
hint_uncertainty_deg	Optional[float]	Angular uncertainty of the attitude hint, in degrees.	None
hint_uncertainty_rad	Optional[float]	Angular uncertainty of the attitude hint, in radians. At most one of the two may be provided; default 1° if neither is set. Used to size the catalog cone search and the initial pixel match radius. Ignored unless attitude_hint is set.	None
strict_hint	bool	If True, do not fall back to lost-in-space if the hinted solve fails. Default False. Ignored unless attitude_hint is set.	False

Returns:

Type	Description
Union[SolveResult, SolveFailure]	A SolveResult on success, or a (falsy) SolveFailure carrying the
Union[SolveResult, SolveFailure]	failure reason (status: 'no_match' / 'timeout' /
Union[SolveResult, SolveFailure]	'too_few') and solve_time_ms. Use if result: to
Union[SolveResult, SolveFailure]	distinguish the two.

print_parameters()

Print the database generation parameters to stdout.

Human-readable dump of the settings this database was built with -- stars per FOV, lattice field oversampling, pattern quantization, FOV range, magnitude limit, and epochs. See parameters for the same data as a dict.

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, model='polynomial', 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, distortion) by alternating per-image constrained WCS refinement with a global least-squares fit.

The distortion model is selected by model:

• "polynomial" (default) — SIP-like polynomial of the given order. Captures arbitrary 2D distortion including tangential and decentering terms; preferred for off-axis CCDs (e.g. TESS).
• "radial" — Brown-Conrady (k1, k2, k3). Three parameters total — well-conditioned with few matches and the standard model in computer-vision camera calibration. Assumes distortion is symmetric about the optical 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 (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
model	str	Distortion model — "polynomial" or "radial". Default "polynomial".	'polynomial'
order	int	Polynomial distortion order (2-6). Ignored unless model="polynomial". 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.