* 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>
25 KiB
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.
- Regions: the infinite region, then bounded regions in the producer's order.
- Shells and faces in order of first appearance, walking regions → shells → oriented faces.
- 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.
- 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.