Merge branch 'dev'

Author: tomasf

Package.resolved

@@ -10,7 +10,7 @@ let package = Package(
         .executable(name: "Helical-Demo", targets: ["Demo"]),
     ],
     dependencies: [
-        .package(url: "https://github.com/tomasf/Cadova.git", .upToNextMinor(from: "0.5.0")),
+        .package(url: "https://github.com/tomasf/Cadova.git", .upToNextMinor(from: "0.5.2")),
     ],
     targets: [
         .target(

Package.swift

@@ -66,7 +66,7 @@ let customBolt = Bolt(
     unthreadedLength: 3,
     unthreadedDiameter: 5,
     headShape: .countersunk(angle: 80°, topDiameter: 10, boltDiameter: 5),
-    socket: .slotted(length: 10, width: 1, depth: 1.4)
+    socket: .slot(length: 10, width: 1, depth: 1.4)
 )
 ```
 
@@ -80,7 +80,7 @@ Creating a matching countersunk clearance hole for a bolt is straightforward:
 Box(13)
     .aligned(at: .centerXY)
     .subtracting {
-        customBolt.clearanceHole(recessedHead: true)
+        customBolt.clearanceHole(entry: .recessedHead)
     }
 ```
 

README.md

@@ -9,9 +9,9 @@ let customBolt = Bolt(
     thread: customThread,
     length: boltLength,
     unthreadedLength: 0,
-    leadinChamferSize: 1.0,
     headShape: PolygonalBoltHeadShape(sideCount: 8, widthAcrossFlats: 12, height: 3, chamferAngle: 40°),
-    socket: PolygonalBoltHeadSocket(sides: 4, acrossWidth: 5, depth: 2)
+    socket: PolygonalBoltHeadSocket(sides: 4, width: 5, depth: 2),
+    point: .leadIn(.constant(depth: 1))
 )
 
 let bolts = [
@@ -35,7 +35,7 @@ let nutsAndWashers: [(String, any Geometry3D)] = [
     ("Thin square nut, M10", Nut.square(.m10, series: .thin)),
     ("Flanged hex nut, M6", Nut.flangedHex(.m6)),
     ("T-slot nut, M8", Nut.tSlotNut(.m8)),
-    ("Custom non-standard nut", Nut(thread: customThread, shape: PolygonalNutBody(sideCount: 8, thickness: 10, widthAcrossFlats: 12), innerChamferAngle: 60°)),
+    ("Custom non-standard nut", Nut(thread: customThread, shape: PolygonalNutBody(sideCount: 8, thickness: 10, widthAcrossFlats: 12), leadIns: .both(.angle(60°)))),
     ("Normal washer, M5", Washer.plain(.m5, series: .normal)),
     ("Large washer, M5", Washer.plain(.m5, series: .large))
 ]

Sources/Demo/main.swift

@@ -1,7 +1,9 @@
-import Foundation
 import Cadova
 
-/// A bolt with a head, threaded section, and optional point.
+/// A complete bolt fastener with a head, threaded shank, and optional point.
+///
+/// `Bolt` composes a head shape, drive socket, threaded section (``Screw``), and point
+/// into a full fastener model. For just the bare threaded geometry, use ``Screw``.
 public struct Bolt: Shape3D {
     /// The screw thread specification.
     public let thread: ScrewThread
@@ -46,36 +48,6 @@ public struct Bolt: Shape3D {
         self.point = point
     }
 
-    /// Creates a bolt with a chamfered point.
-    ///
-    /// - Parameters:
-    ///   - thread: The screw thread specification.
-    ///   - length: Nominal length of the bolt.
-    ///   - unthreadedLength: Length of the unthreaded portion.
-    ///   - unthreadedDiameter: Diameter of the unthreaded portion. Defaults to the thread's major diameter.
-    ///   - leadinChamferSize: Size of the lead-in chamfer at the bolt tip.
-    ///   - headShape: The bolt head geometry.
-    ///   - socket: Optional drive socket in the head.
-    public init(
-        thread: ScrewThread,
-        length: Double,
-        unthreadedLength: Double = 0,
-        unthreadedDiameter: Double? = nil,
-        leadinChamferSize: Double,
-        headShape: any BoltHeadShape,
-        socket: (any BoltHeadSocket)? = nil
-    ) {
-        self.init(
-            thread: thread,
-            length: length,
-            unthreadedLength: unthreadedLength,
-            unthreadedDiameter: unthreadedDiameter,
-            headShape: headShape,
-            socket: socket,
-            point: ProfiledBoltPoint(chamferSize: leadinChamferSize)
-        )
-    }
-
     /// Creates a bolt without threads, for cases where thread detail is unimportant.
     ///
     /// - Parameters:
@@ -130,35 +102,50 @@ public struct Bolt: Shape3D {
             .withThread(thread)
     }
 
-    private func clearanceHoleDepth(recessedHead: Bool = false) -> Double {
-        recessedHead ? (length + headShape.clearanceLength) : (length - headShape.consumedLength)
+    /// The entry geometry for a bolt clearance hole.
+    public enum ClearanceHoleEntry: Sendable {
+        /// No special geometry at the entry.
+        case plain
+        /// An edge profile applied at the hole opening.
+        case edgeProfile (EdgeProfile)
+        /// A recess matching the bolt head shape.
+        case recessedHead
     }
 
     /// Creates a clearance hole sized for this bolt.
     ///
-    /// - Parameters:
-    ///   - depth: Hole depth. Defaults to the bolt length minus head consumption.
-    ///   - edgeProfile: Optional edge profile at the hole opening.
-    /// - Returns: A clearance hole configured for this bolt.
-    public func clearanceHole(depth: Double? = nil, edgeProfile: EdgeProfile? = nil) -> ClearanceHole {
-        ClearanceHole(
-            diameter: thread.majorDiameter,
-            depth: depth ?? clearanceHoleDepth(),
-            edgeProfile: edgeProfile
-        )
-    }
-
-    /// Creates a clearance hole sized for this bolt, optionally with a recess for the head.
+    /// The default depth depends on the entry type: for ``ClearanceHoleEntry/recessedHead``,
+    /// the hole extends deep enough to fully recess the head; otherwise, it extends
+    /// the bolt length minus the head's consumed length.
     ///
     /// - Parameters:
-    ///   - depth: Hole depth. Defaults to a depth that accommodates the full bolt length.
-    ///   - recessedHead: Whether to include a recess matching the bolt head shape.
+    ///   - depth: Hole depth. Defaults to a depth appropriate for the entry type.
+    ///   - entry: The geometry at the entry of the hole. Defaults to `.plain`.
     /// - Returns: A clearance hole configured for this bolt.
-    public func clearanceHole(depth: Double? = nil, recessedHead: Bool) -> ClearanceHole {
+    public func clearanceHole(depth: Double? = nil, entry: ClearanceHoleEntry = .plain) -> ClearanceHole {
+        let recessedHead: Bool
+        let clearanceEntry: ClearanceHole.Entry
+
+        switch entry {
+        case .plain:
+            recessedHead = false
+            clearanceEntry = .plain
+        case .edgeProfile(let profile):
+            recessedHead = false
+            clearanceEntry = .edgeProfile(profile)
+        case .recessedHead:
+            recessedHead = true
+            clearanceEntry = .recess(headShape.recess)
+        }
+
+        let defaultDepth = recessedHead
+            ? (length + headShape.clearanceLength)
+            : (length - headShape.consumedLength)
+
         return ClearanceHole(
             diameter: thread.majorDiameter,
-            depth: depth ?? clearanceHoleDepth(recessedHead: true),
-            boltHeadRecess: recessedHead ? headShape.recess : Empty()
+            depth: depth ?? defaultDepth,
+            entry: clearanceEntry
         )
     }
 }

Sources/Helical/Bolt/Bolt.swift

@@ -1,4 +1,3 @@
-import Foundation
 import Cadova
 
 /// A protocol defining the geometry and dimensions of a bolt head.

Sources/Helical/Bolt/Parts/Heads/BoltHeadShape.swift

@@ -1,4 +1,3 @@
-import Foundation
 import Cadova
 
 /// A conical countersunk bolt head that sits flush with or below the mounting surface.
@@ -10,8 +9,6 @@ public struct CountersunkBoltHeadShape: BoltHeadShape {
     let boltDiameter: Double
     let lensHeight: Double
 
-    @Environment(\.tolerance) var tolerance
-
     /// Creates a countersunk head with the specified countersink geometry.
     ///
     /// - Parameters:
@@ -52,14 +49,15 @@ public struct CountersunkBoltHeadShape: BoltHeadShape {
     }
 
     public var body: any Geometry3D {
+        @Environment(\.tolerance) var tolerance
         let effectiveTopDiameter = countersink.topDiameter - tolerance
         let coneHeight = effectiveTopDiameter / 2 * tan(countersink.angle / 2)
 
         Cylinder(bottomDiameter: effectiveTopDiameter, topDiameter: 0.001, height: coneHeight)
             .translated(z: lensHeight)
             .adding {
                 if lensHeight > 0 {
-                    let diameter = lensHeight + pow(effectiveTopDiameter, 2) / (4 * lensHeight)
+                    let diameter = lensHeight + effectiveTopDiameter * effectiveTopDiameter / (4 * lensHeight)
                     Sphere(diameter: diameter)
                         .aligned(at: .minZ)
                         .within(z: 0..<lensHeight)
@@ -73,23 +71,20 @@ public struct CountersunkBoltHeadShape: BoltHeadShape {
 }
 
 public extension BoltHeadShape where Self == CountersunkBoltHeadShape {
+    /// A countersunk bolt head with a specified cone angle.
+    ///
+    /// - Parameters:
+    ///   - angle: The countersink cone angle. Defaults to 90°.
+    ///   - topDiameter: The diameter at the top of the cone.
+    ///   - boltDiameter: The bolt's major diameter.
     static func countersunk(
         angle: Angle = 90°,
         topDiameter: Double,
         boltDiameter: Double
     ) -> CountersunkBoltHeadShape {
-        countersunk(countersink: .init(angle: angle, topDiameter: topDiameter), boltDiameter: boltDiameter)
-    }
-
-    static func countersunk(
-        countersink: Countersink,
-        boltDiameter: Double
-    ) -> CountersunkBoltHeadShape {
-        .init(countersink: countersink, boltDiameter: boltDiameter)
-    }
-
-    static func standardCountersunk(topDiameter: Double, boltDiameter: Double) -> CountersunkBoltHeadShape {
-        .init(countersink: .init(angle: 90°, topDiameter: topDiameter), boltDiameter: boltDiameter)
+        .init(
+            countersink: Countersink(angle: angle, topDiameter: topDiameter),
+            boltDiameter: boltDiameter
+        )
     }
 }
-

Sources/Helical/Bolt/Parts/Heads/CountersunkBoltHeadShape.swift

@@ -1,4 +1,3 @@
-import Foundation
 import Cadova
 
 /// A cylindrical bolt head, such as those used for socket head cap screws or button head screws.
@@ -13,11 +12,16 @@ public struct CylindricalBoltHeadShape: BoltHeadShape {
 
     /// Creates a cylindrical head with optional edge profiles.
     ///
+    /// The "top" and "bottom" edges refer to the physical bolt orientation: the top
+    /// is the visible face of the head, and the bottom is where it meets the shank.
+    /// Internally, the head is modeled with Z=0 at the top and Z=height at the shank,
+    /// so the edge profile parameters are swapped when passed to extrusion.
+    ///
     /// - Parameters:
     ///   - diameter: The head diameter.
     ///   - height: The head height.
-    ///   - topEdge: Optional edge profile for the top edge.
-    ///   - bottomEdge: Optional edge profile for the bottom edge.
+    ///   - topEdge: Optional edge profile for the top (visible) edge of the head.
+    ///   - bottomEdge: Optional edge profile for the bottom (shank-side) edge of the head.
     public init(diameter: Double, height: Double, topEdge: EdgeProfile? = nil, bottomEdge: EdgeProfile? = nil) {
         self.diameter = diameter
         self.height = height
@@ -43,6 +47,7 @@ public struct CylindricalBoltHeadShape: BoltHeadShape {
     public var body: any Geometry3D {
         @Environment(\.tolerance) var tolerance
 
+        // topEdge/bottomEdge are swapped because Z=0 is the head top, Z=height is the shank side
         Circle(diameter: diameter - tolerance)
             .extruded(height: height, topEdge: bottomEdge, bottomEdge: topEdge)
             .intersecting {
@@ -59,7 +64,14 @@ public struct CylindricalBoltHeadShape: BoltHeadShape {
 }
 
 public extension BoltHeadShape where Self == CylindricalBoltHeadShape {
-    static func cylindrical(
+    /// A cylindrical bolt head with optional edge profiles.
+    ///
+    /// - Parameters:
+    ///   - diameter: The head diameter.
+    ///   - height: The head height.
+    ///   - topEdge: Optional edge profile for the top (visible) edge of the head.
+    ///   - bottomEdge: Optional edge profile for the bottom (shank-side) edge of the head.
+    static func cylinder(
         diameter: Double,
         height: Double,
         topEdge: EdgeProfile? = nil,

Sources/Helical/Bolt/Parts/Heads/CylindricalBoltHeadShape.swift

@@ -1,4 +1,3 @@
-import Foundation
 import Cadova
 
 /// A polygonal bolt head, such as a hex head or square head.
@@ -59,3 +58,26 @@ public struct PolygonalBoltHeadShape: BoltHeadShape {
         PolygonalHeadRecess(sideCount: sideCount, widthAcrossFlats: widthAcrossFlats, height: height)
     }
 }
+
+public extension BoltHeadShape where Self == PolygonalBoltHeadShape {
+    /// A polygonal bolt head with chamfered corners.
+    ///
+    /// - Parameters:
+    ///   - sideCount: Number of sides (6 for hex, 4 for square, etc.).
+    ///   - widthAcrossFlats: Distance between opposite flat faces.
+    ///   - height: The head height.
+    ///   - chamferAngle: Angle of the corner chamfer.
+    static func polygon(sideCount: Int, widthAcrossFlats: Double, height: Double, chamferAngle: Angle = 0°) -> Self {
+        .init(sideCount: sideCount, widthAcrossFlats: widthAcrossFlats, height: height, chamferAngle: chamferAngle)
+    }
+
+    /// A hex bolt head with chamfered corners.
+    ///
+    /// - Parameters:
+    ///   - widthAcrossFlats: Distance between opposite flat faces.
+    ///   - height: The head height.
+    ///   - chamferAngle: Angle of the corner chamfer.
+    static func hex(widthAcrossFlats: Double, height: Double, chamferAngle: Angle = 0°) -> Self {
+        .init(sideCount: 6, widthAcrossFlats: widthAcrossFlats, height: height, chamferAngle: chamferAngle)
+    }
+}