Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-cad

Format-independent analytic CAD surface and face model, with rational B-spline evaluation and trimmed-surface tessellation.

A library written in luce-base. Latest release 0.9.5.

Install#

luc add dymokomi/luce-cad

Documentation#

luce-cad

Format-independent CAD foundation, entirely Luce Base. No STEP syntax, UI, editor commands or donor C/C++ dependencies.

The intended ownership is:

luce-step (file entities) → luce-cad (analytic faces/topology, surface evaluation and trimmed-surface meshing) → luce-geocore (display mesh).

Exports

  • cad (luce_cad.model): CadModel, the analytic model (a B-rep, or independent planar/NURBS faces), its placement, cv domain, overlays and tessellation.
  • cad_geometry (luce_cad.cad_geometry): CAD models as a family of luce-geocore's GeometrySet. The cad component holds models (shared, never copied), places, joins and filters them by face path; CadGeometry.tessellated(set, quality, progress) (a MeshQuality) turns them into the set's mesh in one pass (each face's B-rep path in the path text attribute; instances' prototypes tessellated once each, their placements kept). register_codec() adds the family to geocore's geometry files, so a set with CAD saves and loads as .prism (brep/codec.lucb: every column as stored, bit for bit; derived data is never written). cv_cloud, with_cv_cloud and is_cv_cloud expose the control vertices as a point cloud for geocore's point verbs (model/cv_cloud.lucb).
  • cad_edits (luce_cad.cad_edits): CadEdits, editing a set's models through a pick mesh (the display tessellations joined, tagged with cad_model, cad_face and cad_edge): pick_mesh, transformed_parts (whole models or faces' models moved by a group), without_parts (models or faces deleted) and with_model (a model added).
  • cad_solids (luce_cad.solids): CadSolids, analytic solids as closed B-reps (box, cylinder, cone or frustum, sphere, torus), centered on the origin along +Y with outward faces.
  • modeling (luce_cad.modeling): CadModeling, features that make and change closed solids: sketch profiles extruded and revolved, booleans (union, subtract, intersect), chamfers and fillets (G1, G2, G3) of lines between planes, lines between a plane and a cylinder, and rims, with corners where they meet. How each works and what is not supported yet: docs/MODELING.md.
  • measure (luce_cad.measure): CadMeasure, measuring without changing: check (continuity G0 to G3 across edges at stations, from exact third derivatives, with curvature combs and the lines that draw the result) and deviation (a model's tessellation colored by its signed distance from another's surfaces), and curve_join (how two curves meet, G0 to G4, by their arc-length derivatives). See docs/MODELING.md, Measuring.
  • cad_curves (luce_cad.cad_curves): CadCurves, a set's CAD curves as objects beside its bodies and sketches: free curves and curves on faces, named, drawn, picked and saved; their control points join the CV cloud.
  • curves (luce_cad.curves): CadCurveTools, curves through or with points, from a model's edges and isoparms, on a face, Blend Curve to G4, Attach, Close, Stretch and Reverse. See docs/MODELING.md, Curves.
  • surfacing (luce_cad.surfacing): CadSurfacing, surfacing Stage 3 on a geometry set: Project (along a vector or the normals) and Intersect as curves on faces; Trim (Keep, Discard, Divide) with trim stages Untrim pops, a face's natural surface without them; Trim Convert, Shrink; Stitch and Unstitch with tolerant edges. See docs/MODELING.md, Projection, trims and stitching.
  • cad_exact (luce_cad.exact, Base only): FaceSupport, the exact data exporters read (luce-usd writes CAD faces as USD NurbsPatch prims). model.face_support(face) copies a face's support out (kind, frame, radius or angle, a B-spline's net and knots, sense, placement), and model.face_trim_uv(face, divisions, uv, sizes) gives its trim loops in the support's UV chart, sampled at the display tessellation's baseline edge stations and chained across coedges as the tessellator chains them; both are methods of CadModel and BrepModel that Luce does not see (brep/exact.lucb, model/exact.lucb).

Analytic model API

cad.CadModel() owns independent faces and copies input arrays:

  • add_planar(boundary) adds a simple coplanar polygon boundary, preserving winding.
  • add_nurbs(points, weights, nu, nv, degree_u, degree_v, knots_u, knots_v) retains the exact rational control net and expanded knot vectors.
  • trim_rectangle(face, u0, u1, v0, v1) changes the NURBS face's rectangular parameter domain. Invalid edits leave the previous domain unchanged.
  • `tessellate(segments=16, edge_size=0, progress, curvature=false, directions=false, quick=false)` creates a display mesh without replacing analytic data (quick: a drag's preview, see below). Zero disables size refinement; positive values are target spacing in source units, not a guaranteed minimum/maximum edge length.
  • face_count() counts CAD faces, not tessellated polygons.
  • preview_face(face, divisions=8) produces one disposable display patch, without requiring the entire CAD model to fit a single polygon mesh.
  • preview(progress) previews every face on the worker pool (8 divisions for faces with more than 32 edges, else 16; then 4, then 16 on failure) and returns a CadPreviewSet: display batches of at most 4,096 points and 16,000 corners merged in face order, deduplicated analytic boundary segments (64 chords per curved edge), one normal guide per meshed face, and the failed-face count with the first failure as Patch N: message.
  • planned_face(face, segments=16, edge_size=0) is a B-rep diagnostic: build the complete shared-edge/layout plan, then mesh only the selected face. Unlike isolated preview, this retains the full cook's neighboring station decisions, source-face attributes, display triangulation and normals. Unused points are compacted. Success does not validate the other face jobs or prove that the full model tessellates; independent non-B-rep faces are not supported by this diagnostic.
  • face_edge_count/id/linear/point expose shared boundary identities and exact samples for cached patch outlines, independent of display triangle edges.
  • transformed(translation, rotation, scale) and placed(matrix) return a separate analytic model, retaining trim domains and preserving orientation under reflection.

Planar boundaries currently have one outer loop of 3 or more corners and absolute coplanarity tolerance 1e-6 in source units. A model holds any number of independent faces (their storage grows). A tessellation's cad_face numbers polygons as face_count() does: independent faces first, then the B-rep's.

B-rep storage, the cv domain and the tessellation caches

BrepModel is a structure of arrays: vertices, curves, surfaces, faces and loops are columns (geocore Columns with change ids, brep/model.lucb and brep/store.lucb), so copies of a model share them by count. The control vertices of every B-spline surface form the cv domain (cv_count, cv_position, cv_surface); with_cvs_moved(ids, delta) returns an O(1) copy that shares every column but the cv positions, and `withcvsat(ids, positions)` places cvs exactly (the editor's moves, through CadModel.with_cvs_placed). A moved surface's trim edges are re-projected onto it, so boundary cvs can move too; faces sharing an edge stay joined.

Edges and vertices carry a precision (edge_precision, vertex_precision; Parasolid's tolerant edges): 0 is the model's tolerance; Stitch gives an edge it joined across a gap the gap and how far its faces lie from it, and a merged vertex how far it lies from its edges' ends. Building an edge checks its ends against its vertices' precision, the codec keeps both columns, and meshing and modeling work to model_tolerance(), the largest of them.

Tessellation is a cache, not a conversion:

  • Per face (tessellation/face_cache.lucb): each face job's result is kept as a piece keyed by every input it reads: its support surface, the curves of its edge uses, its boundary points (by position, by which entries share a point and by id rank), its layout plan and the parameters. Corners name boundary points by their place in the face's boundary table, so pieces survive the id shifts of unrelated edges. A moved copy inherits the pieces: only faces whose inputs changed are meshed again (reused_faces() counts hits).
  • Per parameters: mesh(...) keeps the last four whole tessellations, each with the faces' paths in path. CadModel.tessellate with an identity placement returns the kept mesh, and CadGeometry.tessellated places a single model's kept mesh in the set without a copy: a Tessellate node with the viewport's settings is O(1) and its GPU buffers are the ones already made for the display.
  • Quick previews (brep/quick.lucb): during a cv drag, tessellate(..., quick=true) on the moved copy answers from the parent's kept mesh with the moved faces' own points carried onto their new surfaces (shared edge samples stay, so the preview stays joined) in milliseconds; releasing the drag tessellates in full.

CadModel.overlay(mesh) returns a CadOverlay: each B-rep edge as mesh (the model's tessellation) samples it, the mesh's own edges between faces on different surfaces, so a line runs exactly along the faces beside it (an edge's own 64-chord polyline, sampled apart from the mesh, crossed the faces' chords and showed dashed where it dipped behind them; it stays for a mesh without faces), independent faces' outlines, the hull (every control net, rows then columns, per distinct face placement) and a normal guide per face, as point pairs. edges_key() names what the edge lines depend on, so a viewport keeps them while cvs move.

On camera.step (2,710 faces, 26,674 cvs; 707k points, 655k polygons) the kept mesh takes 1.07 s to make (1.51 s before; arc sampling, interval counts and seam comparison now run in parallel), a Tessellate node placing it 0.03 ms, the overlay 46 ms; moving one cv and re-tessellating takes 0.9 s, most of it the global layout plan, with the untouched faces' pieces reused.

Shared boundary topology

BrepModel owns vertices, line/circle/rational spline edges, analytic support surfaces, and faces with oriented edge loops. CadModel.attach_brep retains that model. Adjacent faces reuse the same sampled edge point IDs, including periodic seams. No positional weld is needed for a correctly connected input B-rep.

Supported face meshing:

  • Planes with concave outer boundaries and multiple non-touching holes.
  • Full or partial cylindrical/conical bands bounded by two circular arcs.
  • Four-sided trimmed NURBS and analytic patches use a boundary-conforming Coons grid in parameter space, lifted to the exact support. Logical sides may contain multiple STEP edges. Opposite side counts agree before shared edge sampling; interior curvature can raise the counts even with straight borders. Folded, singular and degenerate grids fall back to constrained trim meshing. A closed patch's seam point lies on both copies of its chart; a boundary walk that comes back on the other copy (a closed B-spline strip round a loop) is walked again from where it ended, so the strip maps (it was refused and outgrew the clipped grid's budget at 48 divisions and more).
  • NURBS trim loops projected to UV, meshed and lifted to the surface. Repeated seams on verified closed supports retain separate periodic chart images but stitch through the original shared 3D identities. Projection must agree within model tolerance; singular/ambiguous charts and arbitrary p-curves can still fail.
  • B-spline edges can retain a trimmed knot subinterval, including a seam-crossing interval on a geometrically closed curve. Endpoints must agree with the curve within model tolerance; no silent tolerance inflation is performed. A few ulps of endpoint reconstruction error are clamped before periodic wrap; an open spline cannot jump to its opposite endpoint from arithmetic roundoff.
  • NURBS interiors use bounded geometric-deflection refinement with shared edge split IDs. Existing shared boundaries remain fixed. Eight passes and a per-patch face budget bound work; this is not a certified global chord-error guarantee.
  • Trimmed cylinders/cones/spheres/tori in unwrapped analytic UV coordinates; a spherical cap bounded by one loop winding once round the axis (a latitude, or a wavy rim such as a variable fillet's contact round a dome) receives a pole-aware mesh: rows from each boundary sample along its meridian to the pole the loop goes round (by the loop's turn about the face's normal, so an inside-out cap takes its own pole). Such a loop with holes inside (a ball drilled through at a slant: each half sphere its equator and a hole) is meshed in an azimuthal equidistant chart about that pole (sphere_disk), where every loop is closed. The constrained fallback's interior lattice finds each point's triangle by walking across neighbors and its inside by even-odd along the lattice row (up to 131,072 cells, a 64-division face's twice over; it scanned every triangle and stopped at 8,192). If rotating a spherical chart turns an authored seam into a retraced interior slit, matching canonical identities allow it as a fixed constraint. Every authored seam segment survives triangulation, grid insertion, diagonal flips, quad pairing and surface refinement. Unidentified overlaps remain errors. Cylinder/cone clipping charts carry the angular branch between successive coedges even without a repeated seam edge. Hole loops choose the outer loop's chart branch; new shared stations retain that branch on refresh. This avoids fictitious full-revolution trim chords without moving any boundary point.
  • Four-sided planar faces share the mapped path. The constrained fallback for complex planes uses an interior lattice before conservative triangle pairing. Planar four-side candidates are preflighted with the actual fitted mesher while shared cuts are still mutable. A folded candidate receives a support grid plan instead of skipping directly to fallback triangles. Successful maps retain their strategy; four logical corners alone do not prove that the fitted parameter grid is valid.
  • Irregular planar, cylindrical, conical and NURBS trims can use a grid-first cell-clipping path. Curvature and edge-size tests seed directional rows; compatible isoparametric coedges transfer their station positions across patch boundaries, including swapped/reversed UV axes. Exact CAD-curve/grid intersections become shared B-rep samples before parallel meshing. Uncut cells remain quads; an oblique trim terminates them as small cut polygons instead of bending every row.
  • Four coedges no longer automatically select a boundary-fitted grid. Hard oblique trims on nonperiodic NURBS domains prefer the independent support grid. Opposite-edge parameter speed alone does not turn a smooth seam into a flow stop. Verified periodic/repeated-edge boundaries can use a cut chart; unsupported charts retain their existing periodic strategies. The clipped path is attempted before a fallback that transports all shared boundary samples.
  • A supported patch without four logical sides owns its cut chart from the start. Its physical-pitch and stopped-end rules apply during planning, not only after an impossible mapped attempt. Nearly incident trim coordinates can straighten into ordered collinear UV corners under existing numerical and model-tolerance limits; canonical 3D positions/IDs remain unchanged. Backtracking, collapsed segments, crossing and orientation reversal remain forbidden. This prevents numerical boundary ribbons from forcing a valid clipped extrusion into a triangle fallback.
  • Support-grid planning checks sampled display-triangle error on both diagonals, in addition to directional isocurve tests. Mixed curvature can add complete rows before shared cuts are frozen. Mapped and clipped neighbors reconcile together. Exact shared boundary stations remain immutable; interior row ownership may stop an incompatible phase without deleting its trim corners.
  • Mapped NURBS interiors can redistribute physical row spacing while keeping every trim vertex fixed. Boundary-to-first-row and last-row-to-boundary gaps participate. Three bounded passes require reduced normalized gap variance, no increased worst gap ratio, consistent UV orientation and a sampled display-deviation check against the tessellation quality budget. Improving one axis is not blocked by an unchanged worst row in the other axis. Rejected moves do nothing; exact trims and CAD boundary tolerance stay fixed. This is not a certified global surface-error bound.
  • Severely crowded clipped NURBS interiors can also redistribute complete grid-line chains. A short terminal boolean-cut interval alone does not trigger this pass. Every trim/hole vertex and polygon connection stays fixed; only interior UV points move and are re-evaluated on the exact support. Three bounded sweeps backtrack under the unchanged display-error budget. Acceptance requires improved physical gap variance, no worse worst gap ratio, reduced aggregate quad distortion, and no worse original stretched/skewed counts or maximum edge ratio. Valid UV triangles and quad corner turns are preserved; originally well-angled charts cannot acquire corners below a sine of 0.5. Actual display triangles and support normals are checked transactionally. This improves spacing without claiming a globally optimal quad layout or eliminating competing station phases at the frozen boundary.
  • Cut polygons retain their own display triangles independently from their real wire edges. Bounded diagonal flips remain inside convex UV quadrilaterals and strictly reduce support-normal violations. UV and projected candidates are checked against exact support normals; consistently oriented candidates survive worker assembly, affine placement, copies and subsets. If local flips stall, a bounded dynamic program searches visible UV diagonals for a complete normal-consistent triangulation (up to 256 corners, only on failed cells). Tiny grazing cut cells can merge across one internal manifold side into a larger neighbor: at most one eighth of its UV area, no extra touching vertices, no moved/deleted trim points, and at most 32 merges per patch. The final lifted mesh still passes the same normal and sampled surface-deviation checks. A clipped patch with an unresolved folded cell is rejected transactionally so the next strategy can run. This does not claim that all legacy fallback meshes are free of folded triangles.
  • Trim ribbons whose physical area/longest-edge ratio is below five percent of model tolerance can merge into a larger adjacent cell. Only boundary-adjacent cells qualify; the existing one-eighth-area, single-shared- side and simple-union guards apply. At most 128 optional dissolves run per patch. This removes redundant interior grid edges, not CAD boundary vertices or geometry; final lifted display validation remains mandatory. Curved charts use lifted physical positions for the area/edge measure, not arbitrary UV distances. Unchanged display triangles are retained when dissolving the shared side. This local cleanup does not promise well-shaped cells for every trim.
  • Compatible circular logical sides transfer angular stations as well as counts, including compound sides made of several coedges. This prevents equal-count but differently phased fillet strips. Fully mapped coaxial families first agree on evenly distributed angular intervals between mandatory CAD endpoints, with a circular-sagitta density floor. Optional quadrant anchors cannot crowd nearby required endpoints. A clipped smooth neighbor seeds every coedge on its dominant parameter rail before curvature refinement, so compound rails do not acquire a competing phase on their shorter segments. Nearly constant parameter rails must also pass a physical-displacement check at every station: UV epsilon alone is unsafe on stretched charts. This classifies row transport; it never snaps the exact trim or increases the model tolerance. Mixed mapped/clipped circular families can therefore share the initial distribution and add support rows together during reconciliation. Hard or incompatible neighbors still terminate interior rows rather than inheriting the full canonical sample set. Mapped, clipped and constrained strategies validate their output before committing. Unsupported layouts fall back without dropping shared seam IDs. A face no strategy meshes is left out of the tessellation, not the model: CadGeometry.skipped_faces(mesh) names each ("Skipped CAD face i: reason", one line each, joined across a set's models and kept beside independent faces). A strategy that makes no polygon fails too ("no mesher made a polygon of it"), so no face is left out without its line; luced-3d shows the lines as the node's warning. Only running out of memory, or every face failing, fails a tessellation.
  • Support grids clip faces of any number of trim loops, coedges and boundary samples (a plate with 500 holes, a cap of 5,000 coedges): the chart, the cut grid and the constrained fallbacks size their scratch by the face, and a cut cell without holes stays one polygon of any size (luce-geocore triangulates it for display). Station/cell budgets still bound the grid. A grooved cylinder/cone is not forced into triangle fans solely because it has more than 128 topological edges. The four-sided mapped recognizer stays separate; admitting a clipped chart does not pretend its jagged boundary is rectangular.
  • Support grids allow up to 1,025 stations per axis under a joint 131,072-grid-point budget. A long, narrow patch is not forced into fallback triangles by a square 257-by-257 axis limit. The joint limit is checked during inherited-row planning and before diagonal-refinement allocation, not only at final clipping. This supports anisotropic layouts; it does not solve inherited phase crowding or promise a minimal polygon count.
  • Endpoint-only smooth rails do not impose a planar interior phase. Independent narrow planes start with proportional physical axis counts. A late seam cut is not extended across such a plane if it would create a rectangle over 20:1 and more than double that same rectangle's previous aspect. An unrelated pre-existing skinny cell cannot excuse damage to another row. The exact cut stays on the shared boundary; useful splits, existing coupled phases, size/curvature rows and nonplanar grids are unchanged by this admission policy.
  • Proven affine NURBS extrusion directions can subdivide long support-grid intervals at an even physical pitch, targeting sixteen times the mean transverse interval. Curved-axis stations and existing straight-axis rows stay fixed. Optional refinement is skipped atomically if its full proposal exceeds either axis capacity or the joint grid budget. This is a support-grid shape target, not a bound on every Boolean cut polygon. Once refined, the straight direction rejects a later neighbor's row phase outside the middle 40–60% of an existing interval; the exact shared cut remains a boundary corner. It does not spread hard-edge samples through the interior or resample curved directions merely to improve aspect ratios.
  • Mapped affine strips (and cylinders) can resolve competing straight-rail phases into one evenly distributed row family, with the same mean-pitch target. Their ends may be one edge each or several (a setback corner's halves). A cylinder, or ends of several edges, takes rows only where its ends' samples do not pair off along the strip: one row of cells from end to end would join samples that do not face each other, its long triangles cutting across the surface (0.13 of volume on a pyramid's G2 strips). The complete control net proves affine translation using Greville positions, including degree-elevated and knot-inserted representations; warped nets and changing rail weights are excluded. Exact parallel line rails must cover the same projected interval. Curved rows are unchanged, every old shared cut is retained as a boundary corner, and over-budget proposals are skipped. The broader recognition does not opt higher-degree charts into the separate clipped endpoint/pitch policies before their neighboring phases are handled.
  • B-spline edges whose every face is a B-spline patch bounded by curves alone (a setback corner's quads) are spaced by length and turning together (layout/curve_spacing.space_curves): their curves bend hard in short stretches, and spacing by length alone crowds the quads (a rectangular pyramid's apex corner: quads of 8,000 to 33,000 triangles at 32 divisions, now 2,000 to 8,000). Every other edge keeps even length, so the two sides of a strip's rows still face each other.
  • Planar circle/ellipse trim envelopes include analytic projected extrema within the trimmed sweep. A sampled arc plus a percentage guard is insufficient for thin segments: later grid intersections can otherwise escape that envelope. Exact envelope bounds do not relocate any canonical boundary vertex. Other support/curve combinations still use their guarded sampled envelopes.
  • Close edge/grid intersections around a sampled boundary turn are distinct incidences, not duplicate estimates of one crossing. Their roots and the intervening extremum survive physical sample deduplication. Monotone runs retain the existing close-point representative and align its chart coordinate without moving canonical geometry. Regressions cover both sides of a shallow tangent under loose/tight model tolerances, idempotent reconciliation, swapped charts, reversed coedges and scaled monotone counterexamples.
  • Boundary stitching and interior row transport are separate. Sampled tangent planes and U/V directors classify seams before meshing: G0-only creases and incompatible smooth frames stop flow; aligned/reversed/90-degree-swapped smooth frames may continue it. Stopped seams retain all shared point IDs as boundary polygon corners without imposing the same interior grid on a neighbor. The former hard-curved-edge support-row override has been removed. If a conformed mapped boundary polygon has invalid projected display ears, it can retry support-chart triangulation, bounded diagonal repair and sampled support error validation. The accepted indices survive worker assembly. A cell that still fails rejects the strategy; boundary IDs are never dropped to hide it.

Transforms retain the B-rep and compose an analytic placement matrix; they do not tessellate the source or approximate nonuniformly scaled circles as circles. Reflection reverses generated face winding. Source coordinates are retained.

Meshes carry cad_face primitive provenance, optional primitive Cd from CAD face colors, and normalized corner N. B-rep shading normals use exact rational NURBS first derivatives or the analytic surface normal, independently per CAD face. Singular NURBS endpoints use a nearby limiting interior evaluation. Face workers prepare the normals alongside geometry, before assembly placement. Positive edge size refines shared boundaries and inserts planar/UV interior lattices. Quads remain quality-filtered; triangles are allowed near trims. Clipped patches reuse their known UVs for normals instead of projecting all generated vertices again. The integer primitive attribute cad_trim_grid identifies that path for diagnostics; cad_face, paths and colors are retained. cad_mesher records the accepted per-patch strategy: 1 = local-row mapping, 2 = clipped support grid, 3 = full canonical-row mapping, 4 = constrained fallback, 5 = baseline fallback conformed to shared seams. It reports the actual accepted path, including parallel face jobs, not a quality guarantee. cad_flow_island identifies connected compatible-flow faces (the minimum local CAD face index in the component). It is layout provenance, not object hierarchy or a mathematically certified continuity classification. The current classifier samples seven seam locations with 0.5-degree tangent-plane and 5-degree director tolerances. Conformed mapped polygons also check actual render triangles against support normals; invalid warped n-gons retry a denser/constrained strategy.

Planning is bounded to 1,025 U/V stations per face under a joint 131,072-point grid budget, 1,025 stations per shared edge, eight initial trim reconciliation passes, 32 mapped-side balancing passes per call, and at most twelve joint mapped/clipped reconciliation rounds. It is not a global cross-field parameterization or a guarantee of all quads. Incompatible row phases may terminate at cut cells; strongly mismatched or singular UV domains still use the constrained fallback. These extra continuity constraints can increase mesh density and tessellation time.

This is not yet a general B-rep kernel. Arbitrary p-curves, periodic trimmed NURBS, general singular trims, sewing disconnected shells, intersections, booleans and tolerance-controlled refinement remain unimplemented. Current stitching follows existing topology; it is not tolerance-based healing. Boundary/support agreement uses the model's tolerance (default 1e-6 source units). Full circles start at 4 * segments intervals; partial circles scale by sweep. Surface-error, shared-row and circular-family constraints can raise these counts before canonical points are frozen. Spline counts use sampled turn/deflection tests within that quality budget; straight/simple splines need fewer intervals. Opposite repeated seams confined to a single four-coedge band can refine the first passing power-of-two count within its bracket. Each returned count passes the same sampled criteria in its own phase. Externally shared edges and irregular trims retain their original dyadic family: changing those independently can crowd neighboring charts even when the curve's own error improves. This is neither a certified tolerance bound nor a globally minimal count. Opposing logical sides agree on total counts, including split edges. Lines start with one interval, then size/structured constraints may refine them. Unsupported trims and mesh-budget overflow fail explicitly.

STEP exposes Step.decode_model / Step.load_model; its mesh convenience APIs delegate to this package. The regressions (see Tests below) cover model preservation, re-tessellation, rectangular trim bounds, invalid-trim atomicity, holes, periodic seams, shared-edge manifoldness, reflection and nonplanar boundary rejection. Mapped-patch tests cover internal valence four, exact curved-interior samples, compound sides, rational derivative normals, endpoint knots and reversed face orientation. Trim-grid tests additionally cover swapped/reversed UV flow, seam valence, oblique cuts, enclosed/crossing holes, and circular fillets with reversed frames and compound opposite sides, including an arbitrary split almost coincident with an optional quadrant anchor. Interior circular rows must remain evenly distributed rather than merely sharing the union of two crowded phases. Seam regressions cover hard-edge n-gons, smooth 45-degree UV mismatches, 90-degree row transport, circular fillet/Cartesian-plane stops and curved strip support. Internal Base regressions cover endpoint roundoff versus real periodic wrap, diagonal curvature with straight isocurves, immutable trims, and first/last interior gaps with distortion in one or both row families. Near-grid corner alignment is completed after crossing alignment, so loop origin and winding cannot strand an endpoint in a neighboring cut cell. The bounded second pass preserves canonical 3D positions and rejects UV orientation changes, new crossings, and independently moved seam aliases. Clipped spacing also recognizes oversized boundary-to-first-row gaps, not just uneven interior gaps; an isolated tiny Boolean-cut interval is still left alone. Spacing proposals retain the existing topology, normal, sampled-deviation and shape-quality gates even when no original quad exceeds the 20:1 diagnostic.

On affine NURBS extrusions, an isoparametric rail ending at a stopped oblique trim contributes a boundary corner, not necessarily an interior station. The planner recognizes translated control-net pairs with matching weights and keeps curved axes, smooth joins, rail subdivisions and uncertain chart aliases conservative. Guard cells cover the trim envelope; actual rectangular sides remain mandatory rows. This removes thin endpoint wedges without moving the exact shared trim. Warped and doubly curved supports retain the previous policy. Contracts cover scaled/transposed rational nets, reversed/rotated loops, smooth versus stopped neighbors, actual row inheritance, clipping area and canonical boundary preservation.

Spherical pole-chart fitting retries a density-biased boundary average with a bounded convex-hull closest-point iteration. Acceptance still requires every sample to lie inside the same open-hemisphere margin; antipodal domains remain unsupported. Scale/frame/density/reversal contracts preserve the exact sphere and boundary points and verify rejection of genuinely incompatible domains.

Curvature analysis

tessellate(..., curvature=true) (and BrepModel.mesh) adds corner attributes curvature.k1 and curvature.k2: the principal curvatures of the exact support at each corner, from its first and second fundamental forms (rational NURBS second derivatives, or the analytic chart's). k1 >= k2; positive where the surface bends away from the face's outward normal, so a sphere of radius r has H = 1/r and K = 1/r^2, a convex cylinder k1 = 1/r and k2 = 0, and a bore k2 = -1/r. directions=true adds unit principal directions curvature.d1/d2. Values are per corner, like N, so faces meeting at a seam keep their own. Off by default; about 0.1 s on a 2.7M-corner model. A CadModel placement must be a uniform scale (curvature divides by it). The columns are float32.

Parallel work

One persistent worker pool (luce-std's parallel, process-wide, shared with the geometry kernels) runs the per-face work: layout seeding and row setup, speculative crossing computation, face meshing and normals, curvature and previews. Each item runs in its own runtime context and hands back raw arrays only. Layout reconciliation stays serial (each face sees its neighbors' newest cuts) but reuses an exact per-face memo of NURBS inversions and edge/grid crossings that a parallel pass fills first, so output is identical to the serial order on any number of cores. Errors are raised in face order.

Source layout

Every module is Luce Base. The public ones are flat files (cad_edits, cad_geometry, exact, solids) or ORDER modules (model, modeling, sketch); the rest are internal, each depending only on those above it in this list:

  • geometry/: surface and curve kinds, the B-rep records (Curve, Surface, BrepFace), rational B-spline evaluation and inversion, surface charts and normals, edge uses, the tolerance policy.
  • polygons/: planar polygon meshing (TrimPolygon, TrimGrid).
  • layout/: where a face's mesh rows go before meshing: edge stations, four logical sides, coedges chained in one chart, row counts shared across edges, and the checks a plan passes.
  • meshing/: one face's mesh from its plan (mapped grids, clipped cells, trimmed charts, bands, fans), its shading normals and checks.
  • tessellation/: a whole B-rep's mesh: planning every face, meshing in parallel jobs, the per-face cache, curvature.
  • brep/: BrepModel, its columns, records, meshes, cv edits, codec.
  • model/, modeling/, sketch/: the public model, features and sketches (modeling/trim, stitch, untrim and face_meets cut, join and rebuild faces for surfacing).
  • nurbs/, curves/, cad_curves: the NURBS toolkit, CAD curves and curves as set objects; cad_trims: a set's trim stages.
  • surfacing/: projection, trim conversion and CadSurfacing.

Surface evaluation and trim meshing (geometry, polygons)

geometry/nurbs.lucb evaluates rational tensor-product B-splines; polygons/ meshes trim loops in a plane.

Points/positive weights use u-major, v-minor order. Knot vectors are expanded, finite and nondecreasing. The evaluator uses Cox–de Boor basis functions and a rational weighted sum over only the active controls, with binary span lookup. sample_checked is for immutable nets already validated by check; callers must not change the net afterward. Returns an immutable indexed polygon mesh; its quads are triangulated by luce-geocore for rendering. No UI, File node or STEP syntax lives here.

surface_normal_checked evaluates exact rational first derivatives on an already validated immutable net and returns their normalized cross product. It returns zero at a singular parameterization; CAD owns limiting-pole policy.

check and check_region validate a net and a rectangular parameter subdomain without allocating anything; an independent patch's grid over its trim rectangle is meshing.nurbs_grid. The CAD model owns the face's chosen domain.

NurbsCurve.at and NurbsSurface.at expose rational evaluation at actual knot-domain parameters. TrimPolygon.triangulate accepts a planar outer loop and holes, checks intersections/nesting, builds visible bridges, and clips ears without dropping boundary vertices. quadrangulate first improves interior diagonals using bounded Delaunay-style edge flips, then pairs adjacent triangles only when convex, with all angles between 20 and 160 degrees and edge length ratio at most 10. It does not move vertices or remove trim boundaries. quadrangulate(..., edge_size=0) optionally inserts an interior regular lattice before improving diagonals and recombining. Zero disables it. Shared boundary sampling remains the caller's responsibility; this routine never splits a boundary edge independently. Refinement is bounded to 8192 candidate cells.

Trim intersections, ear membership and hole containment use dominant-plane orientation signs, with an ordinary floating-point filter and a bounded floating-expansion fallback for ambiguous binary64 determinants. Close points are not automatically touching or welded. These topology predicates are separate from a CAD reader's geometric fitting tolerance. Ear selection still requires locally conditioned display triangles; genuinely degenerate domains remain errors. The fallback assumes finite, normal-range products in the bounded mesh coordinate range, not arbitrary unbounded/subnormal inputs.

Ear clipping avoids leaving a remainder with no conditioned convex corner. If it still stalls on a single loop, it may add one area-centroid interior seed, but only after every original boundary segment forms a positive, conditioned triangle to that point and the area is preserved. This kernel check rejects invisible spokes; holes never take this fallback. Boundary positions and edges remain exact. The seed is subsequently eligible for the ordinary lattice, diagonal-improvement and pairing steps. Diagonal guards are relative to local squared edge length, so ordinary model-unit changes do not disable flips.

triangulate_seams(points, sizes, normal, boundary_ids) and `quadrangulateseams(points, sizes, normal, boundaryids, edge_size=0, second_spacing=0)` accept explicit nonnegative canonical boundary identities. A reversed coincident segment within one loop is legal only when both endpoints have matching identities and exact chart positions. Distinct periodic chart images remain separate. Mere proximity or equal positions with different IDs never authorize overlapping constraints. A bounded visible-diagonal partition can separate a retraced slit tip before ear clipping; it keeps every authored segment and does not insert arbitrary spokes through the domain.

TrimConstraints.build(points, ids, sizes) records coincident seam constraints by stable input point index. Its owner calls close(); meshing stages borrow the table. contains(a,b) protects those segments from grid insertion, diagonal flips, quad pairing and caller refinement. The table is empty for ordinary boundaries, which are protected by one-face incidence. Callers must retain input point indices. This is not a general intersecting-constraint arrangement solver.

Surface-grid sampling is uniform, not a guaranteed chord-error tolerance.

TrimGrid.clip(points, sizes, us, vs) intersects a supplied UV grid with one outer polygon and holes. Whole cells stay quads; boundary cells keep their polygon outlines. Holes within a cell and cells of more than 256 corners are triangulated locally. **Input trim segments must already be split at every grid crossing.** The first output points retain every input point and ID; the clipper neither invents CAD seam samples nor welds distinct vertices. Output validation requires every input trim segment exactly once and every interior edge twice. Touching/ambiguous arrangements are rejected, not silently patched. The implementation uses per-cell boundary buckets and per-row scanline parity.

Curved trim evaluation, cross-patch station planning, adaptive support checks, periodic bands and shared CAD-edge ownership live in the CAD model above. General field-aligned all-quad remeshing is not implemented.

Limits: degree 1–11, 2–1,024 surface control points per direction (262,144 total), up to 4,096 curve control points, divisions 1–64. Invalid weights, knot counts and collapsed surface polygons are checked errors. Planar trims are bounded to 64 loops and 16,384 vertices. Exact shared-vertex junctions within one loop are supported; touching distinct loops and unidentified overlapping segments remain invalid. Explicit retraced seams use the identity API above. Contracts (nurbs_contract, polygons_contract) cover a bilinear plane, a rational quarter cylinder and curve, multiple and touching holes, invalid boundaries, conservative quad recombination, grid-crossing holes, oversized cut cells and rejection of unsplit trim crossings.

Tests

luc test builds and runs two test programs:

  • tests/contracts, the Base contracts (main.lucb runs each topic's contracts; layout_contract and trim_predicates_contract run every contract module they import), which reach the package's internals: geometry, polygons, layout, meshing, modeling (references, march, booleans, surface inversion) and the exporter accessors;
  • tests/regressions, the Luce regressions (main.luc and one *_tests.luc module per topic, sharing checks.luc), which build CAD models in code, mesh them and check topology, trims, normals, volumes and spacing through the public exports.

STEP-file regressions live in luce-step; editor behavior stays in luced-3d.

Dependencies#

Versions#

0.9.5

Browse source · pack · commit 6f61d759ec8e

SHA-256 c716fe9731b90361bafdd343c7ae76a87d37d92cab60925b3ca1a605434af928

luce-cad 0.9.5: batch release

0.9.4

Browse source · pack · commit a309e040982e

SHA-256 2df3fd64e7ccc18ea6513d1b88d95676cd7ac846193d3ed4c3cdfbae2b1a63b3

luce-cad 0.9.4: batch release

0.9.3

Browse source · pack · commit db29f983327d

SHA-256 a325bb210e9a39e3093062609955b661c465e6ec9e82d8ff7fdbdd2b3abefa7c

luce-cad 0.9.3: batch release

0.9.2

Browse source · pack · commit cee7dc92f452

SHA-256 f4c022e913ff2a94641909732f0973efbecb8a9534952779f6d8d74b520acd1e

luce-cad 0.9.2: batch release

0.9.1

Browse source · pack · commit 40c7f57eb665

SHA-256 5c487ad8d3b53218541f94e0739d4078a211b1473125198b33d658cc5c841e95

dependencies name no version