Repository navigation
Description
Code: branch archive/wip/102-flat-ball-patch of tangency-labs/smlib (bc814a5 on dda881f, gated). The USD work in progress is described in the second part; its branch is pushed separately.
Port brief: a Ball patch through the flat arrays (smlib#102, flat part)
What it does
SMLib's Ball corner is an SmBallPatch: a rational stereographic patch that carries its sphere's centre
and radius as its definition, so its offset is exact (the control net scaled by (R ± d)/R). Before this
change the C API's flat arrays wrote it as a bare NURBS and read it back as an SmBSplineSurface, losing
the sphere. A box rounded all round and then shelled therefore failed after a round trip (status 1034):
the corners' offset no longer collapsed exactly, and the shell could not mate across them.
The fix gives the flat arrays a surface kind for definition-carrying faces:
- SMLIB_FLAT_SURFACE_BALL_PATCH = 6, a FACE_SURFACE_TYPE value. A kind-6 face carries its NURBS block
exactly as a NURBS face does (FACE_NURBS_FORM = 0; FACE_RANGE and the UV trims in its NURBS
parameters). - SMLIB_FLAT_FACE_DEFINITION_REAL_COUNT = 36 (int64): one entry per definition-carrying face, in face
order; 4 for a ball patch. - SMLIB_FLAT_FACE_DEFINITION_REALS = 166 (double): those reals packed in the same order (cx, cy, cz, R,
with R > 0).
Export writes an SmBallPatch as kind 6. Import makes the face an SmBallPatch only after
SmBallPatch::IsOnSphere certifies the net: the exact Bernstein identity per Bezier piece, to 1e-12 of
((R + |C|) maxW)^2. A net that fails the certificate is refused (1007).
A reader that doesn't know kind 6 can read it as NURBS and ignore ids 36 and 166, but must write them
back unchanged if it rebuilds the arrays. The design for later definition kinds (for example 7 = the
procedural blend) is in 102-usd-definition-record.md.
Tests
- bdc537a: the box rounded all round (r 1.5, its 8 corners Balls), shelled open at the front. It runs
in process (a guard) and through a flat round trip. It failed before the fix. - 7060575: the flat record checks:
- 8 BALL_PATCH faces, and 8 definitions with each corner's centre and r 1.5;
- a net cut by inserted knots still certifies;
- a sphere 1e-9 larger is refused.
- bc814a5: the fix.
Gate status
Gated on replay dda881f, the final head: build 0, ctest 22/22, the default ops_kernel run "all checks
passed", and the balls known-failing list exits 0.
- The round trip gives 8 ball patches and 8 of 8 definitions, with every corner on its sphere.
- The shell builds, status 0, volume 15305.435784173 (the issue's 15305.435766881; the same as in
process).
It was earlier gated per commit on f916a8d, where every log was identical apart from the new cases'
lines.
What's left
- It never landed. The owner stopped all landing on 2026-11-02.
- The USD half is the follow-up: 102-usd-definition-record.md, WIP branch step4-fix102-usd.
- SolidCraft's reader needs the two new ids and kind 6 in the same pin as the kernel change.
Branch
step4-fix102-dda881f (local rb2-fix102), head bc814a5 on replay dda881f. Bundle:
(bundle, pushed as the wip branch above) (checksum in (bundle, pushed as the wip branch above)). The original is
step4-fix102 (eb1d5c2, on f916a8d).
Port brief: smlib#102 USD follow-up, the BrepArray face definition record
Status: stopped by owner decision; this work moves to solidcore. smlib#102 stays open for it.
What it is for
- smlib#102 was a SolidCraft develop regression. A box rounded all round (r1.5) has eight Ball corners.
- Each corner is an
SmBallPatch: a rational patch stored with its sphere (centre, radius). - Once the body goes through the flat arrays, shelling it 2 in failed with status 1034.
- Each corner is an
- The cause: export wrote the patch as bare NURBS, and import made a plain
SmBSplineSurfacewith no sphere.- A plain B-spline's
OffsetCollapsesis FALSE, so the shell offset the patch past its centre. - Meanwhile the rounds beside it collapsed, and
SmOffsetExecutivecouldn't mate faces across them (23 unbridged edges).
- A plain B-spline's
- The flat fix has landed (see below).
- USD BrepArray loses the patch the same way:
SmuConvert.cppBrepAppend_SMLibToUsdBrepwrites anySmBSplineSurface-kind surface asBrepSurfaceNurbAPI.BrepMove_OneUsdBrepToSMLibDatareads it back as a bareSmBSplineSurface.- Line numbers are on 7048946: about 2280-2286 and 3861-3878.
Approved schema (coordinator 12214)
- No new
face:surfaceTypetoken.- A ball patch stays
BrepSurfaceNurbAPI: its net is in the BrepSurfaceNurbAPI arrays, and itsface:rangeand UV trims are in the net's parameters. - Readers that don't know definitions keep working.
- A ball patch stays
- A new singleApply API,
BrepSurfaceDefinitionAPI(apiSchemaCanOnlyApplyTo ["OmniSolidBrepArray"]). It is authored only when some face has a definition. Its attributes:uniform uint[] face:definition:kind, apiNamefaceDefinitionKind.- One per face; size() = number of faces.
- Values: 0 = none, 6 = ball patch.
- A kind other than 0 is allowed only on a
BrepSurfaceNurbAPIface.
uniform uint[] face:definition:realCount, apiNamefaceDefinitionRealCount.- One per face whose kind is not 0, in face order.
- Each is the count its kind fixes (a ball patch: 4).
uniform double[] face:definition:reals, apiNamefaceDefinitionReals.- Packed as realCount counts them; size() = SUM(realCount).
- A ball patch: cx, cy, cz, R, with R > 0.
- Why realCount stays although the kind fixes it (this is in the doc text):
- A reader that doesn't know a kind can skip that face's reals, keep the NURBS net, and treat the face as plain NURBS.
- SMLib's own import is stricter: it refuses a kind it doesn't know, and takes a known kind only after a certificate shows the net agrees with it. For a ball patch, that is
SmBallPatch::IsOnSphere. - The two behaviours differ in what they trust, not in what the record means.
- Later kinds take new values with no schema change.
The flat-array counterpart (landed, smlib#102; rebased by the coordinator as rb-fix102, 5012517 on 7048946)
- Constants (
capi/include/smlib.h):SMLIB_FLAT_SURFACE_BALL_PATCH = 6, a FACE_SURFACE_TYPE value.SMLIB_FLAT_FACE_DEFINITION_REAL_COUNT = 36(int64).SMLIB_FLAT_FACE_DEFINITION_REALS = 166(double).
- Record:
- A kind-6 face carries its NURBS block as a NURBS face does, with FACE_NURBS_FORM 0.
- It has one REAL_COUNT entry per definition face, in face order (4).
- Its REALS are cx, cy, cz, R.
- Certificate:
SmBallPatch::IsOnSphere(net, C, R, 1e-12, bOn)(SmBallPatch.h/.cpp).- The net is cut into Bézier pieces by raising its interior knots to the degree.
- Over each piece, every Bernstein coefficient of |X − C·W|² − R²·W² (degree 2p, 2q) must be zero within 1e-12 · ((R + |C|) · maxW)².
- It is decided on the net, not at sample points.
- Import builds
SmBallPatch::Create(net, C, R)only when the certificate holds; otherwise it refuses (1007).
- SolidCraft's reader needs kind 6, read as a NURBS face, in the same pin. It may ignore ids 36 and 166, but must write them back unchanged if it rebuilds the arrays.
Where the USD code changes (all done on the branch below, WIP)
- Schema:
source/schema/omniSolid/resources/schema.usdagets the new class after BrepSurfaceNurbAPI, a line in the face:surfaceType doc, and a line in the HasAPI list.generatedSchema.usdaandplugInfo.jsonare regenerated by prebuild. That uses usdGenSchema and needs jinja2 in the system python3.
source/BREP_USD_DATA:UsdBrepTokens.hgets tokensbrepSurfaceDefinitionAPI,faceDefinitionKind,faceDefinitionRealCountandfaceDefinitionReals.UsdBrepArrayData.hgets:- the constants
USDBREP_FACE_DEFINITION_NONE / _BALL_PATCH (6) / _BALL_PATCH_REALS (4); - the arrays
m_sFace_DefinitionKindArray,m_sFace_DefinitionRealCountArrayandm_sFace_DefinitionRealsArray; - span fields
m_lFaceDefinition_StartIndex/_Countandm_lFaceDefinitionReal_StartIndex/_Count.
- the constants
UsdBrepArrayData.cpp: clear, span reset and advance, and the per-face count that refuses truncated data.UsdBrepWrite.cppauthors the three attributes and applies the API (through the apiSchemas list-op, in the SdfChangeBlock) only when some kind is non-zero.UsdBrepRead.cppreads them whenHasAPI(BrepSurfaceDefinitionAPI).
source/USD_BREP_UTILS:- The iterator gets
UsdBrepView::FaceDefinitionKinds/RealCounts/Reals. UsdBrepPacking.cppappends them. Once any brep has kinds, earlier and later faces are padded with kind 0.
- The iterator gets
source/BREP_SM_USD/src/SmuConvert.cpp:- Export (around line 2371): an
SmBallPatchon a NURBS face pushes kind 6 and its 4 reals; every other face pushes kind 0. - Import:
- At the start of the face loop, a kind other than 0 on a face that isn't NURBS is refused.
- In the NURBS branch (around line 3900), a kind other than 6, or a count other than 4, is refused.
- Otherwise
IsOnSpheremust certify the net, thenSmBallPatch::Createreplaces the net. - Local cursors
lDefinitionandlDefinitionRealstart at the brep's span start.
- Export (around line 2371): an
- Validator (
tools/brep_validator/brep_validator.py):_validate_face_definitions, called from CheckPrim after_validate_face_arrays, with requirements:- BA.766: kind size equals the number of faces.
- BA.767: a definition only on a NURBS face.
- BA.768: one realCount per defined face, each its kind's (
FACE_DEFINITION_REALS = {6: 4}; unknown kinds are checked for structure only). - BA.769: reals size is SUM(realCount), all finite.
- BA.770: a ball patch's R > 0.
- BA.771: the attributes only with the API applied, and the API only with the kind authored.
- The validator checks structure only; the sphere certificate is the reader's.
Tests (tests-first commit 967c8b6)
-
source/SmPyLib/tests/test_omni_solid.py,TestUsd.test_ball_corners_keep_their_spheres_through_usd. Export the box rounded all round, then check:- 8 kinds of 6, the rest 0, and 32 reals;
- each centre r in from three faces, with R = 1.5;
- import, export again: the same 8 definitions;
- a radius 1e-9 off its net, written into the file, makes the import raise.
It is marked
@unittest.expectedFailurein 967c8b6; the WIP commit drops the marker. -
Six validator fixtures,
TestFiles/brep_validator/Test_BA_766..771_*.usda. Their generators are intools/brep_validator_test/generate_test_files.py(with_face_definitionsplus one generator per rule).test_brep_validator.pyhas aKNOWN_FAILING_FIXTURESlist: filled in 967c8b6, emptied in the WIP commit.- It also has
test_face_definitions_well_formed_are_accepted.
-
Why the test doesn't shell the body: the Python
shell_brep(SmApiShellBrepFull) returns 1007 on this body even in process, unlike capismlib_shell. That is a separate finding, not looked into.
What's built and its state
- Branch
step4-fix102-usd, worktree(maintainers' notes), on rb-fix102 (5012517). Commits:- 967c8b6: the tests, failing as listed.
- b1ffbbf: WIP, the implementation above.
- Built locally with
./prebuild.shand./repo.sh build, but only withFatalCompileWarningsand-Werrorturned off. The local patch, not committed, is(maintainers' notes).- Replay's premake build fails -Werror on the fork's own code:
- SmObject.h:183 nonnull-compare, through SmBallPatch's
SM_CAST_PTR(.., &crOther); - a shadowed
sOnin SmBlendCornerBall.cpp:541; - a shadowed
sWin SmBlendCorner.cpp:1363; - a member reorder in SmBlendCorner.h (
m_pBallSurfaceandm_lFillOrder).
- SmObject.h:183 nonnull-compare, through SmBallPatch's
- These need fixing for any premake/USD CI.
- Replay's premake build fails -Werror on the fork's own code:
- On that build:
- the round trip's export and read-back checks pass;
- open: the import of the radius-1e-9-off file doesn't raise. To diagnose: whether IsOnSphere's 1e-12 · ((R + |C|) · maxW)² scale (|C| up to ~60 here) admits it, or the failure is swallowed in the import path. The flat test of the same body did refuse it.
- Not run on this state: the validator suite and
tests.sh linux-aarch64.
- Test runner helper:
(maintainers' notes) smpy|validator <unittest selector>.
Design for later definition kinds (from notes-task5/flat-definitions-note.md, for tangency-labs/solidcore#97)
- A new kind value for each surface defined beyond its net, e.g. 7 for an
SmProceduralBlend(step 7 noted the flat transfer carries only its net).- The net stays in the NURBS block (flat) or BrepSurfaceNurbAPI (USD), so a reader that ignores definitions still reads it as NURBS.
- The definition goes in the same two arrays: a per-face count, so a variable-length kind fits, and the packed reals.
- Integer data: a definition that needs integers gets a sibling pair (flat: FACE_DEFINITION_INTS with an INT_COUNT; USD:
face:definition:ints/face:definition:intCount), packed the same way. It is added only when a kind needs it. - Curves: a definition that refers to curves (a procedural blend's spine and rails) should reference curves already in the arrays where it can. Otherwise it needs its own curve block, packed like the edge NURBS blocks.
- Certification: every kind needs an import certificate that the net agrees with its definition. For a procedural blend, that is the certificate it already builds. A kind without one is refused, never silently trusted.
Handed over from SMLib (tangency-labs/smlib), where construction stopped by the owner's decision on 2026-11-02. Please claim on this issue before starting.
🤖 Generated with Claude Code
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsIn Progress
Activity
jyviko commentedon Nov 2, 2026
The USD work in progress is on branch
archive/wip/102-usd-definition-recordof tangency-labs/smlib (b1ffbbf: tangency-labs/solidcore#102's flat fix on 7048946, then 967c8b6 with the tests and b1ffbbf with the WIP implementation).jyviko commentedon Nov 2, 2026
Update (owner, 2026-11-02): this lands in SMLib after all. It is being gated on the current replay/1.0.1 head and will merge there; a port issue follows, as for the other merged blend PRs. This issue then closes in favour of that port issue.
jyviko commentedon Nov 2, 2026
The flat part landed in SMLib as tangency-labs/smlib#121 (d5995c3): port those 4 commits from there. The USD part (the definition record, branch
archive/wip/102-usd-definition-record) stays here as new work.bluecmd commentedon Nov 2, 2026
I'd like to take (a), the port of smlib#121. Here is what I think that means for solidcore; is this the right reading?
smlib_flat.cpp, kind 6 and ids 36/166 exist only in the fork's capi. As The procedural blend's definition kept through SolidCraft's record: a round reopened or split is still solved on S, not its net #13822 puts it, SolidCraft links solidcore directly, and its record already has aball_patchkind. So the flat-array half has nothing to port into.SmBallPatch::IsOnSphere, the per-Bézier-piece Bernstein certificate;fillet_blend_corner, with no new fix field.Two questions:
fix/blend-step4c-ball-patchonce it has the type? Or would you rather foldIsOnSphereinto fix: SmBallPatch, the Ball corner's exact patch (step 4c follow-up) solidcore#2319 itself? Either is fine with us.I'll wait for answers before opening anything.
🤖 Generated with Claude Code
Merge pull request #2526 from tangency-labs/ball-patch-flat-arrays
test: a box rounded all round keeps its ball patches through the data…
fix: a ball patch from data is certified on its sphere before it is m…
test: the ball patch cases at the certificate's real tolerance, the o…
fix: a face use's offset asks whether it collapses before it is made …
docs: WR-464 addendum, the collapse asked before the offset is made (…
jyviko commentedon Nov 4, 2026
Taking this one; PR to follow.
24 remaining items
test: a ball patch far from the origin is certified as tightly as nea…
fix: IsOnSphere's tolerance is the sphere's own size plus the coeffic…
test: a NaN, infinite or overflowing net or loop never certifies on i…
fix: a sphere certificate accepts only a finite residual within a fin…
test: a ball patch read from the B-rep record is certified on its sph…
fix: a ball patch is read from the B-rep record only once certified o…
fix: the geometry nesting walk knows the Ball's definition, which nes…
test: a ball patch face read through to_kernel keeps its sphere only …
fix: one read of a ball patch face, its net and loop certified on its…
style: rustfmt the ball patch read tests (#2357)