rustial_engine/

precision_invariants.rs

//! # Meter-Based Precision Invariants
//!
//! This module documents the precision invariants that Rustial maintains
//! across the engine and both renderer paths (WGPU and Bevy).  These
//! invariants are validated by tests in
//! [`support_contract`](crate::support_contract) and by headless
//! regression tests in the renderer crates.
//!
//! ## 1. Internal units are meters
//!
//! All internal linear distances, world-space coordinates, and
//! elevation values in the engine are expressed in **meters**.
//!
//! | Type | Unit |
//! |------|------|
//! | [`WorldCoord`](rustial_math::WorldCoord) | meters (east, north, up) |
//! | [`GeoCoord::alt`](rustial_math::GeoCoord) | meters above WGS-84 ellipsoid |
//! | [`ElevationGrid`](rustial_math::ElevationGrid) samples | meters |
//! | [`Camera::distance()`](crate::Camera) | meters |
//! | [`Camera::meters_per_pixel()`](crate::Camera) | meters per screen pixel |
//! | Tile bounds ([`tile_bounds_world`](rustial_math::tile_bounds_world)) | meters |
//! | Geodesic distances ([`geodesic_distance`](rustial_math::geodesic_distance)) | meters |
//!
//! ## 2. f64 engine, f32 GPU
//!
//! The engine performs **all math in f64**.  GPU-bound data is cast to
//! f32 only at upload time.  This ensures centimetre-scale precision
//! even at world-edge coordinates (x ~ 20 million metres).
//!
//! ## 3. Camera-relative rendering
//!
//! Both renderers use **camera-relative** vertex positions to avoid
//! catastrophic f32 precision loss at large world coordinates:
//!
//! ```text
//! GPU vertex position = world_position - camera_target_world()
//! ```
//!
//! Because the subtraction happens in f64 *before* the cast to f32,
//! the resulting f32 values are small (within a few kilometres of the
//! origin) and retain sub-centimetre precision.
//!
//! ### Why this is necessary
//!
//! At longitude ~180 degrees, the absolute Mercator X coordinate is
//! approximately 20 million metres.  A 32-bit float at that magnitude
//! has an epsilon of approximately 2 metres -- sub-metre detail would
//! be lost.  Camera-relative rendering eliminates this problem.
//!
//! ### What is subtracted
//!
//! | Renderer | Origin |
//! |----------|--------|
//! | WGPU | `MapState::scene_world_origin()` (= `camera.target_world()`) |
//! | Bevy | Same -- the Bevy camera is at `eye_offset()`, tiles at `(world - origin)` |
//!
//! ## 4. Projection round-trip guarantees
//!
//! For **stable** (v1.0) projections, the following round-trip invariant
//! holds at all valid inputs:
//!
//! ```text
//! let world = projection.project(&geo);
//! let back  = projection.unproject(&world);
//! assert!((back.lat - geo.lat).abs() < 1e-8);
//! assert!((back.lon - geo.lon).abs() < 1e-8);
//! ```
//!
//! | Projection | Latitude accuracy | Longitude accuracy | Altitude |
//! |------------|------------------|--------------------|----------|
//! | Web Mercator | < 1e-8 deg | < 1e-8 deg | passthrough (exact) |
//! | Equirectangular | < 1e-8 deg | < 1e-8 deg | passthrough (exact) |
//! | Globe | < 1e-6 deg | < 1e-6 deg | < 1 m |
//! | Vertical Perspective | < 1e-5 deg | < 1e-5 deg | best-effort |
//!
//! ## 5. Anti-meridian handling
//!
//! - [`GeoCoord::clamped_mercator()`](rustial_math::GeoCoord::clamped_mercator)
//!   wraps longitude to `[-180, 180]` via modular arithmetic.
//! - `+180 deg` and `-180 deg` project to the same world X (validated by test).
//! - Geodesic distance across the dateline follows the **short** path
//!   (e.g. 179 deg E to 179 deg W is approximately 220 km, not 39 800 km).
//!
//! ## 6. High-latitude behaviour
//!
//! - Web Mercator is valid only within approximately +/-85.051 129 deg latitude.
//! - `project_clamped` saturates latitude to this limit.
//! - `project_checked` returns `None` outside the limit.
//! - Scale factor diverges as `sec(lat)`: at 85 deg it is approximately 11.5.
//! - Equirectangular handles poles (+/-90 deg) without singularity.
//!
//! ## 7. Large-world numeric stability
//!
//! - f64 arithmetic preserves centimetre-scale deltas at the Mercator
//!   extent boundary (approximately 20 million metres).
//! - Camera-relative f32 vertices preserve sub-centimetre precision
//!   for geometry within approximately 100 km of the camera target.
//! - At zoom 14 (approximately 10 m per tile pixel), on-screen tile
//!   corners have camera-relative f32 error < 1 cm (validated by test).
//!
//! ## 8. Terrain elevation
//!
//! - `ElevationGrid` stores heights in f32 metres.  The full Earth
//!   elevation range (-11 034 m to +8 848 m) survives the f32 cast
//!   with < 1 cm error.
//! - Bilinear interpolation produces correct intermediate values.
//! - Altitude (`GeoCoord::alt`) passes through projections unchanged.
//! - `TerrainConfig::vertical_exaggeration` scales elevation in the
//!   GPU shader, not in the engine grid, preserving raw accuracy.
//!
//! ## 9. Scale factor
//!
//! - Web Mercator: `sec(lat)` -- unity at the equator, 2.0 at 60 deg.
//! - Equirectangular: `sec(lat)` along X, 1.0 along Y.
//! - `Camera::meters_per_pixel()` uses the scale factor to convert
//!   screen resolution to ground resolution.
//!
//! ## 10. Tile coordinate contract
//!
//! - `geo_to_tile` / `tile_to_geo` round-trip at all zoom levels.
//! - Adjacent tiles share edges with < 1 mm world-space gap.
//! - `tile_bounds_world` at zoom 0 spans the full Mercator world size.
//! - `TileId::quadkey()` / `TileId::from_quadkey()` round-trip.
//! - Parent / child relationships are consistent.
//!
//! ## 11. Renderer parity contract
//!
//! Both WGPU and Bevy renderers consume the same engine outputs:
//!
//! | Engine output | Consumed by |
//! |---------------|-------------|
//! | `camera.target_world()` | Scene origin subtraction |
//! | `camera.eye_offset()` | Camera placement |
//! | `camera.view_matrix(DVec3::ZERO)` | View matrix (camera-relative) |
//! | `camera.projection_matrix()` | Projection matrix |
//! | `tile_bounds_world` + UV mapping | Tile quad vertices |
//! | `ElevationGrid` | Terrain GPU texture (R32Float) |
//! | `VectorMeshData` positions | Vector vertex buffers |
//! | `ModelInstance` position + altitude | Model transform buffers |
//!
//! Because both renderers apply camera-relative subtraction in f64
//! before the f32 cast, the precision guarantees are identical.
//!
//! # Meter-Based Precision Invariants
//!
//! This module documents the precision invariants that Rustial maintains
//! across the engine and both renderer paths (WGPU and Bevy).  These
//! invariants are validated by tests in
//! [`support_contract`](crate::support_contract) and by headless
//! regression tests in the renderer crates.
//!
//! ## 1. Internal units are meters
//!
//! All internal linear distances, world-space coordinates, and
//! elevation values in the engine are expressed in **meters**.
//!
//! | Type | Unit |
//! |------|------|
//! | [`WorldCoord`](rustial_math::WorldCoord) | meters (east, north, up) |
//! | [`GeoCoord::alt`](rustial_math::GeoCoord) | meters above WGS-84 ellipsoid |
//! | [`ElevationGrid`](rustial_math::ElevationGrid) samples | meters |
//! | [`Camera::distance()`](crate::Camera) | meters |
//! | [`Camera::meters_per_pixel()`](crate::Camera) | meters per screen pixel |
//! | Tile bounds ([`tile_bounds_world`](rustial_math::tile_bounds_world)) | meters |
//! | Geodesic distances ([`geodesic_distance`](rustial_math::geodesic_distance)) | meters |
//!
//! ## 2. f64 engine, f32 GPU
//!
//! The engine performs **all math in f64**.  GPU-bound data is cast to
//! f32 only at upload time.  This ensures centimetre-scale precision
//! even at world-edge coordinates (x ~ 20 million metres).
//!
//! ## 3. Camera-relative rendering
//!
//! Both renderers use **camera-relative** vertex positions to avoid
//! catastrophic f32 precision loss at large world coordinates:
//!
//! ```text
//! GPU vertex position = world_position - camera_target_world()
//! ```
//!
//! Because the subtraction happens in f64 *before* the cast to f32,
//! the resulting f32 values are small (within a few kilometres of the
//! origin) and retain sub-centimetre precision.
//!
//! ### Why this is necessary
//!
//! At longitude ~180 degrees, the absolute Mercator X coordinate is
//! approximately 20 million metres.  A 32-bit float at that magnitude
//! has an epsilon of approximately 2 metres -- sub-metre detail would
//! be lost.  Camera-relative rendering eliminates this problem.
//!
//! ### What is subtracted
//!
//! | Renderer | Origin |
//! |----------|--------|
//! | WGPU | `MapState::scene_world_origin()` (= `camera.target_world()`) |
//! | Bevy | Same -- the Bevy camera is at `eye_offset()`, tiles at `(world - origin)` |
//!
//! ## 4. Projection round-trip guarantees
//!
//! For **stable** (v1.0) projections, the following round-trip invariant
//! holds at all valid inputs:
//!
//! ```text
//! let world = projection.project(&geo);
//! let back  = projection.unproject(&world);
//! assert!((back.lat - geo.lat).abs() < 1e-8);
//! assert!((back.lon - geo.lon).abs() < 1e-8);
//! ```
//!
//! | Projection | Latitude accuracy | Longitude accuracy | Altitude |
//! |------------|------------------|--------------------|----------|
//! | Web Mercator | < 1e-8 deg | < 1e-8 deg | passthrough (exact) |
//! | Equirectangular | < 1e-8 deg | < 1e-8 deg | passthrough (exact) |
//! | Globe | < 1e-6 deg | < 1e-6 deg | < 1 m |
//! | Vertical Perspective | < 1e-5 deg | < 1e-5 deg | best-effort |
//!
//! ## 5. Anti-meridian handling
//!
//! - [`GeoCoord::clamped_mercator()`](rustial_math::GeoCoord::clamped_mercator)
//!   wraps longitude to `[-180, 180]` via modular arithmetic.
//! - `+180 deg` and `-180 deg` project to the same world X (validated by test).
//! - Geodesic distance across the dateline follows the **short** path
//!   (e.g. 179 deg E to 179 deg W is approximately 220 km, not 39 800 km).
//!
//! ## 6. High-latitude behaviour
//!
//! - Web Mercator is valid only within approximately +/-85.051 129 deg latitude.
//! - `project_clamped` saturates latitude to this limit.
//! - `project_checked` returns `None` outside the limit.
//! - Scale factor diverges as `sec(lat)`: at 85 deg it is approximately 11.5.
//! - Equirectangular handles poles (+/-90 deg) without singularity.
//!
//! ## 7. Large-world numeric stability
//!
//! - f64 arithmetic preserves centimetre-scale deltas at the Mercator
//!   extent boundary (approximately 20 million metres).
//! - Camera-relative f32 vertices preserve sub-centimetre precision
//!   for geometry within approximately 100 km of the camera target.
//! - At zoom 14 (approximately 10 m per tile pixel), on-screen tile
//!   corners have camera-relative f32 error < 1 cm (validated by test).
//!
//! ## 8. Terrain elevation
//!
//! - `ElevationGrid` stores heights in f32 metres.  The full Earth
//!   elevation range (-11 034 m to +8 848 m) survives the f32 cast
//!   with < 1 cm error.
//! - Bilinear interpolation produces correct intermediate values.
//! - Altitude (`GeoCoord::alt`) passes through projections unchanged.
//! - `TerrainConfig::vertical_exaggeration` scales elevation in the
//!   GPU shader, not in the engine grid, preserving raw accuracy.
//!
//! ## 9. Scale factor
//!
//! - Web Mercator: `sec(lat)` -- unity at the equator, 2.0 at 60 deg.
//! - Equirectangular: `sec(lat)` along X, 1.0 along Y.
//! - `Camera::meters_per_pixel()` uses the scale factor to convert
//!   screen resolution to ground resolution.
//!
//! ## 10. Tile coordinate contract
//!
//! - `geo_to_tile` / `tile_to_geo` round-trip at all zoom levels.
//! - Adjacent tiles share edges with < 1 mm world-space gap.
//! - `tile_bounds_world` at zoom 0 spans the full Mercator world size.
//! - `TileId::quadkey()` / `TileId::from_quadkey()` round-trip.
//! - Parent / child relationships are consistent.
//!
//! ## 11. Renderer parity contract
//!
//! Both WGPU and Bevy renderers consume the same engine outputs:
//!
//! | Engine output | Consumed by |
//! |---------------|-------------|
//! | `camera.target_world()` | Scene origin subtraction |
//! | `camera.eye_offset()` | Camera placement |
//! | `camera.view_matrix(DVec3::ZERO)` | View matrix (camera-relative) |
//! | `camera.projection_matrix()` | Projection matrix |
//! | `tile_bounds_world` + UV mapping | Tile quad vertices |
//! | `ElevationGrid` | Terrain GPU texture (R32Float) |
//! | `VectorMeshData` positions | Vector vertex buffers |
//! | `ModelInstance` position + altitude | Model transform buffers |
//!
//! Because both renderers apply camera-relative subtraction in f64
//! before the f32 cast, the precision guarantees are identical.
//!
//! # Meter-Based Precision Invariants
//!
//! This module documents the precision invariants that Rustial maintains
//! across the engine and both renderer paths (WGPU and Bevy).  These
//! invariants are validated by tests in
//! [`support_contract`](crate::support_contract) and by headless
//! regression tests in the renderer crates.
//!
//! ## 1. Internal units are meters
//!
//! All internal linear distances, world-space coordinates, and
//! elevation values in the engine are expressed in **meters**.
//!
//! | Type | Unit |
//! |------|------|
//! | [`WorldCoord`](rustial_math::WorldCoord) | meters (east, north, up) |
//! | [`GeoCoord::alt`](rustial_math::GeoCoord) | meters above WGS-84 ellipsoid |
//! | [`ElevationGrid`](rustial_math::ElevationGrid) samples | meters |
//! | [`Camera::distance()`](crate::Camera) | meters |
//! | [`Camera::meters_per_pixel()`](crate::Camera) | meters per screen pixel |
//! | Tile bounds ([`tile_bounds_world`](rustial_math::tile_bounds_world)) | meters |
//! | Geodesic distances ([`geodesic_distance`](rustial_math::geodesic_distance)) | meters |
//!
//! ## 2. f64 engine, f32 GPU
//!
//! The engine performs **all math in f64**.  GPU-bound data is cast to
//! f32 only at upload time.  This ensures centimetre-scale precision
//! even at world-edge coordinates (x ~ 20 million metres).
//!
//! ## 3. Camera-relative rendering
//!
//! Both renderers use **camera-relative** vertex positions to avoid
//! catastrophic f32 precision loss at large world coordinates:
//!
//! ```text
//! GPU vertex position = world_position - camera_target_world()
//! ```
//!
//! Because the subtraction happens in f64 *before* the cast to f32,
//! the resulting f32 values are small (within a few kilometres of the
//! origin) and retain sub-centimetre precision.
//!
//! ### Why this is necessary
//!
//! At longitude ~180 degrees, the absolute Mercator X coordinate is
//! approximately 20 million metres.  A 32-bit float at that magnitude
//! has an epsilon of approximately 2 metres -- sub-metre detail would
//! be lost.  Camera-relative rendering eliminates this problem.
//!
//! ### What is subtracted
//!
//! | Renderer | Origin |
//! |----------|--------|
//! | WGPU | `MapState::scene_world_origin()` (= `camera.target_world()`) |
//! | Bevy | Same -- the Bevy camera is at `eye_offset()`, tiles at `(world - origin)` |
//!
//! ## 4. Projection round-trip guarantees
//!
//! For **stable** (v1.0) projections, the following round-trip invariant
//! holds at all valid inputs:
//!
//! ```text
//! let world = projection.project(&geo);
//! let back  = projection.unproject(&world);
//! assert!((back.lat - geo.lat).abs() < 1e-8);
//! assert!((back.lon - geo.lon).abs() < 1e-8);
//! ```
//!
//! | Projection | Latitude accuracy | Longitude accuracy | Altitude |
//! |------------|------------------|--------------------|----------|
//! | Web Mercator | < 1e-8 deg | < 1e-8 deg | passthrough (exact) |
//! | Equirectangular | < 1e-8 deg | < 1e-8 deg | passthrough (exact) |
//! | Globe | < 1e-6 deg | < 1e-6 deg | < 1 m |
//! | Vertical Perspective | < 1e-5 deg | < 1e-5 deg | best-effort |
//!
//! ## 5. Anti-meridian handling
//!
//! - [`GeoCoord::clamped_mercator()`](rustial_math::GeoCoord::clamped_mercator)
//!   wraps longitude to `[-180, 180]` via modular arithmetic.
//! - `+180 deg` and `-180 deg` project to the same world X (validated by test).
//! - Geodesic distance across the dateline follows the **short** path
//!   (e.g. 179 deg E to 179 deg W is approximately 220 km, not 39 800 km).
//!
//! ## 6. High-latitude behaviour
//!
//! - Web Mercator is valid only within approximately +/-85.051 129 deg latitude.
//! - `project_clamped` saturates latitude to this limit.
//! - `project_checked` returns `None` outside the limit.
//! - Scale factor diverges as `sec(lat)`: at 85 deg it is approximately 11.5.
//! - Equirectangular handles poles (+/-90 deg) without singularity.
//!
//! ## 7. Large-world numeric stability
//!
//! - f64 arithmetic preserves centimetre-scale deltas at the Mercator
//!   extent boundary (approximately 20 million metres).
//! - Camera-relative f32 vertices preserve sub-centimetre precision
//!   for geometry within approximately 100 km of the camera target.
//! - At zoom 14 (approximately 10 m per tile pixel), on-screen tile
//!   corners have camera-relative f32 error < 1 cm (validated by test).
//!
//! ## 8. Terrain elevation
//!
//! - `ElevationGrid` stores heights in f32 metres.  The full Earth
//!   elevation range (-11 034 m to +8 848 m) survives the f32 cast
//!   with < 1 cm error.
//! - Bilinear interpolation produces correct intermediate values.
//! - Altitude (`GeoCoord::alt`) passes through projections unchanged.
//! - `TerrainConfig::vertical_exaggeration` scales elevation in the
//!   GPU shader, not in the engine grid, preserving raw accuracy.
//!
//! ## 9. Scale factor
//!
//! - Web Mercator: `sec(lat)` -- unity at the equator, 2.0 at 60 deg.
//! - Equirectangular: `sec(lat)` along X, 1.0 along Y.
//! - `Camera::meters_per_pixel()` uses the scale factor to convert
//!   screen resolution to ground resolution.
//!
//! ## 10. Tile coordinate contract
//!
//! - `geo_to_tile` / `tile_to_geo` round-trip at all zoom levels.
//! - Adjacent tiles share edges with < 1 mm world-space gap.
//! - `tile_bounds_world` at zoom 0 spans the full Mercator world size.
//! - `TileId::quadkey()` / `TileId::from_quadkey()` round-trip.
//! - Parent / child relationships are consistent.
//!
//! ## 11. Renderer parity contract
//!
//! Both WGPU and Bevy renderers consume the same engine outputs:
//!
//! | Engine output | Consumed by |
//! |---------------|-------------|
//! | `camera.target_world()` | Scene origin subtraction |
//! | `camera.eye_offset()` | Camera placement |
//! | `camera.view_matrix(DVec3::ZERO)` | View matrix (camera-relative) |
//! | `camera.projection_matrix()` | Projection matrix |
//! | `tile_bounds_world` + UV mapping | Tile quad vertices |
//! | `ElevationGrid` | Terrain GPU texture (R32Float) |
//! | `VectorMeshData` positions | Vector vertex buffers |
//! | `ModelInstance` position + altitude | Model transform buffers |
//!
//! Because both renderers apply camera-relative subtraction in f64
//! before the f32 cast, the precision guarantees are identical.

// This module is documentation-only; it contains no runtime code.
// The invariants documented here are validated by tests in
// `crates/rustial-engine/src/support_contract.rs`.