Files
solvecraft/docs/native-brep.md
jyviko 9bdb116cea Fillet definitions through the record: Surface::Blend (#15010)
* solidcore-record: a face's surface may be a blend by its definition

`Surface::Blend { definition }`: a procedural blend's definition S, or a round of an exact
class's (`brep::blend::BlendDefinition`), with the face's `nurbs` its net B, stored once there.
The records are the kernel's plain data, mirrored here as `eval::geometry` mirrors the record's
surfaces: `BlendDefinitionRecord` and the records it holds, `ProceduralBlendRecord` for a support
that is itself a blend (no face, so it keeps its net), and `ExactRoundDefinition`, the kernel's
`ExactRoundRecord` without the net's form. Validation is structural, as the kernel's records':
every curve and surface, finite numbers, nesting at most three definitions deep, the items
counted against the record's budget, and a blend label needs its NURBS form.

Tests: a blend face validates and round-trips number for number, and is refused without its
net, nested too deep or with a number not finite; a reader whose surface kinds predate the label
refuses it by name ("unknown variant `blend`") rather than misreading it.

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

* solidcore: a face's blend definition read off for its record, and given back certified

`convert::face_definition` reads the definition a face's surface carries, without its net (the
face's surface is the net): a procedural blend's, or a round of an exact class's whose net has
no analytic label of its own (a surface of revolution, the rational classes' B-spline). A round
on an analytic surface or a ball patch keeps that label in a record, as before, and a definition
whose supports a record cannot hold goes as its net. `FaceDefinition` and
`ExactRoundDefinition` (an `ExactRoundRecord` without its net's form) are the plain data.

`convert::adopt_definitions` gives faces their definitions back: the net is the face's NURBS
surface as built, the definition is made from the record exactly and the net certified against
it again before the face's surface becomes the blend. A net its definition does not certify
refuses the face with the new `SolidError::DefinitionNotCertified { face, eps }`, never kept with
a larger bound; a cancel passes through.

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

* solidcore-convert: a blend face's definition crosses between the record and the kernel

`blend::blend` and `blend::record_blend` copy a face's blend definition field by field between
the record's `BlendDefinition` and the kernel's `FaceDefinition`. A body written as its record
(`to_record`) writes a blend face as its definition with its net as the NURBS form, wherever the
kernel reads one off it; a record built as the kernel's body (`to_kernel`) builds a blend face on
its net, then gives it its definition back, rebuilt and the net certified again
(`adopt_definitions`), refusing the record for a net its definition does not certify. The
record's blend label has no kernel surface of its own: `surface` refuses it by name, as the
curves and surfaces holding one do.

Test: a procedural definition with a nested blend support, and an exact round's, cross both ways
unchanged.

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

* solidcore-tess, solidcore-step: a blend face is meshed and written as its net

A blend label is the face's definition; its geometry is its NURBS form. The mesher names the kind
"blend" in its errors, and the STEP writer writes the face as its NURBS form, pcurves and all, as
it writes a ball patch: STEP has no entity for the definition.

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

* solidcore-ops: a blend face's geometry is its form

A blend label is the face's definition, with no surface or normal of its own: the record's
geometry check reads such a face by its form (its definition is checked structurally and
certified by the kernel when the face is built), and `label::form_turns` says its form turns
nothing, as for a face with no form.

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

* solidcore-ops: a body's blend faces between its record and the kernel

`blend_definition::record_definition` reads a face's definition off its surface as a record keeps
it, and `blend_definition::adopt` gives the faces of a body built from a record their definitions
back, rebuilt and their nets certified again: the modelling layer's calls for a client that
builds bodies its own way (through flat arrays) and needs its blend faces to cross with their
definitions, through the kernel and solidcore-convert.

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

* smlib: a body's blend faces cross to and from its record with their definitions

The flat arrays still carry a blend face as its net alone; the definition crosses beside them
through the modelling layer (`solidcore_ops::blend_definition`). Exporting a body
(`to_native_report`, `to_native_ordered`) writes each face whose surface carries a definition a
record keeps (a procedural blend, a round of an exact class whose net has no analytic label) as
`Surface::Blend` with its net as its form. Importing a record (`from_record`,
`from_record_keeping_splines`) builds a blend face on its net, then gives it its definition
back, rebuilt and the net certified again; a net its definition does not certify refuses the
body (`DefinitionNotCertified`), and so does a body the build gave another number of faces. The
record → arrays mapping sends a blend face as its NURBS form, and record SSI refuses a blend
label as it refuses a ball patch's.

Tests: the round on a bore's rim is written by its definition with its net, survives save and
reopen number for number, comes back from a rebuild with the same definitions, and the rebuilt
body takes a shell.

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

* geom, kernel, cli: a blend face is its definition on its net

A blend label is the face's definition; its geometry is its NURBS form.
- The record's rigid motion (`placement::moved`) refuses a record with one (`None`): moving a
  definition's supports, leader and seeds is the kernel's, and `transform_matrix` then moves the
  body through the kernel's transform, which moves the definition with its net. The affine map
  (`mapped`) refuses it as it refuses every labelled face.
- Hidden lines draw a blend face as its net: the definition is dropped there, for the drawing
  only (`hlr::shifted`).
- The record evaluator, iso curves, the face kinds (freeform) and the offset's analytic surfaces
  (none) read it as its form, as a ball patch's label is read.
- The rig names it `blend` in `surface_types` (tests/kernel-cases/README.md).

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

* Native B-rep: the blend face, and its design-format note

docs/native-brep.md gains the `blend` {definition} surface row and its paragraph: the face's
`nurbs` is its net, stored once; the kernel builds the face on its net and certifies it against
the definition before it is an operand. A pending design-format change says what an older design
and the last release do with it: as the ball patch before it, no SCBREP bump (an older reader
refuses the unknown kind by name, a model-cache miss; solidcore-record's test shows it).

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

* smlib, solidcore-ops: a body's blend definitions through body-level ops calls only

The application reaches a body's blend faces through the modelling layer alone, adding no kernel
path: `solidcore_ops::blend_definition::definitions(k, body)` walks the body's faces in their
order and reads each face's definition, and `adopt(k, body, &[(index, definition)])` gives faces
named by that index their definitions back, an index past the faces refused as
`Error::Argument`. A net its definition does not certify reaches the application as the new
`solidcore_ops::Error::DefinitionNotCertified { face, eps }`, the face by its index; other kernel
refusals as the operation's. crates/smlib/src/core/definition.rs now calls ops alone and imports
nothing from `solidcore::`.

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

* Blend definition record: CI's compile error and clippy findings

- geom `placement::moved`: a face's or edge's NURBS form is moved by a match (the motion of a
  form is an `Option`, so `map(..).transpose()` was the wrong tool).
- The definition enums box their variants (`brep::blend::BlendDefinition` in the record,
  `FaceDefinition` in the kernel): the definitions are large and of different sizes.
- solidcore-record `brep::blend`: the weight checks are one `if let` chain each.
- solidcore `procedural_blend::convert`: an unused operation name goes.

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

* Kernel cases: a blend face is a blend, its net's degrees read on its NURBS form

A round of the exact class is now recorded as its definition
(Surface::Blend) on its net, so the `surface_types` check names it
`blend`, and the `splines` check reads the degrees on the face's NURBS
form (its net). The eight cases that named these rounds `bspline` now
name them `blend`; their spline degrees are unchanged:
cov-fillet-exact-coaxial-cones-r2, -cone-cylinder-sharing-a-ball-r1,
-cylinders-touching-at-a-point-r1, -oblique-plane-cone-rim-r1-5,
-oblique-plane-cylinder-rim-r2, -sphere-coaxial-cone-r3,
-sphere-plane-rim-r2 and cov-fillet-tee-pipe-r8-into-pipe-r20-r3
(surface_types: bspline -> blend).

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

* solidcore: a variable round's leader is its edge's curve cut to its stations

An edge on an unbounded line (a box's) is held as a two-point NURB a
million times the part's size (control points at y = +-24691340), and a
variable round took that curve whole as its leader. Its control points
round at an ulp of 2.5e7, about 1e-9 mm, and recertification, which
takes the round in its own frame (the blend translated by its centre),
carried that rounding into the leader: leader(1) moved from y = 20 to
19.999999998137355 (2^-29), the re-solved feet moved with it, and the
equal-radius round of blend_variable::variable_radius_on_a_box_edge,
whose net is 7.36e-11 from its definition, was refused against its
certified 2.2e-10 (delta 1.86e-9). Recertified unmoved it passes, so the
bound was right and the leader was not.

The leader is now the edge's curve cut to the stations' parameters
(within its natural interval), its control points of the part's size;
the round is built on the cut curve, so build and recertificate solve
the same stations. Measured: the equal-radius round recertifies at
7.36e-11 against 2.2e-10 after the record round trip; the 2 -> 5 round's
certified bound is 3.16e-6 (it was 5.06e-7 on the uncut leader) and
recertifies at 3.159e-6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* solidcore: a derived cylinder's and cone's numbers come from the form's rows

The NURBS form is a blend definition's record's one truth for its
supports, and AnalyticSupport::derive must give back the support the
form is. It took a cylinder's and a cone's numbers from the recognisers
(IsNurbSurfaceCone), whose chained computation tilts the axis by about
1e-13 (an ulp of the origin's size): the raked wedge's cylinder supports
(|origin| ~ 70) came back tilted 1.3e-13 and build refused them as not
the form's parametrisation, so the body read back from its record was
refused (boolean_regression_tests::box_intersect_splits_the_end_off_a_
raked_wedge_after_its_end_rounds).

derive now reads them off the form's control structure. Each circle row
is a rational quadratic arc p0 p1 p2 whose tangents meet at p1, so its
centre is c = p1 + (m - p1) |p0 - p1|^2 / |m - p1|^2 (m the chord's
midpoint) and its radius the ends' distance from it. The axis is the
line through the first and last rows' centres, the origin its point
nearest the recogniser's, the x axis the recogniser's made square to
it; a cylinder is a cylinder by its kind, a cone's angle the radii's
change along the axis. The recogniser gives only its conventions (frame
turn, sweep, generator range, swap); build and evaluates_as judge the
result unchanged. Sphere and torus still derive through the recognisers
(a follow-up).

Tests (derive_revolved_supports): the raked wedge's ten cylinder support
forms, form -> derive -> build, within 64 ulps; a tilted quarter cone
at |origin| 1e3 and 1e5, and a tilted quarter cylinder at 1e3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* solidcore: derive's positive checks in the crate's NaN-refusing form

The circle row's and the axis's positive checks were `!(x > 0.0)`, which
solidcore's clippy refuses (neg_cmp_op_on_partial_ord). They are
`x.partial_cmp(&0.0) != Some(Ordering::Greater)` now, as the file writes
its other NaN-refusing comparisons: a NaN still refuses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* solidcore: a support is built as its own kind, the recogniser giving conventions only

AnalyticSupport::build's on_form took the kind from the recogniser and
refused a support of another: a cylinder about 1e5 from the world origin
(a tilted quarter cylinder, radius 1.5, at (6e4, -4.8e4, 6.4e4)) is read
by Cone::is_nurb_surface_cone as a cone of semi-angle -1.1e-10 degrees,
so its derived cylinder was refused before evaluates_as was asked. As
derive now does, on_form takes only the recognised surface's
conventions (frame turn, sweep, generator range, swap) and builds the
support's own kind with its own numbers: a cylinder sets its angle to 0
and is a cylinder. evaluates_as judges the result, unchanged. The
recogniser is untouched (its misread is a follow-up issue). The tilted
cylinder at 1e5 is back in derive_revolved_supports, which passes, with
wr698 and the raked-wedge regression.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* solidcore: derive turns its axis with *= (clippy's assign_op_pattern)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* solidcore: derive reads a cone's apex row as its axis point of radius 0

AnalyticSupport::revolved_from_rows took each row of a cone's form as a
circle and dropped a row collapsed to one point: its arc has no chord, so
circle() returned None. A cone up to its tip has two rows, the base circle
and the apex, so one circle was left, the axis had no length, and derive
refused the support as not of its kind. The fillet rig's
cov-fillet-exact-cone-cylinder-sharing-a-ball-r1 (a cone to its apex,
rounded where a cylinder meets it) built its round, then the body read
back from its record was refused (SM_ERR_INVALID_INPUT on Hill).

A row whose control points are one point, apart only by the rounding of
dividing each homogeneous point by its weight (gamma_4 of its size, as
euclidean_net makes them), is now the axis's point of radius 0: the
apex. The axis runs from the base circle's centre to it, and the angle
and base radius follow as for any two rows.

Checked locally (owner-approved for this PR): the case fails at
449e72c1f3 with the reported refusal and passes with this change. Test:
derive_revolved_supports' an_off_axis_tilted_cone_up_to_its_apex_round_trips,
a tilted quarter cone up to its apex (apex row last and first) at about
1e3 and 1e5 from the origin, form -> derive -> build within 64 ulps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* solidcore: a re-certificate stops its levels on the certified bound's least value

A round's span over its target is halved at construction, and each half is
certified from its parent's finest level (gn_certify_span_reusing's inherit
path). Recertification takes each half fresh from level 0, to the target,
and close_level's least-value stop ended it after level 0: that least value
took the uv curves' term in the fork's form, which steers the levels but is
not under the bound certified in each parameter's own form (#2690). On
cov-junction-tee-offset-round the half [14.92, 15.31] stopped at 4.27e-6
(fork 5.39e-6) against its target 3.97e-6; level 1, the pieces construction
used, certifies it at 3.83e-6. The oblique unequal tee's span 103 likewise
(4.48e-6 -> 2.68e-7).

To the target (SpanReuse::to_target, recertification's), the stop now takes
each parameter's own least uv term (LevelAcc::uv4_lo, folded as the fork's
is), a lower bound on every level's certified bound. Construction's levels
are steered as before. No tolerance or expected value changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* solidcore: derive takes a cylinder's axis from its columns

AnalyticSupport::revolved_from_rows took every axis as the line through
the first and last rows' circumcentres. A circumcentre of a shallow arc
carries its control points' rounding amplified by the radius over the
sagitta: on the shelled case of the engine's
the_pleats_join_at_every_wall_from_2_4_to_2_6_mm, a 20 mm arc of radius
77.6 mm extruded along Z got an axis tilted by 1.3e-14. build refused it
as not the form's parametrisation, face_surface kept the face as plain
NURBS, and FilletFrontInner and FilletRearInner failed with
SM_ERR_INVALID_INPUT at a 2.4 mm wall.

A cylinder's generators are its form's columns, and each column's first
and last control points differ by the stored extrusion, exactly for an
extruded circle. The axis is now the sum of those differences, through
the first row's centre. A cone's generators meet at its apex, so its
axis stays its centres' line.

Measured locally (the pleat test, approved narrow run): old (recognised)
and new numbers agree within 3.2e-12 in origin and radius on all 31
distinct cylinder forms; the failing form's old axis is exactly Z and the
centres' axis is off by 1.27e-14; with this change all 288 derives build
and the test passes. Test: derive_revolved_supports'
the_pleated_cases_cylinder_supports_round_trip, the 31 forms as derive
met them (data/pleated_case_supports.jsonl), form -> derive -> build
within 64 ulps; it fails with the centres' axis and passes with this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: jyviko <2501648+jyviko@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 05:39:44 +00:00

25 KiB
Raw Permalink Blame History

Native B-rep, schema 4

This is SolidCraft's geometry data model in solidcore_record::brep (solidcore's record crate: geometry as data, no maths). It has no modelling-backend dependency; its geometric checks and evaluation are the kernel's (solidcraft_geom::brep). It is the body encoding of a design's model cache (the container format); it is not a STEP replacement for external interchange. The container reader, binary codec and kernel adapters are separate layers. The truck adapter writes it exactly: a body decoded by the producer that encoded it is that body, number for number.

The records follow SMLib's flat form, SmBrepData. It stores one record per logical use: a kernel keeps two mated halves of each face use, loop use and edge use at run time, and it rebuilds them from the one record. The types take STEP's B-rep names. Each type's documentation names its SMLib record and STEP entity.

Units and numbers

Coordinates are IEEE-754 binary64, in millimetres, right-handed Z-up. Angles and angular parameters are radians, always. (SMLib's STEP-style analytic parameters are degrees; an SMLib adapter converts them, the pcurves on analytic faces included.) References are unsigned 32-bit indices into the body's own lists, never kernel addresses or runtime IDs. Tolerances are millimetres.

Topology

Record SMLib STEP Holds
Brep SmBrep MANIFOLD_SOLID_BREP, BREP_WITH_VOIDS, SHELL_BASED_SURFACE_MODEL tolerance, regions, shells, faces, edges, vertices
Region SmRegionData (implied by shells) its shells, void
Shell SmShellData CLOSED_SHELL, OPEN_SHELL, WIRE_SHELL, VERTEX_SHELL oriented faces and wire edges; or wire edges; or one vertex
OrientedFace SmFaceuseData ORIENTED_FACE face, forward
Face SmFaceData ADVANCED_FACE surface, domain, loops
Loop SmLoopData FACE_BOUND with EDGE_LOOP or VERTEX_LOOP oriented edges, or one vertex
OrientedEdge SmEUData ORIENTED_EDGE and its PCURVE edge, forward, pcurve
Edge SmEdgeData EDGE_CURVE curve, interval, start and end vertex, tolerance, uses
EdgeUseRef SmEUData's radial fields — face, loop, position, upper
Vertex SmVertexData VERTEX_POINT point, tolerance

Regions. regions[0] is the infinite region. It has no outer shell and is never a void. Each bounded region lists its outer shell first, a closed face shell, then its inner shells. A bounded region is material unless void. A closed shell separates two regions, so both list it: it is the outer shell of the region it encloses and an inner shell of the region around it. An open shell, a wire shell or a vertex shell lies in one region and only that one lists it. A shell is closed when every edge its faces use is used at least twice among them.

Shells. A face shell lists oriented faces, and the wire edges embedded in it. A wire shell is a connected graph of edges with no faces. A vertex shell is one isolated point. One shell record stands for both runtime sides of a shell.

Oriented faces. A face is used by one oriented face, or by two in different shells with opposite forward. forward means the face's normal in that shell is its surface's natural normal, ∂S/∂u × ∂S/∂v. In a closed shell, normals point out of the material.

Loops. A face has one outer loop and any number of inner ones, in the producer's order: truck lists some holes before the outer loop, and an SMLib import puts the outer loop first, as SMLib requires. The first loop is an edge loop. A vertex loop (a pole, a collapsed boundary) is only ever an inner loop. Orientation tells outer from inner. Loops are stored relative to the surface's natural normal, whichever side a shell uses: seen from that normal, the outer loop runs counter-clockwise and inner loops clockwise. This lets one face sit in two shells without contradicting itself. An edge loop is a closed chain: each oriented edge starts at the vertex where the one before it ends, and the last ends where the first starts. An oriented edge runs from its edge's start to its end when forward, otherwise from end to start.

Edges. An edge's interval is the part of its curve it covers, min < max. Its vertices are at interval min and max; they are equal for a closed edge. uses lists every oriented edge on it, each once: the primary use first (the first one the canonical walk meets), then the rest in radial order, the right-hand rule about the edge's direction. A wire edge has no uses. upper says the radial cycle enters that use on the side of the surface's natural normal. With loops stored relative to the natural normal it follows from the use: upper is always !forward of the oriented edge it names.

Tolerances. The body, every edge and every vertex carry a tolerance, finite and positive, never optional. The body's is SMLib's intersection tolerance.

Canonical order

The lists are in one backend-independent order, and every adapter produces it. A face's index in faces is its face index everywhere: in history, face sources, paint and persistent names. The same holds for edges and vertices.

  1. Regions: the infinite region, then bounded regions in the producer's order.
  2. Shells and faces in order of first appearance, walking regions → shells → oriented faces.
  3. Edges in order of first appearance, walking faces → loops (in stored order) → oriented edges, then wire edges walking shells. A face whose first oriented face is reversed is walked backwards: each of its loops from its last oriented edge to its first. That is how a reversed face is traversed.
  4. Vertices in order of first appearance, walking edges (start, then end), then vertex loops walking faces → loops, then vertex shells.

Nothing may be listed that the walk does not reach.

Geometry

Curves and surfaces are unbounded. An edge's bounds are its interval, a face's its loops inside its domain. Each kind's parameter is stated exactly. For the kinds the truck adapter writes (line, spline, rational_spline, surface_intersection, plane_through, placed_revolution) the parameter is truck's own evaluation (ParametricCurve::subs, ParametricSurface::subs). Analytic frames store an origin and orthonormal x and y axes; z = x × y.

Curves

Kind Point at t Range of t
line {start, end} start + t (end − start): 0 at start, 1 at end unbounded
circle {frame, radius} origin + r (cos t x + sin t y) periodic
ellipse {frame, radii} origin + r₀ cos t x + r₁ sin t y periodic
polyline {points} segment i spans [i, i + 1] [0, n − 1]
spline {knots, points} B-spline on the full nondecreasing knot vector; degree = knots − points − 1 [knots[degree], knots[count]]
rational_spline {knots, homogeneous} the same basis, homogeneous [x·w, y·w, z·w, w] coefficients as the producer holds them as spline
surface_intersection {surfaces, leader, tolerance} the intersection of two surface records, traced from leader (a polyline or spline near it) to within tolerance mm; t is the leader's the leader's

A surface_intersection is the procedural curve itself, not a fit: another kernel traces it again. Its point at t is the point of both surfaces in the plane through the leader's point at t, normal to the leader there (truck's subs converges to it within 10⁻⁶ mm).

An edge on a line, circle or ellipse may also carry nurbs, a spline or rational_spline: the NURBS form it is parameterised on, as SMLib holds it (every SMLib conic is a B-spline curve, the trims on it in that NURBS's parameter, not the angle). The edge's interval and its pcurves' parameter are then the NURBS's, and curve only says what the edge is (centre, radius). This mirrors a face's nurbs: faces and edges are held as SMLib holds them.

Surfaces

Natural normals are ∂S/∂u × ∂S/∂v.

Kind Point at (u, v) u v
plane {origin, u_axis, v_axis} origin + u u_axis + v v_axis unbounded unbounded
plane_through {origin, u_point, v_point} origin + u (u_point − origin) + v (v_point − origin) unbounded unbounded
cylinder {frame, radius} origin + v z + r (cos u x + sin u y) angle, periodic height, unbounded
cone {frame, radius_at_origin, half_angle} origin + v z + r(v) (cos u x + sin u y), r(v) = radius_at_origin + v tan(half_angle) angle, periodic height, on the side of the apex where r(v) ≥ 0 (a negative half angle narrows along z)
sphere {frame, radius} origin + r (cos v (cos u x + sin u y) + sin v z) longitude, periodic latitude, [−π/2, π/2]
torus {frame, major_radius, minor_radius} origin + (R + r cos v)(cos u x + sin u y) + r sin v z longitude, periodic meridian angle, periodic
ball_patch {center, radius} its nurbs: a label with no (u, v) of its own its form's its form's
blend {definition} its nurbs: a round by its definition, with no (u, v) of its own its form's its form's
spline {u_knots, v_knots, points} tensor-product B-spline, points[i][j] with i along u u knot domain v knot domain
rational_spline {u_knots, v_knots, homogeneous} the same, homogeneous coefficients u knot domain v knot domain
placed_revolution {profile, origin, axis, matrix, forward} M · R(angle) · profile(s): the profile revolved about origin and unit axis by the right-hand rule, then mapped by the column-major affine matrix M forward: s, the profile's parameter; else the angle forward: the angle, [0, 2π); else s

A plane_through is a plane given by three points, as its producer holds them; writers use it rather than the axis form, whose axes would be rounded differences of the points. A placed_revolution keeps the revolution exactly as its producer holds it (truck's RevolutedCurve under a Processor): nothing is baked into the profile, and forward: false swaps u and v, which reverses the natural normal.

A face on a cylinder, cone, sphere or torus may also carry nurbs, a spline or rational_spline: the NURBS form it is parameterised on, as SMLib holds it (every SMLib analytic surface is a B-spline surface, and its trims are in that NURBS's parameters, not the angle). The face's domain and pcurves are then in the NURBS's (u, v), its natural normal is the NURBS's, and surface only says what the face is (axis, radius). Pcurves on such a face are SMLib's own trims, with nothing fitted. A STEP writer writes the analytic surface and the face's edges without pcurves.

A ball_patch face always carries nurbs: the rational patch on the sphere of center and radius that SMLib makes at the corner of three equal rounds (SmBallPatch, flat surface kind 6). The patch is its own net, not a piece of SMLib's sphere NURBS, so it goes back into SMLib as kind 6 with that sphere as its definition, and SMLib takes it only when every point of the net is on the sphere. The sphere is kept because its offsets are exact and collapse at its centre. A STEP writer, with no entity for it, writes the net as the face's B-spline surface, pcurves included.

A blend face always carries nurbs, its net: the certified B-spline of a round whose definition the record keeps (solidcore_record::brep::blend): a procedural blend's definition (supports, ball, section, leader and seeds, its bound and the map from the net's parameters to the definition's), or a round of an exact class's whose net has no analytic label of its own (a surface of revolution, or the rational classes' B-spline), with that net's kind. The net is stored once, as the face's form; a support that is itself a blend keeps its own net in the definition. The kernel builds the face on its net, makes the definition from the record and certifies the net against it again before the face is an operand, refusing a net it does not certify. The flat arrays carry the net alone. A STEP writer writes the net as the face's B-spline surface.

Parameter ranges

An edge interval and each side of a face domain are finite with min < max. In a periodic direction they may start anywhere and run up to one turn (2π), across the seam. Otherwise they lie inside the natural range: a spline's knot domain, a polyline's [0, n − 1], a sphere's latitudes, a cone on its open side of the apex.

Pcurves

Every oriented edge carries its pcurve: the edge in its face's (u, v), as a 2D B-spline (Curve2: spline, or rational_spline with [u·w, v·w, w] coefficients). There is no polyline or analytic 2D kind. 2D lines and arcs are exact as degree-1 and rational quadratic splines; anything else is a fitted B-spline. A pcurve lies on the edge's own interval and runs from interval min to max, whatever the oriented edge's direction. Its interval must equal the edge's within 10⁻⁹ of the interval's magnitude (at least 1), room for a linear remap's rounding. A seam edge has two uses on one face, each with its own pcurve, a period apart. On a periodic surface a loop's pcurves are unwrapped, so each one starts where the one before it ends. A spline surface that closes on itself in a direction (knots clamped there, first and last control rows the same points with the same weights, within 10⁻⁹ of the control net's extent) is periodic in it for pcurves and tessellation, one active knot interval per period: a seam on it has its two uses an interval apart. The record is unchanged; a parameter outside the interval is evaluated a whole number of periods back inside it.

Where a kernel holds a use's pcurve exactly in the record's parameters, the record keeps the kernel's own: the SMLib export takes SMLib's UV trims on B-spline faces for edges recorded as splines or lines (the face's parameters are SMLib's, the edge's parameter SMLib's or an affine image of it). SMLib keeps an analytic face's trims on its internal rational B-spline, whose angle parameter is not the record's angle, and a circle's or ellipse's on its NURBS parameter, not its angle; neither is an exact B-spline in the record's parameters. The rest come from solidcore_ops::pcurve::pcurves (the kernel's solidcore::eval::pcurve), which computes them from a face's surface record and each use's curve record and interval, for every backend (a use's given pcurve is taken as it is). It is exact in closed form for lines, polylines and whole splines on planes, circles about the axis of a cylinder, cone, sphere or torus (v fixed, u the circle's angle plus a constant) and lines along a cylinder's or cone's ruling (u fixed, v linear), each checked by lifting it. On a spline face, a straight (u, v) line is taken where it lifts onto the edge within the tolerance. Anything else, and an exact one that misses, is refused (Failed, "no exact pcurve"): nothing is fitted.

Validation and trust

Brep::validate checks structure and resources without a kernel. It caps 1,024 shells, 4,000,000 combined topology and geometry items (pcurve control points included), geometry nesting at 16, spline degree at 16 and control points per spline direction at 4,096. Numbers must be finite and at most 1e12 in magnitude. It checks knot order, active spline domains, multiplicities, rectangular grids, positive rational weights, nondegenerate planes, orthonormal frames, unit revolution axes, positive radii, ring tori, cone dimensions and tolerances. Then the topology: every index in range; the regions and shells as described above; each face used by one or two oriented faces; first loops are edge loops and vertex loops are inner; loops are closed chains through shared vertices; every edge's uses lists exactly its uses, once each, primary first, with upper as stated; pcurve intervals; parameter ranges; and the canonical order.

The item cap is for records from outside the kernel: a native file, a STEP file, the control channel. Brep::validate_built runs every other check on a record the kernel built in memory (an operation's result, a body's own record, a part of one): that record already sits in memory, its size set by inputs bounded where they came in, and the checks are linear in it, so a cap there would only refuse a real result.

These are structural and resource guards, not a geometric validity certificate. The validator does not check that edges lie on their surfaces, that pcurves lift onto their edges, that a closed shell is watertight or that shells nest as the regions say. A backend's adapter checks what it needs. The binary reader bounds bytes, allocation and nesting before creating these structures.

Brep::check_geometry spot-checks, on a record validate accepted, that its geometry agrees with its topology, each distance against the record's own tolerance: every edge's curve meets its start and end vertices at its interval's ends (within the edge's and the vertex's tolerances together); every oriented edge's pcurve, lifted through its face's surface, lies on the edge's curve at the interval's ends and middle (within the edge's) and starts on the same period as the use before it ends, except along a direction that collapses at a pole; every edge loop's pcurves enclose (u, v) area (more than 10⁻⁹ of the square of the loop's extent), and exactly one loop of each face, the outer, runs counter-clockwise about the natural normal, the rest clockwise (told apart by their areas, not their order); every vertex loop's vertex lies on its face's surface (within the vertex's). It makes a fixed number of evaluations per record, so its work is linear in the record, and a point it cannot evaluate is an error naming the record. It is not a certificate either: between the points it checks, an edge may still leave its surface. The truck adapter runs it before building topology, which truck does without checks of its own.

Schema tests build and validate one minimal body of each form (an open sheet, a closed shell, a seam edge, a vertex loop with a wire and a vertex shell, a void) and one fixture per defect, without a kernel.

History

The runtime history types (FaceOrigin, Change, FaceProv, Side, EdgeOrigin, EdgeProv, History) live in solidcore_record::brep::history, so a backend can report history without the kernel crate. Indices are canonical face and edge indices; operands are numbered by each operation. An operation returns history beside the B-rep. A backend that cannot report it returns none and never guesses. The saved form is the envelope's own records (below).

Face-source certificates, operation history, appearances and persistent document identities belong to a versioned SolidCraft envelope around this geometry. They must be preserved by the cache codec, not reconstructed from face counts or floating-point comparisons. A decoded cache remains provisional until authoritative re-evaluation finishes. The document and original blobs remain sufficient to reopen when a cache, representation, producer or adapter is unsupported.

Body binary envelope, version 5

SCBREP05 is the eight-byte envelope signature. Geometry schema 4 is nested in solid; metadata schema 1 is nested in metadata; runtime holds what the body measured about itself that later operations read (its size, from which kernel tolerances follow, and the orientation mesh's missing-face count), so a decoded body works to the same tolerances. These are separate version numbers because each contract can evolve independently. Signatures 01 and 02 were development prototypes; 02 introduced the explicit geometry schema, 03 separated metadata from runtime Rust types, 04 made the encoding exact and 05 carries schema 4. Unsupported versions are cache misses, not design-file migration failures: a design whose cache holds an older signature opens and is evaluated again.

The envelope uses its own explicitly versioned records for color, paint, authored boundaries, face-source certificates, operation history and boundary protection. Plane, region and segment records are also owned by the wire schema. Exhaustive manual adapter conversions separate these from runtime FaceSource, History, FaceProv, EdgeProv, Paint, Seg2, Region2 and Plane types. Their serde derives or internal refactors cannot silently redefine the saved fields. No truck serde struct, pointer, tessellation or STEP string is written. Changing field semantics requires a format version change, even if a Rust type keeps its name.

Values use tags: null=0, false=1, true=2, signed integer=3, unsigned integer=4, binary64=5, UTF-8 string=6, array=7, object=8. Numbers use eight little-endian bytes. Strings and collections use unsigned 32-bit little-endian lengths; object keys are length-prefixed UTF-8, emitted lexicographically. Readers reject duplicate keys, unknown tags, non-finite numbers and trailing bytes. Limits per body are 256 MiB, 20,000,000 values, depth 48, 1,000,000 entries per collection and 1 MiB per string; a design's cache bounds the total (see the container format).

The truck adapter

Truck keeps a face's wires relative to its surface and flips the face with an orientation flag. That is schema 4's convention: the adapter writes truck's wires as the loops and the flag as forward, with no wire reversed. It numbers faces in face_iter order and edges in first appearance through edge_iter, which walks a reversed face backwards, so the record's indices are the kernel's.

It writes every curve and surface as truck holds it: lines, B-spline and NURBS coefficients, the three points of a plane, a revolution's profile, axis, matrix and orientation, and an intersection's two surfaces, leader and tolerance. An edge's interval is its truck curve's parameter range. Pcurves come from solidcore_ops::pcurve on the records just written; a face's domain is the box around its pcurves' control points, clamped to the surface's natural domain and at most one turn in a periodic direction. Every tolerance is the body's face tolerance, 10⁻⁶ of its size and at least 10⁻⁵ mm, how far later operations take its faces to be from its edges.

Regions come from truck's shells. Open shells lie in the infinite region. One closed shell bounds one material region. With several closed shells, a tessellated nesting test (the one Body::lumps uses) finds which bound material and which voids, and what lies inside what. If truck's shell order is not the canonical one (a void listed before another lump), or open and several closed shells mix, the adapter refuses and the body is a cache miss. So it does for an edge with more than two uses, whose radial order would need geometry.

Decoding builds the same structures without the constructors that would round them (normalizing an axis, composing a matrix with the identity), and rebuilds each shell's topology as recorded, including closed edges on one vertex and seam edges a wire uses twice. It ignores pcurves, regions and domains, which truck does not keep. It refuses what truck cannot hold: wire and vertex shells, wire edges in a face shell, vertex loops, a face used by two shells, standalone polylines, unclamped spline domains and a spline or intersection edge on part of its curve. It loads circles and ellipses as exact rational arcs over the edge's interval, and analytic surfaces as revolutions, which truck parameterizes its own way.

Hashes prove which document and payload a cache belongs to, not who wrote it: the container's key ties a cache to the producer, application build and platform that computed it, and the decoder applies the structural and resource checks above to every body. A second backend needs its own tested adapter before cross-kernel interoperability can be claimed.

The box-and-fillet golden JSON fixture pins the decoded version-5 envelope, field names, tags, topology, geometry and metadata. Integer and structural values are exact; floating coefficients allow 1e-10 relative/absolute platform rounding. The signature is asserted separately. NATIVE_BREP_BLESS=1 rewrites the fixture for an intended change.

Bounded provisional display

native_preview_mesh samples at most 32 points along each curved edge, caps each face's boundary at 4,096 points, and bounds spline controls and nested surfaces before parameter searches. Searches use at most 16 refinement trials. Revolution profiles involving procedural intersections are refused in this display path. The separate mesher uses a fixed grid of at most 16 subdivisions per direction and fixed periodic-seam connections; it never invokes adaptive edge, surface or aspect-ratio refinement. Planes use a single grid cell.

Before projection, the caller reserves a conservative triangle bound covering duplicated projected boundary points, periodic seams and the grid for the complete body. Output is checked against that reservation and for finite coordinates. Missing faces or exceeded budgets cause a cache miss. This mesh is approximate, read-only display; normal modelling/export tessellation is unchanged.