Spike 1: bevel gear math port + Route A (ThruSections loft)

[gsdali]

Part of #84.

Goal

Port the bevel gear math from BOSL2 and build the first solid via Route A: a stack of
closed section wires fed to ThruSectionsBuilder. This is the faithful port. It mirrors what
BOSL2 does, with no booleans.

Time-box: half a day.

Question this spike answers

Does OCCT loft a stack of ~1100-point closed section wires into a valid solid, and how slow is it?

Scope

Straight/zerol teeth only (spiral = 0), no backing, no bore, single gear.

Math to port (all pure functions, low risk)

From gears.scad:

BOSL2	Line	Notes
bevel_pitch_angle(teeth, mate_teeth, drive_angle)	4142	atan(sin S / (N_mate/N + cos S))
pitch_radius()	3928
outer_radius()	3985
_root_radius_basic()	4069
_base_radius()	4105
circular_pitch() / module_value()	3744 / 3803	pitch-system conversions
cone radii + face_width default	2518-2526	default_face_width = min(ocone_rad/3, 10*mod)

The 2D involute tooth profile can start from the existing implementation at
recipes/04-spur-gear/main.swift:38-48 rather than porting BOSL2's full
_gear_tooth_profile() (gears.scad:3366). The undercut, rounding and clipping machinery is
explicitly deferred (see #84).

Construction (Route A)

Port the per-slice transform stack at gears.scad:2546-2564:

scale(u) -> xrot(pitch_angle) -> back(u*pr) -> zrot(ang/sin(pitch_angle)) -> up(...)

where u = dist / ocone_rad. For each of slices+1 stations build one closed section wire
containing all teeth tooth profiles around the full circle, then:

let loft = ThruSectionsBuilder(isSolid: true, isRuled: false)
// addWire per slice

Relevant OCCTSwift API notes:

• ThruSectionsBuilder(isSolid:isRuled:precision:), addWire(_:), build(), shape
• checkCompatibility(_:) reorders wires to avoid twists; likely needed here
• Upstream warns that mixing closed and open profiles causes a SIGSEGV inside OCCT
  (BRepFill_CompatibleWires). All our sections are closed, so keep it that way.

Acceptance criteria

• A 36-tooth zerol bevel gear builds as a solid with isValid == true
• Volume and bounding box recorded (sanity-checkable against the cone geometry)
• Build wall-clock time recorded at 16, 28 and 36 teeth
• Face count recorded. The prediction is ~5500 faces for 36 teeth, which would be a red
  flag for downstream filleting and STEP export
• Findings written up in the issue: does it hold, and is the B-Rep usable or soup?

Prediction on record

Route A works and gets us a picture quickly, but produces a bloated B-Rep. Recording the numbers
is the point. They are the input to the Route A vs Route B decision in #86.

[gsdali]

Spike 1 findings: BOSL2 bevel gear math port + Route A (ThruSections loft)

Summary

Route A works. A 36 tooth zerol bevel gear builds as a solid, reaches isValid == true after a heal() pass, and exports to STEP. Build time is well inside budget (under two seconds even at 36 teeth), and face count is roughly five times better than the ~5500 prediction on record. One caveat is worth carrying into Spike 2: the raw loft is never valid on its own, at any teeth count tested. It needs a heal() pass every time.

Committed at spikes/85-bevel-route-a.swift on spike/85-bevel-math.

What was ported

• bevel_pitch_angle, pitch_radius, outer_radius, _root_radius_basic, _base_radius from gears.scad, with profile_shift = 0, helical = 0.
• The per-slice scale(u) -> xrot(pitch_angle) -> back(u*pr) -> zrot(ang/sin(pitch_angle)) -> up(...) transform stack (gears.scad:2546-2564).
• The 2D involute tooth flank, reused directly from recipe 04's flankPoint/rootPoint math and rotated into BOSL2's local "transverse, radial" tooth-profile convention.

Scope matches #85 and #84's out-of-scope list: spiral = 0 (straight/zerol), no backing, no bore, single gear, mate_teeth == teeth (a 45 degree symmetric miter pair, so bevel_pitch_angle is always 45 degrees here). The lengthwise tooth trace is a straight radial line from the inner to the outer cone radius rather than a port of BOSL2's Gleason cutter-arc simulation; that trace is spike 3's job (#87). No undercut simulation, jaggy-stripping, self-intersection clipping, or profile shift.

Measurements

module = 2mm, pressure angle = 20 degrees, slices = 5 (BOSL2 default, 6 loft stations), 14 samples per involute flank (32 points per tooth). Single run per teeth count, not averaged, on a warm local build.

teeth	pr (mm)	outer cone radius (mm)	face width (mm)	points/section	wire build	loft build	heal	total wall clock	raw isValid	healed?	final isValid	volume (mm^3)	faces	bbox radius (mm)	bbox height (mm)
16	16.0	22.63	7.54	512	1.8 ms	331 ms	86 ms	419 ms	false	yes	true	1941.2	512	17.41	8.10
28	28.0	39.60	13.20	896	1.9 ms	1009 ms	160 ms	1171 ms	false	yes	true	10663.5	896	29.41	12.08
36	36.0	50.91	16.97	1152	2.5 ms	1681 ms	226 ms	1909 ms	false	yes	true	22814.7	1152	37.41	14.75

1152 points per section at 36 teeth confirms the "~1100 point" estimate on record.

Acceptance criteria

• A 36 tooth zerol bevel gear builds as a solid with isValid == true, after a heal() pass. The raw loft output is never valid on its own; see below.
• Volume and bounding box recorded, sanity checked against the cone geometry:
  • Bounding box radius matches the hand-derived pr + module * cos(pitch_angle) to within 0.02mm at all three teeth counts (expected 17.41 / 29.41 / 37.41mm, measured 17.406 / 29.408 / 37.409mm).
  • Bounding box height matches an analytic z-range derivation to within 0.01mm (the tooth root at the large/outer end sits at z = 0 by construction; the tooth tip at the small/apex end is the global maximum).
  • Volume scales close to teeth^3, as expected for a shape that is nearly self-similar once module is held fixed: 16 to 28 teeth measured 5.50x against an expected 5.36x; 28 to 36 measured 2.14x against an expected 2.13x.
• Build wall-clock time recorded at 16, 28, 36 teeth (table above).
• Face count recorded: 512 / 896 / 1152, not ~5500. Face count equals points-per-section exactly (one B-Rep face per loft "column", independent of slice count), not slices times teeth times points-per-tooth as the prediction assumed.
• Findings written up (this comment).

The isValid finding

The raw ThruSectionsBuilder(isSolid: true, isRuled: false).build() output reports isValid == false at every teeth count tested, while:

• detailedCheckStatuses is empty: zero localized errors across vertex, edge, wire, face, shell, and solid.
• isSelfIntersecting(timeout:) returns false.
• shapeTypeString is "solid" with the expected sub-shape counts (1 solid, 1 shell).
• volume already matches the eventual post-heal volume exactly.

A single shape.healed() call (ShapeFix_Shape) fixes it every time, with the same volume and the same face count before and after healing, at all three teeth counts. Healing for free with zero geometric change points at a minor topological flag (same-parameter, tolerance, or similar), not a structural defect. Practical takeaway for later spikes: always heal a ThruSectionsBuilder result built from a dense polygonal section stack like this one before trusting isValid.

I also tried isRuled: true, closer to a literal straight-facet reading of BOSL2's own VNF approach. It came out worse, not better: in an early coarse diagnostic run (teeth = 16, slices = 2, flank samples = 3), smooth gave 192 faces with a correct volume, ruled gave 384 faces with an uncomputable volume even after healing. Smooth (isRuled: false) plus heal is the configuration to carry forward.

Is it usable, or is it soup?

It is a real B-Rep, not soup. Proper solid topology, correct volume, heals cleanly, exports to STEP without incident (158,815 entities across all three gears combined in one file), and the overall shape and bounding box match hand-derived cone geometry closely.

The face count, while far better than the ~5500 prediction, is still high relative to how a bevel gear would be CAD-modeled by hand (a handful of ruled or swept faces per tooth, not 512 to 1152 total). The reason: the tooth flank here is a polyline, 32 straight segments sampled from the involute, the same representation recipe 04's planar spur gear already uses, and every polyline segment becomes its own planar B-Rep face once lofted. That is not a defect introduced by the loft; it is inherent to sampling the involute into points instead of fitting it to a curve. It means downstream filleting will be working with hundreds of tiny, nearly-collinear edges per tooth flank rather than one clean edge, a real risk for fillet robustness and STEP file bloat, even though the raw face count is no longer the alarm bell the ~5500 estimate suggested.

Recommendation for Spike 2 (#86)

Route A clears its bar: fast (well under two seconds even at 36 teeth), and it produces a valid, correctly-volumed, STEP-exportable solid once healed. The question Route A does not resolve is the tooth-flank representation: whether circularPatternCut on a revolved blank in Route B either (a) shares the same polyline-per-flank characteristic, no improvement to expect there, or (b) makes it practical to swap the sampled involute for an actual curve, materially cutting the face count and easing later filleting. That comparison, more than raw loft feasibility, should decide between A and B.

Recommend proceeding to Spike 2 carrying forward the "heal immediately after build" pattern from this spike, and adding tooth-flank face count as one of Route B's own measurements so the two routes are comparable on that axis, not just build time and validity.

Note: unrelated tooling gap found in this worktree

swift run occtkit run <file> fails in this worktree with unknown package 'OCCTSwiftScripts' in dependencies of target 'Script'; valid packages are: 'bevel-gear'. Sources/occtkit/Commands/Run.swift:129 hardcodes the generated workspace's dependency product lookup as package: "OCCTSwiftScripts", but SwiftPM derives a local path dependency's identity from the checkout directory's basename, bevel-gear here since the worktree deliberately lives outside the main checkout, not from the target manifest's name: field. Worked around by copying the spike script over Sources/Script/main.swift and running swift run Script directly (documented in the spike file's own header comment). Did not touch Run.swift; out of scope for this spike, but worth a follow-up issue if more differently-named worktrees or spikes are expected.