ras-commander-fast-map 0.11.0

Native Rust 2D flood inundation mapping: horizontal and sloping surfaces, bounded timesteps and terrain windows
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

//! Native 2D flood inundation mapping: horizontal, sloping, and ras2fim-2D Step05.
//!
//! Extends the immutable baseline prototype `prototype/kernel` (RasMapper_Stored_Maps_Rust,
//! 2026-10-22, CLB Engineering): the barycentric evaluation, the `100 * DBL_EPSILON` inclusion
//! test and the lowest-simplex-id tie rule are copied from that kernel. Upstream algorithm:
//! Andy Carter, PE / University of Texas at Austin, ras2fim-2d `3146f647`, Step05 (BSD-3-Clause).
//!
//! The application uses [`step05`], which preserves the upstream float32 sequence
//! and native approximate reprojection over supplied SciPy transforms and axes.
//! The older [`session`] diagnostic retains its distinct f64 arithmetic.
//! Step05 and triangulated-session scope boundaries:
//! - Interpolation topology is always caller-supplied global SciPy/Qhull simplices. There is no
//!   native triangulation and never a per-AOI or per-tile retriangulation.
//! - Wet masks and sample preparation are caller-supplied (upstream/Python adapters).
//! - Native terrain is same-CRS, north-up, single-band float32 GeoTIFF read through terrio with
//!   an explicit sampling formula. Other terrain types require separate qualification.
//! - The diagnostic session's f64 arithmetic does not replace the Step05 float32 sequence.
//!
//! Independent [`horizontal`] and [`sloping_session`] methods prepare pixel ownership
//! directly from cell polygons. Plain sloping reconstructs hydraulic connectivity
//! and corner interpolation rather than using the Step05 SciPy topology.
#![forbid(unsafe_code)]

/// Version of the standalone crate and Python wheel.
pub const ENGINE_VERSION: &str = env!("CARGO_PKG_VERSION");
/// Source revision of an official build, or `unknown` for an unversioned archive.
pub const ENGINE_COMMIT: &str = env!("FAST_MAP_ENGINE_COMMIT");

pub mod aoi;
pub mod boundary_contour;
pub mod boundary_session;
pub mod cache;
mod finalize;
mod geotiff;
pub mod horizontal;
pub mod interp;
pub mod model;
pub mod ownership;
mod retained;
pub mod scipy_interp;
pub mod session;
pub mod sink;
pub mod sloping;
mod sloping_binary;
pub mod sloping_session;
pub mod step05;
pub mod terrain;
pub mod terrain_scope;
pub mod velocity;
pub mod whole_simulation;

use std::fmt;

/// Identifies the method semantics. Changing any recorded convention must change this string.
pub const METHOD_VERSION: &str = "ras2fim-batch-prototype/0.1.0 method-r1";

/// Identifies the output/failure/budget contract (not the numerical method, which is unchanged).
pub const CONTRACT_VERSION: &str = "ras2fim-batch-prototype contract-r2-hardening";

/// Errors are typed so callers can distinguish invalid input, budgets and unsupported cases.
#[derive(Debug, Clone, PartialEq)]
pub enum MapError {
    Invalid(String),
    Budget(String),
    Unsupported(String),
    Io(String),
    Terrain(String),
    /// A caught panic or broken internal invariant (never a silent partial result).
    Internal(String),
}

impl fmt::Display for MapError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            MapError::Invalid(s) => write!(f, "invalid input: {s}"),
            MapError::Budget(s) => write!(f, "budget exceeded: {s}"),
            MapError::Unsupported(s) => write!(f, "unsupported: {s}"),
            MapError::Io(s) => write!(f, "io error: {s}"),
            MapError::Terrain(s) => write!(f, "terrain error: {s}"),
            MapError::Internal(s) => write!(f, "internal error: {s}"),
        }
    }
}

impl std::error::Error for MapError {}

impl From<std::io::Error> for MapError {
    fn from(e: std::io::Error) -> Self {
        MapError::Io(e.to_string())
    }
}

impl MapError {
    pub fn kind(&self) -> &'static str {
        match self {
            MapError::Invalid(_) => "invalid",
            MapError::Budget(_) => "budget",
            MapError::Unsupported(_) => "unsupported",
            MapError::Io(_) => "io",
            MapError::Terrain(_) => "terrain",
            MapError::Internal(_) => "internal",
        }
    }
}

/// Static description of the implemented semantics, emitted in every report.
pub fn method_record() -> serde_json::Value {
    serde_json::json!({
        "method_version": METHOD_VERSION,
        "interpolation": {
            "topology": "caller-supplied global SciPy/Qhull simplices only; no native or per-AOI triangulation",
            "evaluation": "f64 barycentric linear interpolation (baseline prototype kernel)",
            "inclusion_tolerance": "all barycentric coordinates >= -100*DBL_EPSILON",
            "tie_rule": "lowest supplied simplex index among containing simplices (order independent)",
            "degenerate_simplices": "skipped when determinant == 0 or exact 1-norm reciprocal condition < 1000*DBL_EPSILON; modeled on SciPy's singular-transform skip, not verified bit-identical to SciPy's LAPACK estimate",
            "scipy_eps_broad_fallback": "not implemented; no claim of SciPy find_simplex walk parity",
            "query_point": "x = x0 + col*dx, y = y0 + row*dy in f64 (explicit grid); terrain-aligned grid: x = gt0 + (abs_col + 0.5)*gt1, y = gt3 + (abs_row + 0.5)*gt5"
        },
        "mask": "caller-supplied rasterized wet union on the profile grid (upstream/Python adapter); unmasked pixels are nodata",
        "depth_wse": "depth = raw_wse - ground (f64); wet iff ground present and depth >= 0; wse = raw_wse where wet. Baseline prototype semantics; upstream float32 writes, '<0 -> NaN' sequencing and the Step05 nudge are NOT replicated",
        "terrain_modes": {
            "caller_buffer": "per-profile pre-aligned f64 terrain buffer, null/NaN = nodata (old oracle parity mode)",
            "native_geotiff": {
                "format": "same-CRS, north-up (gt2 == gt4 == 0, gt1 > 0, gt5 < 0), single-band float32 GeoTIFF/BigTIFF via terrio 0.4.2 lazy tile reads",
                "sample_formula": "col = floor((xs - gt0) / gt1), row = floor((ys - gt3) / gt5) in f64",
                "query_convention": "explicit per session: pixel_center (xs = x0 + (col + 0.5)*dx, ys = y0 + (row + 0.5)*dy) or query_point (xs, ys = query point)",
                "nodata_policy": "explicit per session: dry (declared-nodata sentinel -> dry) or raw_value (sentinel subtracted as a number, upstream-like raw subtraction; not qualified)",
                "outside_extent": "dry",
                "nan_value": "dry",
                "reprojection": "never; terrain EPSG must equal the declared session EPSG",
                "not_qualified": "GDAL Warp nearest-neighbour, Step05 inverted-bounds lattice, nudge, upstream raw-sentinel behaviour; rasterio rowcol uses a linear solve and may differ at exact pixel-boundary ties (counted as terrain_near_boundary_samples)"
            }
        },
        "nonfinite_terrain": "NaN terrain is dry; declared NaN or +/-inf nodata is accepted (a pixel is the sentinel iff v == nodata as f32, GDAL-like; report states whether that cast is exact); any other infinite terrain value that is sampled is rejected (native: typed terrain error failing the profile; caller_buffer: invalid request)",
        "aoi": "pixel windows on each profile's own grid; AOI output equals the crop of the full-grid output by construction (same tiles, same per-pixel formula); bounds select pixels whose center lies in [min, max)",
        "outputs": "per (profile, AOI) unit: little-endian f64 rasters with NaN nodata, simplex_id as i64 with -1 nodata, row-major in grid row order",
        "output_contract": {
            "contract_version": CONTRACT_VERSION,
            "commit": "unit.json status in_progress is written before any data; data is written as <product>.bin.partial, fsynced (errors propagate), renamed to .bin, directory synced where supported, then unit.json is atomically replaced with status complete. A .bin is valid only when unit.json says complete",
            "failure": "a failed unit, or every open unit after a session error or caught panic, has its data removed and unit.json status failed; report.json is still written with status aborted when possible (otherwise stderr says so and in_progress/.partial names remain)",
            "json_writes": "<name>.partial, fsync, rename",
            "ids": "[A-Za-z0-9_.-]{1,64}, unique case-insensitively, no trailing '.', no Windows device names (CON, PRN, AUX, NUL, COM0-9, LPT0-9, with any extension)"
        },
        "bounds": {
            "enforced": "decoded resident terrain tiles <= max_cache_bytes; evaluated tile buffers <= effective_tiles_in_flight x output_tile^2 x 40 bytes; plan tiles per profile <= 4194304",
            "admission_estimates": "per-profile load+prepare peak from request content / file lengths before any read (binary/inline: buffer sizes plus an assumed one-copy R-tree bulk-load; legacy JSON: 64 x file length heuristic) checked against max_profile_bytes; optional max_session_bytes packs batches over accounted static terms + batch load peaks + plan metadata",
            "not_bounded": "decoder transients (estimated only), allocator fragmentation, thread stacks, codec state, JSON transients; no hard total memory bound is claimed"
        }
    })
}