forked from 1b-agent/fieldcraft-upstream
* mesh: one transfinite interpolation for mapped hex and mesh.block; stable oracle report mesh.block's lattice is now built from the structured hex mesher's transfinite code: faces by quad::transfinite_grid, the interior by the new quad::transfinite_volume (Gordon-Thiel, blended by the block's graded parameters), which hex::mapped now calls too. 2D patches are the transfinite_grid of their sides. Edge curves return their corners exactly. Oracle: a zero-reference quantity (rounding noise) keeps its absolute tolerance as its fixture band, and docs/oracle.md shows such noise and relative errors inside the fixture band as bounds, so the report no longer changes with the order of floating-point operations (it failed the 'docs/oracle.md is current' check on main after #50). Scordelis-Lo moved by 1.4e-9 relative (an ill-conditioned thin shell of solids: sub-ulp node changes) and is re-blessed. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm * simplify: shared face filling and lattice index; faces blended like the volume; exact ends for every edge quad::transfinite_faces fills a block's six faces (with a per-face hook that hex::mapped uses to project onto its B-rep faces) and quad::lattice_index fixes the lattice layout for all three users. transfinite_grid_blended blends faces by the block's graded parameters, so faces and interior use one parametrisation and mesh.block reproduces its earlier Gordon-Hall lattice (the Scordelis-Lo fixture is back to its blessed value). Straight edges also return their corners exactly. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm --------- Co-authored-by: jyviko <[email protected]> Co-authored-by: Claude Opus 5.5 <[email protected]>
333 lines
16 KiB
Rust
333 lines
16 KiB
Rust
//! Planar all-quadrilateral meshing: mapped (transfinite) meshes of four-sided regions and free
|
||
//! meshes of polygons with holes, on prescribed boundary nodes.
|
||
//!
|
||
//! These are the face meshers under the mapped and swept hexahedral meshers and shell meshing.
|
||
//! Both take the boundary nodes as given (shared edges must share nodes), put them first in the
|
||
//! output in input order, and return counterclockwise `Quad4` connectivity whose every element is
|
||
//! proven valid by the exact corner test ([`crate::quality::planar_quad_validity`]).
|
||
//!
|
||
//! # Mapped: [`mapped_quad_mesh`], [`transfinite_grid`]
|
||
//! Transfinite interpolation (Gordon and Hall 1973), see [`tfi`]. Opposite sides need equal
|
||
//! division counts; a region whose TFI folds (strongly concave sides) is an error, not a tangled
|
||
//! mesh.
|
||
//!
|
||
//! # Free: [`free_quad_mesh`]
|
||
//! **Method.** An indirect tri-to-quad method in three steps:
|
||
//! 1. Keep every other boundary point of each loop (the parity class with the sharper turns, so
|
||
//! corners at even spacing survive) and build the constrained Delaunay triangulation of that
|
||
//! half-resolution region, refined to twice the target size ([`cdt`]: Bowyer–Watson, Sloan
|
||
//! 1993 recovery, Ruppert 1995 refinement without segment splitting).
|
||
//! 2. Recombine adjacent triangles into strictly convex quadrilaterals, greedily, best first by
|
||
//! the smallest corner scaled Jacobian (Lee and Lo, *A new scheme for the generation of a
|
||
//! graded quadrilateral mesh*, Computers & Structures 52(5):847–857, 1994).
|
||
//! 3. Split every element once: a quadrilateral into four, a leftover triangle into three, through
|
||
//! edge mid nodes and a centre node. On a boundary edge the mid node is the prescribed point the
|
||
//! half-resolution loop skipped, so the final boundary nodes are exactly the input points. The
|
||
//! split is the Catmull–Clark topology (Catmull and Clark, CAD 10(6):350–355, 1978) and appears
|
||
//! as the all-quad completion of recombination in Lee and Lo 1994.
|
||
//!
|
||
//! Then constrained Laplacian smoothing ([`smooth`]) and the exact validity gate.
|
||
//!
|
||
//! **Why this method.** The alternatives considered, from their papers:
|
||
//! - *Q-Morph* (Owen, Staten, Canann, Saigal, *Q-Morph: an indirect approach to advancing front
|
||
//! quad meshing*, IJNME 44(9):1317–1340, 1999) gives better-aligned rows along the boundary, but
|
||
//! needs front-edge state classification, side-edge recovery by swaps, seam closing and special
|
||
//! handling where fronts collide; the paper reports the cases that need it, and each is a place
|
||
//! to fail on concave faces with many holes. An odd front remainder still ends in a triangle
|
||
//! to be removed.
|
||
//! - *Paving* (Blacker and Stephenson, IJNME 32(4):811–847, 1991) has the same front-collision
|
||
//! problem with no background triangulation to fall back on; it is the highest-risk choice.
|
||
//! - *Blossom-Quad* (Remacle, Lambrechts, Seny, Marchandise, Johnen, Geuzaine, *Blossom-Quad: a
|
||
//! non-uniform quadrilateral mesh generator using a minimum-cost perfect-matching algorithm*,
|
||
//! IJNME 89(9):1102–1119, 2012; paper only, Gmsh's code is GPL) gives the best matching, but a
|
||
//! perfect matching of the triangle graph need not exist, so it still needs a fallback, and it
|
||
//! needs Edmonds' weighted blossom algorithm (cubic in the worst case).
|
||
//!
|
||
//! The split method is **all-quad by construction**: any triangulation of the half-resolution
|
||
//! region becomes quadrilaterals only, whatever the matching found, so the only requirement is an
|
||
//! even number of boundary points on every loop. Robustness on concave regions with holes is
|
||
//! that of the constrained Delaunay triangulation, which exists for every valid input and is
|
||
//! built here with exact predicates. The implementation risk is low: one triangulator (which the
|
||
//! surface and tetrahedral work need anyway), a greedy matching and a local split. The cost is
|
||
//! quality: the split creates irregular nodes (valence 3 at triangle centres, 6 at some coarse
|
||
//! vertices) and triangle-born quads have a 120° corner; smoothing removes most of the
|
||
//! distortion. If that proves too weak, the greedy matching can be replaced by Blossom-Quad's
|
||
//! minimum-cost matching without touching the rest (fewer leftover triangles, same guarantee).
|
||
//!
|
||
//! **Requirements and failure modes.**
|
||
//! - Every loop has an even number of points, at least 6 when there is more than one loop (a
|
||
//! single 4-point loop is meshed as one quadrilateral). An odd loop is an error, never repaired:
|
||
//! the points are prescribed by neighbouring faces, so adding one would break conformity. Choose
|
||
//! divisions with [`crate::size::loop_divisions`] or [`crate::size::even_divisions`].
|
||
//! - The chords joining every other boundary point must not cross (a boundary too coarse for a
|
||
//! thin feature); both parity classes are tried before this is reported.
|
||
//! - Every output element is checked with exact predicates; a mesh that smoothing cannot make
|
||
//! valid is an error.
|
||
//! - Hostile input (NaN, coordinates beyond the model limit, repeated points, zero-length edges,
|
||
//! crossing or touching loops, holes outside the outer loop or inside another hole) is an
|
||
//! [`Error::Invalid`]; size and work limits are [`Error::Limit`].
|
||
|
||
mod cdt;
|
||
mod domain;
|
||
mod free;
|
||
mod guard;
|
||
mod smooth;
|
||
pub mod tfi;
|
||
|
||
pub use domain::{MAX_BOUNDARY_POINTS, MAX_LOOPS};
|
||
pub use tfi::{MAX_GRID_NODES, lattice_index, transfinite_faces, transfinite_grid, transfinite_grid_blended, transfinite_volume};
|
||
|
||
use crate::predicates::{Point2, Sign, snap_to_domain};
|
||
use crate::quality::{planar_corner, quad_axes, turns_left};
|
||
use crate::size::SizeField;
|
||
use crate::{Error, Result};
|
||
|
||
/// Limits and smoothing of the quad meshers.
|
||
#[derive(Debug, Clone, PartialEq)]
|
||
pub struct QuadOptions {
|
||
/// The most quadrilaterals of one mesh ([`Error::Limit`] beyond).
|
||
pub max_elements: usize,
|
||
/// Smoothing sweeps of the free mesher (0 turns smoothing off).
|
||
pub smoothing_sweeps: usize,
|
||
}
|
||
|
||
impl Default for QuadOptions {
|
||
fn default() -> Self {
|
||
QuadOptions { max_elements: 4_000_000, smoothing_sweeps: 10 }
|
||
}
|
||
}
|
||
|
||
/// What a quad mesher produced and how good it is.
|
||
#[derive(Debug, Clone, PartialEq)]
|
||
pub struct QuadStats {
|
||
/// Smallest corner scaled Jacobian over the mesh (1 for squares).
|
||
pub min_scaled_jacobian: f64,
|
||
/// Largest skew (0 for rectangles).
|
||
pub max_skew: f64,
|
||
/// Largest aspect ratio (1 for squares).
|
||
pub max_aspect_ratio: f64,
|
||
/// Smoothing sweeps run, and whether smoothing converged before its sweep limit.
|
||
pub smoothing_sweeps: usize,
|
||
pub smoothing_converged: bool,
|
||
/// Free mesher: triangle pairs recombined, and triangles split on their own.
|
||
pub recombined: usize,
|
||
pub leftover_triangles: usize,
|
||
}
|
||
|
||
impl Default for QuadStats {
|
||
fn default() -> Self {
|
||
QuadStats {
|
||
min_scaled_jacobian: 1.0,
|
||
max_skew: 0.0,
|
||
max_aspect_ratio: 1.0,
|
||
smoothing_sweeps: 0,
|
||
smoothing_converged: true,
|
||
recombined: 0,
|
||
leftover_triangles: 0,
|
||
}
|
||
}
|
||
}
|
||
|
||
/// A planar all-quadrilateral mesh.
|
||
#[derive(Debug, Clone, PartialEq)]
|
||
pub struct QuadMesh {
|
||
/// Node coordinates. `nodes[..boundary_nodes]` are the input boundary points, unchanged and
|
||
/// in input order (loop by loop), so node `k` of the mesh is boundary point `k`.
|
||
pub nodes: Vec<[f64; 2]>,
|
||
/// Counterclockwise corner node ids (the `Quad4` node order).
|
||
pub quads: Vec<[u32; 4]>,
|
||
pub boundary_nodes: usize,
|
||
pub stats: QuadStats,
|
||
}
|
||
|
||
/// A mapped mesh with its structure: node `(i, j)`, `0 ≤ i ≤ nu`, `0 ≤ j ≤ nv`, is
|
||
/// `mesh.nodes[grid[j·(nu + 1) + i]]`, with `i` running from corner 0 to corner 1 and `j` from
|
||
/// corner 1 to corner 2 (for a sweep: the source face's structured layout).
|
||
#[derive(Debug, Clone, PartialEq)]
|
||
pub struct MappedMesh {
|
||
pub mesh: QuadMesh,
|
||
pub nu: usize,
|
||
pub nv: usize,
|
||
pub grid: Vec<u32>,
|
||
}
|
||
|
||
/// Free all-quadrilateral mesh of a planar region (see the module docs for the method).
|
||
///
|
||
/// `loops[0]` is the outer boundary, the others are holes; each loop lists its boundary nodes
|
||
/// once (not closed), in either orientation, with an even count. `size` sets the interior
|
||
/// density; the boundary density is the given nodes.
|
||
pub fn free_quad_mesh(loops: &[Vec<[f64; 2]>], size: &dyn SizeField, opts: &QuadOptions) -> Result<QuadMesh> {
|
||
free::mesh(loops, size, opts)
|
||
}
|
||
|
||
/// A planar triangle mesh.
|
||
#[derive(Debug, Clone, PartialEq)]
|
||
pub struct TriMesh {
|
||
/// Node coordinates; `nodes[..boundary_nodes]` are the input boundary points in input order.
|
||
pub nodes: Vec<[f64; 2]>,
|
||
/// Counterclockwise corner node ids (the `Tri3` node order).
|
||
pub triangles: Vec<[u32; 3]>,
|
||
pub boundary_nodes: usize,
|
||
}
|
||
|
||
/// Free triangle mesh of a planar region on prescribed boundary nodes: the constrained Delaunay
|
||
/// triangulation of the loops ([`cdt`]: Bowyer–Watson, Sloan 1993 recovery), refined to the size
|
||
/// field by Ruppert-style circumcentre insertion that never splits a boundary edge (Steiner points
|
||
/// keep a clearance of half the local boundary spacing from the boundary), so the boundary nodes
|
||
/// are exactly the input points. Every triangle is checked counterclockwise with exact
|
||
/// predicates. Loops as for [`free_quad_mesh`], with any number of points (at least 3 each).
|
||
pub fn free_tri_mesh(loops: &[Vec<[f64; 2]>], size: &dyn SizeField, opts: &QuadOptions) -> Result<TriMesh> {
|
||
let region = domain::region(loops)?;
|
||
let mut chords = Vec::new();
|
||
for l in ®ion.loops {
|
||
for (i, &a) in l.iter().enumerate() {
|
||
let b = l.get((i + 1) % l.len()).copied().ok_or_else(|| Error::Failed("loop index".into()))?;
|
||
let (pa, pb) = (*region.point(a)?, *region.point(b)?);
|
||
let (ca, cb) = (pa.coords(), pb.coords());
|
||
let m = Point2::new(snap_to_domain(0.5 * (ca[0] + cb[0])), snap_to_domain(0.5 * (ca[1] + cb[1])))?;
|
||
chords.push((pa, pb, m));
|
||
}
|
||
}
|
||
let guard = guard::Guard::new(&chords)?;
|
||
let mut cdt = cdt::Cdt::build(®ion, opts.max_elements.saturating_add(4 * region.pts.len() + 16))?;
|
||
cdt.refine(size, 1.0, &|p, h| guard.allows(p, cdt::CLEARANCE * h))?;
|
||
let tri = cdt.into_triangulation();
|
||
if tri.tris.len() > opts.max_elements {
|
||
return Err(Error::Limit(format!("the mesh would have {} triangles; the limit is {}", tri.tris.len(), opts.max_elements)));
|
||
}
|
||
for t in &tri.tris {
|
||
let [a, b, c] = t.map(|v| tri.p2.get(v as usize));
|
||
match (a, b, c) {
|
||
(Some(a), Some(b), Some(c)) if crate::predicates::orient2d(a, b, c) == Sign::Positive => {}
|
||
_ => return Err(Error::Failed("a triangle is inverted or degenerate".into())),
|
||
}
|
||
}
|
||
Ok(TriMesh { nodes: tri.pts, triangles: tri.tris, boundary_nodes: region.pts.len() })
|
||
}
|
||
|
||
/// Mapped mesh of a four-sided region: `boundary` lists the region's boundary nodes once (either
|
||
/// orientation), and `corners` are the positions in it of the four corners in boundary order.
|
||
/// Opposite sides need the same number of divisions. The grid is transfinite interpolation
|
||
/// ([`transfinite_grid`]); a grid that folds is an error.
|
||
pub fn mapped_quad_mesh(boundary: &[[f64; 2]], corners: [usize; 4], opts: &QuadOptions) -> Result<MappedMesh> {
|
||
let region = domain::region(&[boundary.to_vec()])?;
|
||
let n = boundary.len();
|
||
if let Some(c) = corners.iter().find(|&&c| c >= n) {
|
||
return Err(Error::Invalid(format!("corner position {c} is outside the boundary of {n} points")));
|
||
}
|
||
let c0 = corners[0];
|
||
let d = corners.map(|c| (c + n - c0) % n);
|
||
if !(d[0] == 0 && d[0] < d[1] && d[1] < d[2] && d[2] < d[3]) {
|
||
return Err(Error::Invalid("the corners must be four distinct positions in boundary order".into()));
|
||
}
|
||
let (nu, nv) = (d[1], d[2] - d[1]);
|
||
if d[3] - d[2] != nu || n - d[3] != nv {
|
||
return Err(Error::Invalid(format!("opposite sides need the same number of divisions: {} and {}, {} and {}", nu, d[3] - d[2], nv, n - d[3])));
|
||
}
|
||
let at = |k: usize| region.pts.get((c0 + k) % n).copied().ok_or_else(|| Error::Failed("boundary index".into()));
|
||
let side = |from: usize, len: usize, forward: bool| -> Result<Vec<[f64; 2]>> {
|
||
(0..=len).map(|k| if forward { at(from + k) } else { at(from + n - k) }).collect()
|
||
};
|
||
// Boundary positions relative to corner 0: bottom 0..nu, right nu..nu+nv, top runs backwards
|
||
// from d[3], left backwards from 0 (= n).
|
||
let bottom = side(0, nu, true)?;
|
||
let right = side(d[1], nv, true)?;
|
||
let top = side(d[3], nu, false)?;
|
||
let left = side(n, nv, false)?;
|
||
let points = transfinite_grid(&bottom, &right, &top, &left)?;
|
||
// Node ids: boundary nodes keep their input positions; interior nodes follow, row by row.
|
||
let mut nodes = region.pts.clone();
|
||
let mut grid = Vec::with_capacity(points.len());
|
||
for j in 0..=nv {
|
||
for i in 0..=nu {
|
||
let pos = if j == 0 {
|
||
Some(i)
|
||
} else if i == nu {
|
||
Some(nu + j)
|
||
} else if j == nv {
|
||
Some(d[3] - i)
|
||
} else if i == 0 {
|
||
Some((n - j) % n)
|
||
} else {
|
||
None
|
||
};
|
||
let id = match pos {
|
||
Some(p) => ((c0 + p) % n) as u32,
|
||
None => {
|
||
let x = points.get(j * (nu + 1) + i).copied().ok_or_else(|| Error::Failed("grid index".into()))?;
|
||
nodes.push(domain::admissible(x)?);
|
||
nodes.len() as u32 - 1
|
||
}
|
||
};
|
||
grid.push(id);
|
||
}
|
||
}
|
||
let ccw = domain::loop_orientation(®ion, &(0..n as u32).collect::<Vec<_>>())? == Sign::Positive;
|
||
let g = |i: usize, j: usize| grid.get(j * (nu + 1) + i).copied().ok_or_else(|| Error::Failed("grid index".into()));
|
||
let mut quads = Vec::with_capacity(nu * nv);
|
||
for j in 0..nv {
|
||
for i in 0..nu {
|
||
let (a, b, c, e) = (g(i, j)?, g(i + 1, j)?, g(i + 1, j + 1)?, g(i, j + 1)?);
|
||
quads.push(if ccw { [a, b, c, e] } else { [a, e, c, b] });
|
||
}
|
||
}
|
||
if quads.len() > opts.max_elements {
|
||
return Err(Error::Limit(format!("the mesh would have {} quadrilaterals; the limit is {}", quads.len(), opts.max_elements)));
|
||
}
|
||
let mesh = finish(nodes, quads, n, &QuadOptions { smoothing_sweeps: 0, ..opts.clone() }, QuadStats::default())?;
|
||
Ok(MappedMesh { mesh, nu, nv, grid })
|
||
}
|
||
|
||
/// Smooth (free nodes only), gate every element with the exact validity test and measure.
|
||
pub(crate) fn finish(
|
||
mut nodes: Vec<[f64; 2]>,
|
||
quads: Vec<[u32; 4]>,
|
||
boundary_nodes: usize,
|
||
opts: &QuadOptions,
|
||
mut stats: QuadStats,
|
||
) -> Result<QuadMesh> {
|
||
// Constructed nodes (mid nodes, centres) stay in the predicates' domain.
|
||
for n in nodes.iter_mut() {
|
||
*n = [snap_to_domain(n[0]), snap_to_domain(n[1])];
|
||
}
|
||
if opts.smoothing_sweeps > 0 {
|
||
let (sweeps, converged) = smooth::smooth(&mut nodes, &quads, boundary_nodes, opts.smoothing_sweeps)?;
|
||
stats.smoothing_sweeps = sweeps;
|
||
stats.smoothing_converged = converged;
|
||
}
|
||
let mut invalid = 0usize;
|
||
let mut first_invalid = None;
|
||
let (mut sj, mut skew, mut aspect) = (f64::INFINITY, 0.0_f64, 1.0_f64);
|
||
for (e, q) in quads.iter().enumerate() {
|
||
let mut c = [[0.0; 2]; 4];
|
||
for (k, &v) in q.iter().enumerate() {
|
||
c[k] = nodes.get(v as usize).copied().ok_or_else(|| Error::Failed("node index".into()))?;
|
||
}
|
||
let [a, b, d, f] = c.map(|x| Point2::new(x[0], x[1]));
|
||
if !turns_left([&a?, &b?, &d?, &f?]) {
|
||
invalid += 1;
|
||
first_invalid.get_or_insert(e);
|
||
}
|
||
sj = sj.min((0..4).fold(f64::INFINITY, |m, i| m.min(planar_corner(&c, i).1.unwrap_or(0.0))));
|
||
let (r, k) = quad_axes(c.map(|x| [x[0], x[1], 0.0]));
|
||
aspect = aspect.max(r);
|
||
skew = skew.max(k);
|
||
}
|
||
if invalid > 0 {
|
||
let at = first_invalid.and_then(|e| quads.get(e)).and_then(|q| nodes.get(q[0] as usize)).copied().unwrap_or_default();
|
||
return Err(Error::Failed(format!(
|
||
"{invalid} of {} quadrilaterals are inverted or degenerate (first near {at:?}); refine the boundary there or use a finer size",
|
||
quads.len()
|
||
)));
|
||
}
|
||
if !quads.is_empty() {
|
||
stats.min_scaled_jacobian = sj;
|
||
stats.max_skew = skew;
|
||
stats.max_aspect_ratio = aspect;
|
||
}
|
||
Ok(QuadMesh { nodes, quads, boundary_nodes, stats })
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests;
|