* 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>
372 lines
16 KiB
Rust
372 lines
16 KiB
Rust
//! Original anisotropic GGX reflection with separable Smith masking and Schlick Fresnel.
|
|
//!
|
|
//! Mathematics: Heitz, JCGT 7(4), 2018, equations 1 and 2,
|
|
//! <https://jcgt.org/published/0007/04/01/>. No external implementation adapted.
|
|
//! The explicit legacy numerical controls use the **NDF**:
|
|
//! `p(h) = D(h) * n.h`, then `p(l) = p(h) / (4 * v.h)`.
|
|
//! Rejected reflections are null events, never resampled or renormalized.
|
|
//! The separate `sample_visible_reflection` API uses a matched GGX VNDF and PDF.
|
|
//! Its original spherical-cap construction follows Dupuy and Benyoub (2023),
|
|
//! <https://arxiv.org/abs/2306.05044>; see docs/render-vndf-prototype.md.
|
|
//!
|
|
//! This numerical module does not install a renderer, persist a material or alter
|
|
//! engineering axes. The visual frame's normal may be a shading normal, but the
|
|
//! original geometric normal is required separately to reject below-surface rays.
|
|
//! Consumers retain geometric normals for ray spawning and optical boundaries.
|
|
//! No shading-normal energy correction, multiple scattering or transmission is modeled.
|
|
|
|
use solidcraft_geom::prelude::*;
|
|
use std::f64::consts::{PI, TAU};
|
|
|
|
use solidcore_record::Vec3;
|
|
|
|
use crate::surface::{MIN_ROUGHNESS, OpaqueSurface, SurfaceError, unit_direction};
|
|
|
|
/// Admission or finite-arithmetic failure in the anisotropic numerical contract.
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
|
pub enum AnisotropicError {
|
|
/// An existing opaque-surface parameter or direction was invalid.
|
|
Surface(SurfaceError),
|
|
/// A visual frame was not orthogonal, or opposed its geometric normal.
|
|
Frame,
|
|
/// A variate was not finite in the half-open interval [0, 1).
|
|
Variates,
|
|
/// A computed density, response or sample weight was not finite/nonnegative.
|
|
Arithmetic,
|
|
}
|
|
|
|
impl From<SurfaceError> for AnisotropicError {
|
|
fn from(value: SurfaceError) -> Self {
|
|
Self::Surface(value)
|
|
}
|
|
}
|
|
|
|
impl std::fmt::Display for AnisotropicError {
|
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
match self {
|
|
Self::Surface(e) => std::fmt::Display::fmt(e, f),
|
|
Self::Frame => f.write_str("visual frame must be orthogonal and face the geometric normal"),
|
|
Self::Variates => f.write_str("anisotropic variates must be finite in [0, 1)"),
|
|
Self::Arithmetic => f.write_str("anisotropic result must be finite and nonnegative"),
|
|
}
|
|
}
|
|
}
|
|
impl std::error::Error for AnisotropicError {}
|
|
|
|
type Result<T> = std::result::Result<T, AnisotropicError>;
|
|
|
|
/// Right-handed orthonormal visual axes; independent of engineering material axes.
|
|
#[derive(Clone, Copy, Debug, PartialEq)]
|
|
pub struct VisualFrame {
|
|
normal: Vec3,
|
|
tangent: Vec3,
|
|
bitangent: Vec3,
|
|
}
|
|
|
|
impl VisualFrame {
|
|
/// Normalize finite nonzero orthogonal inputs. An arbitrary oblique tangent is
|
|
/// refused rather than silently choosing a different brushed direction.
|
|
/// Roundoff within 1e-10 of perpendicular is removed by orthogonalization.
|
|
pub fn new(normal: Vec3, tangent: Vec3) -> Result<Self> {
|
|
let normal = unit_direction(normal)?;
|
|
let tangent = unit_direction(tangent)?;
|
|
let dot = normal.dot(tangent);
|
|
if dot.abs() > 1e-10 {
|
|
return Err(AnisotropicError::Frame);
|
|
}
|
|
let tangent = unit_direction(tangent - normal * dot)?;
|
|
let bitangent = unit_direction(normal.cross(tangent))?;
|
|
Ok(Self { normal, tangent, bitangent })
|
|
}
|
|
|
|
/// Shading normal, never a replacement for an original geometric normal.
|
|
pub fn normal(self) -> Vec3 {
|
|
self.normal
|
|
}
|
|
|
|
/// Visual X axis, associated with the first roughness.
|
|
pub fn tangent(self) -> Vec3 {
|
|
self.tangent
|
|
}
|
|
|
|
/// Visual Y axis, associated with the second roughness.
|
|
pub fn bitangent(self) -> Vec3 {
|
|
self.bitangent
|
|
}
|
|
|
|
fn local(self, direction: Vec3) -> Vec3 {
|
|
Vec3::new(self.tangent.dot(direction), self.bitangent.dot(direction), self.normal.dot(direction))
|
|
}
|
|
|
|
fn world(self, local: Vec3) -> Vec3 {
|
|
self.tangent * local.x + self.bitangent * local.y + self.normal * local.z
|
|
}
|
|
|
|
fn geometric(self, normal: Vec3) -> Result<Vec3> {
|
|
let normal = unit_direction(normal)?;
|
|
if normal.dot(self.normal) <= 0.0 {
|
|
return Err(AnisotropicError::Frame);
|
|
}
|
|
Ok(normal)
|
|
}
|
|
}
|
|
|
|
/// A bounded opaque response with two perceptual roughness axes in [0.045, 1].
|
|
/// Alpha is roughness squared, matching [`OpaqueSurface`].
|
|
#[derive(Clone, Copy, Debug, PartialEq)]
|
|
pub struct AnisotropicSurface {
|
|
base: OpaqueSurface,
|
|
roughness_y: f64,
|
|
}
|
|
|
|
/// One reflected **specular-only** sample. Fields are in world coordinates.
|
|
/// Its producing method identifies the NDF or visible-normal proposal.
|
|
#[derive(Clone, Copy, Debug, PartialEq)]
|
|
pub struct ReflectionSample {
|
|
/// Outgoing direction, pointing away from the surface.
|
|
pub direction: Vec3,
|
|
/// Unconditional density per steradian, without renormalizing null events.
|
|
pub pdf: f64,
|
|
/// `specular_brdf * shading_cosine / pdf`, in linear RGB.
|
|
/// Diffuse response is excluded; its sampling strategy belongs to the consumer.
|
|
pub weight: Vec3,
|
|
}
|
|
|
|
impl AnisotropicSurface {
|
|
/// Linear-sRGB reflectance, metal fraction and IOR use the opaque contract.
|
|
/// Perfect delta mirrors and out-of-range roughness are refused, not clamped.
|
|
pub fn new(base_color: Vec3, metallic: f64, roughness_x: f64, roughness_y: f64, dielectric_ior: f64) -> Result<Self> {
|
|
let base = OpaqueSurface::new(base_color, metallic, roughness_x, dielectric_ior)?;
|
|
if !roughness_y.is_finite() || !(MIN_ROUGHNESS..=1.0).contains(&roughness_y) {
|
|
return Err(SurfaceError::Roughness.into());
|
|
}
|
|
Ok(Self { base, roughness_y })
|
|
}
|
|
|
|
/// Admitted perceptual roughness along visual X and Y.
|
|
pub fn roughness(self) -> [f64; 2] {
|
|
[self.base.roughness(), self.roughness_y]
|
|
}
|
|
|
|
fn alpha(self) -> [f64; 2] {
|
|
[self.base.roughness().powi(2), self.roughness_y.powi(2)]
|
|
}
|
|
|
|
fn fresnel(self, cosine: f64) -> Vec3 {
|
|
self.base.specular_fresnel(cosine)
|
|
}
|
|
|
|
fn distribution_local(self, h: Vec3) -> f64 {
|
|
if h.z <= 0.0 {
|
|
return 0.0;
|
|
}
|
|
let [ax, ay] = self.alpha();
|
|
let q = (h.x / ax).powi(2) + (h.y / ay).powi(2) + h.z * h.z;
|
|
1.0 / (PI * ax * ay * q * q)
|
|
}
|
|
|
|
// Smith G1 / cosine, avoiding division by tiny cosines and tan(theta).
|
|
fn visibility(self, w: Vec3) -> f64 {
|
|
let [ax, ay] = self.alpha();
|
|
2.0 / (w.z + (w.z * w.z + (ax * w.x).powi(2) + (ay * w.y).powi(2)).sqrt())
|
|
}
|
|
|
|
/// GGX normal distribution D, per steradian of microfacet normal.
|
|
/// This is not a normalized probability density: [`Self::normal_pdf`] is.
|
|
pub fn distribution(self, frame: VisualFrame, half: Vec3) -> Result<f64> {
|
|
finite_scalar(self.distribution_local(frame.local(unit_direction(half)?)))
|
|
}
|
|
|
|
/// Projected NDF density `D(h) * n.h` on the upper shading hemisphere.
|
|
/// Its integral over that hemisphere is one.
|
|
pub fn normal_pdf(self, frame: VisualFrame, half: Vec3) -> Result<f64> {
|
|
let h = frame.local(unit_direction(half)?);
|
|
finite_scalar(self.distribution_local(h) * h.z.max(0.0))
|
|
}
|
|
|
|
/// Sample the projected NDF by stretching a radial GGX slope distribution.
|
|
/// The inverse radial CDF is `r = sqrt(u/(1-u))`; homogeneous coordinates
|
|
/// `(alpha_x*sqrt(u)*cos(phi), alpha_y*sqrt(u)*sin(phi), sqrt(1-u))`
|
|
/// avoid a large intermediate radius. No heap, rejection loop or RNG is used.
|
|
pub fn sample_normal(self, frame: VisualFrame, variates: [f64; 2]) -> Result<Vec3> {
|
|
let [u, azimuth] = variates;
|
|
if !variates.into_iter().all(|v| v.is_finite() && (0.0..1.0).contains(&v)) {
|
|
return Err(AnisotropicError::Variates);
|
|
}
|
|
let [ax, ay] = self.alpha();
|
|
let phi = TAU * azimuth;
|
|
let radial = u.sqrt();
|
|
let h = unit_direction(Vec3::new(ax * radial * phi.cos(), ay * radial * phi.sin(), (1.0 - u).sqrt()))?;
|
|
Ok(unit_direction(frame.world(h))?)
|
|
}
|
|
|
|
/// One view-conditioned visible-normal attempt. The legacy `sample_normal`
|
|
/// remains an explicitly projected-NDF utility, not this production proposal.
|
|
/// An upper-hemisphere view is required; no retries or probability clamps.
|
|
pub fn sample_visible_normal(self, frame: VisualFrame, view: Vec3, variates: [f64; 2]) -> Result<Option<Vec3>> {
|
|
if !variates.into_iter().all(|u| u.is_finite() && (0.0..1.0).contains(&u)) {
|
|
return Err(AnisotropicError::Variates);
|
|
}
|
|
let v = frame.local(unit_direction(view)?);
|
|
if v.z <= 0.0 {
|
|
return Ok(None);
|
|
}
|
|
let [ax, ay] = self.alpha();
|
|
let stretched = unit_direction(Vec3::new(ax * v.x, ay * v.y, v.z))?;
|
|
// The reflected unit-roughness hemisphere is uniform on z in [-v.z,1].
|
|
// Factor the radial square, avoiding a negative 1-z*z from cancellation.
|
|
let z = 1.0 - variates[0] * (1.0 + stretched.z);
|
|
let radius = ((1.0 - z) * (1.0 + z)).sqrt();
|
|
let phi = TAU * variates[1];
|
|
// Directly retain (v+c).z; adding cap.z to v.z loses this positive
|
|
// component near the lower cap boundary. Normalization is homogeneous,
|
|
// so apply the covector stretch before the single local normalization.
|
|
let height = (1.0 - variates[0]) * (1.0 + stretched.z);
|
|
let h = unit_direction(Vec3::new(ax * (stretched.x + radius * phi.cos()), ay * (stretched.y + radius * phi.sin()), height))?;
|
|
Ok(Some(unit_direction(frame.world(h))?))
|
|
}
|
|
|
|
/// Visible-normal density D(h)*G1(v)*max(v.h,0)/(n.v), per steradian.
|
|
/// This is distinct from the projected-NDF `normal_pdf` utility.
|
|
pub fn visible_normal_pdf(self, frame: VisualFrame, view: Vec3, half: Vec3) -> Result<f64> {
|
|
let v = frame.local(unit_direction(view)?);
|
|
let h = frame.local(unit_direction(half)?);
|
|
let vh = v.dot(h);
|
|
if v.z <= 0.0 || h.z <= 0.0 || vh <= 0.0 {
|
|
return Ok(0.0);
|
|
}
|
|
finite_scalar(self.distribution_local(h) * self.visibility(v) * vh)
|
|
}
|
|
|
|
/// Matched unconditional VNDF reflected-direction density; null attempts are
|
|
/// not renormalized. Reflection's Jacobian cancels the positive v.h factor.
|
|
pub fn visible_reflection_pdf(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result<f64> {
|
|
let Some((v, _, h)) = self.directions(frame, geometric, view, light)? else { return Ok(0.0) };
|
|
finite_scalar(self.distribution_local(h) * self.visibility(v) * 0.25)
|
|
}
|
|
|
|
/// One VNDF specular attempt using the unchanged separable-Smith BSDF.
|
|
/// Weight f*cos/pdf reduces to F(v.h)*G1(l), without dividing by tiny n.v
|
|
/// or v.h. Geometric/shading rejection remains a zero event counted in R.
|
|
pub fn sample_visible_reflection(self, frame: VisualFrame, geometric: Vec3, view: Vec3, variates: [f64; 2]) -> Result<Option<ReflectionSample>> {
|
|
let geometric_unit = frame.geometric(geometric)?;
|
|
let view_unit = unit_direction(view)?;
|
|
let Some(half) = self.sample_visible_normal(frame, view, variates)? else { return Ok(None) };
|
|
if geometric_unit.dot(view_unit) <= 0.0 {
|
|
return Ok(None);
|
|
}
|
|
let vh = view_unit.dot(half);
|
|
if vh <= 0.0 {
|
|
return Ok(None);
|
|
}
|
|
let light = unit_direction(half * (2.0 * vh) - view_unit)?;
|
|
let Some((v, l, h)) = self.directions(frame, geometric, view, light)? else { return Ok(None) };
|
|
let pdf = finite_scalar(self.distribution_local(h) * self.visibility(v) * 0.25)?;
|
|
if pdf <= 0.0 {
|
|
return Err(AnisotropicError::Arithmetic);
|
|
}
|
|
let weight = finite_rgb(self.fresnel(v.dot(h)) * (l.z * self.visibility(l)))?;
|
|
Ok(Some(ReflectionSample { direction: light, pdf, weight }))
|
|
}
|
|
|
|
fn directions(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result<Option<(Vec3, Vec3, Vec3)>> {
|
|
let geometric = frame.geometric(geometric)?;
|
|
let view = unit_direction(view)?;
|
|
let light = unit_direction(light)?;
|
|
let (v, l) = (frame.local(view), frame.local(light));
|
|
if v.z <= 0.0 || l.z <= 0.0 || geometric.dot(view) <= 0.0 || geometric.dot(light) <= 0.0 {
|
|
return Ok(None);
|
|
}
|
|
let h = unit_direction(view + light)?;
|
|
Ok(Some((v, l, frame.local(h))))
|
|
}
|
|
|
|
fn specular_local(self, v: Vec3, l: Vec3, h: Vec3) -> Result<Vec3> {
|
|
finite_rgb(self.fresnel(v.dot(h)) * (self.distribution_local(h) * 0.25 * self.visibility(v) * self.visibility(l)))
|
|
}
|
|
|
|
/// Specular component only, with independent geometric hemisphere rejection.
|
|
/// All input directions point away from the surface.
|
|
pub fn specular_brdf(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result<Vec3> {
|
|
let Some((v, l, h)) = self.directions(frame, geometric, view, light)? else { return Ok(Vec3::ZERO) };
|
|
self.specular_local(v, l, h)
|
|
}
|
|
|
|
/// Full opaque BRDF, including the same symmetric attenuated Lambert term as
|
|
/// [`OpaqueSurface`]. No radiance, cosine, exposure or display transform included.
|
|
/// Equal roughness axes delegate to the existing isotropic numerical contract.
|
|
pub fn brdf(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result<Vec3> {
|
|
let Some((v, l, h)) = self.directions(frame, geometric, view, light)? else { return Ok(Vec3::ZERO) };
|
|
if self.base.roughness() == self.roughness_y {
|
|
return Ok(self.base.brdf(frame.normal, view, light)?);
|
|
}
|
|
let specular = self.specular_local(v, l, h)?;
|
|
let fv = self.fresnel(v.z);
|
|
let fl = self.fresnel(l.z);
|
|
let diffuse = self.base.base_color() * ((1.0 - self.base.metallic()) / PI);
|
|
finite_rgb(
|
|
specular
|
|
+ Vec3::new(
|
|
(1.0 - fv.x) * (1.0 - fl.x) * diffuse.x,
|
|
(1.0 - fv.y) * (1.0 - fl.y) * diffuse.y,
|
|
(1.0 - fv.z) * (1.0 - fl.z) * diffuse.z,
|
|
),
|
|
)
|
|
}
|
|
|
|
/// Unconditional reflected-direction density for the specular NDF sampler.
|
|
/// Integrates to the acceptance probability, not necessarily one: invalid
|
|
/// microfacets and below-geometric/shading-hemisphere reflections are null events.
|
|
/// A mixture with a diffuse or environment sampler must use its own mixture PDF.
|
|
pub fn reflection_pdf(self, frame: VisualFrame, geometric: Vec3, view: Vec3, light: Vec3) -> Result<f64> {
|
|
let Some((v, _, h)) = self.directions(frame, geometric, view, light)? else { return Ok(0.0) };
|
|
finite_scalar(self.distribution_local(h) * h.z.max(0.0) / (4.0 * v.dot(h).max(0.0)))
|
|
}
|
|
|
|
/// One specular NDF attempt. `None` is a zero-contribution event and must
|
|
/// still count towards the consumer's sample denominator. Never retry until
|
|
/// success. Ray origins/visibility use the consumer's original geometric data.
|
|
pub fn sample_reflection(self, frame: VisualFrame, geometric: Vec3, view: Vec3, variates: [f64; 2]) -> Result<Option<ReflectionSample>> {
|
|
let geometric = frame.geometric(geometric)?;
|
|
let view = unit_direction(view)?;
|
|
let half = self.sample_normal(frame, variates)?;
|
|
let v = frame.local(view);
|
|
if v.z <= 0.0 || geometric.dot(view) <= 0.0 {
|
|
return Ok(None);
|
|
}
|
|
let vh = view.dot(half);
|
|
if vh <= 0.0 {
|
|
return Ok(None);
|
|
}
|
|
let light = unit_direction(half * (2.0 * vh) - view)?;
|
|
let l = frame.local(light);
|
|
if l.z <= 0.0 || geometric.dot(light) <= 0.0 {
|
|
return Ok(None);
|
|
}
|
|
let h = frame.local(half);
|
|
let pdf = self.reflection_pdf(frame, geometric, view, light)?;
|
|
if pdf <= 0.0 {
|
|
return Err(AnisotropicError::Arithmetic);
|
|
}
|
|
// Cancel D algebraically in f_spec * cos / pdf. No tiny-cosine division.
|
|
let weight = finite_rgb(self.fresnel(vh) * (self.visibility(v) * (self.visibility(l) * l.z) * vh / h.z))?;
|
|
Ok(Some(ReflectionSample { direction: light, pdf, weight }))
|
|
}
|
|
}
|
|
|
|
fn finite_scalar(value: f64) -> Result<f64> {
|
|
if value.is_finite() && value >= 0.0 { Ok(value) } else { Err(AnisotropicError::Arithmetic) }
|
|
}
|
|
|
|
fn finite_rgb(value: Vec3) -> Result<Vec3> {
|
|
if value.is_finite() && [value.x, value.y, value.z].into_iter().all(|c| c >= 0.0) { Ok(value) } else { Err(AnisotropicError::Arithmetic) }
|
|
}
|
|
|
|
#[cfg(test)]
|
|
#[path = "anisotropic_surface_tests.rs"]
|
|
mod tests;
|
|
|
|
#[cfg(test)]
|
|
#[path = "anisotropic_vndf_tests.rs"]
|
|
mod vndf_tests;
|