CTS EdgeCraft Pro 1.1.1 - Research and implementation decisions
Date: 2026-10-05

The user requested a core change for mixed rectangles, circles, polygons,
irregular boundaries, concavity/convexity and multiple holes. The working
1.0.2 pocket solver has been retained for genuinely orthogonal shells.

Findings in the prior implementation
- The complete-network path assumed three edges per vertex and right-angle
  face/edge relationships. It could not classify general polygonal junctions.
- Preview, Apply and fit probes did not consistently choose the same solver.
- Several retained-face paths relied on native display tessellation. Its seam
  decomposition could differ from the adjacent reconstructed fillet surface.
- Two-face edge counts alone do not detect a closed self-intersecting mesh.
- Sequential edge edits can invalidate faces needed by subsequent edges.

Primary references reviewed
1. SketchUp: Generating Geometry
   https://ruby.sketchup.com/file.generating_geometry.html
   Bulk mesh insertion deduplicates vertices and edges but leaves well-formed
   geometry to the caller. Therefore a complete indexed mesh is prepared and
   checked before insertion, then its native topology is checked again.
2. SketchUp: Entities / fill_from_mesh
   https://ruby.sketchup.com/Sketchup/Entities.html#fill_from_mesh-instance_method
   The temporary group provides an empty insertion context. Source replacement
   follows successful insertion and native face/edge validation.
3. SketchUp: EntitiesBuilder
   https://ruby.sketchup.com/Sketchup/EntitiesBuilder.html
   Bulk APIs avoid the incremental splitting/merging behavior of add_face.
   This supports solving one connected replacement before touching its source.
4. Blender: Bevel and overlap handling
   https://docs.blender.org/manual/en/2.91/modeling/meshes/editing/edge/bevel.html
   https://docs.blender.org/manual/en/2.81/modeling/meshes/editing/subdividing/bevel.html
   Manifold adjacency, corner treatments and feature overlap are distinct
   issues. A connected surface alone does not establish a usable fillet radius.
5. Open CASCADE: BRepFilletAPI_MakeFillet
   https://occt3d.com/dev/doc/refman/html/class_b_rep_fillet_a_p_i___make_fillet.html
   An analytic CAD fillet builder also documents contour/radius compatibility
   and junction limitations. A finite mesh solver must state its own limits
   rather than promise every connected model and every radius will succeed.
6. Mapbox Earcut: polygon triangulation, holes and robustness
   https://github.com/mapbox/earcut
   Its documented concerns include degeneracy and nonconforming triangulation.
   The extension uses its own visibility-bridge/ear-clipping implementation;
   no Mapbox code or runtime dependency is bundled. Exact boundary conformity
   and independent area/coverage checks are applied to the resulting faces.

Changes applied
- MeshFilletKernel dispatches complete-shell preview, Apply and radius probes.
  Orthogonal shells retain the established solver; general shells use the new
  GeneralNetworkBevel. Orthogonal recognition now has a strict angle tolerance
  so slightly skewed geometry uses its actual support angles.
- The general snapshot orients the shell, merges compatible coplanar regions,
  preserves differing material/tag boundaries and removes collinear splits.
  Selected split chains remain selected after endpoint normalization.
- For edge-support inward directions u and v, alpha = acos(dot(u,v)). The
  circular tangent offset is r / tan(alpha/2); the center lies along the angle
  bisector at r / sin(alpha/2). Face corners solve their two offset constraints
  together. Concavity determines the outward strip-normal orientation.
- Compatible smooth wall joints use a shared sampled intersection curve.
  Its projection onto each adjoining cylinder is checked against radius r.
  This replaces axial interpolation that could make adjoining strips cross.
- Edge-strip samples are reused at vertex-patch boundaries. Trihedral patches
  use the established spherical/transfinite construction; higher valence uses
  ordered shared boundary curves and sampled concentric patches.
- The retained-face triangulator chooses a bridge occurrence in the correct
  local sector at duplicated endpoints. It projects relative to a local origin
  for numerical stability, checks area and conforms triangles to loop vertices.
  The same path is used for network, prism, planar-rim and parallel-edge caps.
- A bounding-volume hierarchy checks triangle self-intersections. Closure,
  directed edge pairing and actual native mesh insertion are also checked.
  A failed fit or insertion preserves the source and removes the temporary mesh.
- Numerical radius fitting handles the new collision messages consistently.
  Unsupported topology is not disguised as a radius limit.

Engineering scope
This is a coordinated polygonal mesh fillet solver, not an imported B-rep CAD
kernel. Spherical or exact cylindrical portions can coexist with interpolated
junction patches. A closed manifold shell, compatible corner configuration,
adequate native feature size and a radius that avoids collisions are necessary.
Partial arbitrary networks and nonuniformly scaled group contexts retain the
existing restrictions. The tests document useful coverage, not a proof of
universal correctness. See CORE_VALIDATION.txt for actual executed checks.

Component_5 comparison: corner and speed correction (1.1.1)
- The saved EdgeCraft result has 8 circular segments and radius 2.3498206787
  inches. Its 3,492 vertices were reproduced from the embedded original shell.
- The reference cross-section samples match 4 quadratic-profile segments
  and a 3-inch offset (inferred from the saved vertices). Its topology and profile are not equivalent to the 8-segment
  circular result, so their raw entity counts and total times are not a
  controlled comparison.
- A local mixed corner used the triangular fallback whenever any other part
  of the model prevented the orthogonal whole-shell route. Local support
  geometry now selects the rolling corner independently of that route.
- Both one-concave/two-convex and two-concave/one-convex perpendicular rim joins
  use the torus construction. The walls can meet at a general usable angle.
  Their exact signed normals and bisector determine its section centre and
  sweep. The front boundary is a radius-2r arc; the cross-section at angle phi
  has radius r*(2-sin(phi)) and axial shift r*(1-cos(phi)). This is tangent to
  the cap at phi=0 and the wall cylinder at phi=pi/2. All three incident strips
  share the same sampled boundaries.
- Exactly planar strip/torus panels remain quads. Warped panels remain two
  triangles. The user-selected segment count is preserved.
- SketchUp 2022+ uses EntitiesBuilder and its holes: inner_loops argument to
  create retained faces directly with all holes. The earlier PolygonMesh path
  remains available for older versions. Input boundary matching, native closed
  seams and source-preserving failure checks apply to both.
- Collision validation welds point IDs once, uses scalar box/plane tests and
  rejects ordinary touching neighbours early. Proven retained triangulations
  are not tested against themselves. Independent checks between distinct
  surfaces remain enabled. A 3,000-pair differential test matches the old
  collision predicate, including coplanar and translated shared boundaries.
- Closure and directed winding share one indexed topology check. Retained-face
  seam conformity reuses edge splits and filters candidates by their boxes.
- Validated results are reused between preview, radius probes and Apply. The
  bounded cache includes model identity, source coordinates, loops, active
  edges, materials/tags, finish flags, radius and segments. Equivalent source
  copies can reuse geometry; changed input and failed builds cannot. Returned
  geometry is copied so callers cannot modify a cached result.
- Redundant whole-network default smoothing was removed from LiteObjectJob.
  The final user-selected smooth/border settings still run as before.
- See CORNER_SPEED_VALIDATION.txt for reproducible numerical timings and
  CORE_VALIDATION.txt for executed checks. Native SketchUp timing and
  interactive appearance are not measured by this environment.

Radius-search bottleneck
- Re-running the prior search from 3 inches reproduces the saved radius exactly.
  It made 15 build requests and 8 complete collision checks per segment case.
- Boundary-first probing checks the same current offset loops and edge room
  without triangulating/validating every tentative full mesh. The final
  candidate always receives full validation. A hidden collision triggers the
  established full-search fallback; unsupported errors are propagated.
- Whole-object job and complete-edge probes use this path. Existing specialized
  partial paths keep their full probes. User-selected final segments are kept.
- See CORNER_SPEED_VALIDATION.txt for observed times and new fitted radii.
