@code3d/screws 0.0.1-alpha.4 → 0.0.1-alpha.7

package/src/library/iso-4762.ts

@@ -1,136 +1,71 @@
+import {cylinder, frustum, union} from '@code3d/core';
 import {
-  cylinder,
-  cut,
-  frustum,
-  regularPrism,
-  union,
-  type CanonicalElements,
-  type Bound,
-  type LineAnchor,
-  type SolidModel,
-} from '@code3d/core';
-import {helicalThread} from './thread.js';
-
-export type ClearanceFit = 'close' | 'normal' | 'loose';
-
-export type Specification = Readonly<{
-  designation: string;
-  nominalDiameter: number;
-  pitch: number;
-  headDiameter: number;
-  headHeight: number;
-  hexSocketWidth: number;
-  hexSocketDepth: number;
-  underHeadRadius: number;
-  clearance: Readonly<Record<ClearanceFit, number>>;
-  counterboreDiameter: number;
-}>;
+  metric,
+  headedScrew,
+  validateHead,
+  hexSocket,
+  clearanceHole as buildClearanceHole,
+  type MetricSize,
+  type HeadSpecification,
+  type Screw,
+  type ClearanceHole,
+  type CounterboredHole,
+  type ClearanceHoleOptions,
+  type CounterboreOptions,
+} from './common.js';
+export type {
+  ClearanceFit,
+  ClearanceHoleOptions,
+  CounterboreOptions,
+  Screw,
+  ClearanceHole,
+  CounterboredHole,
+  ScrewElements as SocketCapScrewElements,
+  HoleElements as SocketCapHoleElements,
+  CounterboredHoleElements as CounterboredSocketCapHoleElements,
+} from './common.js';
+
+export type Specification = HeadSpecification &
+  Readonly<{
+    hexSocketWidth: number;
+    hexSocketDepth: number;
+    counterboreDiameter: number;
+  }>;
 
 // ISO 4762 coarse-thread socket-head cap screws; millimetres.
 // Clearance series follow ISO 273. Counterbores follow DIN 974-1 normal series.
+function specification(
+  size: MetricSize,
+  headDiameter: number,
+  headHeight: number,
+  hexSocketWidth: number,
+  hexSocketDepth: number,
+  underHeadRadius: number,
+  counterboreDiameter: number,
+): Specification {
+  return {
+    ...metric(size),
+    headDiameter,
+    headHeight,
+    hexSocketWidth,
+    hexSocketDepth,
+    underHeadRadius,
+    counterboreDiameter,
+  };
+}
 export const specifications = {
-  M3: {
-    designation: 'M3',
-    nominalDiameter: 3,
-    pitch: 0.5,
-    headDiameter: 5.5,
-    headHeight: 3,
-    hexSocketWidth: 2.5,
-    hexSocketDepth: 1.3,
-    underHeadRadius: 0.1,
-    clearance: {close: 3.2, normal: 3.4, loose: 3.6},
-    counterboreDiameter: 6,
-  },
-  M4: {
-    designation: 'M4',
-    nominalDiameter: 4,
-    pitch: 0.7,
-    headDiameter: 7,
-    headHeight: 4,
-    hexSocketWidth: 3,
-    hexSocketDepth: 2,
-    underHeadRadius: 0.2,
-    clearance: {close: 4.3, normal: 4.5, loose: 4.8},
-    counterboreDiameter: 8,
-  },
-  M5: {
-    designation: 'M5',
-    nominalDiameter: 5,
-    pitch: 0.8,
-    headDiameter: 8.5,
-    headHeight: 5,
-    hexSocketWidth: 4,
-    hexSocketDepth: 2.5,
-    underHeadRadius: 0.2,
-    clearance: {close: 5.3, normal: 5.5, loose: 5.8},
-    counterboreDiameter: 10,
-  },
-  M6: {
-    designation: 'M6',
-    nominalDiameter: 6,
-    pitch: 1,
-    headDiameter: 10,
-    headHeight: 6,
-    hexSocketWidth: 5,
-    hexSocketDepth: 3,
-    underHeadRadius: 0.25,
-    clearance: {close: 6.4, normal: 6.6, loose: 7},
-    counterboreDiameter: 11,
-  },
-  M8: {
-    designation: 'M8',
-    nominalDiameter: 8,
-    pitch: 1.25,
-    headDiameter: 13,
-    headHeight: 8,
-    hexSocketWidth: 6,
-    hexSocketDepth: 4,
-    underHeadRadius: 0.4,
-    clearance: {close: 8.4, normal: 9, loose: 10},
-    counterboreDiameter: 15,
-  },
-  M10: {
-    designation: 'M10',
-    nominalDiameter: 10,
-    pitch: 1.5,
-    headDiameter: 16,
-    headHeight: 10,
-    hexSocketWidth: 8,
-    hexSocketDepth: 5,
-    underHeadRadius: 0.4,
-    clearance: {close: 10.5, normal: 11, loose: 12},
-    counterboreDiameter: 18,
-  },
-  M12: {
-    designation: 'M12',
-    nominalDiameter: 12,
-    pitch: 1.75,
-    headDiameter: 18,
-    headHeight: 12,
-    hexSocketWidth: 10,
-    hexSocketDepth: 6,
-    underHeadRadius: 0.6,
-    clearance: {close: 13, normal: 13.5, loose: 14.5},
-    counterboreDiameter: 20,
-  },
-} as const satisfies Readonly<Record<string, Specification>>;
+  M3: specification('M3', 5.5, 3, 2.5, 1.3, 0.1, 6),
+  M4: specification('M4', 7, 4, 3, 2, 0.2, 8),
+  M5: specification('M5', 8.5, 5, 4, 2.5, 0.2, 10),
+  M6: specification('M6', 10, 6, 5, 3, 0.25, 11),
+  M8: specification('M8', 13, 8, 6, 4, 0.4, 15),
+  M10: specification('M10', 16, 10, 8, 5, 0.4, 18),
+  M12: specification('M12', 18, 12, 10, 6, 0.6, 20),
+} as const;
 
 export type Size = keyof typeof specifications;
 export type ScrewInput = Size | Specification;
 
-export type CounterboreOptions = Readonly<{
-  diameter?: number;
-  depth?: number;
-  axialClearance?: number;
-}>;
-
-export type ClearanceHoleOptions = Readonly<{
-  depth: number;
-  fit?: ClearanceFit;
-  diameter?: number;
-  counterbore?: boolean | CounterboreOptions;
-}>;
-
 export type PlainClearanceHoleOptions = ClearanceHoleOptions &
   Readonly<{
     counterbore: false;
@@ -144,32 +79,6 @@ export type CounterboredHoleOptions = Omit<
     counterbore?: true | CounterboreOptions;
   }>;
 
-export type SocketCapScrewElements = CanonicalElements &
-  Readonly<{
-    headTop: Bound;
-    headBottom: Bound;
-    shankTop: Bound;
-    shankBottom: Bound;
-    shankAxis: LineAnchor;
-  }>;
-
-export type SocketCapHoleElements = CanonicalElements &
-  Readonly<{
-    shaftTop: Bound;
-    shaftBottom: Bound;
-    shaftAxis: LineAnchor;
-  }>;
-
-export type CounterboredSocketCapHoleElements = SocketCapHoleElements &
-  Readonly<{
-    counterboreTop: Bound;
-    counterboreBottom: Bound;
-  }>;
-
-export type Screw = SolidModel<SocketCapScrewElements>;
-export type ClearanceHole = SolidModel<SocketCapHoleElements>;
-export type CounterboredHole = SolidModel<CounterboredSocketCapHoleElements>;
-
 /**
  * @code3d.arguments ['M6', 18]
  * @code3d.arguments ['M8', 30]
@@ -177,77 +86,21 @@ export type CounterboredHole = SolidModel<CounterboredSocketCapHoleElements>;
  */
 export function screw(input: ScrewInput, length: number): Screw {
   const spec = resolveSpecification(input);
-  validateSpec(spec);
-  if (!Number.isFinite(length) || length <= spec.pitch + spec.underHeadRadius) {
-    throw new Error(
-      'Screw length must leave room for at least one full thread pitch.',
-    );
-  }
-
+  validateHead(spec);
   const headChamfer = Math.min(spec.pitch / 2, spec.headHeight * 0.12);
-  const headBarrel = cylinder(
-    spec.headDiameter / 2,
-    spec.headHeight - headChamfer,
-  );
-  const headTop = frustum(
+  const barrel = cylinder(spec.headDiameter / 2, spec.headHeight - headChamfer);
+  const crown = frustum(
     spec.headDiameter / 2,
     spec.headDiameter / 2 - headChamfer,
     headChamfer,
-  ).relate(top => top.on(headBarrel.up));
-  const headBlank = union([headBarrel, headTop]);
-
-  const socketToolY = spec.hexSocketDepth + 0.2;
-  const socketTool = regularPrism(
-    spec.hexSocketWidth / Math.sqrt(3),
-    socketToolY,
-    6,
-    30,
-  ).relate(tool =>
-    tool.center.on(headBlank.up).offset(0, -spec.hexSocketDepth / 2 + 0.1, 0),
+  ).relate(part => part.on(barrel.up));
+  const head = hexSocket(
+    union([barrel, crown]),
+    spec.hexSocketWidth,
+    spec.hexSocketDepth,
+    spec.headHeight,
   );
-  const head = cut(headBlank, [socketTool]);
-
-  const transition = frustum(
-    spec.nominalDiameter / 2,
-    spec.nominalDiameter / 2 + spec.underHeadRadius,
-    spec.underHeadRadius,
-  ).relate(part => part.on(head.down));
-  const bodyLength = length - spec.underHeadRadius;
-  const threadedLength = Math.min(bodyLength, threadLength(spec, length));
-  const plainLength = bodyLength - threadedLength;
-  const overlap = Math.min(0.08, spec.pitch / 10);
-  const parts = [head, transition];
-  let previous = transition;
-
-  if (plainLength > overlap) {
-    const shank = cylinder(
-      spec.nominalDiameter / 2,
-      plainLength + overlap,
-    ).relate(part => part.on(previous.down).offset(0, -overlap, 0));
-    parts.push(shank);
-    previous = shank;
-  }
-
-  const fundamentalHeight = (Math.sqrt(3) / 2) * spec.pitch;
-  const minorDiameter =
-    spec.nominalDiameter - 2 * ((5 / 8) * fundamentalHeight);
-  const thread = helicalThread({
-    pitch: spec.pitch,
-    y: threadedLength + overlap,
-    majorDiameter: spec.nominalDiameter,
-    minorDiameter,
-    rootWidth: (3 / 4) * spec.pitch,
-    crestWidth: (1 / 8) * spec.pitch,
-  }).relate(part => part.on(previous.down).offset(0, -overlap, 0));
-  parts.push(thread);
-
-  return union(parts).expose({
-    headTop: head.up,
-    headBottom: head.down,
-    shankTop: transition.up,
-    shankBottom: thread.down,
-    shankAxis: thread.axis,
-  });
+  return headedScrew(head, spec, length, threadLength(spec, length));
 }
 
 /**
@@ -275,63 +128,7 @@ export function clearanceHole(
   input: ScrewInput,
   optionsOrDepth: ClearanceHoleOptions | number,
 ): ClearanceHole | CounterboredHole {
-  const options: ClearanceHoleOptions =
-    typeof optionsOrDepth === 'number'
-      ? {depth: optionsOrDepth}
-      : optionsOrDepth;
-  const spec = resolveSpecification(input);
-  validateSpec(spec);
-  if (!Number.isFinite(options.depth) || options.depth <= 0) {
-    throw new Error('Hole depth must be a positive finite number.');
-  }
-  const fit = options.fit ?? 'normal';
-  const diameter = options.diameter ?? spec.clearance[fit];
-  if (!Number.isFinite(diameter) || diameter <= spec.nominalDiameter) {
-    throw new Error(
-      'Clearance-hole diameter must exceed the nominal screw diameter.',
-    );
-  }
-  const shaft = cylinder(diameter / 2, options.depth);
-  const counterboreOption = options.counterbore ?? true;
-  if (counterboreOption === false) {
-    return shaft.expose({
-      shaftTop: shaft.up,
-      shaftBottom: shaft.down,
-      shaftAxis: shaft.axis,
-    });
-  }
-
-  const counterbore = counterboreOption === true ? {} : counterboreOption;
-  const axialClearance = counterbore.axialClearance ?? 0.5;
-  const counterboreDepth =
-    counterbore.depth ?? spec.headHeight + axialClearance;
-  const counterboreDiameter = counterbore.diameter ?? spec.counterboreDiameter;
-  if (
-    !Number.isFinite(counterboreDepth) ||
-    counterboreDepth <= 0 ||
-    counterboreDepth > options.depth
-  ) {
-    throw new Error('Counterbore depth must be within the total hole depth.');
-  }
-  if (
-    !Number.isFinite(counterboreDiameter) ||
-    counterboreDiameter < spec.headDiameter
-  ) {
-    throw new Error('Counterbore diameter must accommodate the screw head.');
-  }
-  const recess = cylinder(
-    counterboreDiameter / 2,
-    counterboreDepth + 0.2,
-  ).relate(tool =>
-    tool.center.on(shaft.up).offset(0, -counterboreDepth / 2 + 0.1, 0),
-  );
-  return union([shaft, recess]).expose({
-    shaftTop: shaft.up,
-    shaftBottom: shaft.down,
-    shaftAxis: shaft.axis,
-    counterboreTop: recess.up,
-    counterboreBottom: recess.down,
-  });
+  return buildClearanceHole(resolveSpecification(input), optionsOrDepth, true);
 }
 
 export function resolveSpecification(input: ScrewInput): Specification {
@@ -343,30 +140,3 @@ export function threadLength(spec: Specification, length: number): number {
   if (length <= 200) return 2 * spec.nominalDiameter + 18;
   return 2 * spec.nominalDiameter + 31;
 }
-
-function validateSpec(spec: Specification): void {
-  const values = [
-    spec.nominalDiameter,
-    spec.pitch,
-    spec.headDiameter,
-    spec.headHeight,
-    spec.hexSocketWidth,
-    spec.hexSocketDepth,
-    spec.underHeadRadius,
-    spec.clearance.close,
-    spec.clearance.normal,
-    spec.clearance.loose,
-    spec.counterboreDiameter,
-  ];
-  if (values.some(value => !Number.isFinite(value) || value <= 0)) {
-    throw new Error(
-      'Fastener specifications must contain positive finite dimensions.',
-    );
-  }
-  if (spec.headDiameter <= spec.nominalDiameter) {
-    throw new Error('Head diameter must exceed the nominal thread diameter.');
-  }
-  if (spec.hexSocketDepth >= spec.headHeight) {
-    throw new Error('Hex socket depth must be smaller than the head height.');
-  }
-}

package/src/library/iso-7045.ts

@@ -0,0 +1,134 @@
+import {
+  metric,
+  validateHead,
+  headedScrew,
+  panHead,
+  crossSocket,
+  clearanceHole as buildClearanceHole,
+  type CrossRecessType,
+  type CrossRecess,
+  type HeadSpecification,
+  type MetricSize,
+  type Screw,
+  type ClearanceHole,
+  type CounterboredHole,
+  type ClearanceHoleOptions,
+  type PlainHoleOptions,
+  type CounterboredHoleOptions,
+} from './common.js';
+export type {
+  CrossRecessType,
+  CrossRecess,
+  ClearanceFit,
+  Screw,
+  ScrewElements,
+  ClearanceHole,
+  HoleElements,
+  CounterboredHole,
+  CounterboredHoleElements,
+  ClearanceHoleOptions,
+  PlainHoleOptions,
+  CounterboredHoleOptions,
+  CounterboreOptions,
+} from './common.js';
+
+export type Specification = HeadSpecification &
+  Readonly<{
+    headCurvatureRadius: number;
+    recesses: Readonly<Record<CrossRecessType, CrossRecess>>;
+  }>;
+export type ScrewOptions = Readonly<{recess?: CrossRecessType}>;
+// ISO 7045:2011 (M3 and M5 heads differ from DIN 7985). H/Z driving envelopes.
+// https://www.finesz.com/ISO7045.php
+function specification(
+  size: MetricSize,
+  headDiameter: number,
+  headHeight: number,
+  headCurvatureRadius: number,
+  underHeadRadius: number,
+  number: number,
+  width: number,
+  hDiameter: number,
+  hDepth: number,
+  zDiameter: number,
+  zDepth: number,
+): Specification {
+  return {
+    ...metric(size),
+    headDiameter,
+    headHeight,
+    headCurvatureRadius,
+    underHeadRadius,
+    recesses: {
+      H: {number, width, diameter: hDiameter, depth: hDepth},
+      Z: {number, width, diameter: zDiameter, depth: zDepth},
+    },
+  };
+}
+export const specifications = {
+  M3: specification('M3', 5.6, 2.4, 5, 0.1, 1, 0.97, 3, 1.4, 2.8, 1.5),
+  M4: specification('M4', 8, 3.1, 6.5, 0.2, 2, 1.47, 4.4, 1.9, 4.3, 1.89),
+  M5: specification('M5', 9.5, 3.7, 8, 0.2, 2, 1.47, 4.9, 2.4, 4.7, 2.29),
+  M6: specification('M6', 12, 4.6, 10, 0.25, 3, 2.41, 6.9, 3.1, 6.7, 3.03),
+  M8: specification('M8', 16, 6, 13, 0.4, 4, 3.48, 9, 4, 8.8, 4.05),
+  M10: specification('M10', 20, 7.5, 16, 0.4, 4, 3.48, 10.1, 5.2, 9.9, 5.24),
+} as const;
+export type Size = keyof typeof specifications;
+export type ScrewInput = Size | Specification;
+export function resolveSpecification(input: ScrewInput): Specification {
+  return typeof input === 'string' ? specifications[input] : input;
+}
+/** ISO minimum b; shorter screws are threaded to the head transition. */
+export function threadLength(spec: Specification, _length: number): number {
+  return spec.nominalDiameter <= 3 ? 25 : 38;
+}
+/**
+ * @code3d.arguments ['M6', 18]
+ * @code3d.param length {kind: 'length'}
+ */
+export function screw(
+  input: ScrewInput,
+  length: number,
+  options: ScrewOptions = {},
+): Screw {
+  const spec = resolveSpecification(input);
+  validateHead(spec);
+  const type = options.recess ?? 'H';
+  if (type !== 'H' && type !== 'Z')
+    throw new Error('Cross recess type must be H or Z.');
+  const recess = spec.recesses[type];
+  if (recess.depth >= spec.headHeight || recess.width >= recess.diameter)
+    throw new Error('Cross recess must fit inside the head.');
+  const blank = panHead(
+    spec.headDiameter,
+    spec.headHeight,
+    recess.diameter * 1.05,
+    spec.headCurvatureRadius,
+  );
+  return headedScrew(
+    crossSocket(blank, recess, type),
+    spec,
+    length,
+    threadLength(spec, length),
+  );
+}
+/** @code3d.arguments ['M6', 10] */
+export function clearanceHole(input: ScrewInput, depth: number): ClearanceHole;
+export function clearanceHole(
+  input: ScrewInput,
+  options: PlainHoleOptions,
+): ClearanceHole;
+export function clearanceHole(
+  input: ScrewInput,
+  options: CounterboredHoleOptions,
+): CounterboredHole;
+export function clearanceHole(
+  input: ScrewInput,
+  options: ClearanceHoleOptions,
+): ClearanceHole | CounterboredHole;
+export function clearanceHole(
+  input: ScrewInput,
+  options: number | ClearanceHoleOptions,
+): ClearanceHole | CounterboredHole {
+  return buildClearanceHole(resolveSpecification(input), options);
+}