Bevel gear placement: pitchbase / apex reference frames (replaces BOSL2 anchors)

[gsdali]

Part of #84. Blocks the docs page (#89).

Why this is needed

The epic explicitly declines to port BOSL2's attachment system (anchor / spin / orient /
reorient / named_anchor / attachable). It is thousands of lines of BOSL2 infrastructure
with no OCCT analogue.

But Examples 2 and 3 of the deliverable both depend on it. Example 2 meshes a gear pair
using anchor="apex", orient=FWD; Example 3 positions manually using pitch_radius() offsets
plus spin=180/t2. So we need the outputs of the anchor system without the machinery.

What to build

BOSL2 computes exactly three named anchors (gears.scad:2642-2646):

named_anchor("pitchbase", [0,0,pitchoff-ctr_thickness/2+backing/2]),
named_anchor("flattop",   [0,0,ctr_thickness/2+backing/2]),
named_anchor("apex",      [0,0,hyp_ang_to_opp(pitch_angle<90?ocone_rad:icone_rad,90-pitch_angle)
                              +pitchoff-ctr_thickness/2+backing/2])

Expose these as three reference Z heights on the returned gear: a small result struct
alongside the Shape, surfaced into the manifest metadata so render-preview and downstream
consumers can use them. Callers then position with ordinary translated and rotated.

Why the apex matters

For a bevel pair to mesh, the pitch cone apexes must coincide (gears.scad:2363). Anchoring
both gears at their apex and rotating one by the shaft angle is the whole trick. It is why
BOSL2's Example 2 is three lines. Getting this right is what makes a meshing pair demonstrable
rather than eyeballed.

Worth capturing as a helper: given two gears and a shaft angle, return the transform that
meshes them. That is the piece a downstream consumer actually wants, and the correct
replacement for anchor="apex".

Acceptance criteria

• pitchbase, flattop and apex heights computed and exposed per gear
• A meshing helper positions a pair at an arbitrary shaft angle with coincident apexes
• Verified at 90 degrees (Examples 1-3) and at least one non-right angle
• Apex coincidence verified numerically, not just visually. Assert the two computed apex
  points agree within tolerance
• Decision recorded as an OKF entry: explicit reference frames replace BOSL2 anchors

[gsdali]

Status: ready to pick up, with ground truth to check against

The body still applies as written; this is placement math, independent of the construction. Two things have changed since it was filed, and one useful invariant is worth recording before anyone starts.

Build on the current lineage

The construction is Route C, not Route A (see #84). The live file is spikes/87-spiral-route-c.swift, which carries Route C plus unequal mate_teeth (#110) plus the spiral, zerol and straight tooth forms (#87). Extend that lineage.

ctr_thickness and backing, which the anchor formulas above depend on, both exist there and are analytically verified.

Unequal mate_teeth now works, which this issue needs

Examples 2 and 3 use 16/28 and 14/28. #110 established that Route C holds at every pitch angle from 2 to 88 degrees, so the two members of a pair are now buildable. They are not symmetric: each gear has its own pitch angle, so each has its own apex height. That asymmetry is the whole point of this issue.

The invariant that makes apex coincidence checkable independently

Apex height above the pitch base is ocone_rad * cos(pitch_angle), which reduces to pr / tan(pitch_angle). At a 90 degree shaft angle that gives a clean identity:

gear	pr	pitch angle	apex height	mate pr
z=36, mate=36	36.0	45.00 deg	36.000	36.0
z=16, mate=28	16.0	29.74 deg	28.000	28.0
z=28, mate=16	28.0	60.26 deg	16.000	16.0
z=14, mate=28	14.0	26.57 deg	28.000	28.0
z=28, mate=14	28.0	63.43 deg	14.000	14.0

A gear's apex height equals its mate's pitch radius, exactly, in every case. That is why the apexes coincide when a pair is assembled: each gear's apex sits at the other's pitch radius along its own axis, and at 90 degrees those two points are the same point in space.

This matters for how the acceptance criterion is tested. "Assert the two computed apex points agree within tolerance" is weak if both come from the same code path, since a shared sign or factor error passes. Checking each apex height against pr(mate), a closed-form value derived independently, is the stronger test. Do both.

A caution carried from this epic

Several checks in these spikes have turned out to be trivially-passing: a handedness test that compared a vertex sitting exactly on the mirror plane (#87), a volume comparison that could not discriminate a lengthwise twist (#87), and three spikes that reported isValid while emitting solidCount = 0. When the criterion says "verified numerically, not just visually", the question to ask is what result would make the check fail. If nothing plausible would, the check is not doing work.

[gsdali]

Placement done: explicit pitchbase / flattop / apex + a meshing helper

Branch spike/88-placement, cut from #87's Route C lineage, extends
spikes/87-spiral-route-c.swift (through buildRouteC copied unchanged) with
spikes/88-placement.swift.

The three heights

GearReferenceFrames { pitchbase, flattop, apex }, plain Double heights along the gear's own
build axis, computed from the same meridian machinery (meridianRZ) already used and verified
in 87/109/110, not a ported anchor string. pitchbase == pitchoff exactly (asserted as a
regression check against the meridian point directly). flattop is the flat annulus at the
front (near-apex) cone edge, the same point buildFullBlank's innerRoot already computes.
apex = pitchbase + oconeRad * cos(pitchAngle).

One deliberate deviation from BOSL2's literal formula: BOSL2 folds ctr_thickness (a
vertex-array bookkeeping artifact, not an independently derivable quantity) and backing into
all three anchors, because it recenters the whole body around their combined midpoint before
exposing anchors. This file does not recenter, so backing does not shift these heights. The
deviation is invisible to the one quantity that actually gets checked below, apex height above
pitchbase, since those terms cancel identically in BOSL2's own formula too. Full writeup in the
OKF decision: okf/decisions/bevel-gear-explicit-reference-frames.md.

ScriptHarness.BodyDescriptor gained an optional referenceFrames: [String: Double]? field
(and ScriptContext.add(_:Shape...) a matching parameter), so these surface into
manifest.json for render-preview and other downstream consumers. Deliberately generic, not
gear-specific.

Ground truth table, checked against the literal numbers, not re-derived

z=36 mate=36: pitchAngle=45.0deg (expected 45.0) apexAboveBase=36.00000000000001 mate.pr=36.0 diff=7.1e-15 PASS
z=16 mate=28: pitchAngle=29.744881296942225deg (expected 29.74) apexAboveBase=28.000000000000004 mate.pr=28.0 diff=3.6e-15 PASS
z=28 mate=16: pitchAngle=60.25511870305777deg (expected 60.26) apexAboveBase=16.000000000000007 mate.pr=16.0 diff=7.1e-15 PASS
z=14 mate=28: pitchAngle=26.56505117707799deg (expected 26.57) apexAboveBase=28.0 mate.pr=28.0 diff=0.0 PASS
z=28 mate=14: pitchAngle=63.43494882292201deg (expected 63.43) apexAboveBase=14.000000000000004 mate.pr=14.0 diff=3.6e-15 PASS

All five rows match the table in the previous comment, to 1e-9. Since the comparison is against
literal numbers given there, not against anything this file re-derives, a shared sign or factor
error could not pass it by accident.

Non-right-angle case

No independently-sourced ground-truth number exists for a non-90 shaft angle, so this is a
lighter verification than the table above, recorded as a real limitation rather than dressed up
as equally strong. Checked structurally instead, at 65 degrees with 35t/15t: pitch angles sum to
the shaft angle exactly (46.796...deg + 18.204...deg = 65.0deg to 1e-9), the necessary condition
for two pitch cones to be tangent along a common line.

The meshing helper, and how apex coincidence was verified two ways

meshPair(reference:mate:shaftAngle:tiltAxis:matePhaseDeg:) returns a GearMeshStep per gear:
translate the apex to the world origin, optionally spin about the gear's own (still
axis-aligned) Z for tooth phase, then tilt by the shaft angle. Order matters and is enforced:
spin before tilt, matching BOSL2's own anchor -> spin -> orient sequence, since spinning after
the tilt would rotate about the wrong axis. Applied to Shapes via ordinary translated/
rotated, per the brief.

Verified two ways, as asked:

1. Against the pr(mate) closed form (the table above). This is the check that can actually
   fail on a wrong apex formula.
2. World-space agreement of the two positioned apex points, via TransformFactory3D (the
   same gp_Trsf-backed factory Shape.translated/.rotated themselves wrap), applied to each
   gear's own precomputed apex point. This one is called out explicitly in the code and in the
   OKF decision as trivially-passing by construction: meshPair translates each gear by the
   negative of its own computed apex height, so both positioned apexes land at the same point
   regardless of whether that height is correct. It exercises the transform composition
   (translate/phase/tilt order, correct rotation axes), which is real and worth having, but it
   is not evidence the geometry itself is right. Check 1 is that evidence.

Both real gear pairs were built (not just GearGeometry arithmetic) and positioned, with
subShapeCount(ofType: .solid) >= 1 asserted on every gear before use, no heal() anywhere,
and every fallible geometry call as guard/fatalError, no ??.

Rendered meshed pairs

16t (mate 28) + 28t (mate 16, right_handed, conical backing), 90 degree shaft angle:

35t (mate 15) + 15t (mate 35, right_handed), 65 degree shaft angle:

Both from occtkit render-preview --camera right, which happens to be the clearest angle for
this shape: the two gear bodies extend away from the shared apex along their own axes, so a
side-on view shows the join as a clean bend, 90 degrees for the first pair, opened out to 65 for
the second. Bounding boxes for the meshed pair confirm the same story numerically: the 16t body
spans Z in [-29.5, -17.9] (entirely below the origin, extending along -Z), the 28t body spans Y
in [9.3, 21.2] (entirely on the +Y side, extending sideways), neither reaching the shared apex
at the origin, exactly as expected for a pitch cone whose apex sits beyond the gear's own front
face.

Rotational phase for tooth interleaving

The helper handles the mechanics and ordering of phase (spin about the gear's own axis,
before the tilt, matching BOSL2's anchor -> spin -> orient), not the value. matePhaseDeg
is a caller-supplied parameter; the driver demonstrates it with BOSL2's own spin = 180/mate_teeth
idiom (6.43 degrees for the 28t mate, 12.0 degrees for the 15t mate) but this file does not
verify that the teeth actually interleave without collision, that would need flank-level
collision analysis, out of scope here and left as a caller/#89 concern if it turns out to matter
visually.

What remains for #89

Placement and meshing are done. What #89 (the docs-page deliverable) still needs on top of this:

• Cylindrical backing (cone_backing = false) for Example 3, per the epic's own remaining
  checklist item, not part of Bevel gear placement: pitchbase / apex reference frames (replaces BOSL2 anchors) #88.
• The docs page itself, reproducing BOSL2 Examples 1-3 side by side with OCCTSwift renders and
  the Swift source, per EPIC: Port BOSL2 bevel gears to OCCTSwift (spike → docs page) #84's deliverable.
• A decision on whether meshPair's default matePhaseDeg (currently 0, caller opts in) should
  become 180/mate_teeth by default to match BOSL2's own examples exactly, or stay explicit;
  this file demonstrates both forms exist but leaves the ergonomic call for Docs page: reproduce BOSL2 bevel_gear() Examples 1-3 side by side #89 since it depends
  on how many lines Docs page: reproduce BOSL2 bevel_gear() Examples 1-3 side by side #89 actually wants callers to write.

Both GearReferenceFrames/referenceFrames(_:) and GearMeshStep/meshPair/applyMeshStep
are free functions on GearGeometry, not yet promoted to any shared/library location; #89 will
need to decide where they live permanently if the docs page wants to import them rather than
copy them again.