Spike 2: bevel gear Route B (revolved blank + circularPatternCut)

[gsdali]

Part of #84. Depends on #85 (reuses its math port).

Goal

Build the same gear the OCCT-idiomatic way and compare head-to-head with Route A: revolve a
cone-frustum blank, loft one tooth-space cutter, then pattern-cut it N times.

Time-box: half a day.

Question this spike answers

Does circularPatternCut survive 20+ near-tangential boolean cuts against a cone?

This is the historical failure point for B-Rep gear generation, and the single biggest unknown
in the whole epic.

Approach

1. Blank. Revolve the axial profile of the gear body (outer cone, root cone, face width)
   into a frustum.
2. Tooth-space cutter. Loft the gap profile across the same slices+1 stations used in
   Route A, extended radially far enough to clear the blank at both ends.
3. Pattern cut. One call:

   blank.circularPatternCut(tool: toothSpace,
                            axisPoint: .zero,
                            axisDirection: SIMD3(0, 0, 1),
                            count: teeth)

circularPatternCut is confirmed present in OCCTSwift 1.3.1 and later (OCCTSwift#169) and is
already used in this repo by recipes/03-pipe-flange/.

Why this route is worth the risk

A proper B-Rep with roughly 10x fewer faces than Route A: filletable, chamferable, and it
exports a clean STEP. That is the difference between a demo and something a downstream consumer
(OCCTStudio, OCCTMCP) can actually build on.

Acceptance criteria

• Same 36-tooth zerol gear builds with isValid == true
• Face count and build time recorded, compared side by side with Spike 1: bevel gear math port + Route A (ThruSections loft) #85's numbers
• Shape.analyze() snapshot recorded (small edges, free edges, self-intersections). A cut
  that "succeeds" but leaves slivers is a failure for our purposes
• Behaviour at high tooth counts probed (36+), where cuts crowd together
• A recommendation recorded: which route Spike 3: spiral tooth trace + backing / handedness / bore #87 builds on, and why

Failure is still a result

If the booleans prove unreliable, that is a legitimate and cheap finding. It tells us BOSL2
ports in this repo must stay loft-only, and it retires the idea of a filletable parametric gear
until an upstream OCCT fix. Record the specific failure mode (which tooth index, what
analyze() reports). That is what an upstream OCCTSwift issue would need.

[gsdali]

Spike 2 findings: bevel gear Route B (revolved blank + circularPatternCut)

Summary

circularPatternCut survives the full crowding test: a hollow cone-frustum blank cut by one
tooth-space wedge, patterned all the way around, stays isValid with zero self-intersections,
zero free edges, and zero small edges or faces at every tooth count tried, 16 through 60. That
is the question this spike exists to answer, and the answer is yes.

The gear it builds is not correct, though, and that did not get fixed inside the timebox. The
cutter's gap-boundary formula checks out to a few tenths of a millimeter against spike 85's own
tooth flank at three different radii, but the resulting cut removes far less material than it
should: rendered previews show the surviving "teeth" as thin, disconnected blade-like remnants
rather than a continuous toothed rim, and Shape.volume on the final pattern-cut shape returns
nil (uncomputable) whenever the cutter carries the radial clearance #86 asked for to clear the
blank's own boundary. Dropping that clearance to zero, i.e. letting the cutter graze the blank
exactly (the tangency #86 warned against), makes volume computable again but the cuts barely
remove any material at all. Neither configuration is a correct gear. This is reported as an
open, specific, reproducible defect rather than routed around, per #86's own "failure is still a
result" framing.

Committed at spikes/86-bevel-route-b.swift on spike/86-bevel-route-b.

What was built

1. Blank: a hollow cone-frustum shell (outer/addendum cone, root/dedendum cone, same face
   width as spike 85), built by revolving a 4-point trapezoid meridian profile 360 degrees about
   the Z axis. Valid, 4 faces, correct volume every time.
2. Tooth-space cutter: one gap wedge, lofted across the same slices+1 stations spike 85
   used, reusing spike 85's GearGeometry and slicePoint unchanged and generalizing its
   flankPoint/rootPoint closures to accept an explicit radius. The gap boundary uses the same
   involute machinery as a tooth's own flank, at the complementary angular offset
   gapFlankOffset = pi/(2*teeth) - inv(alpha) instead of the tooth's own
   flankOffset = pi/(2*teeth) + inv(alpha), with the two flanks' mirror pairing swapped (a
   tooth converges with radius, a gap diverges). Extended radially past the root and tip
   (radialClearance) so the cut does not graze the blank tangentially.
3. Pattern cut: one blank.circularPatternCut(tool:axisPoint:axisDirection:count:) call, the
   same primitive recipes/03-pipe-flange/main.swift already uses for its bolt circle.

Two real bugs were found and fixed during construction (both documented in the file's header):
a mirror-pairing sign error that made the gap narrow with radius like a tooth instead of
widening like a gap, and a tip-extension that continued along the involute curve past the
addendum instead of projecting radially outward at constant angle, which ate through the
already-thin tooth tip at low tooth counts. Fixing both did not resolve the final defect
described above; a point-by-point coincidence check (tooth flank vs. gap boundary, same 3D
point, evaluated at the base circle, pitch circle, and tip) confirmed the gap formula itself is
correct to within a few tenths of a millimeter at every radius checked, which rules out the
angular math as the remaining cause.

Side-by-side comparison with #85 (Route A)

teeth	A faces	A faces/tooth	A build time	A raw isValid	A volume (mm^3)	B faces	B faces/tooth	B build time	B raw isValid	B volume (mm^3)
16	512	32	419 ms	false (heals)	1941.2	64	4.0	2.60 s	true (no heal needed)	nil (uncomputable)
28	896	32	1171 ms	false (heals)	10663.5	112	4.0	5.86 s	true	nil
36	1152	32	1909 ms	false (heals)	22814.7	144	4.0	7.31 s	true	nil
48	not tested in #85					192	4.0	11.28 s	true	nil
60	not tested in #85					240	4.0	14.08 s	true	nil

Build time ratio (B/A): 6.2x at 16 teeth, 5.0x at 28 teeth, 3.8x at 36 teeth. Route B gets
relatively less slow as teeth increase but stays substantially slower in absolute terms, and
keeps growing past 36 (11.3 s at 48 teeth, 14.1 s at 60). In every run, the single
circularPatternCut call itself is over 98% of total wall clock (the blank revolve and the
one-wedge loft are both under 20 ms combined); the cost is in the N-fold boolean, not the
geometry setup.

One genuinely good sign buried in that row: Route B's raw circularPatternCut output is
isValid immediately, at every tooth count, with no heal() needed. Route A's raw
ThruSectionsBuilder output is never isValid on its own and always needs a heal pass. That
asymmetry held even while the underlying geometry was wrong, which is itself informative about
circularPatternCut's output quality independent of this spike's cutter bug.

Tooth-flank face count, the deciding question from spike 85's recommendation

Spike 85 recommended that this comparison, not raw build time, decide between the routes: does
Route B share Route A's polyline-per-flank characteristic, or does it make swapping the sampled
involute for a fitted curve practical?

This spike cannot answer that question with a straight face, because the built gear is not
geometrically correct. What can be reported:

• The single cutter tool, before any boolean, has 36 faces at every tooth count (matching spike
  85's own finding that loft face count equals points-per-section: the wedge's local profile has
  32 flank/root/tip points, plus loft end caps). That confirms this spike used the same
  14-sample-per-flank discrete polyline as spike 85, not a fitted curve; per Spike 2: bevel gear Route B (revolved blank + circularPatternCut) #86's instruction to
  reuse spike 85's math rather than re-derive it, no curve-fitting was attempted here.
• The final pattern-cut shape settles at an exact 4.0 faces per tooth at every count (64/16,
  112/28, 144/36, 192/48, 240/60), a suspiciously flat, teeth-count-independent number that does
  not track the cutter's own 36-face structure at all. That is a symptom of the same defect
  described above (the boolean is not preserving the cutter's flank segmentation the way a
  correct cut would), not evidence that Route B's construction naturally collapses a
  14-segment-per-flank polyline into 2 faces. Reading it as "Route B gets 8x fewer faces" would
  be reporting a bug as a feature.
• Whether a correct Route B cut would end up with fewer or more effective flank faces than
  Route A's 32/tooth remains open. Structurally there is reason to expect it could still be much
  better (each cut only ever introduces the cutter's own two flank curves, not a full ring of
  teeth flanks per loft section the way Route A's stacked-ring wires do), but that is
  unconfirmed by this run.

Shape.analyze() snapshot

teeth	freeEdgeCount	smallEdgeCount	smallFaceCount	selfIntersectionCount
16	0	0	0	0
28	0	0	0	0
36	0	0	0	0
48	0	0	0	0
60	0	0	0	0

Clean at every tooth count, by every metric analyze() reports. No slivers, no small edges, no
self-intersections, no free edges, at 60 teeth same as 16. Combined with isValid == true
throughout, this is the strongest evidence available that circularPatternCut itself handled
every one of the near-tangential cuts robustly.

It is also the finding that most needs a caveat: this spike's own gear is visibly wrong (thin
blade-like tooth remnants, Shape.volume returning nil) while analyze() reports a completely
clean bill of health. analyze()'s free-edge / small-edge / small-face / self-intersection
metrics did not catch this defect at all. A cut can pass every check analyze() runs and still
be the wrong shape. Worth carrying forward as a caveat on what "clean per analyze()" actually
guarantees for future spikes.

Spike 85's own validity checks used detailedCheckStatuses and isSelfIntersecting(timeout:)
rather than Shape.analyze(), so there is no directly comparable analyze() snapshot for Route A
to set next to this table. Spike 85's writeup does report detailedCheckStatuses empty and
isSelfIntersecting false at all three of its tooth counts, which is consistent with, if not
identical to, Route B's clean analyze() results here.

Behaviour at high tooth counts (36+)

Tested 36, 48, and 60 teeth (up from #85's ceiling of 36). Every metric that indicates crowding
trouble, self-intersections and small/free edges from analyze(), plus isValid itself, stays
at exactly the same clean values from 16 teeth through 60. The one thing that does grow
noticeably is wall clock (2.60 s to 14.08 s, roughly linear-ish in teeth rather than blowing up),
and the pattern-cut step's own share of that time. Nothing in this data suggests the booleans get
less reliable as cuts crowd together; the defect described above is present uniformly at every
tooth count tested, not something that appears or worsens at high counts specifically.

Acceptance criteria

• [x]/[ ] Same 36-tooth zerol gear builds with isValid == true: technically yes, practically
  no. isValid is true and stays true after the run (no heal even required). But the shape
  is not a correct bevel gear: renders show thin disconnected tooth remnants and
  Shape.volume cannot be computed on it. Recording this as a fail against the acceptance
  criterion's evident intent (a working 36-tooth gear), not just its literal bit.
• Face count and build time recorded, compared side by side with Spike 1: bevel gear math port + Route A (ThruSections loft) #85's numbers: see table
  above. Recorded, with the caveat that Route B's face count does not represent a valid gear.
• Shape.analyze() snapshot recorded: see table above. Every field is zero at every tooth
  count. This criterion explicitly warns that "a cut that succeeds but leaves slivers is a
  failure for our purposes"; this spike's actual failure mode is the inverse case,
  analyze() reports no slivers at all, and the shape is still wrong, in a way analyze()
  does not detect.
• Behaviour at high tooth counts probed (36+): tested 36, 48, 60. No degradation observed in
  isValid or analyze() at any count; build time grows but does not blow up.
• A recommendation recorded: see below.

Recommendation for Spike 3 (#87)

Build on Route A. Route A is the only one of the two that is a confirmed-correct,
dimensionally-validated gear (spike 85 sanity-checked its bounding box and volume scaling against
hand-derived cone geometry). Route B's central risk, whether circularPatternCut survives many
near-tangential cuts against a cone, is now answered and it is a clean yes, at 60 teeth as much as
16. That is a genuinely valuable, reusable result: it means a future attempt at Route B is not
fighting boolean robustness, only this spike's own cutter derivation. But it is a foundation with
a real, unresolved, geometry-correctness bug sitting under it, and Spike 3 has its own half-day
budget for the spiral trace, backing, handedness, and bore. Building spike 3 on top of Route B
today would mean spending that budget re-debugging this spike's cutter instead of adding the
spiral trace it is actually scoped for.

The likely next step for whoever picks up Route B later: the wedge's own loft end caps at the two
axial (face-width) stations are, by construction, exactly coplanar with the blank's own end caps
(both come from the same affine meridian-line relationship established in buildBlank and
buildCutterTool/meridianRZ). A single sequential cut against the blank produces a result with
the same face count as the blank had before the cut (4), despite removing real, non-zero
volume, which points at that axial tangency swallowing geometry that should show up as new wall
faces, rather than the angular gap width (which the coincidence check already rules out as the
cause). Instrumenting one isolated cut's actual face-by-face structure, rather than trusting a
single boundary-point check, would be the fastest way to confirm or rule that out. Filing this as
a follow-up issue against Route B specifically, separate from #87, seems more appropriate than
folding it into Spike 3's own scope.

[gsdali]

Independent verification of the above, and a correction to its headline

I re-measured the committed Route B output BREPs from outside the spike session. The
construction work and the defect disclosure above are accurate, but the headline conclusion
does not hold: #86's question is not answered "yes", it is unanswered.

What the written BREPs actually are

body	teeth	shapeType	volume (mm^3)	surface area	bbox max
body-0	16	compound	-75.46	858.7	17.41, 17.41, 8.04
body-1	28	compound	-2255.03	2315.3	29.41, 29.41, 12.04
body-2	36	compound	-6547.29	3737.3	37.41, 37.41, 14.71

Route A's 36 tooth gear, for contrast, was a solid with volume +22814.7.

Two things follow:

1. The results are compounds, not solids. A compound is a bag of pieces, which matches the
   "thin, disconnected blade-like remnants" described above.
2. The volumes are negative. The spike observed Shape.volume returning nil in process; the
   written BREPs give a computable but negative volume via volumeInertia. Both are symptoms of
   the same thing: the result is not a well-formed solid. The bounding boxes do match Route A's
   envelope closely, so the outer extent is right and the interior is not.

Why the robustness claim does not stand up

The claim is that circularPatternCut "survives the full crowding test" because the result stays
isValid with zero self-intersections, zero free edges and zero small edges up to 60 teeth.
Those metrics are real, and I reproduced them: graph-validate on the 36 tooth body reports
isValid: true, freeEdgeCount: 0, smallEdgeCount: 0, smallFaceCount: 0,
selfIntersecting: false.

But they are green on a compound with negative volume. By this spike's own account the cutter
"removes far less material than it should", so the booleans were never asked to resolve the
near-tangential solid-solid contact that #86 set out to stress. A cut that barely engages is a
cheap cut. Passing health checks on the output of a test that did not run is not evidence the
test would pass.

This is exactly the failure mode #86's acceptance criteria anticipated: "a cut that succeeds but
leaves slivers is a failure for our purposes." The criterion for Shape.analyze() should be read
as not met, rather than met.

What this spike did establish

• The blank construction is correct: a valid 4 face revolved frustum with correct volume, every
  time.
• Two real bugs in the cutter derivation were found, fixed and documented (the mirror-pairing
  sign error and the tip extension following the involute instead of projecting radially).
• The gap boundary formula was checked numerically against Spike 1's tooth flank at three radii
  and is correct to within a few tenths of a millimetre, which rules out the angular math.
• Route B is 3.8x to 6.2x slower than Route A even while removing too little material, so the
  true cost of a correct Route B is higher than these timings, not lower.

That is genuine progress and the defect was disclosed rather than routed around, which is the
right instinct. The 4 faces per tooth figure is correctly flagged above as untrustworthy.

Effect on the recommendation

The recommendation to build Spike 3 (#87) on Route A is right, and now better supported:
Route A is the only route that has produced a correct gear. But the reason should be recorded
accurately. It is not "Route B works and needs a cosmetic follow-up". It is:

• Route A: confirmed correct, fast, with a known and cheap heal step.
• Route B: unproven. Its cutter is wrong, and because of that its boolean-robustness result
  is not yet evidence of anything.

#86 should stay open, or a follow-up should be raised, with the specific unanswered question
restated: does circularPatternCut survive N near-tangential cuts when the cutter actually
engages the blank? The next debugging step suggested in the spike file header, coplanar axial
end caps between cutter and blank, remains the right place to start.

[gsdali]

Root cause: local, not upstream. OCCTSwift is behaving correctly.

I isolated this by building the blank, the cutter and each boolean step separately and measuring
each. Results at 36 teeth:

blank                    : type=shell   valid=true  vol=12096.04  faces=4
cutter                   : type=solid   valid=true  vol=206.96    faces=36
blank AND cutter         : type=compound            vol=87.51        <- 42.3% of the cutter overlaps
minDistance(blank,cutter): 0.0                                       <- they do touch
blank - cutter (1x)      : type=compound            vol=12003.16  faces=4
circularPattern(36)       : type=compound            vol=7450.60   faces=1296
blank - pattern (manual) : type=compound            vol=nil       faces=144
circularPatternCut(36)   : type=compound            vol=nil       faces=144

The blank is a shell, not a solid. That is the whole defect.

Shape.revolve(profile: wire, ...) revolves a wire, and revolving a curve sweeps a surface, so
it correctly returns a shell. This is standard BRepPrimAPI_MakeRevol behaviour, not a bug. The
spike then used that shell as the blank and subtracted solids from it. Boolean subtraction against
a shell trims surface patches instead of carving material out of a body, which is exactly why the
teeth came out as thin disconnected blades.

Every symptom follows from that one error:

• compound result instead of a solid
• Shape.volume nil in process, and negative when recomputed from the written BREP
• "removes far less material than it should"
• health metrics all green, because a trimmed shell really is a valid shell

The cutter itself was fine: a valid solid, correct volume, genuinely overlapping the blank by 42%
with a minimum distance of zero. The gap-boundary math the spike verified numerically was never
the problem.

The fix, verified

revolve(wire)            : type=shell   vol=12096.04  faces=4
Shape.face(from: wire)   : type=face    vol=0.00      faces=1
face.revolved(...)       : type=solid   vol=12096.04  faces=4     <- solid blank
SOLID blank - 36 cuts    : type=compound valid=true vol=6029.13 faces=1368

Revolving a face rather than a wire gives a solid, and with that blank circularPatternCut
returns a positive volume result: 6029.13 out of a 12096.04 blank, so roughly half the annular
material removed as tooth gaps, which is the right order for a gear.

What this means for #86

circularPatternCut was never at fault. It was fed a shell and did the correct thing with it.

The spike's question, does circularPatternCut survive N near-tangential cuts when the cutter
actually engages a solid blank, is still unanswered, but it is now cheap to answer: change
buildBlank to face-then-revolve and re-run the existing sweep. The 36 tooth case already
produces a plausible positive-volume result.

Also worth noting for whoever picks this up: Shape.revolve(profile:) returns a shell for both
Wire.polygon (2D) and Wire.polygon3D, so this is consistent behaviour and not a wire-type
quirk. I verified both.

[gsdali]

The one-line change lands, and #86's question is now answered: yes

buildBlank now faces the wire before revolving:

guard let face = Shape.face(from: wire) else { return nil }
return face.revolved(axisOrigin: .zero, axisDirection: SIMD3(0, 0, 1))

Committed as 1f96fbb on spike/86-bevel-route-b. Re-ran the full sweep:

teeth	patternCut ms	volume	faces	faces/tooth	valid	free edges	small	self-X
16	2426	1097.5	608	38.0	true	0	0	0
28	4727	3565.7	1064	38.0	true	0	0	0
36	5998	6029.1	1368	38.0	true	0	0	0
48	7930	10069.3	1440	30.0	true	0	0	0
60	9469	13547.9	1440	24.0	true	0	0	0

circularPatternCut survives up to 60 near-tangential cuts against a solid cone blank, with
positive volume and a clean analyze() at every count: zero free edges, zero small edges or
faces, zero self-intersections. That is the question this spike exists to answer, and unlike the
first run the operands are now what we intended, so the result means something.

The 36 tooth volume of 6029.13 matches the figure predicted in the root-cause comment above,
which is a useful cross-check that the diagnosis was right.

Two things this does not resolve

1. Face count saturates. Total faces plateau at exactly 1440 for both 48 and 60 teeth, so
faces-per-tooth falls 38, then 30, then 24. Something stops scaling. It is not yet clear whether
teeth are merging at high counts or the cutter stops fully resolving, and "valid with clean
analyze" would not necessarily catch either. Worth a look before anyone treats the 48 and 60 rows
as good gears.

2. The volumes are still not comparable with Route A's. This blank spans root radius to
addendum radius only, so it models the toothed rim, while Route A builds the whole gear body.
At 36 teeth the blank is 12096.04 and the result 6029.13, so roughly half the rim is removed as
gaps, which is sensible on its own terms. But Route A's 22814.7 is larger than Route B's entire
blank, so the two are measuring different objects. Route B is not yet a complete gear.

Effect on the Spike 3 recommendation

Unchanged: build #87 on Route A, which remains the only route that has produced a complete,
correct gear. But the reason is now narrower and more accurate than before.

• Route B's boolean robustness is established, not merely suspected. That is a genuine,
  reusable result.
• Route B remains incomplete as a gear (rim only), unexplained at high tooth counts, and roughly
  3x slower than Route A at 36 teeth (6.0s of pattern cutting against Route A's 1.9s total).

So the earlier framing that Route B was "unproven" is now too harsh on the boolean question and
still fair on the geometry question. The deciding factor Spike 1 nominated, whether Route B makes
a fitted involute curve practical, is still untested: at 38 faces per tooth this cutter is
carrying the same sampled-polyline flank as Route A.