Skip to main content

qualia_core_db/domains/geospatial/terrain/
terrain_primitives.rs

1// Copyright (c) EarthCraft contributors
2// Adapted under MIT License for QualiaDB.
3//! Geological landform primitives for procedural and geodetic terrain generation.
4//!
5//! Provides 14 morphological landform primitives surpassing traditional landscape
6//! generators with tectonic, karst, and glacial structures.
7//!
8//! Strictly adheres to Tier-1 `HotZeroHeap` (zero allocations in hot sampling loops).
9
10use std::f32::consts::PI;
11
12/// The 14 distinct geological landform primitive kinds.
13#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14pub enum LandformKind {
15    Mountain,
16    Volcano,
17    Caldera,
18    Canyon,
19    DuneSea,
20    FaultBlock,
21    Escarpment,
22    ImpactCrater,
23    Archipelago,
24    RidgeLine,
25    Plateau,
26    TiltedStrata,
27    KarstTower,
28    GlacialCirque,
29}
30
31/// Parameters controlling landform placement, scale, orientation, and morphological details.
32#[derive(Debug, Clone, Copy, PartialEq)]
33pub struct LandformParams {
34    pub kind: LandformKind,
35    pub center_x: f32,
36    pub center_y: f32,
37    pub radius: f32,
38    pub height: f32,
39    pub azimuth_rad: f32,
40    pub sharpness: f32,
41    pub roughness: f32,
42    pub secondary_ratio: f32,
43    pub seed: u64,
44}
45
46impl Default for LandformParams {
47    fn default() -> Self {
48        Self {
49            kind: LandformKind::Mountain,
50            center_x: 0.0, center_y: 0.0, radius: 1000.0, height: 500.0,
51            azimuth_rad: 0.0, sharpness: 1.0, roughness: 0.2, secondary_ratio: 0.5, seed: 42,
52        }
53    }
54}
55
56#[inline]
57fn hash2(ix: i32, iy: i32, seed: u64) -> f32 {
58    let mut h = seed ^ ((ix as u64).wrapping_mul(0x517c_c1b7_2722_0a95));
59    h ^= (iy as u64).wrapping_mul(0x6c62_272e_07bb_0142);
60    h ^= h >> 32;
61    h = h.wrapping_mul(0x2545_f491_4f6c_dd1d);
62    h ^= h >> 32;
63    ((h & 0x00ff_ffff) as f32) / 16777215.0
64}
65
66#[inline]
67fn val_noise(x: f32, y: f32, seed: u64) -> f32 {
68    let (ix, iy) = (x.floor() as i32, y.floor() as i32);
69    let (fx, fy) = (x - x.floor(), y - y.floor());
70    let wx = fx * fx * (3.0 - 2.0 * fx);
71    let wy = fy * fy * (3.0 - 2.0 * fy);
72    let (n00, n10) = (hash2(ix, iy, seed), hash2(ix + 1, iy, seed));
73    let (n01, n11) = (hash2(ix, iy + 1, seed), hash2(ix + 1, iy + 1, seed));
74    let nx0 = n00 + wx * (n10 - n00);
75    let nx1 = n01 + wx * (n11 - n01);
76    nx0 + wy * (nx1 - nx0)
77}
78
79#[inline]
80fn fbm2(x: f32, y: f32, seed: u64, octaves: u32) -> f32 {
81    let (mut amp, mut freq, mut total, mut max_amp) = (0.5f32, 1.0f32, 0.0f32, 0.0f32);
82    for o in 0..octaves {
83        total += amp * (val_noise(x * freq, y * freq, seed.wrapping_add(o as u64 * 31)) * 2.0 - 1.0);
84        max_amp += amp;
85        amp *= 0.5;
86        freq *= 2.0;
87    }
88    if max_amp > 0.0 { total / max_amp } else { 0.0 }
89}
90
91#[inline]
92fn smoothstep(edge0: f32, edge1: f32, x: f32) -> f32 {
93    let t = ((x - edge0) / (edge1 - edge0)).clamp(0.0, 1.0);
94    t * t * (3.0 - 2.0 * t)
95}
96
97/// Evaluates the elevation contribution of a geological landform at given world coordinates.
98///
99/// Fully adheres to Tier-1 `HotZeroHeap` (zero allocations, constant stack footprint).
100pub fn sample_landform(x: f32, y: f32, params: &LandformParams) -> f32 {
101    let (dx, dy) = (x - params.center_x, y - params.center_y);
102    let dist = (dx * dx + dy * dy).sqrt();
103    let rad = params.radius.max(1e-4);
104    let r = dist / rad;
105    if r >= 1.0 {
106        return 0.0;
107    }
108
109    let (sin_a, cos_a) = (params.azimuth_rad.sin(), params.azimuth_rad.cos());
110    let (u, v) = (dx * cos_a + dy * sin_a, -dx * sin_a + dy * cos_a);
111
112    match params.kind {
113        LandformKind::Mountain => {
114            let phi = dy.atan2(dx);
115            let cone = (1.0 - r).powf(1.0 + params.sharpness.clamp(0.1, 4.0));
116            let rib_angle = 5.0 * phi + fbm2(x * 0.005, y * 0.005, params.seed, 2) * 1.5;
117            let ribs = rib_angle.cos() * 0.5 + 0.5;
118            let rib_factor = 1.0 + 0.35 * ribs * (r * (1.0 - r) * 4.0);
119            let rough = params.roughness * fbm2(x / rad * 6.0, y / rad * 6.0, params.seed, 3) * cone;
120            params.height * (cone * rib_factor + rough).max(0.0)
121        }
122        LandformKind::Volcano => {
123            let flank = (1.0 - r).powf(2.0 + params.sharpness.clamp(0.1, 4.0));
124            let vent_r = 0.12;
125            let vent_factor = if r < vent_r { 0.65 + 0.35 * (r / vent_r).powi(2) } else { 1.0 };
126            let rough = params.roughness * 0.1 * fbm2(x / rad * 8.0, y / rad * 8.0, params.seed, 2) * flank;
127            params.height * (flank * vent_factor + rough).max(0.0)
128        }
129        LandformKind::Caldera => {
130            let rim_r = 0.45;
131            if r >= rim_r {
132                let flank_t = (1.0 - r) / (1.0 - rim_r);
133                let flank = flank_t.clamp(0.0, 1.0).powf(1.5 + params.sharpness * 0.5);
134                let rough = params.roughness * 0.1 * fbm2(x / rad * 6.0, y / rad * 6.0, params.seed, 2);
135                params.height * (flank + rough * flank).max(0.0)
136            } else {
137                let inner_t = r / rim_r;
138                let wall = smoothstep(0.7, 1.0, inner_t);
139                let floor = 0.3 + 0.7 * wall;
140                let dome_r = inner_t / 0.4;
141                let dome = if dome_r < 1.0 { params.secondary_ratio.clamp(0.0, 1.0) * 0.3 * (1.0 - dome_r * dome_r) } else { 0.0 };
142                params.height * (floor + dome)
143            }
144        }
145        LandformKind::Canyon => {
146            let meander = (u / (rad * 0.35)).sin() * (rad * 0.12);
147            let v_dist = (v - meander).abs();
148            let gorge_w = rad * 0.35;
149            let t = (v_dist / gorge_w).clamp(0.0, 1.0);
150            let step = (t * 4.0).floor();
151            let frac = (t * 4.0) - step;
152            let stepped = (step + smoothstep(0.35, 0.85, frac)) / 4.0;
153            let profile = if t < 0.2 { 0.0 } else { stepped };
154            let env = (1.0 - r * r).powi(2);
155            params.height * profile * env
156        }
157        LandformKind::DuneSea => {
158            let barchan = 0.15 * (v / (rad * 0.2)).sin() * rad;
159            let wavelength = rad * 0.2;
160            let phase = (((u - barchan) / wavelength).rem_euclid(1.0)).clamp(0.0, 1.0);
161            let dune_h = if phase < 0.75 {
162                (phase / 0.75).powf(1.3)
163            } else {
164                ((1.0 - phase) / 0.25).powf(3.0)
165            };
166            let skew = 0.1 * (phase * 2.0 * PI).sin();
167            let env = (1.0 - r * r).powi(2);
168            params.height * (dune_h + skew).clamp(0.0, 1.0) * env
169        }
170        LandformKind::FaultBlock => {
171            let env = (1.0 - r * r).powi(2);
172            let scarp_w = rad * 0.08;
173            let v_norm = v / rad;
174            let elev = if v >= 0.0 {
175                let tilt = (1.0 - v_norm * 0.5).clamp(0.4, 1.0);
176                0.85 * tilt
177            } else {
178                let roll = (-v_norm * 0.4).clamp(0.0, 0.3);
179                0.15 + roll
180            };
181            let scarp_factor = smoothstep(-scarp_w / rad, scarp_w / rad, v_norm);
182            let blended = 0.15 + (elev - 0.15) * scarp_factor;
183            params.height * blended * env
184        }
185        LandformKind::Escarpment => {
186            let env = (1.0 - r * r).powi(2);
187            let v_norm = v / rad;
188            let profile = if v_norm < 0.0 {
189                (1.0 + v_norm).clamp(0.0, 1.0).powf(1.0 + params.sharpness * 0.5)
190            } else {
191                let cliff_drop = (-v_norm / 0.15 * (2.0 + params.sharpness)).exp();
192                let talus = 0.35 * (1.0 - v_norm).clamp(0.0, 1.0).powi(2);
193                cliff_drop.max(talus)
194            };
195            params.height * profile * env
196        }
197        LandformKind::ImpactCrater => {
198            let rim_r = 0.45;
199            if r < rim_r {
200                let t = r / rim_r;
201                let floor = 0.15 + 0.75 * t * t;
202                let peak_r = t / 0.3;
203                let peak = if peak_r < 1.0 { params.secondary_ratio.clamp(0.0, 1.0) * 0.35 * (1.0 - peak_r * peak_r) } else { 0.0 };
204                params.height * (floor + peak)
205            } else {
206                let ejecta_t = (1.0 - r) / (1.0 - rim_r);
207                let ejecta = 0.90 * ejecta_t.clamp(0.0, 1.0).powf(2.0 + params.sharpness * 0.5);
208                params.height * ejecta
209            }
210        }
211        LandformKind::Archipelago => {
212            let arc_v = v - 0.2 * (u / rad).powi(2) * rad;
213            let mut max_island = 0.0f32;
214            for k in 0..5 {
215                let frac = (k as f32 - 2.0) / 2.5;
216                let (iu, iv) = (frac * rad * 0.7, 0.0f32);
217                let (du, dv) = (u - iu, arc_v - iv);
218                let idist = (du * du + dv * dv).sqrt();
219                let irad = rad * (0.12 + 0.03 * ((k * 17) % 5) as f32);
220                if idist < irad {
221                    let it = idist / irad;
222                    let cone = (1.0 - it).powf(1.5 + params.sharpness * 0.5);
223                    let shelf = smoothstep(0.0, 0.2, 1.0 - it);
224                    let island = cone * shelf;
225                    if island > max_island {
226                        max_island = island;
227                    }
228                }
229            }
230            let env = (1.0 - r * r).powi(2);
231            params.height * max_island * env
232        }
233        LandformKind::RidgeLine => {
234            let meander = (u / (rad * 0.3)).sin() * (rad * 0.12);
235            let v_crest = (v - meander).abs();
236            let flank = (-v_crest / (rad * 0.2) * (1.5 + params.sharpness)).exp();
237            let cols = 0.8 + 0.2 * (u / (rad * 0.15)).cos();
238            let env = (1.0 - r * r).powi(2);
239            params.height * flank * cols * env
240        }
241        LandformKind::Plateau => {
242            let phi = dy.atan2(dx);
243            let canyons = 0.08 * (phi * 7.0 + params.seed as f32).cos();
244            let rim_r = (0.55 + canyons).clamp(0.3, 0.8);
245            let elev = if r < rim_r {
246                1.0
247            } else {
248                let cliff_t = (r - rim_r) / (1.0 - rim_r);
249                (1.0 - cliff_t).clamp(0.0, 1.0).powf(4.0 + params.sharpness * 2.0)
250            };
251            params.height * elev
252        }
253        LandformKind::TiltedStrata => {
254            let bed_spacing = rad * 0.2;
255            let bed_phase = ((v / bed_spacing).rem_euclid(1.0)).clamp(0.0, 1.0);
256            let cuesta = if bed_phase < 0.7 {
257                (bed_phase / 0.7).powf(1.0 + params.sharpness * 0.5)
258            } else {
259                ((1.0 - bed_phase) / 0.3).powf(2.0 + params.sharpness)
260            };
261            let diff_erosion = 0.85 + 0.15 * fbm2(u / rad * 4.0, 0.0, params.seed, 2);
262            let env = (1.0 - r * r).powi(2);
263            params.height * cuesta * diff_erosion * env
264        }
265        LandformKind::KarstTower => {
266            let mut max_tower = 0.0f32;
267            let offsets: [(f32, f32, f32); 7] = [
268                (0.0, 0.0, 1.0), (0.35, 0.25, 0.85), (-0.30, 0.32, 0.90), (-0.25, -0.35, 0.80),
269                (0.40, -0.22, 0.75), (0.15, 0.50, 0.70), (-0.45, -0.10, 0.65),
270            ];
271            for (ox, oy, h_scale) in offsets {
272                let (tx, ty) = (ox * rad * 0.8, oy * rad * 0.8);
273                let tdist = ((dx - tx).powi(2) + (dy - ty).powi(2)).sqrt();
274                let tower_r = rad * 0.09;
275                let tower = h_scale / (1.0 + (tdist / tower_r).powi(8));
276                if tower > max_tower {
277                    max_tower = tower;
278                }
279            }
280            let env = (1.0 - r * r).powi(2);
281            params.height * max_tower * env
282        }
283        LandformKind::GlacialCirque => {
284            let env = (1.0 - r * r).powi(2);
285            let headwall_r = ((u.min(0.0) * 1.4).powi(2) + v.powi(2)).sqrt() / rad;
286            let headwall = smoothstep(0.2, 0.65, headwall_r).powf(1.5 + params.sharpness * 0.5);
287            let tarn_dist = ((u + rad * 0.05).powi(2) + v.powi(2)).sqrt() / (rad * 0.3);
288            let tarn = (-tarn_dist * tarn_dist * 2.0).exp();
289            let lip_u = (u - rad * 0.35).abs() / (rad * 0.15);
290            let lip_v = v.abs() / (rad * 0.4);
291            let moraine_lip = if lip_u < 1.0 && lip_v < 1.0 { 0.35 * (1.0 - lip_u * lip_u) * (1.0 - lip_v * lip_v) } else { 0.0 };
292            let valley_open = if u > rad * 0.4 { ((u - rad * 0.4) / (rad * 0.6)).clamp(0.0, 1.0) * 0.2 } else { 0.0 };
293            let elev = (0.2 + 0.8 * headwall - 0.25 * tarn + moraine_lip - valley_open).clamp(0.0, 1.2);
294            params.height * elev * env
295        }
296    }
297}
298
299/// Evaluates a geological landform over a 2D regular grid into a caller-supplied slice.
300///
301/// Fully adheres to Tier-1 `HotZeroHeap` (zero allocations, caller provides buffer).
302pub fn generate_landform_grid_into(
303    width: usize,
304    height: usize,
305    domain_min: [f32; 2],
306    domain_max: [f32; 2],
307    params: &LandformParams,
308    out: &mut [f32],
309) -> Result<(), &'static str> {
310    if width == 0 || height == 0 {
311        return Err("Grid dimensions must be non-zero");
312    }
313    let total_cells = width.checked_mul(height).ok_or("Grid dimensions overflow")?;
314    if out.len() < total_cells {
315        return Err("Output buffer too small for grid dimensions");
316    }
317    let dx = if width > 1 { (domain_max[0] - domain_min[0]) / (width as f32 - 1.0) } else { 0.0 };
318    let dy = if height > 1 { (domain_max[1] - domain_min[1]) / (height as f32 - 1.0) } else { 0.0 };
319    for j in 0..height {
320        let y = domain_min[1] + j as f32 * dy;
321        let row_offset = j * width;
322        for i in 0..width {
323            let x = domain_min[0] + i as f32 * dx;
324            out[row_offset + i] = sample_landform(x, y, params);
325        }
326    }
327    Ok(())
328}
329
330#[cfg(test)]
331mod tests {
332    use super::*;
333
334    const ALL_KINDS: [LandformKind; 14] = [
335        LandformKind::Mountain, LandformKind::Volcano, LandformKind::Caldera, LandformKind::Canyon,
336        LandformKind::DuneSea, LandformKind::FaultBlock, LandformKind::Escarpment, LandformKind::ImpactCrater,
337        LandformKind::Archipelago, LandformKind::RidgeLine, LandformKind::Plateau, LandformKind::TiltedStrata,
338        LandformKind::KarstTower, LandformKind::GlacialCirque,
339    ];
340
341    #[test]
342    fn test_all_14_landforms_finite_and_far_field() {
343        for kind in ALL_KINDS {
344            let mut params = LandformParams::default();
345            params.kind = kind;
346            params.center_x = 100.0;
347            params.center_y = -50.0;
348            params.radius = 500.0;
349            params.height = 300.0;
350
351            let c = sample_landform(params.center_x, params.center_y, &params);
352            assert!(c.is_finite(), "{:?} center was not finite", kind);
353
354            let rim = sample_landform(params.center_x + params.radius * 0.45, params.center_y, &params);
355            assert!(rim.is_finite(), "{:?} rim was not finite", kind);
356
357            let far = sample_landform(params.center_x + params.radius * 2.0, params.center_y, &params);
358            assert!(far.is_finite(), "{:?} far-field was not finite", kind);
359            assert_eq!(far, 0.0, "{:?} far-field was not zero", kind);
360        }
361    }
362
363    #[test]
364    fn test_caldera_morphology_profile() {
365        let mut params = LandformParams::default();
366        params.kind = LandformKind::Caldera;
367        params.radius = 1000.0;
368        params.height = 800.0;
369        params.secondary_ratio = 0.4;
370
371        let center = sample_landform(0.0, 0.0, &params);
372        let rim = sample_landform(params.radius * 0.45, 0.0, &params);
373        assert!(rim > center, "Caldera rim ({}) should be higher than center depression ({})", rim, center);
374    }
375
376    #[test]
377    fn test_impact_crater_morphology_profile() {
378        let mut params = LandformParams::default();
379        params.kind = LandformKind::ImpactCrater;
380        params.radius = 1000.0;
381        params.height = 500.0;
382        params.secondary_ratio = 0.3;
383
384        let floor = sample_landform(params.radius * 0.2, 0.0, &params);
385        let rim = sample_landform(params.radius * 0.45, 0.0, &params);
386        assert!(rim > floor, "Impact crater rim ({}) should be higher than cavity floor ({})", rim, floor);
387    }
388
389    #[test]
390    fn test_fault_block_morphology_profile() {
391        let mut params = LandformParams::default();
392        params.kind = LandformKind::FaultBlock;
393        params.radius = 1000.0;
394        params.height = 400.0;
395        params.azimuth_rad = 0.0;
396
397        let footwall = sample_landform(0.0, params.radius * 0.2, &params);
398        let hanging_wall = sample_landform(0.0, -params.radius * 0.2, &params);
399        assert!(
400            footwall > hanging_wall,
401            "Fault block footwall ({}) should be higher than hanging wall ({})",
402            footwall, hanging_wall
403        );
404    }
405
406    #[test]
407    fn test_grid_generation_16x16_stack_buffer() {
408        let params = LandformParams::default();
409        let mut grid = [0.0f32; 256];
410        let res = generate_landform_grid_into(16, 16, [-500.0, -500.0], [500.0, 500.0], &params, &mut grid);
411        assert!(res.is_ok());
412
413        let mut has_positive = false;
414        for &val in grid.iter() {
415            assert!(val.is_finite());
416            if val > 0.0 {
417                has_positive = true;
418            }
419        }
420        assert!(has_positive, "Grid should contain positive landform heights");
421    }
422
423    #[test]
424    fn test_grid_generation_buffer_too_small() {
425        let params = LandformParams::default();
426        let mut small_buf = [0.0f32; 10];
427        let res = generate_landform_grid_into(4, 4, [-10.0, -10.0], [10.0, 10.0], &params, &mut small_buf);
428        assert!(res.is_err());
429    }
430}