Files
solidcraft/crates/render/src/surface_patterns.rs
T
dc38349cbf Layer split stage 1: the B-rep record, native body file and Vec/Plane come from solidcore-record (#11496)
* Kernel: the B-rep record and the native body file come from solidcore-record

SolidCraft's portable B-rep record (`solidcraft_geom::brep`: brep.rs, topology, history,
envelope, part, curve2) and the native body file (`solidcraft_kernel::native`: the tagged binary
codec and the container) move to solidcore's `solidcore-record` crate: geometry as data, with
structural validation and no maths (solidcore's docs/layers.md, stage 1). Every caller uses
`solidcore_record::brep` and `solidcore_record::native`; the old copies are deleted.

What computes from coordinates stays with the kernel, in geom's `brep`:
- `brep::check`: the record's geometric checks (orthonormal frames, non-degenerate planes,
  unit revolution axes, non-singular placements). `check::validate` and
  `check::validate_built` are the record's validation and these together, and every caller of
  `Brep::validate` uses them, so what is accepted is unchanged;
- `brep::label`: a surface's natural ranges (a cone's apex), `curve_interval`,
  `edge_curve_interval` and `form_turns`;
- `brep::pcurve::eval`: a pcurve's point;
- `geometry::check`, `placement::moved` and `split_edges` become functions on the record.

The kernel's native module keeps the conversion between a body and its saved record
(metadata.rs) and checks the decoded record's geometry. `native/analytic.rs`, which no module
declared, is deleted.

solidcore-record is pinned to its rev on solidcore's `layer-record` branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvoxKMbMFSQU8tzRtoJhtT

* Geometry: Vec2, Vec3, Plane and the profile types come from solidcore-record

The plain data of vectors and points, sketch planes and planar profiles (`Seg2`, `Loop2`,
`Region2`) moves to `solidcore-record`, with its constants and component-wise operators only
(owner decision, solidcore layer split). Their geometry stays in geom as traits:
`Vec2Geom`, `Vec3Geom`, `PlaneGeom`, `Seg2Geom`, `Loop2Geom`, `Region2Geom`, `Seg2ArcFit`,
`Loop2ArcFit` and `Region2ArcFit`, in scope with `use solidcraft_geom::prelude::*`. Every caller
names the types from `solidcore_record`; geom no longer defines or re-exports them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvoxKMbMFSQU8tzRtoJhtT

* Kernel: pin solidcore-record to solidcore main f5e8e9a29

solidcore-record is merged on solidcore main (tangency-labs/solidcore#2519); its crate there is
identical to the rev pinned before but for its clippy configuration. The lock is regenerated
against the merged rev.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NvoxKMbMFSQU8tzRtoJhtT

---------

Co-authored-by: jyviko <2501648+jyviko@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 09:04:26 -05:00

218 lines
8.7 KiB
Rust

//! Original periodic preview fields in an explicit world-space millimetre frame.
//! Only roughness and shading normals change; geometry and visibility do not.
use serde::{Deserialize, Serialize};
use solidcore_record::Vec3;
use solidcraft_geom::prelude::*;
use std::f64::consts::TAU;
use crate::job::{ErrorCode, JobError, Result};
use crate::surface::{MIN_ROUGHNESS, OpaqueSurface, unit_direction};
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct MappingFrame {
pub origin_mm: [f64; 3],
/// Right-handed unit axes, expressed in world coordinates.
pub axes: [[f64; 3]; 3],
}
impl Default for MappingFrame {
fn default() -> Self {
Self { origin_mm: [0.0; 3], axes: [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]] }
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SurfaceEffect {
#[serde(deserialize_with = "bounded_body_name")]
pub body: String,
#[serde(default)]
pub frame: MappingFrame,
pub repeat_mm: [f64; 3],
#[serde(default)]
pub roughness_amplitude: f64,
#[serde(default)]
pub bump_amplitude_mm: f64,
}
#[derive(Clone, Copy, Debug)]
pub struct PreparedEffect {
origin: Vec3,
axes: [Vec3; 3],
repeat: [f64; 3],
roughness: f64,
bump: f64,
}
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ShadingSurface {
pub surface: OpaqueSurface,
pub shading_normal: Vec3,
}
fn invalid(message: &'static str) -> JobError {
JobError::new(ErrorCode::InvalidRequest, message)
}
fn vector([x, y, z]: [f64; 3]) -> Vec3 {
Vec3::new(x, y, z)
}
fn bounded_position(p: Vec3) -> bool {
p.is_finite() && p.x.abs().max(p.y.abs()).max(p.z.abs()) <= 1.0e12
}
impl SurfaceEffect {
pub fn prepare(&self) -> Result<PreparedEffect> {
if self.body.is_empty() || self.body.len() > 256 || self.body.capacity() > 256 || self.body.chars().any(char::is_control) {
return Err(invalid("surface effect requires an exact bounded captured-body name"));
}
let origin = vector(self.frame.origin_mm);
let axes = self.frame.axes.map(vector);
if !bounded_position(origin)
|| axes.iter().any(|axis| !axis.is_finite() || (axis.dot(*axis) - 1.0).abs() > 1.0e-9)
|| axes.iter().enumerate().any(|(i, a)| axes.iter().skip(i + 1).any(|b| a.dot(*b).abs() > 1.0e-9))
|| (axes
.first()
.copied()
.ok_or_else(|| invalid("missing mapping axis"))?
.cross(*axes.get(1).ok_or_else(|| invalid("missing mapping axis"))?)
.dot(*axes.get(2).ok_or_else(|| invalid("missing mapping axis"))?)
- 1.0)
.abs()
> 1.0e-9
{
return Err(invalid("surface mapping frame must be finite, right-handed and orthonormal"));
}
if !self.repeat_mm.iter().all(|n| n.is_finite() && (0.001..=1.0e6).contains(n))
|| !self.roughness_amplitude.is_finite()
|| !(0.0..=1.0).contains(&self.roughness_amplitude)
|| !self.bump_amplitude_mm.is_finite()
|| !(0.0..=1.0e3).contains(&self.bump_amplitude_mm)
{
return Err(invalid("invalid surface repeat or amplitude"));
}
// Bound the L1 norm of the analytic height gradient before shading.
if self.repeat_mm.iter().map(|r| self.bump_amplitude_mm * TAU / (3.0 * r)).sum::<f64>() > 4.0 {
return Err(invalid("surface bump gradient exceeds preview bound 4"));
}
Ok(PreparedEffect { origin, axes, repeat: self.repeat_mm, roughness: self.roughness_amplitude, bump: self.bump_amplitude_mm })
}
}
fn bounded_body_name<'de, D: serde::Deserializer<'de>>(d: D) -> std::result::Result<String, D::Error> {
struct Name;
impl serde::de::Visitor<'_> for Name {
type Value = String;
fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("captured body name of 1..256 bytes without control characters")
}
fn visit_str<E: serde::de::Error>(self, value: &str) -> std::result::Result<String, E> {
if value.is_empty() || value.len() > 256 || value.chars().any(char::is_control) {
return Err(E::custom("bounded captured body name required"));
}
let mut name = String::new();
name.try_reserve_exact(value.len()).map_err(E::custom)?;
name.push_str(value);
Ok(name)
}
}
d.deserialize_str(Name)
}
pub(crate) fn deserialize_effects<'de, D: serde::Deserializer<'de>>(deserializer: D) -> std::result::Result<Option<Vec<SurfaceEffect>>, D::Error> {
struct Effects;
impl<'de> serde::de::Visitor<'de> for Effects {
type Value = Vec<SurfaceEffect>;
fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("at most 32 surface effects")
}
fn visit_seq<A: serde::de::SeqAccess<'de>>(self, mut sequence: A) -> std::result::Result<Self::Value, A::Error> {
let mut effects = Vec::new();
while let Some(effect) = sequence.next_element()? {
if effects.len() == 32 {
return Err(serde::de::Error::custom("at most 32 surface effects"));
}
effects.push(effect);
}
Ok(effects)
}
}
deserializer.deserialize_seq(Effects).map(Some)
}
pub fn validate_effects(effects: &[SurfaceEffect]) -> Result<()> {
if effects.len() > 32 {
return Err(invalid("at most 32 surface effects"));
}
for (i, effect) in effects.iter().enumerate() {
effect.prepare()?;
if effects.iter().take(i).any(|old| old.body == effect.body) {
return Err(invalid("duplicate surface-effect body target"));
}
}
Ok(())
}
impl PreparedEffect {
pub fn is_identity(self) -> bool {
self.roughness == 0.0 && self.bump == 0.0
}
/// Height in mm, world gradient in mm/mm, and a dimensionless roughness field.
pub fn field(self, position: Vec3) -> Result<(f64, Vec3, f64)> {
if !bounded_position(position) {
return Err(invalid("surface sample position exceeds millimetre bounds"));
}
let offset = position - self.origin;
let (mut height, mut gradient, mut roughness) = (0.0, Vec3::ZERO, 0.0);
for (axis, repeat) in self.axes.iter().zip(self.repeat) {
let cycles = offset.dot(*axis) / repeat;
if !cycles.is_finite() || cycles.abs() > 1.0e9 {
return Err(invalid("surface sample exceeds periodic precision bound"));
}
let phase = TAU * cycles.rem_euclid(1.0);
let (sine, cosine) = phase.sin_cos();
height += self.bump * sine / 3.0;
gradient += *axis * (self.bump * TAU * cosine / (3.0 * repeat));
roughness += cosine / 3.0;
}
Ok((height, gradient, roughness))
}
pub fn apply(self, surface: OpaqueSurface, shading_normal: Vec3, geometric_normal: Vec3, position: Vec3) -> Result<ShadingSurface> {
if self.is_identity() {
return Ok(ShadingSurface { surface, shading_normal });
}
let (_, gradient, field) = self.field(position)?;
let normal = unit_direction(shading_normal).map_err(|_| invalid("invalid shading normal"))?;
let geometric = unit_direction(geometric_normal).map_err(|_| invalid("invalid geometric normal"))?;
let mut changed = shading_normal;
if self.bump != 0.0 {
let tangent = gradient - normal * gradient.dot(normal);
let candidate = unit_direction(normal - tangent).map_err(|_| invalid("invalid bump normal"))?;
// Never turn the normal through the geometric surface. Visibility and
// offsets continue to use the original geometric normal independently.
changed = if candidate.dot(geometric) > 0.0 { candidate } else { shading_normal };
}
let surface = if self.roughness == 0.0 {
surface
} else {
let changed = OpaqueSurface::new(
surface.base_color(),
surface.metallic(),
(surface.roughness() + self.roughness * field).clamp(MIN_ROUGHNESS, 1.0),
surface.dielectric_ior(),
)
.map_err(|_| invalid("invalid procedural surface"))?;
// GPU2 shares this surface type. Changing the substrate roughness
// must retain an already captured coat for direct-light evaluation.
surface.clear_coat().map_or(changed, |coat| changed.with_clear_coat(coat))
};
Ok(ShadingSurface { surface, shading_normal: changed })
}
}
#[cfg(test)]
#[path = "surface_patterns_tests.rs"]
mod tests;