tetra3 0.9.0

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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

//! Types and helpers for working with Hipparcos catalog stars.
//!
//! This module contains the `HipparcosStar` representation, magnitude
//! conversion utilities, and helpers to load the Hipparcos catalog file
//! shipped with this crate.
//!
//! The Hipparcos catalog (new reduction, I/311) can be downloaded from
//! <http://cdsarc.u-strasbg.fr/ftp/I/311/hip2.dat.gz>.
//! The file `data/hip2.dat` in this crate is a copy of the catalog
//! as of 2025-11-15.

/// A star from the Hipparcos catalog.
///
/// Only the fields the solver consumes (position, proper motion, and the
/// magnitude/colour used for the Hp→V transform) are parsed and stored; the
/// catalog's per-field uncertainties, parallax, and V−I colour are skipped.
#[derive(Debug, Clone, PartialEq)]
pub struct HipparcosStar {
    pub hip: u32,
    pub ra_rad: f64,
    pub dec_rad: f64,
    pub pm_ra: f64,
    pub pm_dec: f64,
    pub hpmag: f32,
    pub b_v: f32,
}

impl HipparcosStar {
    /// Convert Hipparcos Hp magnitude and Johnson B−V colour
    /// to Johnson V using the standard 4th-order polynomial.
    ///
    /// Reference: ESA SP-1200, Volume 1, Table 1.3.5 (magnitude transformations).
    /// PDF mirror: https://www.cosmos.esa.int/documents/532822/552851/vol1_all.pdf
    ///
    /// Valid for roughly -0.2 < (B−V) < 1.8.
    pub fn hp_to_v(&self) -> f32 {
        let b = self.b_v;
        let delta = 0.304 * b - 0.202 * b * b + 0.107 * b * b * b - 0.045 * b * b * b * b;
        self.hpmag - delta
    }
}

/// Parse a single Hipparcos catalog record into a `HipparcosStar`.
fn parse_hipparcos_star(record: &str) -> Option<HipparcosStar> {
    // Highest column offset the parser reads is the B−V field ending at 158.
    if record.len() < 158 {
        return None;
    }

    Some(HipparcosStar {
        hip: record[0..6].trim().parse().ok()?,
        ra_rad: record[15..28].trim().parse().ok()?,
        dec_rad: record[29..42].trim().parse().ok()?,
        pm_ra: record[51..59].trim().parse().ok()?,
        pm_dec: record[60..68].trim().parse().ok()?,
        hpmag: record[129..136].trim().parse().ok()?,
        b_v: record[152..158].trim().parse().ok()?,
    })
}

/// Load the Hipparcos catalog from an in-memory string.
pub fn load_hipparcos_catalog(data: &str) -> Vec<HipparcosStar> {
    data.lines().filter_map(parse_hipparcos_star).collect()
}

pub fn load_hipparcos_catalog_from_file<P: AsRef<std::path::Path>>(
    path: P,
) -> crate::Result<Vec<HipparcosStar>> {
    let data = std::fs::read_to_string(path)?;
    let total_lines = data.lines().filter(|l| !l.trim().is_empty()).count();
    let stars = load_hipparcos_catalog(&data);
    // A wrong-format file parses to zero stars but would otherwise build a
    // useless (empty) database without any error; surface that here.
    if total_lines > 0 && stars.is_empty() {
        return Err(crate::error::Error::InvalidCatalog(format!(
            "Hipparcos catalog: parsed 0 stars from {total_lines} non-empty lines (wrong format?)"
        )));
    }
    let dropped = total_lines - stars.len();
    if dropped > 0 {
        tracing::warn!("Hipparcos catalog: skipped {dropped} unparseable line(s)");
    }
    Ok(stars)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    #[ignore]
    fn load_hipparcos_from_file() {
        let fname = "data/hip2.dat";
        let data = std::fs::read_to_string(fname).expect("Failed to read Hipparcos catalog file");
        let stars = load_hipparcos_catalog(&data);
        assert!(!stars.is_empty());
    }
}