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.
This commit is contained in:
selune authored and GitHub committed 2026-10-24 08:31:59 +02:00
1 parent f0995dab1c
commit ce1c8db7fb
5 files changed
+311

No files matched your search

+2
View File
@@ -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
+1
View File
@@ -13,6 +13,7 @@ mod curve_display;
mod gif;
pub mod job;
pub mod lighting;
pub mod mapping;
mod product;
mod raster;
mod scene;
+141
View File
@@ -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<GrainAxis, MappingError> {
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<Self, MappingError> {
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<Vec3, MappingError> {
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;
+112
View File
@@ -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));
}
+55
View File
@@ -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.