v0.6.0 profile controls and proof hardening

Author: scottconverse

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ on:
 
 jobs:
   render:
-    name: Render-proof (fast suite)
+    name: Render proof
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -20,32 +20,15 @@ jobs:
           sudo apt-get install -y openscad
           openscad --version
 
-      - name: Fast suite (preset assertions + smoke grid)
+      - name: Full render proof (split fast cells + examples + negative asserts + mesh checks)
+        shell: pwsh
         run: |
-          set -e
-          openscad -o fast.stl tq_threads_fast_tests.scad 2> fast.log || (cat fast.log; exit 1)
-          echo "--- OpenSCAD output ---"; cat fast.log
-          # fail on any manifold warning or error
-          if grep -Ei "WARNING|ERROR|not a valid 2-manifold" fast.log; then
-            echo "::error::OpenSCAD reported a warning/error"; exit 1
-          fi
-          test -s fast.stl
-          echo "Fast suite passed."
+          & ./scripts/render_proof.ps1 -OpenSCAD openscad -OutDir proof/ci
 
-      - name: Smoke-render a few examples
-        run: |
-          set -e
-          for id in bolt nut washer csk_bolt coupler; do
-            openscad -o "ex_$id.stl" -D "SHOW=\"$id\"" tq_threads_examples.scad 2> "ex_$id.log"
-            grep -Ei "WARNING|ERROR|not a valid 2-manifold" "ex_$id.log" && exit 1 || true
-            test -s "ex_$id.stl"
-          done
-          echo "Example smoke renders passed."
-
-      - name: Upload STL artifacts
+      - name: Upload proof artifacts
         if: always()
         uses: actions/upload-artifact@v4
         with:
-          name: render-output
-          path: "*.stl"
+          name: render-proof-output
+          path: proof/ci
           if-no-files-found: ignore

CHANGELOG.md

@@ -4,6 +4,44 @@
 All notable changes to tq-threads. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com); versions are git tags.
 
+## [0.6.0] - 2026-06-23
+
+Flexible non-60-degree profile-control release.
+
+### Added
+- `profile="square"` and `profile="rectangle"` thread forms.
+- `thread_size=` to decouple one tooth's axial width from pitch, enabling
+  wide-pitch/narrow-tooth threads and grooves.
+- `rect_ratio=` for rectangular threads; `1` is square, `1/3` is shallow.
+- `groove=true` to make a helical channel cut into the cylinder surface as a
+  direct manifold height-field solid.
+- `side_angle=` for the half-angle measured from the plane perpendicular to the
+  axis. `side_angle=30` is the conventional 60-degree included V. Existing
+  `angle=60` remains the backward-compatible included-angle parameter.
+- `lead_ends="none"|"start"|"end"|"both"` as a clearer lead chamfer selector,
+  while retaining `lead_in` / `lead_out`.
+- `taper_rate=` plus `tq_npt_taper_rate()` (`1/16` diameter change per length)
+  for rate-based taper input.
+
+### Changed
+- The render proof now covers the new square, rectangular, groove, narrow-tooth,
+  six-start, lead-end, taper-rate, preset-wrapper, and TPI-wrapper cases.
+- `profile="sharp"` is now the documented full-height pointed V form. The
+  default flat ISO/UN profile remains unchanged for existing calls.
+- `tq_thread_preset()` and `tq_thread_tpi()` now forward the full v0.6 profile
+  controls (`thread_size`, `side_angle`, `rect_ratio`, `groove`, `taper_rate`,
+  `lead_ends`, and related overrides).
+- The official render proof now captures combined stdout/stderr from OpenSCAD,
+  enforces strict explicit `-OpenSCAD` paths, runs independent STL mesh checks
+  for every positive render, and is the CI proof used on push.
+
+### Fixed
+- `thread_size > pitch` is rejected consistently for square and rectangular
+  profiles before internal-thread relief or clamping is applied.
+- `tq_wood_screw()` now supplies an explicit printable tooth depth for its
+  coarse sharp-profile default, so the stricter full-sharp-V semantics do not
+  make the default/example non-renderable.
+
 ## [0.5.0] - 2026-06-23
 
 Printability proof release for TinkerQuarry, plus two targeted geometry fixes.

MANUAL.md

@@ -77,16 +77,22 @@ default (or an oversize internal **cutter** with `internal=true`).
 | `hand` | `"right"` | `"right"` or `"left"`. |
 | `clearance` | `0.4` | **Total diametral** FDM fit gap (mm); external shrinks `clearance/2`, internal grows `clearance/2`. |
 | `fit` | `undef` | Optional **ISO 965** tolerance *position* (allowance): external `"e"/"f"/"g"/"h"` or internal `"G"/"H"` (also accepts `"6g"`,`"6H"`,…; the grade digit is ignored — band width is not modelled). Applied on top of `clearance`. Case must match `internal`. This is nominal intent; M8 `6g` is only about 0.029 mm diametral shift, so tune `clearance` for real FDM fit. |
-| `profile` | `"flat"` | `"flat"` (ISO/UN basic), `"sharp"` (full V), `"rounded"` (filleted root/crest). |
-| `angle` | `60` | Included flank angle (degrees). 60 = ISO/UN; e.g. 55 ≈ Whitworth. Thread height derives from it. |
+| `profile` | `"flat"` | `"flat"` (ISO/UN basic), `"sharp"` (full V), `"rounded"` (filleted root/crest), `"square"`, `"rectangle"`/`"rect"`. |
+| `angle` | `60` | Included flank angle (degrees). 60 = ISO/UN; e.g. 55 ≈ Whitworth. Kept for backward compatibility. |
+| `side_angle` | `undef` | Half-angle measured from the plane perpendicular to the axis; `30` gives a 60-degree included V. Overrides `angle` for V-height derivation. |
+| `thread_size` | `pitch` | Axial width of one tooth/profile, independent of pitch. Must be `<= pitch`. |
+| `rect_ratio` | `1` square, `1/3` rectangle | Rectangular radial depth as a fraction of `thread_size`. |
+| `groove` | `false` | Invert the profile into a helical channel cut into the cylinder surface. |
 | `tooth_height` | `undef` | Explicit radial flight depth (mm). Overrides the angle-derived height. |
 | `minor_d` | `undef` | Set the core/minor diameter directly (mm, in `(0,d)`); thread depth becomes `(d − minor_d)/2`. |
 | `taper` | `0` | Total **diameter** reduction over the length (mm), applied linearly (base full, top reduced) — NPT-ish tapers / auger tips. |
+| `taper_rate` | `undef` | Diameter reduction per axial mm. `tq_npt_taper_rate()` returns `1/16`. Added to `taper`. |
 | `crest_flat` | `pitch/8` | Axial crest-flat width (mm) for `flat`. |
 | `root_flat` | `pitch/4` | Axial root-flat width (mm) for `flat`. |
 | `round` | `1` | Fillet scale for `profile="rounded"` (1 = standard ISO radii). |
 | `lead_in` | `true` | Taper the **start** (Z=0) end so the thread begins cleanly. |
 | `lead_out` | `true` | Taper the **far** (Z=length) end. |
+| `lead_ends` | `undef` | Optional selector `"none"`, `"start"`, `"end"`, or `"both"`; overrides `lead_in`/`lead_out` when set. |
 | `chamfer` | `=thread height` | Axial length of the lead taper(s). |
 | `arc` | `360` | Angular sweep in degrees; `<360` makes a partial arc. |
 | `fn` | `undef` | Per-call angular segment override (else `$fn`/`$fa`/`$fs`). |
@@ -96,8 +102,10 @@ default (or an oversize internal **cutter** with `internal=true`).
 **Validation.** Bad inputs `assert` with a clear message instead of rendering
 malformed geometry: non-positive `d`/`pitch`/`length`/`steps_per_pitch`, `arc`
 outside `(0,360]`, `hand` not in `{right,left}`, `profile` not in
-`{flat,sharp,rounded}`, non-integer/`<1` `starts`, negative `clearance`/`chamfer`,
-flats exceeding the pitch, or a thread so deep the minor radius ≤ 0.
+`{flat,sharp,rounded,square,rect,rectangle}`, non-integer/`<1` `starts`,
+negative `clearance`/`chamfer`, invalid `side_angle`, `thread_size > pitch`,
+non-positive `rect_ratio`, flats exceeding the thread size, or a thread so deep
+the minor radius ≤ 0.
 
 **Geometry produced (flat profile).** Crest at `d/2`, engaged height
 `0.5413·P`, minor diameter `d − 1.0825·P` (ISO/UN basic). With `clearance`, the
@@ -240,11 +248,20 @@ tq_washer(8);                                                  // ISO 7089 M8
 tq_thread(12, 2, 14, angle=55);            // 55° flank (Whitworth-ish)
 tq_thread(10, 2, 14, tooth_height=1.2);    // set the radial flight depth directly
 tq_thread(12, 1.75, 16, taper=3);          // cone: 3 mm dia reduction over the length
+tq_thread(10, 4, 14, thread_size=1, side_angle=30, profile="sharp"); // narrow 60-degree V
+tq_thread(12, 3, 14, profile="square", thread_size=1.5);
+tq_thread(12, 6, 14, profile="rectangle", thread_size=4, rect_ratio=1/3);
+tq_thread(14, 4, 14, profile="square", groove=true, lead_ends="both");
+tq_thread(12, 2, 14, taper_rate=tq_npt_taper_rate());
 ```
 `angle` (default 60) sets the included flank angle; the thread height derives
-from it. `tooth_height` overrides that height explicitly. `taper` shifts the
-whole profile inward linearly along Z (NPT-ish tapers, auger tips). The
-minor-radius safety assert accounts for both rounded roots and `taper`.
+from it. `side_angle` uses the alternate convention from the plane perpendicular
+to the axis, so `side_angle=30` maps to a 60-degree included V. `thread_size`
+decouples tooth width from pitch. `tooth_height` overrides radial height
+explicitly. `taper` and `taper_rate` shift the whole profile inward linearly
+along Z; `tq_npt_taper_rate()` is the 1:16 diameter-change reference rate only,
+not a full NPT profile. The minor-radius safety assert accounts for rounded
+roots and taper.
 
 ### Auger / deep coarse flight
 ```openscad
@@ -439,6 +456,9 @@ Notes:
   rather than per-side tolerances.
 - Default profile is the ISO/UN **basic** (flat) form; use `profile="rounded"`
   for a deeper rounded root.
+- v0.6 generic profile forms map as follows: `profile="sharp"` is a full-height
+  pointed V, `profile="square"` uses radial depth equal to `thread_size`, and
+  `profile="rectangle"` uses radial depth `thread_size * rect_ratio`.
 
 ---
 
@@ -449,12 +469,13 @@ openscad -o out.stl tq_threads_fast_tests.scad      # fast: asserts + small grid
 openscad -o demo.stl tq_threads_heavy_tests.scad    # heavy: full visual grid
 ```
 ```powershell
-pwsh scripts/render-tests.ps1            # fast suite, with manifold-warning check
-pwsh scripts/render-tests.ps1 -Heavy     # add the heavy grid
+powershell -ExecutionPolicy Bypass -File scripts\render_proof.ps1          # full proof
+powershell -ExecutionPolicy Bypass -File scripts\render_proof.ps1 -Heavy   # add heavy grid
 ```
-The fast suite also runs **compile-time assertions** that every required preset
-(M2…M64) resolves to the correct pitch. CI (`.github/workflows/ci.yml`) runs the
-fast suite on every push.
+The proof captures both stdout and stderr from OpenSCAD, runs negative/assert
+tests, and checks every positive STL with the independent mesh edge-pairing
+checker. `scripts/render-tests.ps1` remains only as a deprecated compatibility
+alias. CI (`.github/workflows/ci.yml`) runs the same proof on every push.
 
 ---
 
@@ -463,6 +484,10 @@ fast suite on every push.
 | Symptom | Cause / fix |
 |---|---|
 | `assert` failure on render | Read the message — it names the bad parameter. |
+| `thread_size must be <= pitch` | Narrow-tooth profiles can be smaller than pitch, but a single tooth cannot exceed one pitch. |
+| `side_angle must be > 0 and < 90` | `side_angle` is the half-angle from the plane perpendicular to the thread axis; use `30` for a conventional 60-degree V. |
+| `rect_ratio must be > 0` | Rectangular depth is `thread_size * rect_ratio`; use `1` for square or about `1/3` for shallow rectangular threads. |
+| `lead_ends must be none/start/end/both` | Use `lead_ends` for the common cases, or the older `lead_in` / `lead_out` booleans for compatibility. |
 | Thread too tight / loose when printed | Adjust `clearance` (see [FDM](#fdm-deep-dive)); recalibrate. |
 | Faceted / coarse flanks | Raise `$fn` or lower `$fs`; raise `steps_per_pitch`. |
 | Huge mesh / slow render | Lower `$fn`/`steps_per_pitch`; it's a height-field. |
@@ -477,8 +502,12 @@ fast suite on every push.
 **Current limitations** (see also [README](README.md#limitations)):
 - Internal threads via external-form cutter (pragmatic for FDM, not metrology-grade).
 - Countersunk head diameters are nominal ISO 10642 values (overridable).
-- No tapered pipe (NPT), ACME/trapezoidal, or buttress forms (60°-V only).
-
-**Possible future work:** ACME/trapezoidal profile, true ISO internal profile
-option, more named hardware presets, and a parametric thread-relief groove. PRs
-and ideas welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+- Square, rectangular, narrow-tooth, and groove profiles are generic printable
+  forms, not standards-accurate ACME/trapezoidal/buttress fit-class profiles.
+- `taper_rate` can express a 1:16 NPT-style diameter taper reference, but the
+  NPT truncated thread profile and sealing rules are not implemented.
+
+**Possible future work:** standards-accurate ACME/trapezoidal/buttress profiles,
+true ISO internal profile option, more named hardware presets, and more
+manufacturing-oriented relief presets. PRs and ideas welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md).

PROVENANCE.md

@@ -18,6 +18,7 @@ Fidelity classes: **EXACT** (nominal standard value used verbatim) ·
 | Source / spec | Used for | Class | Faithfulness & notes |
 |---|---|---|---|
 | **ISO 68-1** (metric basic profile) | 60° form, `H=(√3/2)P`, crest `P/8`, root `P/4`, engaged `0.5413P` | EXACT/DERIVED | Geometry transcribed/derived from the basic-profile definition. |
+| **First-principles thread geometry** | `side_angle`, `thread_size`, square/rectangular profiles, groove inversion | DERIVED/APPROX | Generic printable forms implemented from the behavioral spec and trig; no standards fit class claimed. |
 | **ISO 261** (general plan) | metric coarse + fine major Ø & pitch (presets) | EXACT | Nominal diameter/pitch series. Verified by `tq_presets_selfcheck()` + cross-checked online. |
 | **ISO 262** (selected sizes) | preferred metric subset | EXACT | Informs which presets are "common". |
 | **ISO 965-1 §13.1** (tolerances) | `fit=` fundamental deviation (allowance) | DERIVED (exact formula) | external e/f/g/h, internal G/H. **Position only**, not the grade/band. Formula value (unrounded); ISO tables round to whole µm. NOT metrology-grade. |
@@ -28,10 +29,31 @@ Fidelity classes: **EXACT** (nominal standard value used verbatim) ·
 | **ISO 4762** (socket head cap screws) | `tq_shcs_head` (dk,k), `tq_hex_key_af` | EXACT (listed) / APPROX (fallback) | |
 | **ISO 10642** (csk socket head) | `tq_csk_head_dia` (90°) | EXACT (listed) / APPROX (fallback) | |
 | **ISO 4757** (cross recesses) | Phillips recess *concept* | APPROX | Printable cruciform approximation; NOT gauge-accurate. |
-| **ASME B1.20.1** (NPT) | taper *context* only | — | Linear `taper` is generic; NPT's truncated profile is NOT implemented. |
+| **ASME B1.20.1** (NPT) | taper-rate context only | DERIVED | `tq_npt_taper_rate()` returns the published 1:16 diameter taper reference. NPT's truncated profile is NOT implemented. |
 | *(none — generic)* | `tq_auger`, `tq_bottle_thread`, `tq_wood_screw` | APPROX/GENERIC | Printable generic forms; **no** standard claimed (explicitly documented). |
 | *(this library)* | `clearance` default 0.4 mm (½/½ split), `TQ_MIN_SEG`, lead-in chamfers, rounded fillets `H/6`,`H/12` | FDM/DERIVED | Printability choices / derived geometry, not standards. |
 
+## v0.6 profile-control provenance
+
+The v0.6 profile controls came from the local capability specification dated
+2026-06-23 and first-principles geometry, not from any third-party OpenSCAD
+library.
+
+- `side_angle` uses the right-triangle relation `h = S/(2*tan(beta))`, where
+  `S` is the axial tooth width and `beta` is the flank angle from the plane
+  perpendicular to the axis. `beta=30` gives the familiar 60-degree included V.
+- `thread_size` is a caller-selected axial tooth width and is validated before
+  internal-thread relief or square/rectangular clamping. Values greater than
+  pitch are rejected.
+- `profile="sharp"` is a full-height V. The compatibility default remains the
+  flat ISO/UN basic form with crest/root truncation.
+- Square, rectangular, and groove profiles are generic printable height-field
+  shapes. They do not claim ACME, trapezoidal, buttress, or pipe-thread gauge
+  compatibility.
+- `taper_rate` is just diameter change per unit length. The NPT helper returns
+  the public 1:16 taper-rate reference only; it does not implement the NPT
+  truncated profile or sealing/gauge requirements.
+
 ## What could only be validated with physical prints + calipers
 - Real-world **fit** of a printed bolt/nut pair at a given `clearance`/`fit`.
 - Whether a printed thread meets an actual **ISO/ASME tolerance class** (tq-threads