Skip to main content

qualia_geospatial/
isogloss.rs

1//! Diachronic Isogloss Mapping & Geospatial Sonic Toponym Streamer.
2//!
3//! Projects dynamic linguistic variety boundaries (isoglosses) and acoustic wave-fields
4//! over 3D terrain geometry, linking oral mother-tongues, sacred liturgical chants,
5//! and cadastral toponyms to geodetic coordinates.
6
7use crate::frame::{GeodeticCoord, GeodeticFrame};
8pub use qualia_core_db::modalities::spatiotemporal_linguistics::{
9    SpatioTemporalLect, TimeFrequencyBox,
10};
11
12/// Diachronic Isogloss boundary representing the spatial and temporal distribution
13/// of a linguistic feature or lect variety over a geographical region.
14#[derive(Debug, Clone, PartialEq)]
15pub struct DiachronicIsogloss {
16    /// Lect variety identifier
17    pub lect_id_hash: u64,
18    /// Bounding polygon center coordinate in geodetic frame
19    pub center_coord: GeodeticCoord,
20    /// Spatial radius in meters from center where the feature is active
21    pub radius_m: f64,
22    /// Historical era start year (e.g. 1850.0)
23    pub era_start_year: f32,
24    /// Historical era end year (e.g. 1920.0)
25    pub era_end_year: f32,
26}
27
28impl DiachronicIsogloss {
29    pub fn new(
30        lect_id_hash: u64,
31        center_coord: GeodeticCoord,
32        radius_m: f64,
33        era_start_year: f32,
34        era_end_year: f32,
35    ) -> Self {
36        Self {
37            lect_id_hash,
38            center_coord,
39            radius_m,
40            era_start_year,
41            era_end_year,
42        }
43    }
44
45    /// Evaluates whether a target coordinate and timestamp fall within this isogloss.
46    pub fn contains_point(
47        &self,
48        coord: &GeodeticCoord,
49        year: f32,
50        frame: &GeodeticFrame,
51    ) -> bool {
52        if year < self.era_start_year || year > self.era_end_year {
53            return false;
54        }
55
56        let (x1_mm, y1_mm, _) = frame.project_to_local_mm(&self.center_coord);
57        let (x2_mm, y2_mm, _) = frame.project_to_local_mm(coord);
58
59        let dx_m = ((x2_mm - x1_mm) as f64) / 1000.0;
60        let dy_m = ((y2_mm - y1_mm) as f64) / 1000.0;
61        let dist_m = (dx_m * dx_m + dy_m * dy_m).sqrt();
62
63        dist_m <= self.radius_m
64    }
65
66    /// Evaluates acoustic prosody attenuation weight $w \in [0.0, 1.0]$ based on radial distance.
67    pub fn evaluate_attenuation_weight(
68        &self,
69        coord: &GeodeticCoord,
70        year: f32,
71        frame: &GeodeticFrame,
72    ) -> f64 {
73        if year < self.era_start_year || year > self.era_end_year {
74            return 0.0;
75        }
76
77        let (x1_mm, y1_mm, _) = frame.project_to_local_mm(&self.center_coord);
78        let (x2_mm, y2_mm, _) = frame.project_to_local_mm(coord);
79
80        let dx_m = ((x2_mm - x1_mm) as f64) / 1000.0;
81        let dy_m = ((y2_mm - y1_mm) as f64) / 1000.0;
82        let dist_m = (dx_m * dx_m + dy_m * dy_m).sqrt();
83
84        if dist_m >= self.radius_m {
85            0.0
86        } else {
87            // Smooth cosine bell falloff
88            let norm_dist = dist_m / self.radius_m;
89            0.5 * (1.0 + (norm_dist * std::f64::consts::PI).cos())
90        }
91    }
92}
93
94/// Geospatial Sonic Toponym Streamer binding raw physical acoustic wave-fields
95/// to 3D terrain coordinates, with terrain-aware acoustic propagation.
96#[derive(Debug, Clone, PartialEq)]
97pub struct SonicToponymStreamer {
98    /// Geodesic anchor coordinate of the sonic toponym / sacred site
99    pub site_coord: GeodeticCoord,
100    /// Time-frequency bounds of the acoustic recording
101    pub wave_bounds: TimeFrequencyBox,
102    /// Custodial Scope DID Hash
103    pub custodial_scope_id: u64,
104    /// Base sound pressure level in dB at 1 meter
105    pub base_spl_db: f32,
106}
107
108impl SonicToponymStreamer {
109    pub fn new(
110        site_coord: GeodeticCoord,
111        wave_bounds: TimeFrequencyBox,
112        custodial_scope_id: u64,
113        base_spl_db: f32,
114    ) -> Self {
115        Self {
116            site_coord,
117            wave_bounds,
118            custodial_scope_id,
119            base_spl_db,
120        }
121    }
122
123    /// Calculates acoustic attenuation in dB at a listener coordinate over terrain.
124    ///
125    /// Follows the inverse-square law: $L = L_0 - 20 \log_{10}(d)$ with elevation damping.
126    pub fn evaluate_listener_spl_db(
127        &self,
128        listener_coord: &GeodeticCoord,
129        frame: &GeodeticFrame,
130    ) -> f32 {
131        let (x1_mm, y1_mm, z1_mm) = frame.project_to_local_mm(&self.site_coord);
132        let (x2_mm, y2_mm, z2_mm) = frame.project_to_local_mm(listener_coord);
133
134        let dx_m = (x2_mm - x1_mm) as f64 / 1000.0;
135        let dy_m = (y2_mm - y1_mm) as f64 / 1000.0;
136        let dz_m = (z2_mm - z1_mm) as f64 / 1000.0;
137
138        let distance_m = (dx_m * dx_m + dy_m * dy_m + dz_m * dz_m).sqrt().max(1.0);
139        let attenuation_db = 20.0 * (distance_m as f32).log10();
140
141        (self.base_spl_db - attenuation_db).max(0.0)
142    }
143
144    /// Evaluates Doppler pitch shift factor $f' / f = 1 + v_r / c$ for a moving listener.
145    pub fn evaluate_doppler_factor(
146        &self,
147        listener_velocity_m_s: [f64; 3],
148        listener_coord: &GeodeticCoord,
149        frame: &GeodeticFrame,
150    ) -> f64 {
151        const SPEED_OF_SOUND_M_S: f64 = 343.0; // At ~20°C in air
152
153        let (x1_mm, y1_mm, z1_mm) = frame.project_to_local_mm(&self.site_coord);
154        let (x2_mm, y2_mm, z2_mm) = frame.project_to_local_mm(listener_coord);
155
156        let dx = (x1_mm - x2_mm) as f64 / 1000.0;
157        let dy = (y1_mm - y2_mm) as f64 / 1000.0;
158        let dz = (z1_mm - z2_mm) as f64 / 1000.0;
159        let dist = (dx * dx + dy * dy + dz * dz).sqrt().max(0.001);
160
161        // Unit vector pointing towards source
162        let dir = [dx / dist, dy / dist, dz / dist];
163
164        // Radial velocity towards source: v_r = v . dir
165        let v_radial = listener_velocity_m_s[0] * dir[0]
166            + listener_velocity_m_s[1] * dir[1]
167            + listener_velocity_m_s[2] * dir[2];
168
169        1.0 + (v_radial / SPEED_OF_SOUND_M_S)
170    }
171}
172