jscad-electronics 0.0.185 → 0.0.187

package/README.md

@@ -50,6 +50,35 @@ This example creates a 3D model of an SOT-23-3P component with extruded pads.
 
 ## Available Components
 
+### Cable meshes
+
+`jscad-electronics/cables` creates indexed, colored triangle meshes for USB-C,
+JST SH/PH, and NEMA 5-15P to IEC C13 cables. Pass a physical definition from
+cableprinter and an already resolved path in millimeters (+Z up):
+
+```ts
+import { createCableMeshes } from "jscad-electronics/cables"
+import { parseCableString } from "@tscircuit/cableprinter"
+
+const meshes = createCableMeshes({
+  definition: parseCableString("jst_ph_pins4"),
+  path: resolvedPath,
+})
+```
+
+The first and last path samples are cable exit centers. Connector poses follow
+the endpoint tangents; bundle wires follow parallel-transported frames. Each
+mesh provides `positions`, `indices`, `color`, `name`, and `smooth`. Connector
+details include hollow shells/sockets, contacts, and strain reliefs. Physical
+definitions, route generation and sagging remain separate from this renderer.
+The cables entrypoint does not import React or a viewer.
+
+Cable visual regression tests live in `tests/snapshots/cable-meshes.test.ts`.
+They render local meshes with poppygl: all four cable types and mating faces,
+JST SH/PH pin-count comparisons, and spatial paths viewed from both sides.
+Annotations use `@tscircuit/alphabet`. Regenerate these six PNGs explicitly with
+`BUN_UPDATE_SNAPSHOTS=1 bun test tests/snapshots/cable-meshes.test.ts`.
+
 jscad-electronics includes models for various components, including:
 
 - Resistors (0402, 0603, 0805)

package/dist/cables.d.ts

@@ -0,0 +1,52 @@
+type CablePoint = [number, number, number];
+type CableColor = [number, number, number, number];
+type ConnectorBody = {
+    bodyWidth: number;
+    bodyHeight: number;
+    bodyDepth: number;
+};
+type CableConnectorSpec = ConnectorBody & ({
+    kind: "usb_c_plug";
+    shellWidth: number;
+    shellHeight: number;
+    shellDepth: number;
+} | {
+    kind: "jst_sh_housing" | "jst_ph_housing";
+    pinCount: number;
+    pitch: number;
+} | {
+    kind: "nema_5_15p" | "iec_c13";
+});
+/** Structural subset of a cableprinter definition; no runtime spec dependency. */
+type CableGeometryDefinition = {
+    connectorA: CableConnectorSpec;
+    connectorB: CableConnectorSpec;
+    crossSection: {
+        kind: "round_jacket";
+        diameter: number;
+        color: string;
+    } | {
+        kind: "wire_bundle";
+        wirePitch: number;
+        wires: {
+            diameter: number;
+            color: string;
+        }[];
+    };
+};
+type CableMesh = {
+    name: string;
+    positions: number[];
+    indices: number[];
+    color: CableColor;
+    smooth: boolean;
+};
+
+/** Mesh generation only. Path samples are already resolved in world millimeters, +Z up. */
+declare function createCableMeshes({ definition, path, radialSegments, }: {
+    definition: CableGeometryDefinition;
+    path: CablePoint[];
+    radialSegments?: number;
+}): CableMesh[];
+
+export { type CableColor, type CableConnectorSpec, type CableGeometryDefinition, type CableMesh, type CablePoint, createCableMeshes };

package/dist/cables.js

@@ -0,0 +1,582 @@
+// lib/cables/connector-meshes.ts
+import jscad2 from "@jscad/modeling";
+
+// lib/cables/geometry-to-mesh.ts
+import jscad from "@jscad/modeling";
+
+// lib/cables/path-frames.ts
+var add = (a, b) => [
+  a[0] + b[0],
+  a[1] + b[1],
+  a[2] + b[2]
+];
+var subtract = (a, b) => [
+  a[0] - b[0],
+  a[1] - b[1],
+  a[2] - b[2]
+];
+var scale = (point, factor) => [
+  point[0] * factor,
+  point[1] * factor,
+  point[2] * factor
+];
+var dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+var cross = (a, b) => [
+  a[1] * b[2] - a[2] * b[1],
+  a[2] * b[0] - a[0] * b[2],
+  a[0] * b[1] - a[1] * b[0]
+];
+function normalize(point) {
+  const length = Math.hypot(...point);
+  if (length < 1e-10)
+    throw new Error(
+      "Cable path must not contain coincident points or a reversing tangent"
+    );
+  return scale(point, 1 / length);
+}
+function createCablePathFrames(path) {
+  if (path.length < 2 || path.some((point) => point.length !== 3 || !point.every(Number.isFinite))) {
+    throw new Error("Cable path needs at least two finite 3D points");
+  }
+  const segments = path.slice(1).map((point, index) => normalize(subtract(point, path[index])));
+  const tangents = path.map(
+    (_, index) => index === 0 ? segments[0] : index === path.length - 1 ? segments.at(-1) : normalize(add(segments[index - 1], segments[index]))
+  );
+  const initialUp = Math.abs(tangents[0][2]) > 0.95 ? [0, 1, 0] : [0, 0, 1];
+  let normal = normalize(cross(initialUp, tangents[0]));
+  return tangents.map((tangent, index) => {
+    if (index > 0) {
+      const previousTangent = tangents[index - 1];
+      const axis = cross(previousTangent, tangent);
+      const sine = Math.hypot(...axis);
+      const cosine = Math.max(-1, Math.min(1, dot(previousTangent, tangent)));
+      if (sine > 1e-10) {
+        const unitAxis = scale(axis, 1 / sine);
+        normal = normalize(
+          add(
+            add(scale(normal, cosine), scale(cross(unitAxis, normal), sine)),
+            scale(unitAxis, dot(unitAxis, normal) * (1 - cosine))
+          )
+        );
+      }
+    }
+    return {
+      point: path[index],
+      tangent,
+      normal,
+      binormal: normalize(cross(tangent, normal))
+    };
+  });
+}
+
+// lib/cables/geometry-to-mesh.ts
+function geometryToCableMesh({
+  geometry,
+  color,
+  name
+}) {
+  const triangles = jscad.geometries.geom3.toPolygons(geometry);
+  const positions = [];
+  const indices = [];
+  const vertices = /* @__PURE__ */ new Map();
+  for (const triangle of triangles) {
+    const polygonIndices = [];
+    for (const point of triangle.vertices) {
+      const key = point.map((coordinate) => coordinate.toFixed(8)).join(",");
+      let index = vertices.get(key);
+      if (index === void 0) {
+        index = positions.length / 3;
+        positions.push(...point);
+        vertices.set(key, index);
+      }
+      polygonIndices.push(index);
+    }
+    for (let side = 1; side < polygonIndices.length - 1; side++) {
+      indices.push(
+        polygonIndices[0],
+        polygonIndices[side],
+        polygonIndices[side + 1]
+      );
+    }
+  }
+  return { name, positions, indices, color, smooth: false };
+}
+function placeConnectorMesh({
+  mesh,
+  frame,
+  wireExitDepth,
+  isEnd
+}) {
+  const tangent = scale(frame.tangent, isEnd ? -1 : 1);
+  const binormal = isEnd ? scale(frame.binormal, -1) : frame.binormal;
+  const origin = add(frame.point, scale(tangent, -wireExitDepth));
+  const positions = [];
+  for (let index = 0; index < mesh.positions.length; index += 3) {
+    positions.push(
+      ...add(
+        origin,
+        add(
+          add(
+            scale(frame.normal, mesh.positions[index]),
+            scale(binormal, mesh.positions[index + 1])
+          ),
+          scale(tangent, mesh.positions[index + 2])
+        )
+      )
+    );
+  }
+  return { ...mesh, positions };
+}
+
+// lib/cables/connector-meshes.ts
+var { cuboid, roundedCuboid, cylinder, roundedRectangle, polygon, sphere } = jscad2.primitives;
+var { extrudeLinear } = jscad2.extrusions;
+var { translate, rotateY } = jscad2.transforms;
+var { subtract: subtract2, union } = jscad2.booleans;
+var plastic = [0.055, 0.07, 0.09, 1];
+var housing = [0.86, 0.84, 0.75, 1];
+var metal = [0.6, 0.64, 0.7, 1];
+var brass = [0.66, 0.46, 0.18, 1];
+function connectorWireExitDepth(connector) {
+  if (connector.kind === "usb_c_plug")
+    return connector.shellDepth + connector.bodyDepth;
+  if (connector.kind === "nema_5_15p") return 19.05 + connector.bodyDepth;
+  return connector.bodyDepth;
+}
+function createJstMeshes(connector) {
+  const {
+    bodyWidth: width,
+    bodyHeight: height,
+    bodyDepth: depth,
+    pinCount,
+    pitch
+  } = connector;
+  const opening = pitch === 1 ? 0.55 : 1.05;
+  const holes = Array.from({ length: pinCount }, (_, index) => {
+    const x = (index - (pinCount - 1) / 2) * pitch;
+    return cuboid({
+      size: [opening, opening * 1.35, depth - 0.6],
+      center: [x, 0, (depth - 0.6) / 2 - 0.02]
+    });
+  });
+  const backHoles = Array.from(
+    { length: pinCount },
+    (_, index) => cylinder({
+      radius: pitch * 0.34,
+      height: 1.3,
+      segments: 16,
+      center: [(index - (pinCount - 1) / 2) * pitch, 0, depth - 0.5]
+    })
+  );
+  const latchCut = cuboid({
+    size: [width * 0.45, 0.5, depth * 0.5],
+    center: [0, height / 2, depth * 0.65]
+  });
+  const body = subtract2(
+    roundedCuboid({
+      size: [width, height, depth],
+      center: [0, 0, depth / 2],
+      roundRadius: 0.1,
+      segments: 8
+    }),
+    ...holes,
+    ...backHoles,
+    latchCut,
+    ...Array.from(
+      { length: pinCount },
+      (_, index) => cuboid({
+        size: [opening * 0.8, height * 0.7, depth * 0.24],
+        center: [(index - (pinCount - 1) / 2) * pitch, height / 2, depth * 0.7]
+      })
+    )
+  );
+  const contacts = Array.from({ length: pinCount }, (_, index) => {
+    const x = (index - (pinCount - 1) / 2) * pitch;
+    return geometryToCableMesh({
+      name: `contact-${index + 1}`,
+      color: metal,
+      geometry: subtract2(
+        cuboid({
+          size: [opening * 0.92, opening * 1.25, depth * 0.65],
+          center: [x, 0, depth * 0.45]
+        }),
+        cuboid({
+          size: [
+            opening * 0.92 - 0.12,
+            opening * 1.25 - 0.12,
+            depth * 0.65 + 0.2
+          ],
+          center: [x, 0, depth * 0.45]
+        })
+      )
+    });
+  });
+  return [
+    geometryToCableMesh({ geometry: body, color: housing, name: "housing" }),
+    ...contacts
+  ];
+}
+function createUsbMeshes(connector) {
+  const {
+    shellWidth,
+    shellHeight,
+    shellDepth,
+    bodyWidth,
+    bodyHeight,
+    bodyDepth
+  } = connector;
+  const shell = subtract2(
+    extrudeLinear(
+      { height: shellDepth },
+      roundedRectangle({
+        size: [shellWidth, shellHeight],
+        roundRadius: shellHeight / 2 - 0.02,
+        segments: 32
+      })
+    ),
+    translate(
+      [0, 0, -0.1],
+      extrudeLinear(
+        { height: shellDepth + 0.2 },
+        roundedRectangle({
+          size: [shellWidth - 0.4, shellHeight - 0.4],
+          roundRadius: (shellHeight - 0.4) / 2 - 0.02,
+          segments: 32
+        })
+      )
+    )
+  );
+  const liner = subtract2(
+    extrudeLinear(
+      { height: shellDepth },
+      roundedRectangle({
+        size: [shellWidth - 0.41, shellHeight - 0.41],
+        roundRadius: 0.85,
+        segments: 32
+      })
+    ),
+    translate(
+      [0, 0, -0.1],
+      extrudeLinear(
+        { height: shellDepth - 0.3 },
+        roundedRectangle({
+          size: [shellWidth - 0.8, shellHeight - 0.8],
+          roundRadius: 0.65,
+          segments: 32
+        })
+      )
+    )
+  );
+  const body = roundedCuboid({
+    size: [bodyWidth, bodyHeight, bodyDepth],
+    center: [0, 0, shellDepth + bodyDepth / 2],
+    roundRadius: Math.min(1.3, bodyHeight / 4),
+    segments: 16
+  });
+  const contacts = Array.from(
+    { length: 24 },
+    (_, index) => cuboid({
+      size: [0.22, 0.08, 3.5],
+      center: [(index % 12 - 5.5) * 0.5, index < 12 ? 0.77 : -0.77, 2.6]
+    })
+  );
+  return [
+    geometryToCableMesh({ geometry: body, color: plastic, name: "overmold" }),
+    geometryToCableMesh({ geometry: shell, color: metal, name: "shell" }),
+    geometryToCableMesh({
+      geometry: liner,
+      color: [0.025, 0.026, 0.03, 1],
+      name: "liner"
+    }),
+    ...contacts.map(
+      (geometry, index) => geometryToCableMesh({
+        geometry,
+        color: brass,
+        name: `contact-${index + 1}`
+      })
+    )
+  ];
+}
+function createMainsMeshes(connector) {
+  const { bodyWidth, bodyHeight, bodyDepth, kind } = connector;
+  const faceDepth = kind === "nema_5_15p" ? 19.05 : 0;
+  let body = roundedCuboid({
+    size: [bodyWidth, bodyHeight, bodyDepth],
+    center: [0, 0, faceDepth + bodyDepth / 2],
+    roundRadius: 2,
+    segments: 16
+  });
+  if (kind === "nema_5_15p") {
+    const blades = [-6.35, 6.35].map((x) => {
+      const blade = cuboid({
+        size: [1.524, 6.35, 15.875],
+        center: [x, 2.7, 19.05 - 15.875 / 2]
+      });
+      const hole = translate(
+        [x, 2.7, 7.3],
+        rotateY(
+          Math.PI / 2,
+          cylinder({ radius: 1.1, height: 3, segments: 20 })
+        )
+      );
+      return subtract2(blade, hole);
+    });
+    const ground = union(
+      cylinder({
+        radius: 2.38125,
+        height: 19.05 - 2.38125,
+        center: [0, -9.20625, (19.05 + 2.38125) / 2],
+        segments: 32
+      }),
+      sphere({ radius: 2.38125, center: [0, -9.20625, 2.38125], segments: 32 })
+    );
+    return [
+      geometryToCableMesh({
+        geometry: body,
+        color: plastic,
+        name: "plug-body"
+      }),
+      ...blades.map(
+        (geometry, index) => geometryToCableMesh({
+          geometry,
+          color: brass,
+          name: `blade-${index + 1}`
+        })
+      ),
+      geometryToCableMesh({
+        geometry: ground,
+        color: brass,
+        name: "ground-pin"
+      })
+    ];
+  }
+  const recess = translate(
+    [0, 0, -0.1],
+    extrudeLinear(
+      { height: 3.2 },
+      polygon({
+        points: [
+          [-9, -6],
+          [9, -6],
+          [9, 2],
+          [5, 6],
+          [-5, 6],
+          [-9, 2]
+        ]
+      })
+    )
+  );
+  const sockets = [
+    [-4.4, -1.8, 8],
+    [4.4, -1.8, 8],
+    [0, 3.1, 8]
+  ];
+  body = subtract2(
+    body,
+    recess,
+    ...sockets.map((center) => cuboid({ size: [2.3, 3.4, 16.2], center }))
+  );
+  return [
+    geometryToCableMesh({
+      geometry: body,
+      color: plastic,
+      name: "appliance-body"
+    }),
+    ...sockets.map(
+      ([x, y], index) => geometryToCableMesh({
+        geometry: cuboid({ size: [0.15, 2.8, 6], center: [x - 1.05, y, 7.8] }),
+        color: brass,
+        name: `socket-contact-${index + 1}`
+      })
+    )
+  ];
+}
+function createConnectorMeshes({
+  connector,
+  jacketDiameter
+}) {
+  const meshes = connector.kind === "usb_c_plug" ? createUsbMeshes(connector) : "pinCount" in connector ? createJstMeshes(connector) : createMainsMeshes(connector);
+  if (jacketDiameter !== void 0) {
+    const exit = connectorWireExitDepth(connector);
+    const boot = union(
+      cylinder({
+        radius: jacketDiameter / 2 + 0.15,
+        height: 5,
+        center: [0, 0, exit + 2.5],
+        segments: 32
+      }),
+      ...Array.from(
+        { length: 7 },
+        (_, index) => cylinder({
+          radius: jacketDiameter / 2 + 0.8 - index * 0.06,
+          height: 0.28,
+          center: [0, 0, exit + 0.4 + index * 0.7],
+          segments: 32
+        })
+      )
+    );
+    meshes.push(
+      geometryToCableMesh({
+        geometry: boot,
+        color: plastic,
+        name: "strain-relief"
+      })
+    );
+  }
+  return meshes;
+}
+
+// lib/cables/sweep-round-cable.ts
+function sweepRoundCable({
+  frames,
+  diameter,
+  offset = 0,
+  radialSegments,
+  color,
+  name
+}) {
+  const positions = [];
+  const indices = [];
+  for (const frame of frames) {
+    const center = add(frame.point, scale(frame.normal, offset));
+    for (let side = 0; side < radialSegments; side++) {
+      const angle = side * Math.PI * 2 / radialSegments;
+      positions.push(
+        ...add(
+          center,
+          add(
+            scale(frame.normal, diameter * Math.cos(angle) / 2),
+            scale(frame.binormal, diameter * Math.sin(angle) / 2)
+          )
+        )
+      );
+    }
+  }
+  for (let ring = 0; ring < frames.length - 1; ring++) {
+    for (let side = 0; side < radialSegments; side++) {
+      const a = ring * radialSegments + side;
+      const b = ring * radialSegments + (side + 1) % radialSegments;
+      const c = a + radialSegments;
+      const d = b + radialSegments;
+      indices.push(a, b, c, b, d, c);
+    }
+  }
+  const startCenter = positions.length / 3;
+  positions.push(...add(frames[0].point, scale(frames[0].normal, offset)));
+  const endCenter = positions.length / 3;
+  positions.push(
+    ...add(frames.at(-1).point, scale(frames.at(-1).normal, offset))
+  );
+  const lastRing = (frames.length - 1) * radialSegments;
+  for (let side = 0; side < radialSegments; side++) {
+    const next = (side + 1) % radialSegments;
+    indices.push(
+      startCenter,
+      next,
+      side,
+      endCenter,
+      lastRing + side,
+      lastRing + next
+    );
+  }
+  return { name, positions, indices, color, smooth: true };
+}
+
+// lib/cables/create-cable-meshes.ts
+function parseCableColor(color) {
+  if (!/^#[a-f\d]{6}$/i.test(color))
+    throw new Error("Cable colors must be six-digit hex strings");
+  return [
+    parseInt(color.slice(1, 3), 16) / 255,
+    parseInt(color.slice(3, 5), 16) / 255,
+    parseInt(color.slice(5, 7), 16) / 255,
+    1
+  ];
+}
+function validateCableDefinition(definition) {
+  for (const connector of [definition.connectorA, definition.connectorB]) {
+    const dimensions = [
+      connector.bodyWidth,
+      connector.bodyHeight,
+      connector.bodyDepth
+    ];
+    if (connector.kind === "usb_c_plug")
+      dimensions.push(
+        connector.shellWidth,
+        connector.shellHeight,
+        connector.shellDepth
+      );
+    if (dimensions.some(
+      (dimension) => !Number.isFinite(dimension) || dimension <= 0
+    ))
+      throw new Error("Connector dimensions must be finite and positive");
+    if ("pinCount" in connector && (!Number.isInteger(connector.pinCount) || connector.pinCount < 2 || !Number.isFinite(connector.pitch) || connector.pitch <= 0))
+      throw new Error(
+        "JST connectors need a positive pitch and at least two contacts"
+      );
+  }
+  const crossSection = definition.crossSection;
+  const diameters = crossSection.kind === "round_jacket" ? [crossSection.diameter] : crossSection.wires.map((wire) => wire.diameter);
+  if (diameters.length === 0 || diameters.some((diameter) => !Number.isFinite(diameter) || diameter <= 0))
+    throw new Error("Cable diameters must be finite and positive");
+  if (crossSection.kind === "wire_bundle") {
+    if (!Number.isFinite(crossSection.wirePitch) || crossSection.wires.some((wire) => wire.diameter > crossSection.wirePitch))
+      throw new Error("Insulated bundle wires must not overlap");
+    for (const connector of [definition.connectorA, definition.connectorB]) {
+      if (!("pinCount" in connector) || connector.pinCount !== crossSection.wires.length)
+        throw new Error("Bundle wire count must match connector contact count");
+    }
+  }
+}
+function createCableMeshes({
+  definition,
+  path,
+  radialSegments = 24
+}) {
+  validateCableDefinition(definition);
+  if (!Number.isInteger(radialSegments) || radialSegments < 8 || radialSegments > 128)
+    throw new Error("radialSegments must be an integer from 8 to 128");
+  const frames = createCablePathFrames(path);
+  const crossSection = definition.crossSection;
+  const jacketDiameter = crossSection.kind === "round_jacket" ? crossSection.diameter : void 0;
+  const meshes = crossSection.kind === "round_jacket" ? [
+    sweepRoundCable({
+      frames,
+      diameter: crossSection.diameter,
+      radialSegments,
+      color: parseCableColor(crossSection.color),
+      name: "jacket"
+    })
+  ] : crossSection.wires.map(
+    (wire, index) => sweepRoundCable({
+      frames,
+      diameter: wire.diameter,
+      offset: (index - (crossSection.wires.length - 1) / 2) * crossSection.wirePitch,
+      radialSegments,
+      color: parseCableColor(wire.color),
+      name: `wire-${index + 1}`
+    })
+  );
+  for (const [index, connector] of [
+    definition.connectorA,
+    definition.connectorB
+  ].entries()) {
+    const frame = index === 0 ? frames[0] : frames.at(-1);
+    const parts = createConnectorMeshes({ connector, jacketDiameter });
+    meshes.push(
+      ...parts.map(
+        (mesh) => placeConnectorMesh({
+          mesh: { ...mesh, name: `${index === 0 ? "A" : "B"}-${mesh.name}` },
+          frame,
+          isEnd: index === 1,
+          wireExitDepth: connectorWireExitDepth(connector)
+        })
+      )
+    );
+  }
+  return meshes;
+}
+export {
+  createCableMeshes
+};
+//# sourceMappingURL=cables.js.map