DOCSEARCHbyAlgolia
Submit Docs

threadlib OpenSCAD Library

repository·develop·Indexed 19 days ago

https://github.com/adrianschlatter/threadlib

An OpenSCAD library for generating production-ready thread profiles, including Metric (M0.25 to M600), Unified (UNC, UNF, UNEF, etc.), BSP parallel (G1/16 to G6), Bottle (PCO-1881, PCO-1810), and RMS threads. It provides modules for creating threads, bolts, nuts, and tapped holes with built-in clearances and tapers. The library includes a THREAD_TABLE for technical specifications and supports the addition of custom thread definitions via CSV and AWK translation scripts.

Tokens
3.2K
Snippets
9
Records
17
Agent score
61%

What's inside threadlib

  1. Derive threadlib specs from industrial norms

    develop

    To create a new thread specification for threadlib, you must translate values from an industrial standard (e.g., BS EN ISO 228-1) into the piecewise linear profile used by the library.

    Derivation Logic

    1. Pitch (P): Must match the pitch defined in the norm exactly (e.g., 0.907 mm for G1/16).
    2. Pitch Diameter: Choose a value in the center of the tolerance range provided by the norm.
    3. Radii (r_crest and r_valley):
      • r_crest: This is the major/minor radius (external/internal). It must account for both the allowed deviations in the norm and the rounding radius. To ensure the piecewise linear profile stays on the correct side of the true profile, the crest radius should equal the radius where the straight rising edge of the profile touches the rounding circle.
      • r_valley: This is the minor/major radius (external/internal). Since norms often do not specify limits for the valley, choose a small, finite width for the "valley floor" that ensures ample clearance to the parting line and ensures the thread profile covers less than one pitch.

  2. Understand the BSP-Parallel Thread calculation logic

    develop

    The BSP-Parallel thread profile is generated by calculating specific diameters and profile points to ensure the thread strictly adheres to its side of the theoretical parting line. The core logic is implemented in the calculateThreadlibSpecs() function within BSPP_thread.awk.

    Key Parameters and Calculation Steps

    1. Pitch (P): Sourced from the BSPP_thread.csv data table.
    2. Pitch Diameter:
      • External threads: Aim for a smaller pitch diameter (DPitchExt). threadlib defaults to Class A and targets the center of the acceptable range in the CSV.
      • Internal threads: Aim for a larger pitch diameter (DPitchInt).
    3. Major/Minor Diameter:
      • For external threads, the major diameter (DMaxExt) is chosen as the center of the acceptable range.
      • For internal threads, the minor diameter (DMinInt) is chosen as the center of the acceptable range.
    4. Support Diameter (DSupportExt, DSupportInt): This must reside on the correct side of the parting line. It is calculated as the midpoint between the intended major/minor diameter and the corner of the fundamental triangle: Pitch Diameter +/- 2 * 5/12 * H (where H is the full height of the fundamental triangle).
    5. Valley Diameter (DValleyExt, DValleyInt): These define the valleys of the actual part and are chosen to overlap with the support diameter (corresponding to Rrot).
    6. Crest Diameter (DCrest): Adjusted to ensure the straightened profile's crest does not cross the parting line.

    Profile Point Generation

    The thread profile is defined by four points $(dr_i, z_i)$ in the OpenSCAD x-y plane. The radii ($dr_i$) are calculated as:

    • $0$
    • $0$
    • $(DCrest - DValley) / 2$
    • $(DCrest - DValley) / 2$

    The corresponding $z$-values are derived using the triangle formed by the crest/valley line and the corner of the fundamental triangle.

  3. Understand the structure of threadlib

    develop

    threadlib is a lightweight OpenSCAD-based library consisting of two primary files:

    1. threadlib.scad: Contains the functional code used to generate threads, bolts, and nuts.
    2. THREAD_TABLE.scad: A data file containing a large dictionary named THREAD_TABLE which maps thread designators to their specific technical specifications.

  4. Understand thread validation logic in test_table.awk

    develop

    The test_table.awk script uses pattern matching to apply different validation rules to different thread types:

    • External Threads ("[^,]+-ext):
      • Must have a positive radius of rotation (Rrot > 0).
      • Must overlap with the support (Rrot > Dsupport / 2).
    • Metric External Threads (/M[0-9.x-]+-ext/):
      • Must have specific thread angles (e.g., +/-60 degree slopes).
      • Must pass horizontal crest/valley tests via test_horizontal().

    If a test fails, the script prints an error message to the screen and sets the PASS variable to 0. A thread that does not match any specific test pattern is also marked as a failure.

  5. Extend threadlib with custom threads

    develop

    You can add your own thread definitions by providing a custom table to the thread() function using the table argument. The table format is an array of arrays, where each entry defines a thread name and its parameters.

    Table Format: ["name", [pitch, Rrot, Dsupport, [[r0, z0], [r1, z1], ..., [rn, zn]]]]

    use <threadlib/threadlib.scad>

MY_THREAD_TABLE = [
                   ["special", [pitch, Rrot, Dsupport, [[r0, z0], [r1, z1], ..., [rn, zn]]]]
                   ];

thread("special", turns=15, table=MY_THREAD_TABLE);

  6. Handling valley diameter limits for internal threads

    develop
    For certain internal threads, the calculated valley diameter might fall on the corner or outside the fundamental triangle. To prevent one thread turn from overlapping with the next (which would cause mechanical interference), threadlib includes a built-in safety check. This check limits the valley diameter to a safe range to ensure proper thread separation.

  7. How Metric Thread specifications are calculated

    develop

    Metric thread specifications in threadlib are derived from standard norms using a two-step process:

    1. Data Source: metric_thread.csv contains the raw numbers directly from the norm without modification.
    2. Calculation: metric_thread.awk processes this data to calculate the specific threadlib specs based on the following logic:
    • Designator: Uses the simplified variant.
    • Pitch diameters: Calculated using the center of the tolerance range.
    • Support diameters: Calculated using the center of the tolerance range.
    • Valley diameter: Calculated at the border of the tolerance range to ensure overlap with the support diameter is assured.
    • Crest diameters: Calculated using the center of the tolerance range.

  8. Add new thread specifications to threadlib

    develop

    Follow these steps to integrate new thread data into the THREAD_TABLE.scad file:

    1. Tabulate Data: Create a file named design/newthreads.csv containing the raw specifications extracted from the industrial norm.
    2. Create Translation Script: Write an AWK script at design/newthreads.awk that translates your newthreads.csv into the tabular threadlib format.
    3. Update Makefile: Add a command to your Makefile to automate the concatenation and translation:
      cat design/newthreads.csv | awk -f design/newthreads.awk >> design/THREAD_TABLE.csv
    4. Autogeneration: The existing design/autogenerate.awk script will automatically convert the resulting THREAD_TABLE.csv into the final THREAD_TABLE.scad (adding necessary quoting and bracketing) when you run make.

    THREAD_TABLE.csv Format

    The CSV must follow this column structure: DESIGNATOR, P, Rrot, Dsup, dr_0, z0, dr_1, z_1, dr_2, z_2, dr_3, z_3

    cat design/newthreads.csv | awk -f design/newthreads.awk >> design/THREAD_TABLE.csv

  9. Verify THREAD_TABLE.scad using awk

    develop

    The THREAD_TABLE.scad file is validated using an awk script located at tests/test_table.awk. This script parses every line of the thread table and runs specific tests based on the thread designator (e.g., identifying external threads or specific metric threads).

    To run the tests, you feed the contents of THREAD_TABLE.scad into the awk script. The script tracks success via a PASS variable (initialized to 1 in the BEGIN block) and ensures every thread is covered by checking a tested flag.

    # Example command structure (conceptual)
awk -f tests/test_table.awk THREAD_TABLE.scad

  10. Test newly created thread specifications

    develop

    After adding new threads, you must verify them by extending the test suite. At a minimum, you should add a test for the thread angles.

    1. Update Tests: Extend tests/test_table.awk to include your new thread specifications.
    2. Run Tests: Execute the tests from the top-level directory or from within the tests/ subdirectory using make.
    make test
# OR
cd tests && make

    If the output displays TESTS SUCCESSFUL, the new threads have passed. Note that if a thread spec exists in the table but is not covered by any test, the test suite will fail.

    make test

  11. Install threadlib for OpenSCAD

    develop

    To use threadlib, you must first install its prerequisites into your OpenSCAD library folder.

    Prerequisites

    Ensure the following are saved in your OpenSCAD library folder:

    1. openscad/scad-utils
    2. list-comprehension
    3. threadprofile.scad

    threadlib Installation

    Clone the threadlib repository into a folder named threadlib inside your OpenSCAD library folder. Your library directory structure should look like this:

    libraries
├── list-comprehension-demos/
├── scad-utils/
├── thread_profile.scad
└── threadlib/

  12. Create bolts and nuts

    develop

    Use bolt() and nut() for common threaded components.

    Note on Units: threadlib is designed in millimeters. Ensure your OpenSCAD units are set to mm or scale the output accordingly.

    Bolts

    To create a bolt (without head) with a specific number of turns and a configurable Higbee arc:

    bolt("M4", turns=5, higbee_arc=30);

    Nuts

    To create a nut, you must specify an outer diameter (Douter). The inner diameter is determined by the thread designator. You can also specify the number of sides (e.g., nut_sides=6 for a hex nut).

    nut("M12x0.5", turns=10, Douter=16);
// Hex nut example
nut("M30", turns=4, Douter=46, nut_sides=6);
    bolt("M4", turns=5, higbee_arc=30);

nut("M12x0.5", turns=10, Douter=16);

nut("M30", turns=4, Douter=46, nut_sides=6);