Skip to main content

qualia_geospatial/raster_m64/
mod.rs

1//! Explicit developmental M64 georaster v3 producer and lossless source recovery.
2//! The legacy geotiff writer and M64_VERSION=2 remain unchanged.
3mod writer;
4use crate::{ElevationRaster, GeodeticFrame};
5use qualia_core_db::q42::m64_matter::{
6    M64GeoRasterError, M64GeoRasterMetadata, M64RasterEdges, M64RasterRows, M64RasterSample,
7    M64Reader,
8};
9use std::sync::atomic::{AtomicBool, Ordering};
10pub use writer::compile_raster_to_m64_v3;
11
12#[derive(Clone, Copy, Debug, PartialEq, Eq)]
13pub struct RasterM64Limits {
14    pub max_output_bytes: usize,
15    pub max_chunks: usize,
16    pub max_records: usize,
17}
18
19/// The two placement/padding decisions have no implicit defaults.
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub struct RasterM64Policy {
22    pub rows: M64RasterRows,
23    pub edges: M64RasterEdges,
24    /// None explicitly declares all samples valid; Some retains that sentinel.
25    pub nodata_sentinel_mm: Option<i32>,
26}
27
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub enum RasterM64Error {
30    Metadata(M64GeoRasterError),
31    DimensionMismatch,
32    OutputByteLimit,
33    ChunkLimit,
34    RecordLimit,
35    BufferTooSmall,
36    Cancelled,
37    UnsupportedEndian,
38    NotGeoRaster,
39}
40
41impl RasterM64Policy {
42    pub fn metadata(
43        &self,
44        raster: &ElevationRaster<'_>,
45        frame: &GeodeticFrame,
46    ) -> M64GeoRasterMetadata {
47        M64GeoRasterMetadata {
48            width: raster.width as u64,
49            height: raster.height as u64,
50            origin_lat_deg: frame.origin_lat_deg,
51            origin_lon_deg: frame.origin_lon_deg,
52            origin_elevation_mm: frame.origin_elevation_mm,
53            cell_size_mm: raster.cell_size_mm,
54            epoch_year: frame.epoch_year,
55            srid: frame.srid,
56            vertical_datum: frame.vertical_datum,
57            rows: self.rows,
58            edges: self.edges,
59            nodata_sentinel_mm: self.nodata_sentinel_mm,
60        }
61    }
62}
63
64/// Losslessly recover the original integer samples and exact frame declarations.
65/// Output capacity/cancellation are checked before mutation. Final bounded copy
66/// is non-interruptible; an arriving cancellation may complete successfully.
67pub fn decode_raster_from_m64_v3(
68    reader: &M64Reader<'_>,
69    cancelled: &AtomicBool,
70    out: &mut [i32],
71) -> Result<(usize, GeodeticFrame), RasterM64Error> {
72    let meta = reader.georaster().ok_or(RasterM64Error::NotGeoRaster)?;
73    let shape = meta.shape().map_err(RasterM64Error::Metadata)?;
74    let count = shape
75        .width
76        .checked_mul(shape.height)
77        .ok_or(RasterM64Error::DimensionMismatch)?;
78    if out.len() < count {
79        return Err(RasterM64Error::BufferTooSmall);
80    }
81    if cancelled.load(Ordering::Relaxed) {
82        return Err(RasterM64Error::Cancelled);
83    }
84    for (index, value) in out[..count].iter_mut().enumerate() {
85        // The immutable checked reader guarantees every source coordinate exists.
86        *value = match reader
87            .raster_sample(index % shape.width, index / shape.width)
88            .expect("checked v3 source extent")
89        {
90            M64RasterSample::ElevationMm(v) | M64RasterSample::Nodata(v) => v,
91        };
92    }
93    Ok((
94        count,
95        GeodeticFrame {
96            srid: meta.srid,
97            vertical_datum: meta.vertical_datum,
98            epoch_year: meta.epoch_year,
99            origin_lat_deg: meta.origin_lat_deg,
100            origin_lon_deg: meta.origin_lon_deg,
101            origin_elevation_mm: meta.origin_elevation_mm,
102        },
103    ))
104}