Skip to main content

qualia_geospatial/
geotiff.rs

1//! Multi-Format DEM Ingestion & Chunking (GeoTIFF, Terrain-RGB, Terrarium).
2//!
3//! Converts raw floating-point elevation rasters or compressed 24-bit elevation tiles
4//! into cache-aligned $64 \times 64$ cell `.m64` strata chunks in row-major order,
5//! with a 2D Hilbert index recorded for each chunk.
6
7use super::frame::GeodeticFrame;
8use super::hilbert::xy_to_hilbert;
9use qualia_core_db::q42::m64_matter::{
10    M64ChunkDirectoryEntry, M64Header, M64StrataColumnRecord, M64_MAGIC, M64_MODE_STRATA,
11};
12
13pub const CHUNK_GRID_SIZE: usize = 64; // 64 x 64 cells per chunk
14pub const CHUNK_CELL_COUNT: usize = CHUNK_GRID_SIZE * CHUNK_GRID_SIZE; // 4096 cells
15
16/// Decodes Mapbox Terrain-RGB encoded pixel (R, G, B) into elevation in millimeters.
17///
18/// $h_{\text{meters}} = -10000.0 + (R \cdot 65536 + G \cdot 256 + B) \cdot 0.1$
19#[inline]
20pub fn decode_terrain_rgb_mm(r: u8, g: u8, b: u8) -> i32 {
21    let raw = ((r as u32) << 16) | ((g as u32) << 8) | (b as u32);
22    let meters = -10000.0 + (raw as f64) * 0.1;
23    (meters * 1000.0).round() as i32
24}
25
26/// Encodes elevation in millimeters into Mapbox Terrain-RGB (R, G, B).
27#[inline]
28pub fn encode_terrain_rgb(elevation_mm: i32) -> [u8; 3] {
29    let meters = (elevation_mm as f64) / 1000.0;
30    let raw = (((meters + 10000.0) * 10.0).round().max(0.0) as u32) & 0x00FF_FFFF;
31    [
32        ((raw >> 16) & 0xFF) as u8,
33        ((raw >> 8) & 0xFF) as u8,
34        (raw & 0xFF) as u8,
35    ]
36}
37
38/// Decodes Mapzen Terrarium encoded pixel (R, G, B) into elevation in millimeters.
39///
40/// $h_{\text{meters}} = (R \cdot 256 + G + B / 256.0) - 32768.0$
41#[inline]
42pub fn decode_terrarium_mm(r: u8, g: u8, b: u8) -> i32 {
43    let meters = (r as f64) * 256.0 + (g as f64) + ((b as f64) / 256.0) - 32768.0;
44    (meters * 1000.0).round() as i32
45}
46
47/// Codec identifiers for .m64 spatial chunks (stored in `compression_flags`).
48/// The raster producer currently implements only `UncompressedMmap`; all other
49/// identifiers fail before output mutation rather than mislabelling raw bytes.
50#[repr(u8)]
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub enum CompressionCodec {
53    /// 0: Uncompressed raw zero-copy direct mmap.
54    UncompressedMmap = 0,
55    /// 1: LZ4 block compression.
56    Lz4 = 1,
57    /// 2: Bao verified BLAKE3 outboard chunk tree.
58    BaoTree = 2,
59    /// 3: HTJ2K / Wavelet multiresolution progressive (JPEG 2000 Part 15 / ISO/IEC 15444-15).
60    Htj2kWavelet = 3,
61    /// 4: Packed 24-bit Mapbox Terrain-RGB PNG tile pyramid.
62    TerrainRgbPng = 4,
63    /// 5: Packed 24-bit Mapzen Terrarium PNG tile pyramid.
64    TerrariumPng = 5,
65    /// 6: Hardware-accelerated AV1 / HEVC all-intra video decode for visual drape.
66    Av1IntraDrape = 6,
67}
68
69impl Default for CompressionCodec {
70    fn default() -> Self {
71        Self::UncompressedMmap
72    }
73}
74
75/// Raw raster elevation grid descriptor.
76pub struct ElevationRaster<'a> {
77    pub width: usize,
78    pub height: usize,
79    pub cell_size_mm: u32, // e.g. 30,000 for 30m DEM
80    pub elevations_mm: &'a [i32],
81}
82
83/// Errors during raster ingestion and compilation.
84#[derive(Debug, Clone, PartialEq, Eq)]
85pub enum IngestionError {
86    DimensionMismatch,
87    BufferTooSmall,
88    InvalidChunkCount,
89    UnsupportedCompression(CompressionCodec),
90    SizeOverflow,
91    UnsupportedEndian,
92}
93
94/// Partitions a DEM raster into $64 \times 64$ `.m64` strata chunks in row-major
95/// order, retaining a Hilbert index in each directory entry.
96///
97/// Writes the complete `.m64` container bytes (Header + Directory + Records) into `out`.
98pub fn compile_raster_to_m64(
99    raster: &ElevationRaster,
100    frame: &GeodeticFrame,
101    lut_bank_epoch: u16,
102    out: &mut [u8],
103) -> Result<usize, IngestionError> {
104    compile_raster_to_m64_with_codec(raster, frame, lut_bank_epoch, CompressionCodec::UncompressedMmap, out)
105}
106
107/// Partitions a DEM raster into $64 \times 64$ `.m64` strata chunks with an explicit compression codec.
108pub fn compile_raster_to_m64_with_codec(
109    raster: &ElevationRaster,
110    frame: &GeodeticFrame,
111    lut_bank_epoch: u16,
112    codec: CompressionCodec,
113    out: &mut [u8],
114) -> Result<usize, IngestionError> {
115    if codec != CompressionCodec::UncompressedMmap {
116        return Err(IngestionError::UnsupportedCompression(codec));
117    }
118    if !cfg!(target_endian = "little") {
119        return Err(IngestionError::UnsupportedEndian);
120    }
121    if raster.width == 0 || raster.height == 0
122        || raster.width.checked_mul(raster.height) != Some(raster.elevations_mm.len()) {
123        return Err(IngestionError::DimensionMismatch);
124    }
125
126    let chunks_x = raster.width / CHUNK_GRID_SIZE + usize::from(raster.width % CHUNK_GRID_SIZE != 0);
127    let chunks_y = raster.height / CHUNK_GRID_SIZE + usize::from(raster.height % CHUNK_GRID_SIZE != 0);
128    let total_chunks = chunks_x.checked_mul(chunks_y).ok_or(IngestionError::SizeOverflow)?;
129
130    let header_size = std::mem::size_of::<M64Header>();
131    let dir_entry_size = std::mem::size_of::<M64ChunkDirectoryEntry>();
132    let record_size = std::mem::size_of::<M64StrataColumnRecord>();
133    let chunk_payload_size = CHUNK_CELL_COUNT * record_size;
134
135    let required_len = total_chunks.checked_mul(dir_entry_size + chunk_payload_size)
136        .and_then(|size| header_size.checked_add(size)).ok_or(IngestionError::SizeOverflow)?;
137    if out.len() < required_len {
138        return Err(IngestionError::BufferTooSmall);
139    }
140
141    // 1. Build Header
142    let mut header = M64Header {
143        magic: M64_MAGIC,
144        version: 1,
145        header_size: header_size as u64,
146        total_file_size: required_len as u64,
147        spatial_origin: [frame.origin_lat_deg as f32, frame.origin_lon_deg as f32],
148        elevation_datum: [frame.origin_elevation_mm as f32 / 1000.0, 1.0],
149        chunk_table_offset: header_size as u64,
150        chunk_count: total_chunks as u64,
151        header_crc32c: 0,
152        container_flags: 0,
153    };
154    header.update_crc();
155
156    out[..header_size].copy_from_slice(bytemuck::bytes_of(&header));
157
158    let dir_offset = header_size;
159    let mut payload_offset = dir_offset + total_chunks * dir_entry_size;
160
161    // 2. Emit row-major chunks with Hilbert keys; no sorting is performed.
162    for cy in 0..chunks_y {
163        for cx in 0..chunks_x {
164            let chunk_idx = cy * chunks_x + cx;
165            let hilbert_idx = xy_to_hilbert(cx as u32, cy as u32, 16);
166
167            let mut dir_entry = M64ChunkDirectoryEntry {
168                chunk_uuid: [0; 16],
169                spatial_hilbert_index: hilbert_idx,
170                byte_offset: payload_offset as u64,
171                byte_length: chunk_payload_size as u32,
172                record_count: CHUNK_CELL_COUNT as u32,
173                srid_geodetic_code: frame.srid,
174                lut_bank_epoch_id: lut_bank_epoch,
175                chunk_record_mode: M64_MODE_STRATA,
176                compression_flags: codec as u8,
177                bao_root_hash_prefix: [0; 12],
178                entry_crc32c: 0,
179            };
180
181            // Derive deterministic UUID from hilbert index
182            let h_bytes = hilbert_idx.to_le_bytes();
183            dir_entry.chunk_uuid[..8].copy_from_slice(&h_bytes);
184            dir_entry.chunk_uuid[8..16].copy_from_slice(&h_bytes);
185            dir_entry.update_crc();
186
187            // Write directory entry
188            let entry_dest = dir_offset + chunk_idx * dir_entry_size;
189            out[entry_dest..entry_dest + dir_entry_size].copy_from_slice(bytemuck::bytes_of(&dir_entry));
190
191            // 3. Write 4096 strata column records for this chunk
192            for local_y in 0..CHUNK_GRID_SIZE {
193                for local_x in 0..CHUNK_GRID_SIZE {
194                    let rx = (cx * CHUNK_GRID_SIZE + local_x).min(raster.width - 1);
195                    let ry = (cy * CHUNK_GRID_SIZE + local_y).min(raster.height - 1);
196                    let elev_mm = raster.elevations_mm[ry * raster.width + rx];
197
198                    let mut record = M64StrataColumnRecord::default();
199                    record.surface_elevation_mm = elev_mm;
200                    record.update_crc();
201
202                    let rec_dest = payload_offset + (local_y * CHUNK_GRID_SIZE + local_x) * record_size;
203                    out[rec_dest..rec_dest + record_size].copy_from_slice(bytemuck::bytes_of(&record));
204                }
205            }
206
207            payload_offset += chunk_payload_size;
208        }
209    }
210
211    Ok(required_len)
212}
213
214/// Cloud-Optimised GeoTIFF (COG) Image File Directory (IFD) header (GAP-13 / G66).
215///
216/// Deterministic zero-heap descriptor for TIFF/COG tile and strip rasters.
217#[repr(C)]
218#[derive(Clone, Copy, Debug, PartialEq, Eq)]
219pub struct CogIfdHeader {
220    pub little_endian: bool,
221    pub image_width: u32,
222    pub image_height: u32,
223    pub bits_per_sample: u16,
224    /// 1 = unsigned int, 2 = two's complement signed int, 3 = IEEE floating point.
225    pub sample_format: u16,
226    /// 1 = uncompressed, 5 = LZW, 8 = Deflate.
227    pub compression: u16,
228    pub tile_width: u32,
229    pub tile_height: u32,
230    pub first_strip_or_tile_offset: u32,
231    pub first_strip_or_tile_byte_count: u32,
232    /// Pixel scale in XYZ (metres per pixel or degrees), stored as `f32::to_bits` for deterministic Eq.
233    pub pixel_scale_xyz: [u32; 3],
234}
235
236#[inline]
237fn read_u16_raw(bytes: &[u8], offset: usize, le: bool) -> Option<u16> {
238    if offset + 2 > bytes.len() {
239        return None;
240    }
241    let arr = [bytes[offset], bytes[offset + 1]];
242    Some(if le { u16::from_le_bytes(arr) } else { u16::from_be_bytes(arr) })
243}
244
245#[inline]
246fn read_u32_raw(bytes: &[u8], offset: usize, le: bool) -> Option<u32> {
247    if offset + 4 > bytes.len() {
248        return None;
249    }
250    let arr = [
251        bytes[offset],
252        bytes[offset + 1],
253        bytes[offset + 2],
254        bytes[offset + 3],
255    ];
256    Some(if le { u32::from_le_bytes(arr) } else { u32::from_be_bytes(arr) })
257}
258
259#[inline]
260fn read_f64_raw(bytes: &[u8], offset: usize, le: bool) -> Option<f64> {
261    if offset + 8 > bytes.len() {
262        return None;
263    }
264    let arr = [
265        bytes[offset],
266        bytes[offset + 1],
267        bytes[offset + 2],
268        bytes[offset + 3],
269        bytes[offset + 4],
270        bytes[offset + 5],
271        bytes[offset + 6],
272        bytes[offset + 7],
273    ];
274    Some(if le { f64::from_le_bytes(arr) } else { f64::from_be_bytes(arr) })
275}
276
277/// Parses a TIFF / Cloud-Optimised GeoTIFF (COG) IFD0 header with zero heap allocation.
278///
279/// Extracts geometry, sample format, compression, and strip/tile offsets for raster window decoding.
280pub fn parse_cog_ifd_header_zero_heap(bytes: &[u8]) -> Option<CogIfdHeader> {
281    if bytes.len() < 8 {
282        return None;
283    }
284
285    let little_endian = match &bytes[0..4] {
286        [0x49, 0x49, 0x2A, 0x00] => true,
287        [0x4D, 0x4D, 0x00, 0x2A] => false,
288        _ => return None,
289    };
290
291    let ifd_offset = read_u32_raw(bytes, 4, little_endian)? as usize;
292    if ifd_offset + 2 > bytes.len() {
293        return None;
294    }
295
296    let num_entries = read_u16_raw(bytes, ifd_offset, little_endian)? as usize;
297    if ifd_offset + 2 + num_entries * 12 > bytes.len() {
298        return None;
299    }
300
301    let mut image_width: u32 = 0;
302    let mut image_height: u32 = 0;
303    let mut bits_per_sample: u16 = 32;
304    let mut sample_format: u16 = 1; // Default: 1 = unsigned integer per TIFF spec
305    let mut compression: u16 = 1;   // Default: 1 = uncompressed
306    let mut tile_width: u32 = 0;
307    let mut tile_height: u32 = 0;
308    let mut tile_offsets: Option<(u32, u32, u16)> = None;   // (count, raw_val, type)
309    let mut tile_counts: Option<(u32, u32, u16)> = None;
310    let mut strip_offsets: Option<(u32, u32, u16)> = None;
311    let mut strip_counts: Option<(u32, u32, u16)> = None;
312    let mut pixel_scale_xyz: [u32; 3] = [0, 0, 0];
313
314    for i in 0..num_entries {
315        let entry_off = ifd_offset + 2 + i * 12;
316        let tag = read_u16_raw(bytes, entry_off, little_endian)?;
317        let tag_type = read_u16_raw(bytes, entry_off + 2, little_endian)?;
318        let count = read_u32_raw(bytes, entry_off + 4, little_endian)?;
319        let val_off = entry_off + 8;
320
321        match tag {
322            256 => {
323                // ImageWidth
324                image_width = if tag_type == 3 {
325                    read_u16_raw(bytes, val_off, little_endian)? as u32
326                } else {
327                    read_u32_raw(bytes, val_off, little_endian)?
328                };
329            }
330            257 => {
331                // ImageLength / ImageHeight
332                image_height = if tag_type == 3 {
333                    read_u16_raw(bytes, val_off, little_endian)? as u32
334                } else {
335                    read_u32_raw(bytes, val_off, little_endian)?
336                };
337            }
338            258 => {
339                // BitsPerSample
340                bits_per_sample = if count == 1 {
341                    read_u16_raw(bytes, val_off, little_endian)?
342                } else {
343                    let ptr = read_u32_raw(bytes, val_off, little_endian)? as usize;
344                    read_u16_raw(bytes, ptr, little_endian)?
345                };
346            }
347            259 => {
348                // Compression
349                compression = read_u16_raw(bytes, val_off, little_endian)?;
350            }
351            273 => {
352                // StripOffsets
353                let raw = read_u32_raw(bytes, val_off, little_endian)?;
354                strip_offsets = Some((count, raw, tag_type));
355            }
356            279 => {
357                // StripByteCounts
358                let raw = read_u32_raw(bytes, val_off, little_endian)?;
359                strip_counts = Some((count, raw, tag_type));
360            }
361            322 => {
362                // TileWidth
363                tile_width = if tag_type == 3 {
364                    read_u16_raw(bytes, val_off, little_endian)? as u32
365                } else {
366                    read_u32_raw(bytes, val_off, little_endian)?
367                };
368            }
369            323 => {
370                // TileLength
371                tile_height = if tag_type == 3 {
372                    read_u16_raw(bytes, val_off, little_endian)? as u32
373                } else {
374                    read_u32_raw(bytes, val_off, little_endian)?
375                };
376            }
377            324 => {
378                // TileOffsets
379                let raw = read_u32_raw(bytes, val_off, little_endian)?;
380                tile_offsets = Some((count, raw, tag_type));
381            }
382            325 => {
383                // TileByteCounts
384                let raw = read_u32_raw(bytes, val_off, little_endian)?;
385                tile_counts = Some((count, raw, tag_type));
386            }
387            339 => {
388                // SampleFormat (1 = uint, 2 = int, 3 = IEEE float)
389                sample_format = if count == 1 {
390                    read_u16_raw(bytes, val_off, little_endian)?
391                } else {
392                    let ptr = read_u32_raw(bytes, val_off, little_endian)? as usize;
393                    read_u16_raw(bytes, ptr, little_endian)?
394                };
395            }
396            33550 => {
397                // ModelPixelScaleTag (DOUBLE, count = 3: ScaleX, ScaleY, ScaleZ)
398                if tag_type == 12 && count >= 3 {
399                    let ptr = read_u32_raw(bytes, val_off, little_endian)? as usize;
400                    if let (Some(sx), Some(sy), Some(sz)) = (
401                        read_f64_raw(bytes, ptr, little_endian),
402                        read_f64_raw(bytes, ptr + 8, little_endian),
403                        read_f64_raw(bytes, ptr + 16, little_endian),
404                    ) {
405                        pixel_scale_xyz = [
406                            (sx as f32).to_bits(),
407                            (sy as f32).to_bits(),
408                            (sz as f32).to_bits(),
409                        ];
410                    }
411                }
412            }
413            _ => {}
414        }
415    }
416
417    let resolve_entry = |item: Option<(u32, u32, u16)>| -> (u32, u32) {
418        match item {
419            Some((c, raw, tag_t)) => {
420                if c == 1 {
421                    if tag_t == 3 {
422                        (raw & 0xFFFF, 0)
423                    } else {
424                        (raw, 0)
425                    }
426                } else {
427                    let ptr = raw as usize;
428                    if tag_t == 3 {
429                        (read_u16_raw(bytes, ptr, little_endian).unwrap_or(0) as u32, 0)
430                    } else {
431                        (read_u32_raw(bytes, ptr, little_endian).unwrap_or(0), 0)
432                    }
433                }
434            }
435            None => (0, 0),
436        }
437    };
438
439    let (first_strip_or_tile_offset, first_strip_or_tile_byte_count) = if tile_offsets.is_some() {
440        let (off, _) = resolve_entry(tile_offsets);
441        let (cnt, _) = resolve_entry(tile_counts);
442        (off, cnt)
443    } else {
444        let (off, _) = resolve_entry(strip_offsets);
445        let (cnt, _) = resolve_entry(strip_counts);
446        (off, cnt)
447    };
448
449    if tile_width == 0 {
450        tile_width = image_width;
451    }
452    if tile_height == 0 {
453        tile_height = image_height;
454    }
455
456    Some(CogIfdHeader {
457        little_endian,
458        image_width,
459        image_height,
460        bits_per_sample,
461        sample_format,
462        compression,
463        tile_width,
464        tile_height,
465        first_strip_or_tile_offset,
466        first_strip_or_tile_byte_count,
467        pixel_scale_xyz,
468    })
469}
470
471/// Extracts floating-point elevation values from an uncompressed COG tile or strip with zero heap allocation.
472///
473/// Decodes either IEEE-754 32-bit float (`sample_format = 3`) or 16-bit signed integer (`sample_format = 2`)
474/// samples into `out_elevations_m`. Returns the number of elevation samples written.
475pub fn extract_cog_f32_window_zero_heap(
476    bytes: &[u8],
477    header: &CogIfdHeader,
478    out_elevations_m: &mut [f32],
479) -> usize {
480    if header.compression != 1 {
481        // Only uncompressed direct raster payloads supported in zero-heap extraction
482        return 0;
483    }
484
485    let offset = header.first_strip_or_tile_offset as usize;
486    let byte_count = header.first_strip_or_tile_byte_count as usize;
487    if offset > bytes.len() || offset + byte_count > bytes.len() {
488        return 0;
489    }
490
491    let payload = &bytes[offset..offset + byte_count];
492    let le = header.little_endian;
493
494    match (header.bits_per_sample, header.sample_format) {
495        (32, 3) => {
496            // IEEE 754 32-bit single precision float
497            let available = payload.len() / 4;
498            let count = out_elevations_m.len().min(available);
499            for i in 0..count {
500                let off = i * 4;
501                let s_bytes = [
502                    payload[off],
503                    payload[off + 1],
504                    payload[off + 2],
505                    payload[off + 3],
506                ];
507                out_elevations_m[i] = if le {
508                    f32::from_le_bytes(s_bytes)
509                } else {
510                    f32::from_be_bytes(s_bytes)
511                };
512            }
513            count
514        }
515        (16, 2) => {
516            // 16-bit signed integer (common in SRTM / NSW DEM rasters)
517            let available = payload.len() / 2;
518            let count = out_elevations_m.len().min(available);
519            for i in 0..count {
520                let off = i * 2;
521                let s_bytes = [payload[off], payload[off + 1]];
522                let raw = if le {
523                    i16::from_le_bytes(s_bytes)
524                } else {
525                    i16::from_be_bytes(s_bytes)
526                };
527                out_elevations_m[i] = raw as f32;
528            }
529            count
530        }
531        (16, 1) => {
532            // 16-bit unsigned integer
533            let available = payload.len() / 2;
534            let count = out_elevations_m.len().min(available);
535            for i in 0..count {
536                let off = i * 2;
537                let s_bytes = [payload[off], payload[off + 1]];
538                let raw = if le {
539                    u16::from_le_bytes(s_bytes)
540                } else {
541                    u16::from_be_bytes(s_bytes)
542                };
543                out_elevations_m[i] = raw as f32;
544            }
545            count
546        }
547        (32, 1) | (32, 2) => {
548            // 32-bit integer
549            let available = payload.len() / 4;
550            let count = out_elevations_m.len().min(available);
551            for i in 0..count {
552                let off = i * 4;
553                let s_bytes = [
554                    payload[off],
555                    payload[off + 1],
556                    payload[off + 2],
557                    payload[off + 3],
558                ];
559                let raw = if le {
560                    i32::from_le_bytes(s_bytes)
561                } else {
562                    i32::from_be_bytes(s_bytes)
563                };
564                out_elevations_m[i] = raw as f32;
565            }
566            count
567        }
568        _ => 0,
569    }
570}
571
572/// Computes clamped non-negative canopy height model: `CHM = (DSM - DEM).max(0.0)`.
573///
574/// Drives `space_colonization_3d` tree height envelopes without heap allocation.
575pub fn compute_canopy_height_model_zero_heap(
576    dsm_m: &[f32],
577    bare_earth_dem_m: &[f32],
578    out_chm_m: &mut [f32],
579) -> usize {
580    let count = dsm_m.len().min(bare_earth_dem_m.len()).min(out_chm_m.len());
581    for i in 0..count {
582        let dsm = dsm_m[i];
583        let dem = bare_earth_dem_m[i];
584        if dsm.is_finite() && dem.is_finite() {
585            out_chm_m[i] = (dsm - dem).max(0.0);
586        } else {
587            out_chm_m[i] = 0.0;
588        }
589    }
590    count
591}
592
593#[cfg(test)]
594mod tests {
595    use super::*;
596
597    #[test]
598    fn m64_unimplemented_codecs_fail_without_mutating_output() {
599        let elevations = [1000];
600        let raster = ElevationRaster { width: 1, height: 1, cell_size_mm: 1000, elevations_mm: &elevations };
601        let frame = GeodeticFrame::default();
602        for codec in [CompressionCodec::Lz4, CompressionCodec::BaoTree,
603            CompressionCodec::Htj2kWavelet, CompressionCodec::TerrainRgbPng,
604            CompressionCodec::TerrariumPng, CompressionCodec::Av1IntraDrape] {
605            let mut output = [0xa5; 512];
606            assert_eq!(compile_raster_to_m64_with_codec(&raster, &frame, 1, codec, &mut output),
607                Err(IngestionError::UnsupportedCompression(codec)));
608            assert_eq!(output, [0xa5; 512]);
609        }
610    }
611
612    #[test]
613    fn m64_raw_codec_preserves_version_layout_and_checked_sdk_readability() {
614        use qualia_core_db::q42::m64_matter::{M64Reader, M64ReadLimits, M64PayloadInterval};
615        let elevations = [500_000];
616        let raster = ElevationRaster { width: 1, height: 1, cell_size_mm: 30_000, elevations_mm: &elevations };
617        let frame = GeodeticFrame::default();
618        let mut output = vec![0; 64 + 64 + 4096 * 64];
619        let written = compile_raster_to_m64(&raster, &frame, 1, &mut output).unwrap();
620        let reader = M64Reader::parse(&output[..written], M64ReadLimits {
621            max_file_bytes: output.len(), max_chunks: 1, max_records: 4096,
622        }, &mut [M64PayloadInterval::default(); 1]).unwrap();
623        assert_eq!(reader.header().version, 1);
624        assert_eq!(reader.verification().record_crc_checked, 4096);
625        assert_eq!(reader.verification().records_without_checksum, 0);
626        let chunk = reader.chunk(0).unwrap();
627        assert_eq!(chunk.directory_entry().compression_flags, 0);
628        assert_eq!(chunk.directory_entry().bao_root_hash_prefix, [0; 12]);
629        let mut expected_record = M64StrataColumnRecord::default();
630        expected_record.surface_elevation_mm = 500_000;
631        expected_record.update_crc();
632        assert!(chunk.payload().chunks_exact(64).all(|raw| raw == bytemuck::bytes_of(&expected_record)));
633    }
634
635    #[test]
636    fn m64_invalid_dimensions_fail_before_mutation() {
637        let raster = ElevationRaster { width: usize::MAX, height: 2, cell_size_mm: 1, elevations_mm: &[] };
638        let mut output = [0xa5; 64];
639        assert_eq!(compile_raster_to_m64(&raster, &GeodeticFrame::default(), 1, &mut output),
640            Err(IngestionError::DimensionMismatch));
641        assert_eq!(output, [0xa5; 64]);
642    }
643
644    #[test]
645    fn test_parse_cog_ifd_header_and_extract_elevation() {
646        let mut tiff_bytes = vec![0u8; 512];
647
648        // 1. TIFF header (8 bytes)
649        tiff_bytes[0..2].copy_from_slice(b"II"); // Little-endian
650        tiff_bytes[2..4].copy_from_slice(&42u16.to_le_bytes()); // TIFF magic 42
651        tiff_bytes[4..8].copy_from_slice(&8u32.to_le_bytes()); // IFD0 offset = 8
652
653        // 2. IFD0 at offset 8:
654        let entry_count: u16 = 10;
655        tiff_bytes[8..10].copy_from_slice(&entry_count.to_le_bytes());
656
657        let mut write_tag = |idx: usize, tag: u16, tag_type: u16, count: u32, val_or_off: u32| {
658            let off = 10 + idx * 12;
659            tiff_bytes[off..off + 2].copy_from_slice(&tag.to_le_bytes());
660            tiff_bytes[off + 2..off + 4].copy_from_slice(&tag_type.to_le_bytes());
661            tiff_bytes[off + 4..off + 8].copy_from_slice(&count.to_le_bytes());
662            tiff_bytes[off + 8..off + 12].copy_from_slice(&val_or_off.to_le_bytes());
663        };
664
665        write_tag(0, 256, 3, 1, 4); // ImageWidth = 4
666        write_tag(1, 257, 3, 1, 4); // ImageLength = 4
667        write_tag(2, 258, 3, 1, 32); // BitsPerSample = 32
668        write_tag(3, 259, 3, 1, 1); // Compression = 1 (uncompressed)
669        write_tag(4, 322, 3, 1, 4); // TileWidth = 4
670        write_tag(5, 323, 3, 1, 4); // TileLength = 4
671        write_tag(6, 324, 4, 1, 300); // TileOffsets = offset 300
672        write_tag(7, 325, 4, 1, 64); // TileByteCounts = 64 bytes
673        write_tag(8, 339, 3, 1, 3); // SampleFormat = 3 (float)
674        write_tag(9, 33550, 12, 3, 200); // ModelPixelScaleTag offset 200
675
676        // Next IFD offset: 4 bytes of 0 at 10 + 10 * 12 = 130
677        tiff_bytes[130..134].copy_from_slice(&0u32.to_le_bytes());
678
679        // ModelPixelScaleTag at offset 200 (3 f64s = 24 bytes): scale_x=1.0, scale_y=1.0, scale_z=0.0
680        tiff_bytes[200..208].copy_from_slice(&1.0f64.to_le_bytes());
681        tiff_bytes[208..216].copy_from_slice(&1.0f64.to_le_bytes());
682        tiff_bytes[216..224].copy_from_slice(&0.0f64.to_le_bytes());
683
684        // Payload at offset 300: 16 f32 NSW elevation samples
685        let sample_elevations: [f32; 16] = [
686            520.0, 521.5, 523.0, 524.5,
687            521.0, 522.5, 524.0, 525.5,
688            522.0, 523.5, 525.0, 526.5,
689            523.0, 524.5, 526.0, 527.5,
690        ];
691        for (i, &elev) in sample_elevations.iter().enumerate() {
692            let off = 300 + i * 4;
693            tiff_bytes[off..off + 4].copy_from_slice(&elev.to_le_bytes());
694        }
695
696        // Test 1: parse header
697        let header = parse_cog_ifd_header_zero_heap(&tiff_bytes).expect("valid header parsed");
698        assert!(header.little_endian);
699        assert_eq!(header.image_width, 4);
700        assert_eq!(header.image_height, 4);
701        assert_eq!(header.bits_per_sample, 32);
702        assert_eq!(header.sample_format, 3);
703        assert_eq!(header.compression, 1);
704        assert_eq!(header.tile_width, 4);
705        assert_eq!(header.tile_height, 4);
706        assert_eq!(header.first_strip_or_tile_offset, 300);
707        assert_eq!(header.first_strip_or_tile_byte_count, 64);
708        assert_eq!(header.pixel_scale_xyz[0], 1.0f32.to_bits());
709        assert_eq!(header.pixel_scale_xyz[1], 1.0f32.to_bits());
710
711        // Test 2: extract elevation samples
712        let mut extracted = [0.0f32; 16];
713        let n = extract_cog_f32_window_zero_heap(&tiff_bytes, &header, &mut extracted);
714        assert_eq!(n, 16);
715        for i in 0..16 {
716            assert_eq!(extracted[i], sample_elevations[i]);
717        }
718
719        // Test 3: compute canopy height model (CHM = DSM - DEM)
720        let bare_earth_dem = [
721            500.0, 500.0, 500.0, 500.0,
722            500.0, 500.0, 500.0, 500.0,
723            500.0, 500.0, 500.0, 500.0,
724            530.0, 500.0, 500.0, 500.0, // note 530.0 > 523.0 DSM (should clamp to 0.0)
725        ];
726        let mut chm = [0.0f32; 16];
727        let chm_count = compute_canopy_height_model_zero_heap(&extracted, &bare_earth_dem, &mut chm);
728        assert_eq!(chm_count, 16);
729        assert!((chm[0] - 20.0).abs() < 1e-4); // 520.0 - 500.0 = 20.0 m tree canopy
730        assert!((chm[1] - 21.5).abs() < 1e-4);
731        assert_eq!(chm[12], 0.0); // 523.0 - 530.0 = -7.0 clamped to 0.0
732    }
733
734    #[test]
735    fn test_strip_i16_elevation_extraction() {
736        let mut tiff_bytes = vec![0u8; 256];
737
738        // Little-endian TIFF header
739        tiff_bytes[0..2].copy_from_slice(b"II");
740        tiff_bytes[2..4].copy_from_slice(&42u16.to_le_bytes());
741        tiff_bytes[4..8].copy_from_slice(&8u32.to_le_bytes());
742
743        // IFD0: 6 entries
744        let entry_count: u16 = 6;
745        tiff_bytes[8..10].copy_from_slice(&entry_count.to_le_bytes());
746
747        let mut write_tag = |idx: usize, tag: u16, tag_type: u16, count: u32, val_or_off: u32| {
748            let off = 10 + idx * 12;
749            tiff_bytes[off..off + 2].copy_from_slice(&tag.to_le_bytes());
750            tiff_bytes[off + 2..off + 4].copy_from_slice(&tag_type.to_le_bytes());
751            tiff_bytes[off + 4..off + 8].copy_from_slice(&count.to_le_bytes());
752            tiff_bytes[off + 8..off + 12].copy_from_slice(&val_or_off.to_le_bytes());
753        };
754
755        write_tag(0, 256, 3, 1, 2); // ImageWidth = 2
756        write_tag(1, 257, 3, 1, 2); // ImageLength = 2
757        write_tag(2, 258, 3, 1, 16); // BitsPerSample = 16
758        write_tag(3, 273, 4, 1, 100); // StripOffsets = offset 100
759        write_tag(4, 279, 4, 1, 8); // StripByteCounts = 8 bytes (4 i16s)
760        write_tag(5, 339, 3, 1, 2); // SampleFormat = 2 (signed int)
761
762        // Payload at 100: 4 i16s [-10, 0, 1500, 2228]
763        let samples: [i16; 4] = [-10, 0, 1500, 2228];
764        for (i, &s) in samples.iter().enumerate() {
765            let off = 100 + i * 2;
766            tiff_bytes[off..off + 2].copy_from_slice(&s.to_le_bytes());
767        }
768
769        let header = parse_cog_ifd_header_zero_heap(&tiff_bytes).expect("valid header parsed");
770        assert_eq!(header.bits_per_sample, 16);
771        assert_eq!(header.sample_format, 2);
772        assert_eq!(header.tile_width, 2); // defaulted to image_width
773        assert_eq!(header.tile_height, 2);
774
775        let mut out = [0.0f32; 4];
776        let n = extract_cog_f32_window_zero_heap(&tiff_bytes, &header, &mut out);
777        assert_eq!(n, 4);
778        assert_eq!(out, [-10.0, 0.0, 1500.0, 2228.0]);
779    }
780}