Professional User Manual

Overview

`tq-threads` creates printable threads as direct watertight geometry. It is built from public standards and first-principles geometry, with explicit FDM fit controls rather than hidden slicer assumptions.

include <tq_threads.scad>;
$fn = 64;

tq_thread_preset("M8", 20);

difference() {
    cube([20,20,12], center=true);
    tq_threaded_hole(6, 1.0, 12);
}

Architecture

The public modules are wrappers around one core engine. Presets, bolts, nuts, tapped holes, augers, and cutters all converge on `tq_thread`, so fit, handedness, profile selection, taper, starts, and validation stay consistent.

How a call becomes mesh

1. A model calls a public module such as `tq_thread_preset("M8", 20)`.
2. The wrapper resolves nominal dimensions and forwards to `tq_thread`.
3. `tq_thread` validates inputs and computes radii, clearance, fit offset, lead, profile table, chamfers, taper, arc, and sampling density.
4. The engine samples `r(z, theta)` into side faces plus end caps.
5. OpenSCAD receives one closed polyhedron.

r(z, theta) = profile(frac((z - dir * (theta / 360) * lead) / pitch))

Installation

include <tq_threads.scad>;

git submodule add https://github.com/scottconverse/tq-threads libs/tq-threads

include <libs/tq-threads/tq_threads.scad>;

Use `include`, not `use`, when you need functions and constants such as `tq_preset`, `tq_in`, `TQ_PRESETS`, or `TQ_THREADS_VERSION`.

Thread Model

The default profile is the ISO/UN basic 60-degree V. For pitch `P`, the sharp triangle height is `H = sqrt(3)/2 * P`. The flat basic profile uses crest flat `P/8`, root flat `P/4`, and engaged radial depth `5H/8`.

Core API: `tq_thread`

`tq_thread` renders an external thread by default. Set `internal=true` to render an oversized cutter for a tapped hole or nut.

tq_thread(d, pitch, length,
          internal=false, starts=1, hand="right",
          clearance=0.4, fit=undef,
          profile="flat", angle=60,
          tooth_height=undef, minor_d=undef,
          crest_flat=undef, root_flat=undef, round=1,
          lead_in=true, lead_out=true, chamfer=undef,
          taper=0, arc=360, fn=undef,
          steps_per_pitch=16, center=false,
          thread_size=undef, side_angle=undef,
          rect_ratio=undef, groove=false,
          taper_rate=undef, lead_ends=undef);

tq_thread(8, 1.25, 20);

difference() {
    part();
    tq_thread(6, 1.0, 14, internal=true);
}

tq_thread(12, 2, 24, starts=3, hand="left");

Profile Control

The default `flat` profile is the standards-based ISO/UN basic form. The other profiles are printable controls for real-world design needs.

tq_thread(10, 4, 20, thread_size=1, side_angle=30, profile="sharp");
tq_thread(12, 3, 20, profile="square", thread_size=1.5);
tq_thread(12, 6, 20, profile="rectangle", thread_size=4, rect_ratio=1/3);
tq_thread(14, 4, 20, profile="square", groove=true, lead_ends="both");

Presets & Lookup Functions

tq_preset("M8");                  // [8, 1.25]
tq_thread_preset("M8", 20);
tq_thread_tpi(d=tq_in(1/4), tpi=20, length=tq_in(1/2));
tq_preset_count();               // 101
tq_presets_selfcheck();          // true

Threaded Primitives

difference() {
    bracket();
    tq_threaded_hole(6, 1.0, 12);
}

tq_nut(8, 1.25);
tq_standoff(5, 0.8, 14, od=9);

Fasteners

tq_bolt(8, 1.25, 20, head="socket", shank=4);
tq_countersunk_bolt(5, 0.8, 16, drive="phillips");
tq_wood_screw(5, 20, point="cone", shank=4);
tq_bottle_thread(28, 4, 10, starts=2);
tq_auger(18, 80, pitch=18, flight=5);

Holes, Washers, Couplers & Wrappers

Clearance, counterbore, and countersink helpers are negative cutters. Child-difference wrappers apply the cutter directly to `children()`.

tq_clearance_hole(5, 10, fit="medium");
tq_recessed_clearance_hole(5, 12);
tq_countersunk_clearance_hole(5, 8);
tq_washer(8);
tq_rod_coupler(8, 1.25, 18);

tq_tap(8, 1.25, 12)
    cube([24,24,12]);

Drives, Hex Helpers & Debug

Drive helpers are ordinary OpenSCAD solids intended for subtraction or visualization. The Phillips form is a printable approximation, not gauge-certified drive geometry.

difference() {
    cylinder(h=6, d=12);
    translate([0,0,-0.01]) tq_hex_drive(4, 3);
}

tq_phillips_tip(size=2);
tq_thread_debug(8, 1.25, 12);

FDM Fit & Print Tuning

• Print the thread axis vertical for clean flanks.
• Use lead chamfers for self-starting threads.
• Use `profile="rounded"` for stronger roots.
• Use heat-set inserts for small, high-cycle, or high-torque holes.

Integration Patterns

BOSL2 / NopSCADlib

Use other libraries for shapes and catalogs; use tq-threads for printable thread geometry.

include <BOSL2/std.scad>
include <tq_threads.scad>

difference() {
    cuboid([24,24,12], rounding=2);
    tq_threaded_hole(6, 1.0, 12);
}

TinkerQuarry code generation

Generated OpenSCAD should explicitly call `tq_thread*` APIs when a design requires real printed threads. Smooth bolt/nut blanks do not prove thread use.

Migration from Other OpenSCAD Thread Libraries

`tq-threads` is a clean-room implementation with its own API. The table below maps common legacy call shapes to the `tq_*` surface.

Testing & Release Proof

powershell -ExecutionPolicy Bypass -File scripts\render_proof.ps1
powershell -ExecutionPolicy Bypass -File scripts\render_proof.ps1 -Heavy

The proof captures stdout and stderr, renders split examples, requires negative tests to fail with real `assert` text, writes BOM-free generated SCAD, and checks every positive STL with the independent edge-pairing mesh checker.

Troubleshooting

Limits & Design Honesty