Skip to main content

qualia_core_db/domains/geospatial/
environmental_raster.rs

1//! Continuous environmental raster and GeoTIFF conversion pipeline (§GAP-02).
2//!
3//! Provides continuous `f32` field handling for environmental layers (elevation,
4//! slope, canopy height, canopy cover, solar radiation, soil moisture, rainfall),
5//! derived raster calculations, bilinear spatial sampling, and serialisation into
6//! the `.10d` Field section (`FIEL`).
7
8use crate::container_10d::field_section::{
9    encode_field_section_with_rasters, ContinuousRasterField, FieldSectionError,
10};
11use crate::q_hash;
12
13/// Standard environmental raster layer identifiers and units.
14pub const ENV_ELEVATION_URI: &str = "qualia:env:elevation";
15pub const ENV_SLOPE_URI: &str = "qualia:env:slope";
16pub const ENV_CANOPY_HEIGHT_URI: &str = "qualia:env:canopy_height";
17pub const ENV_CANOPY_COVER_URI: &str = "qualia:env:canopy_cover";
18pub const ENV_SOLAR_RADIATION_URI: &str = "qualia:env:solar_radiation";
19pub const ENV_SOIL_MOISTURE_URI: &str = "qualia:env:soil_moisture";
20pub const ENV_RAINFALL_URI: &str = "qualia:env:rainfall";
21
22pub const UNIT_METER: &str = "qudt:Meter";
23pub const UNIT_DEGREE: &str = "qudt:Degree";
24pub const UNIT_PERCENT: &str = "qudt:Percent";
25pub const UNIT_WATT_PER_SQM: &str = "qudt:WattPerSquareMeter";
26pub const UNIT_MILLIMETER: &str = "qudt:MilliMeter";
27
28/// Continuous environmental raster layer representation.
29#[derive(Debug, Clone)]
30pub struct EnvironmentalRasterLayer<'a> {
31    pub name_uri: &'static str,
32    pub unit_uri: &'static str,
33    pub width: usize,
34    pub height: usize,
35    pub cell_size_m: f64,
36    pub bbox: (f64, f64, f64, f64), // west, south, east, north
37    pub samples: &'a [f32],
38}
39
40impl<'a> EnvironmentalRasterLayer<'a> {
41    /// Creates a default `EnvironmentalRasterLayer`.
42    pub fn new(
43        name_uri: &'static str,
44        unit_uri: &'static str,
45        width: usize,
46        height: usize,
47        cell_size_m: f64,
48        bbox: (f64, f64, f64, f64),
49        samples: &'a [f32],
50    ) -> Self {
51        assert_eq!(
52            samples.len(),
53            width * height,
54            "Raster samples length must equal width * height"
55        );
56        Self {
57            name_uri,
58            unit_uri,
59            width,
60            height,
61            cell_size_m,
62            bbox,
63            samples,
64        }
65    }
66
67    /// Sample the continuous field at normalised UV coordinates `[0.0, 1.0]` using bilinear interpolation.
68    #[inline]
69    pub fn sample_uv(&self, u: f32, v: f32) -> f32 {
70        sample_bilinear(self.samples, self.width, self.height, u, v)
71    }
72
73    /// Sample the continuous field at geodetic coordinates (lon, lat) within the layer's bbox.
74    pub fn sample_geo(&self, lon: f64, lat: f64) -> Option<f32> {
75        let (w, s, e, n) = self.bbox;
76        if lon < w || lon > e || lat < s || lat > n {
77            return None;
78        }
79        let u = ((lon - w) / (e - w)).clamp(0.0, 1.0) as f32;
80        let v = ((n - lat) / (n - s)).clamp(0.0, 1.0) as f32;
81        Some(self.sample_uv(u, v))
82    }
83}
84
85/// Bilinear interpolation of a continuous 2D scalar grid.
86/// Zero heap, hot path.
87pub fn sample_bilinear(grid: &[f32], width: usize, height: usize, u: f32, v: f32) -> f32 {
88    if width == 0 || height == 0 || grid.is_empty() {
89        return 0.0;
90    }
91    let u_clamped = u.clamp(0.0, 1.0);
92    let v_clamped = v.clamp(0.0, 1.0);
93
94    let fx = u_clamped * (width.saturating_sub(1) as f32);
95    let fy = v_clamped * (height.saturating_sub(1) as f32);
96
97    let x0 = fx.floor() as usize;
98    let y0 = fy.floor() as usize;
99    let x1 = (x0 + 1).min(width - 1);
100    let y1 = (y0 + 1).min(height - 1);
101
102    let wx = fx - x0 as f32;
103    let wy = fy - y0 as f32;
104
105    let v00 = grid[y0 * width + x0];
106    let v10 = grid[y0 * width + x1];
107    let v01 = grid[y1 * width + x0];
108    let v11 = grid[y1 * width + x1];
109
110    let top = v00 * (1.0 - wx) + v10 * wx;
111    let bot = v01 * (1.0 - wx) + v11 * wx;
112    top * (1.0 - wy) + bot * wy
113}
114
115/// Derives slope in degrees from an elevation heightfield using Horn's 3x3 finite-difference algorithm.
116/// Zero heap caller-buffered.
117pub fn derive_slope_horn(
118    elevation: &[f32],
119    width: usize,
120    height: usize,
121    cell_size_m: f64,
122    out: &mut [f32],
123) {
124    assert_eq!(elevation.len(), width * height);
125    assert_eq!(out.len(), width * height);
126    if width < 2 || height < 2 || cell_size_m <= 0.0 {
127        out.fill(0.0);
128        return;
129    }
130
131    let scale = (8.0 * cell_size_m) as f32;
132
133    for y in 0..height {
134        let ym = y.saturating_sub(1);
135        let yp = (y + 1).min(height - 1);
136
137        for x in 0..width {
138            let xm = x.saturating_sub(1);
139            let xp = (x + 1).min(width - 1);
140
141            let z_tl = elevation[ym * width + xm];
142            let z_tc = elevation[ym * width + x];
143            let z_tr = elevation[ym * width + xp];
144
145            let z_ml = elevation[y * width + xm];
146            let z_mr = elevation[y * width + xp];
147
148            let z_bl = elevation[yp * width + xm];
149            let z_bc = elevation[yp * width + x];
150            let z_br = elevation[yp * width + xp];
151
152            // Horizontal gradient dz/dx
153            let dz_dx = ((z_tr + 2.0 * z_mr + z_br) - (z_tl + 2.0 * z_ml + z_bl)) / scale;
154            // Vertical gradient dz/dy
155            let dz_dy = ((z_bl + 2.0 * z_bc + z_br) - (z_tl + 2.0 * z_tc + z_tr)) / scale;
156
157            let rise_run = (dz_dx * dz_dx + dz_dy * dz_dy).sqrt();
158            let slope_deg = rise_run.atan().to_degrees().clamp(0.0, 90.0);
159
160            out[y * width + x] = slope_deg;
161        }
162    }
163}
164
165/// Derives a local canopy cover percentage grid `[0.0, 100.0]` from canopy height values.
166/// Any pixel with height >= `min_height_m` is considered canopy.
167pub fn derive_canopy_cover_grid(
168    canopy_height: &[f32],
169    min_height_m: f32,
170    window_radius: usize,
171    width: usize,
172    height: usize,
173    out: &mut [f32],
174) {
175    assert_eq!(canopy_height.len(), width * height);
176    assert_eq!(out.len(), width * height);
177
178    for y in 0..height {
179        let y_min = y.saturating_sub(window_radius);
180        let y_max = (y + window_radius).min(height - 1);
181
182        for x in 0..width {
183            let x_min = x.saturating_sub(window_radius);
184            let x_max = (x + window_radius).min(width - 1);
185
186            let mut count = 0usize;
187            let mut canopy_count = 0usize;
188
189            for wy in y_min..=y_max {
190                for wx in x_min..=x_max {
191                    count += 1;
192                    if canopy_height[wy * width + wx] >= min_height_m {
193                        canopy_count += 1;
194                    }
195                }
196            }
197
198            let pct = if count > 0 {
199                (canopy_count as f32 / count as f32) * 100.0
200            } else {
201                0.0
202            };
203            out[y * width + x] = pct;
204        }
205    }
206}
207
208/// Error kinds for GeoTIFF parsing and decoding.
209#[derive(Debug, Clone, Copy, PartialEq, Eq)]
210pub enum GeoTiffError {
211    InvalidMagic,
212    UnsupportedEndian,
213    MalformedIfd,
214    UnsupportedCompression,
215    UnsupportedFormat,
216    BufferTooSmall,
217    TruncatedData,
218}
219
220/// Metadata and spatial bounds extracted from a GeoTIFF header.
221#[derive(Debug, Clone, Copy, PartialEq)]
222pub struct GeoTiffRasterInfo {
223    pub width: usize,
224    pub height: usize,
225    pub cell_size_m: f64,
226    pub bbox: (f64, f64, f64, f64), // west, south, east, north
227    pub sample_format: u16,         // 1 = UInt, 2 = Int, 3 = IEEE Float
228    pub bits_per_sample: u16,
229    pub sample_count: usize,
230}
231
232/// Zero-heap GeoTIFF raster decoder.
233///
234/// Decodes uncompressed (raw/strip) raster bands (Float32, Int16, or UInt16)
235/// into a caller-supplied `&mut [f32]` buffer, extracting spatial resolution,
236/// georeferenced bounding box (`ModelTiepointTag` + `ModelPixelScaleTag`),
237/// and dimensions.
238pub fn decode_geotiff_raster_into(
239    tiff_bytes: &[u8],
240    out: &mut [f32],
241) -> Result<GeoTiffRasterInfo, GeoTiffError> {
242    if tiff_bytes.len() < 8 {
243        return Err(GeoTiffError::TruncatedData);
244    }
245
246    let is_le = match &tiff_bytes[0..2] {
247        b"II" => true,
248        b"MM" => false,
249        _ => return Err(GeoTiffError::InvalidMagic),
250    };
251
252    if !is_le {
253        // Little-endian is the canonical Qualia standard
254        return Err(GeoTiffError::UnsupportedEndian);
255    }
256
257    let magic = u16::from_le_bytes(tiff_bytes[2..4].try_into().unwrap());
258    if magic != 42 {
259        return Err(GeoTiffError::InvalidMagic);
260    }
261
262    let ifd_offset = u32::from_le_bytes(tiff_bytes[4..8].try_into().unwrap()) as usize;
263    if ifd_offset + 2 > tiff_bytes.len() {
264        return Err(GeoTiffError::TruncatedData);
265    }
266
267    let num_entries =
268        u16::from_le_bytes(tiff_bytes[ifd_offset..ifd_offset + 2].try_into().unwrap()) as usize;
269    let entries_start = ifd_offset + 2;
270    let entries_end = entries_start + num_entries * 12;
271    if entries_end > tiff_bytes.len() {
272        return Err(GeoTiffError::MalformedIfd);
273    }
274
275    let mut width = 0usize;
276    let mut height = 0usize;
277    let mut bits_per_sample = 32u16;
278    let mut compression = 1u16; // 1 = None
279    let mut sample_format = 3u16; // default Float32
280    let mut strip_offsets_val = 0u32;
281    let mut strip_offsets_count = 0u32;
282    let mut _strip_byte_counts = 0u32;
283
284    let mut tiepoint_origin = (0.0f64, 0.0f64);
285    let mut pixel_scale = (1.0f64, 1.0f64);
286    let mut has_tiepoint = false;
287    let mut _has_scale = false;
288
289    for i in 0..num_entries {
290        let entry_off = entries_start + i * 12;
291        let tag = u16::from_le_bytes(tiff_bytes[entry_off..entry_off + 2].try_into().unwrap());
292        let field_type =
293            u16::from_le_bytes(tiff_bytes[entry_off + 2..entry_off + 4].try_into().unwrap());
294        let count =
295            u32::from_le_bytes(tiff_bytes[entry_off + 4..entry_off + 8].try_into().unwrap());
296        let val_or_off = u32::from_le_bytes(
297            tiff_bytes[entry_off + 8..entry_off + 12]
298                .try_into()
299                .unwrap(),
300        );
301
302        let read_u32 = || -> u32 {
303            if field_type == 3 {
304                // SHORT
305                val_or_off & 0xFFFF
306            } else {
307                val_or_off
308            }
309        };
310
311        match tag {
312            256 => width = read_u32() as usize,
313            257 => height = read_u32() as usize,
314            258 => bits_per_sample = read_u32() as u16,
315            259 => compression = read_u32() as u16,
316            273 => {
317                strip_offsets_val = val_or_off;
318                strip_offsets_count = count;
319            }
320            279 => _strip_byte_counts = read_u32(),
321            339 => sample_format = read_u32() as u16,
322            // ModelPixelScaleTag (33550)
323            33550 if field_type == 12 && count >= 2 => {
324                let off = val_or_off as usize;
325                if off + 16 <= tiff_bytes.len() {
326                    let sx = f64::from_le_bytes(tiff_bytes[off..off + 8].try_into().unwrap());
327                    let sy = f64::from_le_bytes(tiff_bytes[off + 8..off + 16].try_into().unwrap());
328                    pixel_scale = (sx, sy);
329                    _has_scale = true;
330                }
331            }
332            // ModelTiepointTag (33922) - typically 6 doubles: (I, J, K, X, Y, Z)
333            33922 if field_type == 12 && count >= 6 => {
334                let off = val_or_off as usize;
335                if off + 48 <= tiff_bytes.len() {
336                    let x = f64::from_le_bytes(tiff_bytes[off + 24..off + 32].try_into().unwrap());
337                    let y = f64::from_le_bytes(tiff_bytes[off + 32..off + 40].try_into().unwrap());
338                    tiepoint_origin = (x, y);
339                    has_tiepoint = true;
340                }
341            }
342            _ => {}
343        }
344    }
345
346    if width == 0 || height == 0 {
347        return Err(GeoTiffError::MalformedIfd);
348    }
349    if compression != 1 {
350        return Err(GeoTiffError::UnsupportedCompression);
351    }
352
353    let total_samples = width * height;
354    if out.len() < total_samples {
355        return Err(GeoTiffError::BufferTooSmall);
356    }
357
358    let data_offset = if strip_offsets_count == 1 {
359        strip_offsets_val as usize
360    } else {
361        // If multiple strips or offset points to array, read first offset
362        let off = strip_offsets_val as usize;
363        if off + 4 <= tiff_bytes.len() {
364            u32::from_le_bytes(tiff_bytes[off..off + 4].try_into().unwrap()) as usize
365        } else {
366            return Err(GeoTiffError::TruncatedData);
367        }
368    };
369
370    // Decode sample values
371    match (sample_format, bits_per_sample) {
372        (3, 32) => {
373            // IEEE Float32
374            let bytes_needed = total_samples * 4;
375            if data_offset + bytes_needed > tiff_bytes.len() {
376                return Err(GeoTiffError::TruncatedData);
377            }
378            for i in 0..total_samples {
379                let b_off = data_offset + i * 4;
380                out[i] = f32::from_le_bytes(tiff_bytes[b_off..b_off + 4].try_into().unwrap());
381            }
382        }
383        (1, 16) | (2, 16) => {
384            // 16-bit integer
385            let bytes_needed = total_samples * 2;
386            if data_offset + bytes_needed > tiff_bytes.len() {
387                return Err(GeoTiffError::TruncatedData);
388            }
389            for i in 0..total_samples {
390                let b_off = data_offset + i * 2;
391                let val = if sample_format == 1 {
392                    u16::from_le_bytes(tiff_bytes[b_off..b_off + 2].try_into().unwrap()) as f32
393                } else {
394                    i16::from_le_bytes(tiff_bytes[b_off..b_off + 2].try_into().unwrap()) as f32
395                };
396                out[i] = val;
397            }
398        }
399        _ => return Err(GeoTiffError::UnsupportedFormat),
400    }
401
402    // Compute bounding box
403    let (west, north) = if has_tiepoint {
404        tiepoint_origin
405    } else {
406        (0.0, (height as f64) * pixel_scale.1)
407    };
408    let east = west + (width as f64) * pixel_scale.0;
409    let south = north - (height as f64) * pixel_scale.1;
410    let bbox = (west, south, east, north);
411
412    let cell_size_m = pixel_scale.0;
413
414    Ok(GeoTiffRasterInfo {
415        width,
416        height,
417        cell_size_m,
418        bbox,
419        sample_format,
420        bits_per_sample,
421        sample_count: total_samples,
422    })
423}
424
425/// Compile a collection of environmental raster layers into `.10d` Field section bytes.
426pub fn compile_environmental_rasters_to_10d(
427    layers: &[EnvironmentalRasterLayer],
428    out: &mut [u8],
429) -> Result<usize, FieldSectionError> {
430    let mut fields = Vec::with_capacity(layers.len());
431    for l in layers {
432        fields.push(ContinuousRasterField {
433            name_hash: q_hash(l.name_uri),
434            unit_hash: q_hash(l.unit_uri),
435            width: l.width as u32,
436            height: l.height as u32,
437            samples: l.samples,
438        });
439    }
440
441    encode_field_section_with_rasters(&fields, out)
442}
443
444#[cfg(test)]
445mod tests {
446    use super::*;
447
448    #[test]
449    fn test_bilinear_interpolation() {
450        // 2x2 grid:
451        // 0.0  10.0
452        // 20.0 30.0
453        let grid = [0.0f32, 10.0, 20.0, 30.0];
454        assert_eq!(sample_bilinear(&grid, 2, 2, 0.0, 0.0), 0.0);
455        assert_eq!(sample_bilinear(&grid, 2, 2, 1.0, 0.0), 10.0);
456        assert_eq!(sample_bilinear(&grid, 2, 2, 0.0, 1.0), 20.0);
457        assert_eq!(sample_bilinear(&grid, 2, 2, 1.0, 1.0), 30.0);
458        assert_eq!(sample_bilinear(&grid, 2, 2, 0.5, 0.5), 15.0);
459    }
460
461    #[test]
462    fn test_derive_slope_flat_and_steep() {
463        let flat = [100.0f32; 9];
464        let mut slope = [0.0f32; 9];
465        derive_slope_horn(&flat, 3, 3, 10.0, &mut slope);
466        for &s in &slope {
467            assert!(s.abs() < 1e-4);
468        }
469
470        // 3x3 inclined ramp: elevation increases 10m per 10m cell horizontally
471        let ramp = [0.0f32, 10.0, 20.0, 0.0, 10.0, 20.0, 0.0, 10.0, 20.0];
472        let mut slope_ramp = [0.0f32; 9];
473        derive_slope_horn(&ramp, 3, 3, 10.0, &mut slope_ramp);
474        // Centre cell dz/dx = 1.0 -> 45 degrees slope
475        assert!((slope_ramp[4] - 45.0).abs() < 1.0);
476    }
477
478    #[test]
479    fn test_compile_environmental_rasters_to_10d() {
480        let elev = [100.0f32, 105.0, 110.0, 115.0];
481        let canopy = [2.0f32, 15.0, 18.0, 0.5];
482
483        let layers = [
484            EnvironmentalRasterLayer::new(
485                ENV_ELEVATION_URI,
486                UNIT_METER,
487                2,
488                2,
489                5.0,
490                (144.0, -37.0, 144.1, -36.9),
491                &elev,
492            ),
493            EnvironmentalRasterLayer::new(
494                ENV_CANOPY_HEIGHT_URI,
495                UNIT_METER,
496                2,
497                2,
498                5.0,
499                (144.0, -37.0, 144.1, -36.9),
500                &canopy,
501            ),
502        ];
503
504        let mut out = vec![0u8; 1024];
505        let written = compile_environmental_rasters_to_10d(&layers, &mut out).unwrap();
506        assert!(written > 0);
507    }
508
509    #[test]
510    fn test_decode_geotiff_raster_into() {
511        // Construct a synthetic 2x2 Float32 GeoTIFF in memory
512        let mut tiff = Vec::new();
513        // 1. Header (8 bytes)
514        tiff.extend_from_slice(b"II"); // Little endian
515        tiff.extend_from_slice(&42u16.to_le_bytes()); // Magic
516        tiff.extend_from_slice(&8u32.to_le_bytes()); // IFD offset at 8
517
518        // 2. IFD at offset 8: 7 entries
519        let entries_count = 7u16;
520        tiff.extend_from_slice(&entries_count.to_le_bytes());
521
522        let strip_data_offset = 120u32;
523
524        let mut push_entry = |tag: u16, ftype: u16, count: u32, val_or_off: u32| {
525            tiff.extend_from_slice(&tag.to_le_bytes());
526            tiff.extend_from_slice(&ftype.to_le_bytes());
527            tiff.extend_from_slice(&count.to_le_bytes());
528            tiff.extend_from_slice(&val_or_off.to_le_bytes());
529        };
530
531        push_entry(256, 4, 1, 2); // Width = 2
532        push_entry(257, 4, 1, 2); // Height = 2
533        push_entry(258, 3, 1, 32); // BitsPerSample = 32
534        push_entry(259, 3, 1, 1); // Compression = 1 (None)
535        push_entry(273, 4, 1, strip_data_offset); // StripOffsets
536        push_entry(279, 4, 1, 16); // StripByteCounts = 16 (4 * 4 bytes)
537        push_entry(339, 3, 1, 3); // SampleFormat = 3 (Float32)
538
539        tiff.extend_from_slice(&0u32.to_le_bytes()); // Next IFD = 0
540
541        // Pad up to strip_data_offset
542        while tiff.len() < strip_data_offset as usize {
543            tiff.push(0);
544        }
545
546        // Float samples: 10.5, 20.5, 30.5, 40.5
547        tiff.extend_from_slice(&10.5f32.to_le_bytes());
548        tiff.extend_from_slice(&20.5f32.to_le_bytes());
549        tiff.extend_from_slice(&30.5f32.to_le_bytes());
550        tiff.extend_from_slice(&40.5f32.to_le_bytes());
551
552        let mut out = [0.0f32; 4];
553        let info = decode_geotiff_raster_into(&tiff, &mut out).expect("should decode GeoTIFF");
554        assert_eq!(info.width, 2);
555        assert_eq!(info.height, 2);
556        assert_eq!(info.sample_count, 4);
557        assert_eq!(out, [10.5, 20.5, 30.5, 40.5]);
558    }
559}