SG-LibSolid Geometry Library Toolbox
SG-Lib

Milestone 2026-07-11 — Path 2: lateral clearance insertion (LEARNING case)

Rendered views

Learning case — no printable STL for this milestone.

Type: learning/teaching case (NOT an autonomous error-free design, but Tim closely teaching “Path 2”). Deliberately kept as a milestone to document this kind of case too.

Task

Insert a cuboid (first 6x6x6, then 3x4x5) laterally, in -x direction, with a clearance fit into a cylinder (dia 10, height 40). The subtraction body (blind pocket) is pulled in via a surface frame; insertion depth 4 mm, with clearance in the depth as well.

The binding procedure (Path 2) that was learned

  1. No absolute coordinates. Get target info by geometric query from the body: face+frame via TofSGFSselect (access path = frame z). Read the frame via SGTget.
  2. Measure body dimensions; never reuse the build number. Extent along the axis by ray-cast crosspointVLFL (aC=max(dd)-min(dd)), not aC=6. Only specs (insertion depth d) are literal numbers.
  3. Contour by projection - a DIRECTION, not a frame - CPLofSGprojection(SG, ez); and evaluate the returned frame T (the contour is in T’s orientation!): V=VLtransT(CVL,inv(TZ)); CPL=V(:,1:2).
  4. Real fit: slc=slfit('c'); grow the contour with CPLbuffer(...,'miter') (sharp corners, no FDM welding); SGwarnfittinguse at the top.
  5. Arrange ONLY via frame relations (alignT/matchT); the relative offset goes INSIDE the braces ({FA,FB,TofP([0 0 v])}), never as a trailing ,'transz',v (that is absolute).
  6. Primitives without default frames (SGbox(...,'noframe')); carry frames across booleans with SGTcopy.
  7. Check the result visually (not just nm=0): seating, size, orientation, clearance.

By-product (SG-Lib improvement)

CPLofSGprojection now projects headless & exactly via Manifold (project() through CLAUDE_sg_manifold.project_vlfl) instead of the graphics board (CPLofgcaprojection/getframe), with graphics fallback. See ..._projection_manifold_vs_graphics.png (exact 4-point square vs 9 pixel-traced). Apache-2.0 notice for Manifold added (LICENSE_thirdparty_Manifold_Apache2.txt, SG-Lib_LICENSE.txt clause 9); SGmanifoldSetup now also verifies project_vlfl.

Honest meta-lesson (the real reason for this milestone)

The design took 2-3 hours - far too long. Not for lack of knowledge (the rules were already in the md files), but because I did not apply them consistently: each rule violation (magic number, absolute transz, frame instead of direction, T not evaluated) cost one iteration. Consequence: a pre-flight checklist (in CLAUDE_SGLIB_PATH2.md) to tick off before every run - apply the rules rather than rediscover them after the error. That is the lesson this case records.

Files

  • ..._build_sgtestclaude.m - final, rule-conforming build (3x4x5, measured, no magic numbers).
  • ..._views.png - result (cuboid inserted laterally with clearance, correctly oriented).
  • ..._projection_manifold_vs_graphics.png - projection comparison Manifold vs graphics.
  • Conversation: ..._conversation_de.md / ..._conversation_en.md.

References (rules stored durably)

CLAUDE_SGLIB_PATH2.md (checklist + rules R1/R2), CLAUDE_SGLIB_LEARN.md (naming/frame/measure rules), CLAUDE_SGLIB_PARAMS.md (CPLofSGprojection, crosspointVLFL, slfit, inconsistencies).

Design conversation (English)

Conversation (excerpt/essence) — Path 2, lateral insertion, 2026-07-11

Condensed record of the teaching conversation (Tim <-> Claude). Order = the learning path.

  • Tim: second learning path “Path 2” (boolean-compositional), precondition: booleans now error-free (Manifold2). Later clarified: Paths 1 and 2 have the same rules, only a different order.
  • Tim: “Show me your cylinder construction.” -> Claude shows the old cylinder stack.
  • Tim (rule): No absolute coordinates. Get target info by geometric query - face + frame (TofSGFSselect); the frame defines the access path.
  • Tim (rule): compute the through/exit point, never store it as a constant - crosspointVLFL from the surface point backwards. “Never rely on knowing the geometry.”
  • Exercise: cylinder dia10x40, frames TO/TU by query, glued with SGTset. OK
  • Tim (rules): contour relative to the frame; blind-hole length = depth + overhang; subtraction body never in absolute coordinates, always relative to the surface frame. SGTget instead of the self-computed variable.
  • Exercise: square blind hole at TO. OK (frames survive SGsubtract - proven; visible only with SGTplotalpha, not SGplotalpha/montage. Ground rule: show frames when frames are the topic.)
  • Tim (rules): arrange only via frame relation (alignT), the subtraction body gets its own frame 'C'. Naming: solids/contours with datatype prefix in uppercase (SGB, SGHsub, CPLA), kit suffix lowercase (sub/add/supp). SGbox(...,'noframe') when setting own frames. SGTcopy for frames.
  • Tim (rule): fixed fits: slc=slfit('c'), slt=slfit('t'), sli=slfit('i'); every function using fits calls SGwarnfittinguse. CPLbuffer(...,'miter') (sharp corners, no welding) - 'round' is unsuitable.
  • Problem: CPLofSGprojection returns a wrong contour in the headless batch (graphics board/getframe). -> Manifold has Project() (silhouette on X-Y) and Slice(height). Wired in as a headless-exact replacement (project_vlfl), signature unchanged, graphics fallback, no per-call try/catch (Tim: try/catch is slow), Apache-2.0 license added.
  • Mistake 1 (Claude): magic number aC=6. Tim: “Next time 3x4x5 - the 6 is wrong. Measure the extent from the frame via crosspointVLFL. If this doesn’t work I must stop the teaching.”
  • Mistake 2 (Claude): relative offset as trailing ,'transz',v -> absolute world CS -> cube moved up instead of radially. Tim: the offset belongs inside the braces ({FA,FB,TofP([0 0 v])}) = relative.
  • Mistake 3 (Claude): did not evaluate the frame T returned by CPLofSGprojection -> contour rotated 90 deg. Tim: “CPL is in T’s orientation, not yours.” -> V=VLtransT(CVL,inv(TU)).
  • Result: 3x4x5 cuboid inserted laterally with clearance, extent measured, no magic numbers, correct orientation, clearance respected. nm=0.
  • Tim (meta): “Now it’s correct - but it took 2-3 hours. Please fix the rules and really adhere to them.” -> pre-flight checklist in CLAUDE_SGLIB_PATH2.md.

Core lesson: the knowledge was there; the time loss came from not applying it. Tick off the rules before every run, don’t rediscover them after the error.