295 lines
13 KiB
Python
295 lines
13 KiB
Python
"""Parametric screw-thread generator built on build123d geometry.
|
|
|
|
Strategy
|
|
--------
|
|
A screw thread is a helical prism: one trapezoidal tooth profile swept along a
|
|
helix using the OCC Frenet frame. ``is_frenet=True`` keeps the profile
|
|
orientation constant along a straight helix (the curvature vector always
|
|
points at the axis), which is exactly the configuration a machined thread has:
|
|
the flank is a true helical surface with a constant axial pitch.
|
|
|
|
The generator builds a single seamless "tooth ribbon" (one pitch wide per
|
|
loop) plus the core cylinder, fuses them, and trims both ends flush at
|
|
``z in [0, length_mm]``. The tooth root is sunk slightly below the core
|
|
radius so the boolean union has a clean volume overlap instead of a pair of
|
|
coincident faces (which OCC cannot fuse reliably).
|
|
|
|
``spec.internal=False`` builds an external thread (thread_add): a solid rod
|
|
whose crest envelope is ``major_diameter_mm``. ``spec.internal=True`` builds
|
|
an internal-thread cutting tool: the identical helical-rod topology but with
|
|
the crest radius over-sized by ``INTERNAL_CUT_OVERLAP_MM`` so that
|
|
``body.cut(tool)`` removes a clean helical groove from the host wall instead
|
|
of collapsing on coincident faces. External threads may add plain root-radius
|
|
end shanks (``relief_length_mm``, total length then becomes
|
|
``length_mm + 2 * relief_length_mm``) and crest/root fillet radii; the
|
|
internal cutting form accepts fillets but not relief.
|
|
|
|
The module stays independent of the CDSL runtime: it only reads
|
|
``runtime_types.ThreadSpec`` (a build123d-free data class) and returns an OCC
|
|
``Solid``. Construction happens in a local +Z frame anchored at ``z = 0``;
|
|
frame placement/rotation to ``spec.axis`` is the adapter's responsibility.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import math
|
|
|
|
from build123d import Compound, Edge, Face, Location, Plane, ShapeList, Solid, Vector, Wire
|
|
|
|
from .runtime_types import ThreadSpec
|
|
|
|
#: How far below the nominal core radius the tooth root extends (mm, clamped).
|
|
#: The extra overlap guarantees the root cylinder union is a clean volume
|
|
#: boolean rather than a coincident-face attachment.
|
|
_ROOT_OVERLAP_MM = 0.15
|
|
#: Minimum surviving flat on the tooth crest before the flanks would overlap.
|
|
_MIN_CREST_HALF_WIDTH_MM = 0.02
|
|
#: Internal-thread cutting tool over-size beyond the nominal major radius (mm).
|
|
#: ``body.cut(tool)`` removes a helical groove whose crest envelope has to
|
|
#: penetrate the host wall by a thin material layer; an exact-fit tool would
|
|
#: place coincident faces inside OCC's boolean and fail unpredictably.
|
|
INTERNAL_CUT_OVERLAP_MM = 0.02
|
|
|
|
|
|
def _validate_spec(spec: ThreadSpec) -> tuple[float, float, float, float, float]:
|
|
"""Range-check a spec and return geometry parameters.
|
|
|
|
Returns ``(crest_radius, root_radius, sink, flank_throw, flank_half_tan)``
|
|
where ``flank_throw`` is the horizontal flank run per tooth side and
|
|
``flank_half_tan`` is ``tan(flank_half_angle)``.
|
|
"""
|
|
if spec.internal and spec.relief_length_mm > 0:
|
|
raise ValueError("relief_length_mm is only supported on external threads (thread_add)")
|
|
if spec.major_diameter_mm <= 0 or spec.minor_diameter_mm <= 0:
|
|
raise ValueError("thread diameters must be positive")
|
|
if spec.minor_diameter_mm >= spec.major_diameter_mm:
|
|
raise ValueError("thread minor diameter must be smaller than the major diameter")
|
|
if spec.pitch_mm <= 0:
|
|
raise ValueError("thread pitch must be positive")
|
|
if spec.length_mm <= 0:
|
|
raise ValueError("thread length must be positive")
|
|
if not 0 < spec.angle_deg < 180:
|
|
raise ValueError("thread angle_deg must be between 0 and 180")
|
|
|
|
if spec.internal:
|
|
# 内螺纹刀具：牙顶必须比名义 major 大一个薄材料层，body.cut 才能
|
|
# 切入宿主孔壁完成布尔差，而不是在 coincident faces 上退化。
|
|
crest_radius = spec.major_diameter_mm / 2.0 + INTERNAL_CUT_OVERLAP_MM
|
|
else:
|
|
crest_radius = spec.major_diameter_mm / 2.0
|
|
root_radius = spec.minor_diameter_mm / 2.0
|
|
depth_radius = crest_radius - root_radius
|
|
if depth_radius <= 0:
|
|
raise ValueError("thread major diameter must exceed the minor diameter")
|
|
|
|
sink = min(_ROOT_OVERLAP_MM, 0.25 * depth_radius, 0.1 * spec.pitch_mm)
|
|
full_depth = depth_radius + sink # from sunk root up to the crest
|
|
flank_half_tan = math.tan(math.radians(spec.angle_deg / 2.0))
|
|
flank_throw = full_depth * flank_half_tan
|
|
return crest_radius, root_radius, sink, flank_throw, flank_half_tan
|
|
|
|
|
|
def _build_z_aligned(spec: ThreadSpec) -> Solid:
|
|
"""Construct an external thread along +Z spanning ``z in [0, length_mm]``.
|
|
|
|
Local frame: z = thread axis, the leading end face sits at ``z = 0`` and
|
|
starts inside a tooth valley so the first crest rises cleanly off the end
|
|
face. Helix pitch runs right-handed (or left-handed when ``lefthand``).
|
|
"""
|
|
crest_radius, root_radius, sink, flank_throw, _flank_half_tan = _validate_spec(spec)
|
|
pitch = spec.pitch_mm
|
|
|
|
# Tooth geometry in the axial cross-section (z = axial, r = radial).
|
|
# One full tooth occupies a pitch-wide interval centered on the crest flat;
|
|
# the flank horizontal throw is `full_depth * tan(half_angle)`.
|
|
crest_half_width = pitch / 2.0 - flank_throw
|
|
if crest_half_width < _MIN_CREST_HALF_WIDTH_MM:
|
|
raise ValueError(f"thread pitch is too small for the given depth and flank angle (flank throw {flank_throw:.4f} mm must stay below pitch/2)")
|
|
|
|
# Overshoot both ends by one pitch so the trimmed faces land in full
|
|
# material; the crest centre sits at the helix start phase (z = 0), which
|
|
# also puts the z = 0 end face through full crest material after trimming.
|
|
helix_height = spec.length_mm + 2.0 * pitch
|
|
helix = Edge.make_helix(
|
|
pitch=pitch,
|
|
height=helix_height,
|
|
radius=root_radius,
|
|
lefthand=spec.lefthand,
|
|
)
|
|
|
|
# Profile vertices (z, r) -> world (x = r, y = 0, z). Order is counter
|
|
# clockwise in the (z, r) plane: bottom edge first, then crest right,
|
|
# crest flat, crest left back down. The bottom edge spans the full pitch
|
|
# so consecutive helical loops share an identical seam line.
|
|
sunk_root = root_radius - sink
|
|
pts = [
|
|
Vector(sunk_root, 0.0, -pitch / 2.0),
|
|
Vector(sunk_root, 0.0, pitch / 2.0),
|
|
Vector(crest_radius, 0.0, crest_half_width),
|
|
Vector(crest_radius, 0.0, -crest_half_width),
|
|
]
|
|
wire = Wire([Edge.make_line(pts[index], pts[(index + 1) % len(pts)]) for index in range(len(pts))])
|
|
wire = _apply_profile_fillets(wire, spec, crest_radius, sunk_root, pitch, crest_half_width)
|
|
ribbon = Solid.sweep(section=Face(wire), path=helix, make_solid=True, is_frenet=True)
|
|
|
|
# Core cylinder at the nominal minor radius spanning the whole helix.
|
|
# (The sunken tooth roots overlap it so the union below is clean.)
|
|
# The profile spans z in [-pitch/2, +pitch/2] around the helix start, so
|
|
# the core begins at -pitch/2 and covers the shell plus one extra pitch.
|
|
core_height = helix_height + pitch
|
|
core = Solid.make_cylinder(root_radius, core_height, Plane(origin=(0.0, 0.0, -pitch / 2.0)))
|
|
|
|
fused = core.fuse(ribbon)
|
|
|
|
if spec.relief_length_mm > 0:
|
|
# 端部收尾（relief）：螺纹有效段保持 length_mm 不变，置于总长中部
|
|
# z ∈ [relief, relief + length]，两端各附一个牙根半径的光杆段，总长 =
|
|
# length + 2 * relief。光杆与芯柱做实体重叠后由 trim 裁出干净的纯光杆端面。
|
|
return _build_external_with_relief(spec, fused, root_radius, crest_radius, pitch)
|
|
|
|
# 平移半个牙距，使 z = 0 端面落在牙谷中心：首尾端面无半牙、端面圆盘完整，
|
|
# 裁切后 [0, length_mm] 内牙顶平台数稳定为 length/pitch。
|
|
fused = fused.moved(Location((0.0, 0.0, -pitch / 2.0)))
|
|
return _trim_thread_z(fused, 0.0, spec.length_mm, crest_radius)
|
|
|
|
|
|
def _trim_thread_z(fused: Solid | Compound, z0: float, z1: float, crest_radius: float) -> Solid:
|
|
"""Intersect ``fused`` with an oversized box clamped to ``z in [z0, z1]``.
|
|
|
|
A threaded solid may leave OCC float slivers at the trim planes; the
|
|
largest surviving solid is returned as the canonical body.
|
|
"""
|
|
trim_margin = 2.0
|
|
half_span = crest_radius + trim_margin
|
|
clamp = Solid.make_box(
|
|
2.0 * half_span,
|
|
2.0 * half_span,
|
|
z1 - z0,
|
|
Plane(origin=(-half_span, -half_span, z0)),
|
|
)
|
|
intersected = fused.intersect(clamp)
|
|
if isinstance(intersected, ShapeList):
|
|
candidates = list(intersected)
|
|
elif intersected is not None:
|
|
candidates = [intersected]
|
|
else:
|
|
candidates = []
|
|
members: list[Solid] = []
|
|
for candidate in candidates:
|
|
if isinstance(candidate, Solid):
|
|
members.append(candidate)
|
|
else:
|
|
members.extend(candidate.solids())
|
|
if not members:
|
|
raise ValueError("thread end trim produced no solid")
|
|
# 端部裁齐应保持单一主体；若 OCC 留下浮点碎屑，取体积最大的实心主体。
|
|
trimmed = members[0] if len(members) == 1 else max(members, key=lambda shape: shape.volume)
|
|
return trimmed
|
|
|
|
|
|
def _build_external_with_relief(
|
|
spec: ThreadSpec,
|
|
aligned: Solid | Compound,
|
|
root_radius: float,
|
|
crest_radius: float,
|
|
pitch: float,
|
|
) -> Solid:
|
|
"""Build an externally threaded rod with plain root-radius end shanks.
|
|
|
|
The threaded portion keeps its full ``length_mm`` and sits in the middle of
|
|
the part: ``z in [relief, relief + length_mm]``. A plain shank of radius
|
|
``root_radius`` (the thread root/minor radius) extends over ``z in
|
|
[0, relief]`` and ``[relief + length_mm, total]``, so the total part length
|
|
is ``length_mm + 2 * relief_length_mm``.
|
|
|
|
``aligned`` is the fused core+ribbon *before* the valley-centring shift.
|
|
The build first trims a clean valley-centred thread over ``[0, length_mm]``
|
|
(identical phase and tooth count to the plain build), then shifts it up by
|
|
``relief`` so both end planes land inside tooth valleys. Each shank
|
|
cylinder overlaps the threaded core by ``_ROOT_OVERLAP_MM`` so both fuses
|
|
are volume booleans, and the final trim turns the two end planes into clean
|
|
plain discs at ``z = 0`` and ``z = total``.
|
|
"""
|
|
relief = spec.relief_length_mm
|
|
length = spec.length_mm
|
|
overlap = _ROOT_OVERLAP_MM
|
|
total = length + 2.0 * relief
|
|
thread = _trim_thread_z(aligned.moved(Location((0.0, 0.0, -pitch / 2.0))), 0.0, length, crest_radius)
|
|
thread = thread.moved(Location((0.0, 0.0, relief)))
|
|
bottom = Solid.make_cylinder(root_radius, relief + overlap, Plane(origin=(0.0, 0.0, 0.0)))
|
|
top = Solid.make_cylinder(
|
|
root_radius,
|
|
relief + overlap,
|
|
Plane(origin=(0.0, 0.0, relief + length - overlap)),
|
|
)
|
|
fused = thread.fuse(bottom).fuse(top)
|
|
return _trim_thread_z(fused, 0.0, total, crest_radius)
|
|
|
|
|
|
def _apply_profile_fillets(
|
|
wire: Wire,
|
|
spec: ThreadSpec,
|
|
crest_radius: float,
|
|
sunk_root: float,
|
|
pitch: float,
|
|
crest_half_width: float,
|
|
) -> Wire:
|
|
"""Round the tooth crest/root corners of the axial cross-section.
|
|
|
|
A crest/root radius that is too large for the flank lengths makes OCC's
|
|
``fillet_2d`` fail; the profile then falls back to the sharp-cornered
|
|
trapezoid instead of blocking the whole build (AGENTS: never destroy a
|
|
buildable model over a cosmetic detail).
|
|
"""
|
|
if spec.crest_radius_mm <= 0 and spec.root_radius_mm <= 0:
|
|
return wire
|
|
try:
|
|
if spec.crest_radius_mm > 0:
|
|
crest_vertices = [
|
|
vertex for vertex in wire.vertices()
|
|
if vertex.X >= crest_radius - 1e-6 and abs(vertex.Z) <= crest_half_width + 1e-6
|
|
]
|
|
if crest_vertices:
|
|
wire = wire.fillet_2d(spec.crest_radius_mm, crest_vertices)
|
|
if spec.root_radius_mm > 0:
|
|
root_vertices = [
|
|
vertex for vertex in wire.vertices()
|
|
if vertex.X <= sunk_root + 1e-6 and abs(vertex.Z) >= pitch / 2.0 - 1e-6
|
|
]
|
|
if root_vertices:
|
|
wire = wire.fillet_2d(spec.root_radius_mm, root_vertices)
|
|
except Exception:
|
|
# 清根圆角过大导致截面退化：保留尖角梯形，不阻断生成。
|
|
pass
|
|
return wire
|
|
|
|
|
|
def build_thread_solid(spec: ThreadSpec) -> Solid:
|
|
"""Build one external-threaded solid segment for ``spec``.
|
|
|
|
Returns a solid whose thread axis is +Z and whose leading end face is at
|
|
``z = 0``. The caller (geometry adapter) is responsible for placing the
|
|
solid at ``spec.axis``.
|
|
"""
|
|
result = _build_z_aligned(spec)
|
|
if not result.solids():
|
|
raise ValueError("thread generation produced no solid")
|
|
return result
|
|
|
|
|
|
def build_thread_cut_tool(spec: ThreadSpec) -> Solid:
|
|
"""Build the internal-thread cutting tool that ``thread_cut`` subtracts.
|
|
|
|
The tool is exactly the ``internal=True`` thread form: the identical
|
|
helical-rod topology as ``thread_add`` but with the crest envelope
|
|
over-sized by ``INTERNAL_CUT_OVERLAP_MM`` beyond the nominal major radius.
|
|
``host.cut(tool)`` then removes a clean full-depth helical groove from the
|
|
host bore wall instead of collapsing on a pair of coincident faces (which
|
|
OCC cannot cut reliably). This is the geometry-side entry point of the
|
|
``thread_cut`` atomic; the caller (geometry adapter) places the resulting
|
|
+Z-aligned tool at ``spec.axis`` exactly like an external thread segment.
|
|
"""
|
|
if not spec.internal:
|
|
raise ValueError("build_thread_cut_tool requires an internal-thread spec (internal=True)")
|
|
return build_thread_solid(spec)
|