From ce1c8db7fbf330f58634a248bc8291ff7d6765f3 Mon Sep 17 00:00:00 2001 From: selune <35337584+0xlillith@users.noreply.github.com> Date: Sat, 24 Oct 2026 08:31:59 +0200 Subject: [PATCH] feat(render): reconcile definition-local visual mapping (#1214) (#1223) Retain the original mapping implementation, all eight analytic/hostile-input tests and mapping contract byte-for-byte from #1223. Reconcile only module registration and the current roadmap on render. Actual current render library 166/0; strict all-target render Clippy, wasm32 and repository gates pass. No persistence, sampler, new capability, kernel/vendor change or external code is added. Historical mixed-base full-CI failures are not relabelled. --- ROADMAP.md | 2 + crates/render/src/lib.rs | 1 + crates/render/src/mapping.rs | 141 +++++++++++++++++++++++++++++ crates/render/src/mapping_tests.rs | 112 +++++++++++++++++++++++ docs/render-visual-mapping.md | 55 +++++++++++ 5 files changed, 311 insertions(+) create mode 100644 crates/render/src/mapping.rs create mode 100644 crates/render/src/mapping_tests.rs create mode 100644 docs/render-visual-mapping.md diff --git a/ROADMAP.md b/ROADMAP.md index 01168c25b..1c9198882 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -143,6 +143,8 @@ completed drawings publish atomically. The browser still exports synchronously. ## Render foundation +- Definition-local visual mapping (#1214) supplies a bounded numerical frame, physical repeat coordinates and a deterministic one-time grain-axis suggestion. It adds no saved record or texture consumer; see [the mapping contract](docs/render-visual-mapping.md). + - Explicit texture normalization (#1218) produces completed float RGBA with role-aware linear color/data semantics, bounded matrix/TRC ICC conversion and opt-in EXIF orientation. It retains high-precision raw samples and records lossy diff --git a/crates/render/src/lib.rs b/crates/render/src/lib.rs index 4e14b3e36..9390ab01d 100644 --- a/crates/render/src/lib.rs +++ b/crates/render/src/lib.rs @@ -13,6 +13,7 @@ mod curve_display; mod gif; pub mod job; pub mod lighting; +pub mod mapping; mod product; mod raster; mod scene; diff --git a/crates/render/src/mapping.rs b/crates/render/src/mapping.rs new file mode 100644 index 000000000..4e34f4aae --- /dev/null +++ b/crates/render/src/mapping.rs @@ -0,0 +1,141 @@ +//! Definition-local visual coordinates, independent of geometry and engineering axes. +//! This numerical foundation installs no texture sampler, shader or persistent record. + +use solidcraft_geom::{Aabb3, Vec3}; + +/// Admission bounds, not a GPU precision or engineering applicability guarantee. +pub const MAX_LOCAL_MM: f64 = 1e9; +pub const MIN_REPEAT_MM: f64 = 1e-3; +pub const MAX_REPEAT_MM: f64 = 1e6; +pub const MAX_REPEAT_COORDINATE: f64 = 1e6; +/// Absolute tolerance for unit-length squared, orthogonality and handedness checks. +pub const FRAME_TOLERANCE: f64 = 1e-10; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum MappingError { + Position, + Frame, + RepeatSize, + Coordinates, + Bounds, +} + +impl std::fmt::Display for MappingError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(match self { + Self::Position => "visual mapping positions must be finite and within +/-1e9 mm", + Self::Frame => "visual mapping axes must form a right-handed orthonormal frame", + Self::RepeatSize => "visual repeat sizes must be finite and within [0.001, 1e6] mm", + Self::Coordinates => "visual repeat coordinates exceed the +/-1e6 admission limit", + Self::Bounds => "grain suggestion needs finite ordered local bounds with a positive extent", + }) + } +} +impl std::error::Error for MappingError {} + +/// A one-time visual suggestion; not a material-local mechanical L/R/T assignment. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum GrainAxis { + X, + Y, + Z, +} + +impl GrainAxis { + /// First axis is the visual grain direction. The other two complete a right-handed frame. + pub fn axes(self) -> [Vec3; 3] { + match self { + Self::X => [Vec3::X, Vec3::Y, Vec3::Z], + Self::Y => [Vec3::Y, Vec3::Z, Vec3::X], + Self::Z => [Vec3::Z, Vec3::X, Vec3::Y], + } + } +} + +/// Suggest from definition-local bounds only, with exact ties resolved X, then Y, then Z. +/// The caller stores an accepted frame once; this function never observes a later rebuild. +pub fn suggest_grain_axis(local_bounds: Aabb3) -> Result { + if !bounded_position(local_bounds.min) || !bounded_position(local_bounds.max) || local_bounds.is_empty() { + return Err(MappingError::Bounds); + } + let extent = local_bounds.max - local_bounds.min; + if extent.x.max(extent.y).max(extent.z) <= 0.0 { + return Err(MappingError::Bounds); + } + if extent.x >= extent.y && extent.x >= extent.z { + Ok(GrainAxis::X) + } else if extent.y >= extent.z { + Ok(GrainAxis::Y) + } else { + Ok(GrainAxis::Z) + } +} + +/// Immutable admitted visual frame. Fields cannot be changed without readmission. +/// No serde implementation: eventual document/catalog readers must use `new`. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct VisualMapping { + origin_mm: Vec3, + axes: [Vec3; 3], + repeat_mm: Vec3, +} + +impl VisualMapping { + /// Axes are unit directions in definition-local space, in grain/across/depth order. + /// Repeat sizes are distances along those directions, not body-bound fractions. + /// Small floating-point frame error is admitted within `FRAME_TOLERANCE`; no skew, + /// reflection, rescaling, orthogonalization or replacement frame is manufactured. + pub fn new(origin_mm: Vec3, axes: [Vec3; 3], repeat_mm: Vec3) -> Result { + if !bounded_position(origin_mm) { + return Err(MappingError::Position); + } + let [x, y, z] = axes; + if !axes.into_iter().all(|v| v.is_finite() && (v.len2() - 1.0).abs() <= FRAME_TOLERANCE) + || x.dot(y).abs() > FRAME_TOLERANCE + || x.dot(z).abs() > FRAME_TOLERANCE + || y.dot(z).abs() > FRAME_TOLERANCE + || (x.cross(y).dot(z) - 1.0).abs() > FRAME_TOLERANCE + { + return Err(MappingError::Frame); + } + if ![repeat_mm.x, repeat_mm.y, repeat_mm.z].into_iter().all(|v| v.is_finite() && (MIN_REPEAT_MM..=MAX_REPEAT_MM).contains(&v)) { + return Err(MappingError::RepeatSize); + } + Ok(Self { origin_mm, axes, repeat_mm }) + } + + pub fn origin_mm(self) -> Vec3 { + self.origin_mm + } + pub fn axes(self) -> [Vec3; 3] { + self.axes + } + pub fn repeat_mm(self) -> Vec3 { + self.repeat_mm + } + + /// Unwrapped signed repeat coordinates, calculated in f64. No clamping or UV seam. + /// The host must first invert the selected instance placement into definition-local + /// space. World-space bounding boxes and camera/mesh positions are not inputs here. + /// Samplers choose wrapping/filtering; GPU consumers need their own precision budget. + pub fn coordinates(self, local_point_mm: Vec3) -> Result { + if !bounded_position(local_point_mm) { + return Err(MappingError::Position); + } + let delta = local_point_mm - self.origin_mm; + let [x, y, z] = self.axes; + let result = Vec3::new(delta.dot(x) / self.repeat_mm.x, delta.dot(y) / self.repeat_mm.y, delta.dot(z) / self.repeat_mm.z); + if !result.is_finite() || [result.x, result.y, result.z].into_iter().any(|v| v.abs() > MAX_REPEAT_COORDINATE) { + return Err(MappingError::Coordinates); + } + Ok(result) + } +} + +fn bounded_position(value: Vec3) -> bool { + value.is_finite() && [value.x, value.y, value.z].into_iter().all(|v| v.abs() <= MAX_LOCAL_MM) +} + +#[cfg(test)] +#[path = "mapping_tests.rs"] +mod tests; diff --git a/crates/render/src/mapping_tests.rs b/crates/render/src/mapping_tests.rs new file mode 100644 index 000000000..5dcac3f66 --- /dev/null +++ b/crates/render/src/mapping_tests.rs @@ -0,0 +1,112 @@ +use super::*; + +fn close(actual: Vec3, expected: Vec3) { + assert!((actual - expected).len() < 1e-10, "{actual:?} != {expected:?}"); +} + +#[test] +fn physical_repeats_translation_negative_coordinates_and_manual_rotation() { + // +90 degrees around local Z: grain +Y, across -X, depth +Z. + let origin = Vec3::new(10.0, -20.0, 30.0); + let mapping = VisualMapping::new(origin, [Vec3::Y, -Vec3::X, Vec3::Z], Vec3::new(100.0, 20.0, 5.0)).unwrap(); + close(mapping.coordinates(origin).unwrap(), Vec3::ZERO); + close(mapping.coordinates(origin + Vec3::new(-10.0, 200.0, -15.0)).unwrap(), Vec3::new(2.0, 0.5, -3.0)); + // One repeat is a physical distance, independent of a body's dimensions. + close(mapping.coordinates(origin + Vec3::Y * 100.0).unwrap(), Vec3::X); + assert_eq!(mapping.origin_mm(), origin); + assert_eq!(mapping.axes(), [Vec3::Y, -Vec3::X, Vec3::Z]); + assert_eq!(mapping.repeat_mm(), Vec3::new(100.0, 20.0, 5.0)); +} + +#[test] +fn oblique_frame_has_analytic_coordinates_without_automatic_orthogonalization() { + let a = std::f64::consts::FRAC_1_SQRT_2; + let axes = [Vec3::new(a, a, 0.0), Vec3::new(-a, a, 0.0), Vec3::Z]; + let mapping = VisualMapping::new(Vec3::ZERO, axes, Vec3::new(2.0, 3.0, 4.0)).unwrap(); + close(mapping.coordinates(Vec3::new(2.0 * a, 2.0 * a, 0.0)).unwrap(), Vec3::X); + close(mapping.coordinates(Vec3::new(-3.0 * a, 3.0 * a, 4.0)).unwrap(), Vec3::new(0.0, 1.0, 1.0)); + assert_eq!(mapping.axes(), axes); +} + +#[test] +fn longest_local_axis_uses_xyz_ties_and_accepts_planar_bounds() { + for (extent, expected) in [ + (Vec3::new(3.0, 3.0, 3.0), GrainAxis::X), + (Vec3::new(2.0, 3.0, 3.0), GrainAxis::Y), + (Vec3::new(1.0, 2.0, 3.0), GrainAxis::Z), + (Vec3::new(0.0, 3.0, 0.0), GrainAxis::Y), + ] { + let min = Vec3::new(10.0, -4.0, 2.0); + let axis = suggest_grain_axis(Aabb3 { min, max: min + extent }).unwrap(); + assert_eq!(axis, expected); + assert!(VisualMapping::new(Vec3::ZERO, axis.axes(), Vec3::new(1.0, 1.0, 1.0)).is_ok()); + } +} + +#[test] +fn accepted_frame_does_not_flip_after_a_different_resize_suggestion() { + let first = suggest_grain_axis(Aabb3 { min: Vec3::ZERO, max: Vec3::new(100.0, 20.0, 10.0) }).unwrap(); + let mapping = VisualMapping::new(Vec3::ZERO, first.axes(), Vec3::new(10.0, 10.0, 10.0)).unwrap(); + let point = Vec3::new(25.0, 15.0, 5.0); + let before = mapping.coordinates(point).unwrap(); + assert_eq!(suggest_grain_axis(Aabb3 { min: Vec3::ZERO, max: Vec3::new(100.0, 200.0, 10.0) }).unwrap(), GrainAxis::Y); + assert_eq!(mapping.coordinates(point).unwrap(), before); + close(before, Vec3::new(2.5, 1.5, 0.5)); +} + +#[test] +fn rigid_instances_share_definition_coordinates_after_explicit_inverse_placement() { + let mapping = VisualMapping::new(Vec3::new(1.0, 2.0, 3.0), GrainAxis::Z.axes(), Vec3::new(5.0, 10.0, 20.0)).unwrap(); + let definition_point = Vec3::new(21.0, -8.0, 13.0); + let expected = Vec3::new(2.0, 2.0, -0.5); + close(mapping.coordinates(definition_point).unwrap(), expected); + // Independent analytic instance transform: (x,y,z) -> (-y,x,z) + translation. + let translation = Vec3::new(-300.0, 70.0, 12.0); + let world = Vec3::new(-definition_point.y, definition_point.x, definition_point.z) + translation; + let shifted = world - translation; + let inverted = Vec3::new(shifted.y, -shifted.x, shifted.z); + close(mapping.coordinates(inverted).unwrap(), expected); + // Passing world points directly is deliberately not corrected by the utility. + assert_ne!(mapping.coordinates(world).unwrap(), expected); +} + +#[test] +fn malformed_frames_refuse_instead_of_repairing_or_reflecting() { + for axes in [ + [Vec3::ZERO, Vec3::Y, Vec3::Z], + [Vec3::X * 2.0, Vec3::Y, Vec3::Z], + [Vec3::X, Vec3::X, Vec3::Z], + [Vec3::X, Vec3::Y, -Vec3::Z], + [Vec3::X, Vec3::new(0.01, 1.0, 0.0), Vec3::Z], + [Vec3::new(f64::NAN, 0.0, 0.0), Vec3::Y, Vec3::Z], + [Vec3::new(f64::MAX, 0.0, 0.0), Vec3::Y, Vec3::Z], + ] { + assert_eq!(VisualMapping::new(Vec3::ZERO, axes, Vec3::new(1.0, 1.0, 1.0)), Err(MappingError::Frame)); + } +} + +#[test] +fn hostile_positions_sizes_bounds_and_excessive_coordinates_refuse() { + let mapping = VisualMapping::new(Vec3::ZERO, GrainAxis::X.axes(), Vec3::new(1.0, 1.0, 1.0)).unwrap(); + for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, f64::MAX, MAX_LOCAL_MM * 2.0] { + let point = Vec3::new(value, 0.0, 0.0); + assert_eq!(VisualMapping::new(point, GrainAxis::X.axes(), Vec3::new(1.0, 1.0, 1.0)), Err(MappingError::Position)); + assert_eq!(mapping.coordinates(point), Err(MappingError::Position)); + assert_eq!(suggest_grain_axis(Aabb3 { min: Vec3::ZERO, max: point }), Err(MappingError::Bounds)); + } + for value in [0.0, -1.0, f64::NAN, f64::INFINITY, f64::MIN_POSITIVE, MIN_REPEAT_MM * 0.5, MAX_REPEAT_MM * 2.0] { + assert_eq!(VisualMapping::new(Vec3::ZERO, GrainAxis::X.axes(), Vec3::new(1.0, value, 1.0)), Err(MappingError::RepeatSize)); + } + for bounds in [Aabb3::EMPTY, Aabb3 { min: Vec3::X, max: Vec3::ZERO }, Aabb3 { min: Vec3::ZERO, max: Vec3::ZERO }] { + assert_eq!(suggest_grain_axis(bounds), Err(MappingError::Bounds)); + } + assert_eq!(mapping.coordinates(Vec3::new(MAX_REPEAT_COORDINATE + 1.0, 0.0, 0.0)), Err(MappingError::Coordinates)); +} + +#[test] +fn admitted_boundaries_remain_finite() { + let mapping = VisualMapping::new(Vec3::new(MAX_LOCAL_MM, 0.0, 0.0), GrainAxis::X.axes(), Vec3::new(MAX_REPEAT_MM, MIN_REPEAT_MM, 1.0)).unwrap(); + close(mapping.coordinates(Vec3::new(-MAX_LOCAL_MM, 0.0, 0.0)).unwrap(), Vec3::new(-2000.0, 0.0, 0.0)); + let tiny = VisualMapping::new(Vec3::ZERO, GrainAxis::X.axes(), Vec3::new(MIN_REPEAT_MM, 1.0, 1.0)).unwrap(); + close(tiny.coordinates(Vec3::new(1000.0, 0.0, 0.0)).unwrap(), Vec3::new(MAX_REPEAT_COORDINATE, 0.0, 0.0)); +} diff --git a/docs/render-visual-mapping.md b/docs/render-visual-mapping.md new file mode 100644 index 000000000..4181c354d --- /dev/null +++ b/docs/render-visual-mapping.md @@ -0,0 +1,55 @@ +# Definition-local visual mapping + +`solidcraft_render::mapping` provides numerical admission and coordinates for #1214, +the first mapping foundation under #786. It is original Rust code with no new +dependency or asset. It does not install a sampler, triplanar shader, texture pack, +document record, command or UI. No renderer capability changes. Textured wood is +not yet available through this utility. + +`VisualMapping::new(origin_mm, axes, repeat_mm)` admits an immutable frame. Origin +and axes belong to the body's **definition-local** space. Axes are ordered visual +grain/across/depth, not engineering L/R/T. They must be finite, unit length and +mutually perpendicular, with positive handedness. Squared lengths, dot products +and determinant use absolute tolerance `1e-10` for floating-point rotation error. +Values within that tolerance are retained exactly; no normalization, skew repair +or substitute frame is performed. Private fields and the absence of serde require +future loaders to go through admission. + +Repeat sizes are positive physical distances along those axes, not fractions of a +body's current bounds. Coordinates are the signed, unwrapped values +`dot(local_point_mm - origin_mm, axis_i) / repeat_mm_i`. Negative coordinates are +valid. Wrapping, filtering, map-role interpretation and normal-map tangent bases +belong to the eventual consumer. These coordinates alone do not define seamless +triplanar blending, end-grain appearance or an anisotropic optical model. + +Admission limits: + +- Each local origin/input coordinate: finite, absolute value at most `1e9` mm. +- Each repeat size: finite, `[0.001, 1e6]` mm. +- Each resulting repeat coordinate: finite, absolute value at most `1e6`. + +These are explicit numerical refusal bounds, not measured engineering ranges or +GPU quality guarantees. Calculations use f64; a future f32 shader needs its own +precision budget and supported scene limits. Values are never silently clamped. + +`suggest_grain_axis` considers only a finite, ordered definition-local AABB with +at least one positive extent. It selects the largest extent; exact ties use X, +then Y, then Z. Flat or line bounds are admissible, a point/empty box is not. Its +`GrainAxis::axes()` supplies a deterministic right-handed initial frame. A caller +must store an accepted frame once, and allow explicit edits; it must not rerun the +suggestion automatically when parameters change. `VisualMapping` holds no bounds +and therefore cannot independently flip on resize. + +For an instance, the host first inverts the actual rigid placement to recover +definition-local coordinates. This utility neither guesses placement from world +bounds nor implements another transform system. Mirroring, deformed/nonrigid +instances and face-specific mapping need explicit consumer policies. Tests use an +independent analytic quarter-turn/translation to check this coordinate convention; +they do not certify a document/assembly adapter that has not been installed. + +The remaining phases are persistence/copy/undo/reopen through existing appearance +commands, actual CPU/GPU texture consumption and honest unsupported-map behavior, +then manual controls and native/browser visual evidence. No document version is +reserved here. Source/license receipts and admitted resources must remain portable +when that consumer is added. Visual grain never changes mass, CAD bounds, mechanical +axes or manufacturing stock/nesting. #786/#813/#922 remain open.