tetra3 0.7.3

Rust implementation of Tetra3: Fast and robust star plate solver
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

//! Lens distortion models for correcting optical distortion in star images.
//!
//! Distortion is applied by **undistorting** observed centroid pixel coordinates
//! before they are converted to unit vectors for pattern matching and solving.
//! This means the distortion correction is applied once, up front, and benefits
//! the entire solver pipeline (pattern hashing, verification, and refinement).
//!
//! # Supported models
//!
//! - [`Distortion::Radial`] — classic radial distortion with up to 3 coefficients (k1, k2, k3)
//! - [`Distortion::Polynomial`] — SIP-like polynomial distortion with arbitrary cross-terms
//!
//! # Usage
//!
//! Distortion models can be:
//!
//! 1. **Provided** to the solver via [`SolveConfig::distortion`](crate::SolveConfig) if the
//!    distortion is already known (e.g. from a calibration procedure or FITS header).
//!
//! 2. **Fitted** from one or more solve results — either through
//!    [`calibrate_camera`] (which fits a SIP polynomial model and returns a
//!    fully-populated [`CameraModel`]) or directly via the internal radial
//!    fitter for the simpler `(k1, k2, k3)` model.
//!    Both fitters use iterative robust sigma-clipping to reject
//!    mismatched stars.

pub(crate) mod calibrate;
pub(crate) mod fit;
pub(crate) mod polynomial;
pub(crate) mod radial;

pub use calibrate::{calibrate_camera, CalibrateConfig, CalibrateResult, DistortionModelType};
pub use polynomial::{num_coeffs, PolynomialDistortion};
pub use radial::RadialDistortion;

/// Lens distortion model.
///
/// An enum-based distortion model that supports radial and polynomial
/// distortion correction. All coordinates are in pixels relative to
/// the optical center (typically the image center).
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, Default)]
pub enum Distortion {
    /// No distortion correction.
    #[default]
    None,
    /// Radial distortion: r_distorted = r × (1 + k1·r² + k2·r⁴ + k3·r⁶).
    Radial(RadialDistortion),
    /// SIP-like polynomial distortion with independent x,y correction terms.
    Polynomial(PolynomialDistortion),
}

impl Distortion {
    /// Convert observed (distorted) pixel coordinates to ideal (pinhole) coordinates.
    ///
    /// This is the primary operation used by the solver to correct centroids
    /// before computing unit vectors.
    pub fn undistort(&self, x: f64, y: f64) -> (f64, f64) {
        match self {
            Distortion::None => (x, y),
            Distortion::Radial(r) => r.undistort(x, y),
            Distortion::Polynomial(p) => p.undistort(x, y),
        }
    }

    /// Convert ideal (pinhole) pixel coordinates to observed (distorted) coordinates.
    ///
    /// This is the forward model: given where a star *should* appear in a perfect
    /// pinhole camera, compute where it actually appears due to lens distortion.
    pub fn distort(&self, x: f64, y: f64) -> (f64, f64) {
        match self {
            Distortion::None => (x, y),
            Distortion::Radial(r) => r.distort(x, y),
            Distortion::Polynomial(p) => p.distort(x, y),
        }
    }

    /// Returns `true` if this is `Distortion::None`.
    pub fn is_none(&self) -> bool {
        matches!(self, Distortion::None)
    }
}