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:
1 parent
f0995dab1c
commit
ce1c8db7fb
5 files changed
+311
No files matched your search
@@ -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
|
||||
|
||||
@@ -13,6 +13,7 @@ mod curve_display;
|
||||
mod gif;
|
||||
pub mod job;
|
||||
pub mod lighting;
|
||||
pub mod mapping;
|
||||
mod product;
|
||||
mod raster;
|
||||
mod scene;
|
||||
|
||||
@@ -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;
|
||||
@@ -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));
|
||||
}
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user