thread - parametric helical threads

Helical threads are very common in mechanical designs but can be tricky to create in a robust and efficient manner. This sub-package provides classes that create several common types of threads:

• ISO Standard 60° threads found on most fasteners

• Whitworth 55° threads with rounded crests and roots

• ISO 228 BSPP (G-series) parallel pipe threads

• Acme 29° threads found on imperial machine equipment

• Metric Trapezoidal 30° thread found on metric machine equipment

In addition, all threads support four different end finishes:

• “raw” - where the thread extends beyond the desired length ready for integration into another part

• “fade” - where the end of the thread spirals in - or out for internal threads

• “square” - where the end of the thread is flat

• “chamfer” - where the end of the thread is chamfered as commonly found on machine screws

Here is what they look like (clockwise from the top: “fade”, “chamfer”, “square” and “raw”):

When choosing between these four options, consider the performance differences between them. Here are some measurements that give a sense of the relative performance:

Finish	Time
“raw”	0.018s
“fade”	0.087s
“square”	0.370s
“chamfer”	1.641s

The “raw” and “fade” end finishes do not use any boolean operations which is why they are so fast. “square” does a cut() operation with a box while “chamfer” does an intersection() with a chamfered cylinder.

The following sections describe the different thread classes.

Thread

class Thread(*args, **kwargs)

Helical thread

The most general thread class used to build all of the other threads. Creates right or left hand helical thread with the given root and apex radii.

Parameters:

• apex_radius – Radius at the narrow tip of the thread.

• apex_width – Width at the narrow tip of the thread.

• root_radius – Radius at the wide base of the thread.

• root_width – Thread base width.

• pitch – Length of 360° of thread rotation.

• length – End to end length of the thread.

• apex_offset – Asymmetric thread apex offset from center. Defaults to 0.0.

• interference – Amount the thread will overlap with nut or bolt core. Used to help create valid threaded objects where the thread must fuse with another object. For threaded objects built as Compounds, this value could be set to 0.0. Defaults to 0.2.

• hand – Twist direction. Defaults to “right”.

• taper_angle – Cone angle for tapered thread. Defaults to None.

• end_finishes – Profile of each end, one of “raw”, “fade”, “square”, or “chamfer”. Defaults to (“raw”, “raw”).

• simple – Stop at thread calculation, don’t create thread. Defaults to False.

• manufacturing_compensation – Radial allowance for vertically printed FDM threads. A positive value moves an external thread inward or an internal thread outward without changing its pitch or profile. Calibrate the value for the printer, material, and print settings. It does not compensate horizontal-print stair stepping or sagging. Defaults to 0.0.

Raises:

ValueError – if end_finishes not in [“raw”, “square”, “fade”, “chamfer”]:

IsoThread

class IsoThread(*args, **kwargs)

ISO Standard Thread

Both external and internal ISO standard 60° threads as shown in the following diagram (from https://en.wikipedia.org/wiki/ISO_metric_screw_thread):

The following is an example of an internal thread with a chamfered end as might be found inside a nut:

Parameters:

• major_diameter (float) – Primary thread diameter

• pitch (float) – Length of 360° of thread rotation

• length (float) – End to end length of the thread

• external (bool, optional) – External or internal thread selector. Defaults to True.

• hand (Literal[, optional) – Twist direction. Defaults to “right”.

• end_finishes (Tuple[ Literal[, optional) –

  Profile of each end, one of:

  ”raw”

  unfinished which typically results in the thread extended below z=0 or above z=length

  ”fade”

  the thread height drops to zero over 90° of arc (or 1/4 pitch)

  ”square”

  clipped by the z=0 or z=length plane

  ”chamfer”

  conical ends which facilitates alignment of a bolt into a nut

  Defaults to (“fade”, “square”).

• interference – Amount the thread will overlap with nut or bolt core. Used to help create valid threaded objects where the thread must fuse with another object. For threaded objects built as Compounds, this value could be set to 0.0. Defaults to 0.2.

• simple – Stop at thread calculation, don’t create thread. Defaults to False.

• manufacturing_compensation – Radial allowance for vertically printed FDM threads. A positive value moves an external thread inward or an internal thread outward. Calibrate it for the printing process; it does not compensate horizontal-print Z-axis errors. Defaults to 0.0.

• rotation (RotationLike, optional) – object rotation. Defaults to (0, 0, 0).

• align (Union[None, Align, tuple[Align, Align, Align]], optional) – object alignment. Defaults to None.

• mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Variables:

• thread_angle (int) – 60 degrees

• h_parameter (float) – Value of h as shown in the thread diagram

• min_radius (float) – Inside radius of the thread diagram

Raises:

• ValueError – if hand not in [“right”, “left”]:

• ValueError – end_finishes not in [“raw”, “square”, “fade”, “chamfer”]

WhitworthThread

class WhitworthThread(*args, **kwargs)

Full- or truncated-form 55° Whitworth thread.

Creates the rounded crest and root profile used as the basic thread form by standards including ISO 228. The full profile has tangent circular arcs at both the crest and roots. A truncated profile is made by splitting this full profile at the requested radial crest depth before it is swept.

Parameters:

• major_diameter – Basic major diameter of the thread.

• pitch – Length of 360° of thread rotation.

• length – End-to-end length of the thread.

• external – External or internal thread selector. Defaults to True.

• hand – Twist direction. Defaults to “right”.

• end_finishes – Profile of the two ends. Defaults to (“fade”, “square”).

• interference – Radial overlap with the mating cylindrical core. Defaults to 0.2.

• simple – Calculate the profile without creating the swept thread. Defaults to False.

• rotation – Object rotation. Defaults to (0, 0, 0).

• align – Object alignment. Defaults to None.

• mode – Combination mode. Defaults to Mode.ADD.

• crest_truncation – Radial depth removed from the theoretical rounded crest before sweeping. Defaults to 0.0.

• manufacturing_compensation – Radial allowance for vertically printed FDM threads. A positive value moves an external thread inward or an internal thread outward. Calibrate it for the printing process; it does not compensate horizontal-print Z-axis errors. Defaults to 0.0.

Variables:

• thread_angle – Included profile angle of 55°.

• fundamental_triangle_height – Height H of the fundamental triangle.

• thread_height – Radial height h of the full-form profile.

• rounding_radius – Radius r of the rounded crests and roots.

• crest_diameter – Resulting external major or internal minor diameter.

BSPPThread

class BSPPThread(*args, **kwargs)

ISO 228-1 G-series British Standard Pipe Parallel thread.

By default the generated solid uses the nominal full-form Whitworth profile. Supplying a crest diameter within the applicable ISO limits creates the corresponding truncated profile before the thread is swept. Pitch-diameter limits remain independent metadata.

Parameters:

• size – G-series designation, such as "G1/2". The forms "G 1/2" and "1/2" are also accepted.

• length – End-to-end length of the thread.

• external – External or internal thread selector. Defaults to True.

• tolerance_class – External pitch-diameter tolerance class "A" or "B". Defaults to "A" for external threads and must be omitted for internal threads.

• hand – Twist direction. Defaults to “right”.

• end_finishes – Profile of the two ends. Defaults to (“fade”, “square”).

• interference – Radial overlap with the mating cylindrical core. Defaults to 0.2.

• simple – Calculate the profile without creating the swept thread. Defaults to False.

• rotation – Object rotation. Defaults to (0, 0, 0).

• align – Object alignment. Defaults to None.

• mode – Combination mode. Defaults to Mode.ADD.

• crest_diameter – Selected external major or internal minor diameter. Defaults to the basic full-form diameter.

• manufacturing_compensation – Radial allowance for vertically printed FDM threads. A positive value moves an external thread inward or an internal thread outward. Calibrate it for the printing process; it does not compensate horizontal-print Z-axis errors. Defaults to 0.0.

Variables:

• designation – ISO designation including external class and left hand.

• tpi – Number of threads in 25.4 mm.

• basic_major_diameter – Basic ISO major diameter.

• basic_pitch_diameter – Basic ISO pitch diameter.

• basic_minor_diameter – Basic ISO minor diameter.

• pitch_diameter_limits – Minimum and maximum pitch diameters.

• major_diameter_limits – External major-diameter limits, otherwise None.

• minor_diameter_limits – Internal minor-diameter limits, otherwise None.

AcmeThread

class AcmeThread(*args, **kwargs)

ACME Thread

The original trapezoidal thread form, and still probably the one most commonly encountered worldwide, with a 29° thread angle, is the Acme thread form.

The following is the acme thread with faded ends:

Parameters:

• size (str) – size as a string (i.e. “3/4” or “1 1/4”)

• length (float) – thread length

• external (bool, optional) – external or internal thread selector. Defaults to True.

• hand (Literal[, optional) – twist direction. Defaults to “right”.

• end_finishes (Tuple[ Literal[, optional) –

  Profile of each end, one of:

  ”raw”

  unfinished which typically results in the thread extended below z=0 or above z=length

  ”fade”

  the thread height drops to zero over 90° of arc (or 1/4 pitch)

  ”square”

  clipped by the z=0 or z=length plane

  ”chamfer”

  conical ends which facilitates alignment of a bolt into a nut

  Defaults to (“fade”, “fade”).

• interference – Amount the thread will overlap with nut or bolt core. Used to help create valid threaded objects where the thread must fuse with another object. For threaded objects built as Compounds, this value could be set to 0.0. Defaults to 0.2.

• manufacturing_compensation – Radial allowance for vertically printed FDM threads. A positive value moves an external thread inward or an internal thread outward. Calibrate it for the printing process; it does not compensate horizontal-print Z-axis errors. Defaults to 0.0.

• rotation (RotationLike, optional) – object rotation. Defaults to (0, 0, 0).

• align (Union[None, Align, tuple[Align, Align, Align]], optional) – object alignment. Defaults to None.

• mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises:

• ValueError – hand must be one of “right” or “left”

• ValueError – end_finishes invalid, must be tuple() of “raw, square, taper, or chamfer”

Variables:

• thread_angle (int) – thread angle in degrees

• diameter (float) – thread diameter

• pitch (float) – thread pitch

MetricTrapezoidalThread

class MetricTrapezoidalThread(*args, **kwargs)

Metric Trapezoidal Thread

The ISO 2904 standard metric trapezoidal thread with a thread angle of 30°

Parameters:

• size (str) – specified as a sting with diameter x pitch in mm (i.e. “8x1.5”)

• length (float) – End to end length of the thread

• external (bool, optional) – external or internal thread selector. Defaults to True.

• hand (Literal[, optional) – twist direction. Defaults to “right”.

• end_finishes (Tuple[ Literal[, optional) –

  Profile of each end, one of:

  ”raw”

  unfinished which typically results in the thread extended below z=0 or above z=length

  ”fade”

  the thread height drops to zero over 90° of arc (or 1/4 pitch)

  ”square”

  clipped by the z=0 or z=length plane

  ”chamfer”

  conical ends which facilitates alignment of a bolt into a nut

  Defaults to (“fade”, “fade”).

• interference – Amount the thread will overlap with nut or bolt core. Used to help create valid threaded objects where the thread must fuse with another object. For threaded objects built as Compounds, this value could be set to 0.0. Defaults to 0.2.

• manufacturing_compensation – Radial allowance for vertically printed FDM threads. A positive value moves an external thread inward or an internal thread outward. Calibrate it for the printing process; it does not compensate horizontal-print Z-axis errors. Defaults to 0.0.

• rotation (RotationLike, optional) – object rotation. Defaults to (0, 0, 0).

• align (Union[None, Align, tuple[Align, Align, Align]], optional) – object alignment. Defaults to None.

• mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises:

• ValueError – hand must be one of “right” or “left”

• ValueError – end_finishes invalid, must be tuple() of “raw, square, taper, or chamfer”

Variables:

• thread_angle (int) – thread angle in degrees

• diameter (float) – thread diameter

• pitch (float) – thread pitch

TrapezoidalThread

The base class of the AcmeThread and MetricTrapezoidalThread classes.

class TrapezoidalThread(*args, **kwargs)

Trapezoidal Thread Base Class

Trapezoidal thread forms are screw thread profiles with trapezoidal outlines. They are the most common forms used for leadscrews (power screws). They offer high strength and ease of manufacture. They are typically found where large loads are required, as in a vise or the leadscrew of a lathe.

Trapezoidal Thread is a base class for Metric and Acme derived classes, or can be used to create a trapezoidal thread with arbitrary properties.

Parameters:

• thread_angle (int) – thread angle in degrees

• diameter (float) – thread diameter

• pitch (float) – thread pitch - for threads with multiple starts, pitch is the distance between adjacent threads along the axis of the screw.

• size (str) – specified by derived class

• length (float) – thread length

• external (bool, optional) – external or internal thread selector. Defaults to True.

• starts (int, optional) – the number of thread starts, which indicates how many threads run parallel to each other along the screw. Defaults to 1.

• hand (Literal[, optional) – twist direction. Defaults to “right”.

• end_finishes (Tuple[ Literal[, optional) –

  Profile of each end, one of:

  ”raw”

  unfinished which typically results in the thread extended below z=0 or above z=length

  ”fade”

  the thread height drops to zero over 90° of arc (or 1/4 pitch)

  ”square”

  clipped by the z=0 or z=length plane

  ”chamfer”

  conical ends which facilitates alignment of a bolt into a nut

  Defaults to (“fade”, “fade”).

• interference – Amount the thread will overlap with nut or bolt core. Used to help create valid threaded objects where the thread must fuse with another object. For threaded objects built as Compounds, this value could be set to 0.0. Defaults to 0.2.

• manufacturing_compensation – Radial allowance for vertically printed FDM threads. A positive value moves an external thread inward or an internal thread outward. Calibrate it for the printing process; it does not compensate horizontal-print Z-axis errors. Defaults to 0.0.

• rotation (RotationLike, optional) – object rotation. Defaults to (0, 0, 0).

• align (Union[None, Align, tuple[Align, Align, Align]], optional) – object alignment. Defaults to None.

• mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises:

• ValueError – hand must be one of “right” or “left”

• ValueError – end_finishes invalid, must be tuple() of “raw, square, taper, or chamfer”

Variables:

• thread_angle (int) – thread angle in degrees

• diameter (float) – thread diameter

• pitch (float) – thread pitch

PlasticBottleThread

class PlasticBottleThread(*args, **kwargs)

Plastic bottle thread.

ASTM D2911 is selected by default. PCO1881 is selected with bottle_type="pco1881". The PCO1881 external profile uses the standard bottle-finish diameters, while its internal profile uses a separate empirically fitted closure minor diameter.

L Style:

All-Purpose Thread - trapezoidal shape with 30° shoulders, metal or platsic closures

M Style:

Modified Buttress Thread - asymmetric shape with 10° and 40/45/50° shoulders, plastic closures

Parameters:

• size (str) – as defined by the ASTM is specified as [L|M][diameter(mm)]SP[100|103|110|200|400|410|415|425|444] for ASTM D2911, or "28" for PCO1881.

• bottle_type – Bottle thread standard, either "astm_d2911" or "pco1881". Defaults to "astm_d2911".

• external (bool, optional) – external or internal thread selector. Defaults to True.

• hand (Literal[, optional) – twist direction. Defaults to “right”.

• interference – Amount the thread will overlap with nut or bolt core. Used to help create valid threaded objects where the thread must fuse with another object. For threaded objects built as Compounds, this value could be set to 0.0. Defaults to 0.2.

• manufacturing_compensation – Radial allowance for vertically printed FDM threads. A value of 0.2 mm moves an external thread inward by 0.2 mm or an internal thread outward by 0.2 mm. Calibrate it for the printer, material, and print settings. It does not compensate horizontal-print stair stepping or sagging. Defaults to 0.0.

• rotation – RotationLike = (0, 0, 0),

• align – Union[None, Align, tuple[Align, Align, Align]] = None,

• mode – Mode = Mode.ADD,

Raises:

• ValueError – hand must be one of “right” or “left”

• ValueError – size invalid, must match [L|M][diameter(mm)]SP[100|103|110|200|400|410|415:425|444]

• ValueError – finish invalid

• ValueError – diameter invalid

Example

thread = PlasticBottleThread(
    size="M38SP444", external=False, manufacturing_compensation=0.2 * MM
)

classmethod bottle_types() → tuple[str, ...]

Return the supported bottle thread standards.

classmethod identify(neck_diameter: float | None = None, major_diameter: float | None = None, pitch: float | None = None, tpi: float | None = None, turns: float | None = None, style: Literal['L', 'M'] = 'M', tolerance: float = 0.5) → list[PlasticBottleThreadMatch]

The standard threads that fit measurements taken off a bottle

A finish is named for the diameter over its thread crests, which is not the diameter of the neck: a neck of 30 is a 33 finish. Measure either, or both, and as much of the rest as can be had. The distance between threads separates the coarse sizes from the fine, and the number of turns separates the finishes of one size: a bottle has at least the turns its finish requires and usually a little more.

These are single start threads, so check that only one thread begins at the top of the neck; on a multiple start thread the distance between neighbouring threads is not the pitch. Finishes of one size differ mostly in the height of the neck, which is not tabulated here, so those the turns allow all come back, the finish made in the most sizes first as the likeliest to be met.

Parameters:

• neck_diameter – diameter of the neck between the threads.

• major_diameter – diameter over the thread crests.

• pitch – distance from one thread to the next.

• tpi – threads per inch, in place of pitch.

• turns – times the thread wraps the neck.

• style – ASTM D2911 thread style the sizes are given in, “L” or “M”. Defaults to “M”.

• tolerance – how far outside a standard a measured diameter or pitch may fall and still fit. Defaults to 0.5.

Raises:

ValueError – neither diameter is given, both pitch and tpi are, or style is invalid

Returns:

what fits, best first

Return type:

list[PlasticBottleThreadMatch]

Example

best = PlasticBottleThread.identify(neck_diameter=30, pitch=4, turns=1.5)[0]
cap_thread = PlasticBottleThread(best.size, external=False)

classmethod sizes(bottle_type: str = 'astm_d2911') → list[str]

Return valid sizes for a bottle thread standard.

Bottles are not marked with their thread, and the name of a finish follows the diameter over its thread crests rather than the neck’s, so identify finds the standard threads that fit measurements taken off a bottle:

>>> for match in PlasticBottleThread.identify(neck_diameter=30, pitch=4, turns=1.5):
...     print(match.size, match.major_diameter, match.min_turns)
M33SP400 (31.52, 32.13) 1.0
M33SP444 (31.52, 32.13) 1.125
M33SP100 (31.52, 32.13) 1.125

class PlasticBottleThreadMatch(size: str, bottle_type: str, major_diameter: Tuple[float, float], neck_diameter: Tuple[float, float], pitch: float, min_turns: float | None, error: float)

A bottle thread standard that fits a set of measurements

Variables:

• size (str) – the size to give PlasticBottleThread

• bottle_type (str) – the bottle_type to give PlasticBottleThread

• major_diameter (Tuple[float, float]) – smallest and largest diameter over the thread crests, ASTM D2911’s T

• neck_diameter (Tuple[float, float]) – smallest and largest diameter of the neck between the threads, ASTM D2911’s E

• pitch (float) – distance from one thread to the next

• min_turns (float | None) – fewest turns of thread the finish allows, None where the standard fixes a thread length instead

• error (float) – how far the measurements fall outside the standard, in mm