Skip to content

Ball patches through the flat arrays and USD: a definition record for faces (from smlib#102) #13826

Open

Description

@jyviko

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.
  • The cause: export wrote the patch as bare NURBS, and import made a plain SmBSplineSurface with no sphere.
    • A plain B-spline's OffsetCollapses is FALSE, so the shell offset the patch past its centre.
    • Meanwhile the rounds beside it collapsed, and SmOffsetExecutive couldn't mate faces across them (23 unbridged edges).
  • The flat fix has landed (see below).
  • USD BrepArray loses the patch the same way:
    • SmuConvert.cpp BrepAppend_SMLibToUsdBrep writes any SmBSplineSurface-kind surface as BrepSurfaceNurbAPI.
    • BrepMove_OneUsdBrepToSMLibData reads it back as a bare SmBSplineSurface.
    • Line numbers are on 7048946: about 2280-2286 and 3861-3878.

Approved schema (coordinator 12214)

  • No new face:surfaceType token.
    • A ball patch stays BrepSurfaceNurbAPI: its net is in the BrepSurfaceNurbAPI arrays, and its face:range and UV trims are in the net's parameters.
    • Readers that don't know definitions keep working.
  • A new singleApply API, BrepSurfaceDefinitionAPI (apiSchemaCanOnlyApplyTo ["OmniSolidBrepArray"]). It is authored only when some face has a definition. Its attributes:
    • uniform uint[] face:definition:kind, apiName faceDefinitionKind.
      • One per face; size() = number of faces.
      • Values: 0 = none, 6 = ball patch.
      • A kind other than 0 is allowed only on a BrepSurfaceNurbAPI face.
    • uniform uint[] face:definition:realCount, apiName faceDefinitionRealCount.
      • 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, apiName faceDefinitionReals.
      • 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.usda gets the new class after BrepSurfaceNurbAPI, a line in the face:surfaceType doc, and a line in the HasAPI list.
    • generatedSchema.usda and plugInfo.json are regenerated by prebuild. That uses usdGenSchema and needs jinja2 in the system python3.
  • source/BREP_USD_DATA:
    • UsdBrepTokens.h gets tokens brepSurfaceDefinitionAPI, faceDefinitionKind, faceDefinitionRealCount and faceDefinitionReals.
    • UsdBrepArrayData.h gets:
      • the constants USDBREP_FACE_DEFINITION_NONE / _BALL_PATCH (6) / _BALL_PATCH_REALS (4);
      • the arrays m_sFace_DefinitionKindArray, m_sFace_DefinitionRealCountArray and m_sFace_DefinitionRealsArray;
      • span fields m_lFaceDefinition_StartIndex/_Count and m_lFaceDefinitionReal_StartIndex/_Count.
    • UsdBrepArrayData.cpp: clear, span reset and advance, and the per-face count that refuses truncated data.
    • UsdBrepWrite.cpp authors the three attributes and applies the API (through the apiSchemas list-op, in the SdfChangeBlock) only when some kind is non-zero.
    • UsdBrepRead.cpp reads them when HasAPI(BrepSurfaceDefinitionAPI).
  • source/USD_BREP_UTILS:
    • The iterator gets UsdBrepView::FaceDefinitionKinds/RealCounts/Reals.
    • UsdBrepPacking.cpp appends them. Once any brep has kinds, earlier and later faces are padded with kind 0.
  • source/BREP_SM_USD/src/SmuConvert.cpp:
    • Export (around line 2371): an SmBallPatch on 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 IsOnSphere must certify the net, then SmBallPatch::Create replaces the net.
      • Local cursors lDefinition and lDefinitionReal start at the brep's span start.
  • 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.expectedFailure in 967c8b6; the WIP commit drops the marker.

  • Six validator fixtures, TestFiles/brep_validator/Test_BA_766..771_*.usda. Their generators are in tools/brep_validator_test/generate_test_files.py (with_face_definitions plus one generator per rule).

    • test_brep_validator.py has a KNOWN_FAILING_FIXTURES list: 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 capi smlib_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.sh and ./repo.sh build, but only with FatalCompileWarnings and -Werror turned 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 sOn in SmBlendCornerBall.cpp:541;
      • a shadowed sW in SmBlendCorner.cpp:1363;
      • a member reorder in SmBlendCorner.h (m_pBallSurface and m_lFillOrder).
    • These need fixing for any premake/USD CI.
  • 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

https://claude.ai/code/session_01DtL5M41G8Nua7HvuFPZkmJ

Activity

  1. jyviko commented on Nov 2, 2026

    @jyviko
    CollaboratorAuthor

    The USD work in progress is on branch archive/wip/102-usd-definition-record of tangency-labs/smlib (b1ffbbf: tangency-labs/solidcore#102's flat fix on 7048946, then 967c8b6 with the tests and b1ffbbf with the WIP implementation).

  2. jyviko commented on Nov 2, 2026

    @jyviko
    CollaboratorAuthor

    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.

  3. jyviko commented on Nov 2, 2026

    @jyviko
    CollaboratorAuthor

    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.

  4. bluecmd commented on Nov 2, 2026

    @bluecmd
    Contributor

    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?

    • No flat C API here. 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 a ball_patch kind. So the flat-array half has nothing to port into.
    • What remains is small:
      • SmBallPatch::IsOnSphere, the per-Bézier-piece Bernstein certificate;
      • a public certified constructor (net + centre + R → ball-patch surface, refused with 1007 otherwise);
      • an accessor for the definition, so SolidCraft's record can export and import a ball patch in place of the capi.
    • It sits on SmBallPatch. The type itself (f8e6709) is fix: SmBallPatch, the Ball corner's exact patch (step 4c follow-up) solidcore#2319's scope, so this would build on it and stay opt-in under the existing fillet_blend_corner, with no new fix field.
    • Tests: smlib#121's three cases.
      • The box rounded all round (r 1.5, 8 Balls), its corner faces rebuilt from net + definition, then shelled 2 open at the front (volume 15305.4357…).
      • A net with knots inserted still certifies.
      • A radius 1e-9 larger is refused.

    Two questions:

    1. @jyviko: should we also take (b), the USD definition record, as a follow-up, or is someone already on it?
    2. @brett19: are you happy for me to build on fix/blend-step4c-ball-patch once it has the type? Or would you rather fold IsOnSphere into 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

  5. self-assigned this
    on Nov 3, 2026
  6. added a commit that references this issue on Nov 3, 2026
  7. jyviko commented on Nov 4, 2026

    @jyviko
    CollaboratorAuthor

    Taking this one; PR to follow.

  8. 24 remaining items

  9. moved this from Todo to In Progress in Blends Sprinton Nov 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requesthelp wantedExtra attention is neededin progresssomeone is working on it (see comments)needs-triageno priority yet; a maintainer sorts it with /triage

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions