@protoboardai/ext-harness-cad 0.0.0-stage → 0.2.0

package/ops/package.ts

@@ -0,0 +1,108 @@
+/**
+ * Contributions to the Manufacturing Package (@protoboardai/ext-release section
+ * contract) for the cables this provider routes: their preparation in the
+ * unit's work order (cut length against the supplied length, strip length,
+ * gauge, lay, and how each end is terminated and onto what), and routing
+ * checks in the test plan (bend radius, clearance, slack). Values come from
+ * the cable's UHD facts (cut list) and the routed standard output
+ * (out/body.manifest.json).
+ */
+import type { CapabilityBinding, Project } from "@protoboardai/core";
+import type { Block, SectionContext, SectionFn } from "@protoboardai/ext-release";
+import { cutList, perBuild, providerModules, readOutput } from "@protoboardai/ext-release/helpers";
+
+const PROVIDER = "@protoboardai/ext-harness-cad";
+
+interface RouteManifest {
+  length_mm?: number;
+  route_length_mm?: number;
+  length_fit?: { slack_mm?: number; method?: string; worst_clearance_mm?: number };
+  bundle?: { kind?: string; conductors?: number; bundle_od_mm?: number; twist_pitch_mm?: number };
+  bend_radius_mm?: { target?: number; minimum?: number; centreline?: number };
+  clearance_mm?: { min_conductor_surface?: number };
+  ends?: Record<string, { counterpart?: string; termination?: string; link?: string }>;
+}
+
+// manifests write null for a value the router could not measure (callers check with != null)
+const n = (v: number, d = 1) => String(Number(v.toFixed(d)));
+
+/** How an end is finished, by the termination the route records. */
+const TERMINATION: Record<string, string> = {
+  solder: "strip, tin, solder to the pads; keep each joint clear of its neighbours, and fix the lead near the pad (tie or tape) so the joint carries no strain",
+  plug: "plugs in (pre-terminated housing); check the latch",
+  integral: "fixed to the part (its own leads): nothing to terminate",
+  crimp: "crimp the contacts and insert them in the housing positions of the cut list",
+};
+
+export function cables(p: Project, unit: SectionContext["unit"]) {
+  return providerModules(p, unit, PROVIDER).map((b: CapabilityBinding) => {
+    const def = p.definitions.get(b.module!)!.def;
+    return { b, def, cut: cutList(def), m: readOutput<RouteManifest>(p, b, "body.manifest.json") ?? {}, per: perBuild(unit, def.id) };
+  });
+}
+
+export const workOrder: SectionFn = ({ project: p, unit, release }: SectionContext) => {
+  const cs = cables(p, unit);
+  if (!cs.length) return undefined;
+  const builds = unit.perProduct * release.build;
+  const blocks: Block[] = [
+    { kind: "paragraph", text: `${cs.length} cable${cs.length === 1 ? "" : "s"} routed in this unit. Cut each to its installed length before fitting; the routed length is the centreline the CAD found, with the slack it bows into. Per-conductor rows (positions, colours) are in files/harnesses/<cable>/cut-list.csv.`, keep: true },
+    {
+      kind: "table",
+      columns: [
+        { key: "cable", label: "Cable" },
+        { key: "qty", label: "Qty", align: "right" },
+        { key: "cut", label: "Cut to" },
+        { key: "strip", label: "Strip" },
+        { key: "wire", label: "Conductors" },
+        { key: "lay", label: "Lay" },
+        { key: "bend", label: "Min bend" },
+      ],
+      rows: cs.map(({ def, cut, m, per }) => {
+        const c = cut[0];
+        return {
+          cable: def.name ?? def.id,
+          qty: per * builds,
+          cut: c?.length_mm ? `${c.length_mm} mm${c.supplied_length_mm && c.supplied_length_mm !== c.length_mm ? ` (of ${c.supplied_length_mm})` : ""}` : "as supplied",
+          strip: c?.strip_mm ? `${c.strip_mm} mm` : "—",
+          wire: [String(cut.length || m.bundle?.conductors || "?"), c?.gauge_awg ? `${c.gauge_awg} AWG` : ""].filter(Boolean).join(" × "),
+          lay: c?.lay || m.bundle?.kind || "",
+          bend: m.bend_radius_mm?.minimum ? `${n(m.bend_radius_mm.minimum)} mm` : "",
+        };
+      }),
+      caption: "Cable preparation",
+    },
+    { kind: "heading", text: "Terminations" },
+    {
+      kind: "table",
+      columns: [{ key: "cable", label: "Cable" }, { key: "end", label: "End" }, { key: "onto", label: "Onto" }, { key: "how", label: "How" }],
+      rows: cs.flatMap(({ def, m }) =>
+        Object.entries(m.ends ?? {}).map(([id, e]) => ({ cable: def.name ?? def.id, end: def.interfaces.find((i) => i.id === id)?.name ?? id, onto: e.counterpart ?? "", how: TERMINATION[e.termination ?? ""] ?? e.termination ?? "" })),
+      ),
+      caption: "Terminations",
+    },
+  ];
+  return { title: "Cables", order: 40, blocks };
+};
+
+export const testPlan: SectionFn = ({ project: p, unit }: SectionContext) => {
+  const cs = cables(p, unit).filter(({ m }) => m.bend_radius_mm || m.clearance_mm || m.length_fit);
+  if (!cs.length) return undefined;
+  return {
+    title: "Cable routing",
+    order: 40,
+    blocks: [
+      { kind: "paragraph", text: "After final assembly, each cable as the routed CAD lays it: compare with the assembly guide's figures.", keep: true },
+      {
+        kind: "table",
+        columns: [{ key: "cable", label: "Cable" }, { key: "bend", label: "Bend radius" }, { key: "clear", label: "Clearance" }, { key: "slack", label: "Slack" }],
+        rows: cs.map(({ def, m }) => ({
+          cable: def.name ?? def.id,
+          bend: m.bend_radius_mm?.minimum ? `no bend tighter than ${n(m.bend_radius_mm.minimum)} mm` : "",
+          clear: m.clearance_mm?.min_conductor_surface != null ? `clear of every part (routed ${n(m.clearance_mm.min_conductor_surface, 2)} mm); nothing rubs on an edge or a moving part` : "clear of moving parts",
+          slack: m.length_fit?.slack_mm != null ? `${n(m.length_fit.slack_mm)} mm taken up${m.length_fit.method ? ` (${m.length_fit.method})` : ""}; no tension at either end` : "no tension at either end",
+        })),
+      },
+    ],
+  };
+};

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@protoboardai/ext-harness-cad",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Protoboard extension: routed 3D geometry for wire harnesses, generated from the assembled UHD model (obstacle-aware routing, swept conductors, connector and solder bodies) with build123d; a provider of the cad capability",
+  "license": "Apache-2.0",
+  "author": "Delta Robotics, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Delta-Robotics-Inc/protoboard-stack.git",
+    "directory": "packages/ext-harness-cad"
+  },
+  "type": "module",
+  "exports": {
+    "./artifacts": "./lib/artifacts.ts",
+    "./job": "./lib/job.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "protoboard-extension.json",
+    "py",
+    "lib",
+    "ops",
+    "checks",
+    "skills",
+    "evals",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@protoboardai/core": "^0.2.0",
+    "@deltarobotics/uhd": ">=0.3.0",
+    "@protoboardai/ext-release": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@protoboardai/ext-release": {
+      "optional": true
+    }
+  }
+}

package/protoboard-extension.json

@@ -0,0 +1,106 @@
+{
+  "schema": "protoboard.extension/v0",
+  "id": "@protoboardai/ext-harness-cad",
+  "version": "0.2.0",
+  "description": "Routed wire-harness CAD (a provider of the cad capability): each cable's 3D geometry (conductors swept along an obstacle-free route, twisted where the cable is, connector housings and solder joints) generated from the assembled UHD model and bound to the frames its ends land on.",
+  "compatibility": {
+    "protoboard": "^0.2.0",
+    "uhd": ">=0.3.0"
+  },
+  "skills": [
+    {
+      "id": "harness-cad",
+      "summary": "Generate and bind a wire harness's routed 3D geometry from the assembled model; read the route report (length fit, bend radius, clearance) and fix what it finds",
+      "path": "skills/harness-cad/SKILL.md"
+    }
+  ],
+  "tools": [
+    {
+      "id": "python-build123d",
+      "purpose": "Python with build123d, numpy and scipy (voxel routing, sweeps, STEP/GLB export)",
+      "probe": [
+        "sh",
+        "-c",
+        "exec \"${PROTOBOARD_PYTHON:-python3}\" -c 'import build123d, numpy, scipy; print(\"build123d \" + build123d.__version__)'"
+      ],
+      "install": "protoboard tools install cad (a project venv with these pins), or point PROTOBOARD_PYTHON at an interpreter with build123d==0.13.0 numpy==2.5.3 scipy==1.18.1",
+      "runtime": {
+        "id": "cad",
+        "kind": "python",
+        "packages": [
+          "build123d==0.13.0",
+          "numpy==2.5.3",
+          "scipy==1.18.1"
+        ],
+        "env": "PROTOBOARD_PYTHON",
+        "python": ">=3.11,<3.15"
+      }
+    }
+  ],
+  "capabilities": [
+    {
+      "id": "cad",
+      "summary": "Routed wire harnesses: an obstacle-free route through the assembled model, swept conductors, plug housings and solder joints (build123d)",
+      "native": "harness-cad",
+      "operations": {
+        "generate": {
+          "entry": "./ops/cad.ts#generate",
+          "requires": [
+            "python-build123d"
+          ],
+          "summary": "Route the harness through the assembled model, around the cables routed before it in the system's order, and write harness-cad/route.json (conductor paths, length fit, bend limits, clearance)"
+        },
+        "export": {
+          "entry": "./ops/cad.ts#exportOutputs",
+          "requires": [
+            "python-build123d"
+          ],
+          "summary": "Build the bodies from harness-cad/route.json and write out/body.glb, body.step and body.manifest.json (end frames, lengths, bend radii, clearance)"
+        },
+        "extract": {
+          "entry": "./ops/cad.ts#extract",
+          "summary": "The end frames the route was generated for, and the harness's artifacts"
+        },
+        "check": {
+          "entry": "./ops/cad.ts#check",
+          "summary": "The route is not older than the model, the export not older than the route; the cable fits its length, routed clear, and every end still meets its part"
+        }
+      }
+    }
+  ],
+  "operations": [
+    {
+      "id": "harness-cad",
+      "summary": "Alias of cad:generate then cad:export for every wire harness (or the named ones), each bound by its cad.config.ts, in one routing run",
+      "entry": "./ops/harness-cad.ts#harnessCad",
+      "effect": "export",
+      "requires": [
+        "python-build123d"
+      ],
+      "inputs": {
+        "harness": {
+          "description": "comma-separated harness definition ids or instance paths (default: every wire harness with a cable_build trait)"
+        }
+      }
+    },
+    {
+      "id": "package:work-order",
+      "summary": "Manufacturing Package: preparation of each routed cable in its unit's work order (cut length, strip, conductors, lay, bend radius, terminations)",
+      "entry": "./ops/package.ts#workOrder",
+      "effect": "pure"
+    },
+    {
+      "id": "package:test-plan",
+      "summary": "Manufacturing Package: routing checks of each cable (bend radius, clearance, slack)",
+      "entry": "./ops/package.ts#testPlan",
+      "effect": "pure"
+    }
+  ],
+  "checks": [
+    {
+      "id": "routes",
+      "summary": "Wire harnesses that no cad.config.ts binds to a cad provider (each bound harness's route report is its cad:check)",
+      "entry": "./checks/routes.ts#routes"
+    }
+  ]
+}

package/py/glb.py

@@ -0,0 +1,171 @@
+"""Minimal binary glTF (GLB) reader and writer for the harness router.
+
+Reading: every triangle primitive of every mesh node, with node transforms
+applied, in glTF coordinates (metres, Y up). Only what the build123d
+exports and vendor conversions in this repo contain is supported: float32
+positions, uint16/uint32 indices, TRS or matrix node transforms.
+
+Writing: named meshes with PBR materials (base colour, metallic, roughness),
+one node per mesh under named group nodes.
+"""
+from __future__ import annotations
+
+import json
+import struct
+from pathlib import Path
+
+import numpy as np
+
+_COMPONENT = {5120: np.int8, 5121: np.uint8, 5122: np.int16, 5123: np.uint16, 5125: np.uint32, 5126: np.float32}
+_COUNT = {"SCALAR": 1, "VEC2": 2, "VEC3": 3, "VEC4": 4, "MAT4": 16}
+
+
+def _quat_matrix(q):
+    x, y, z, w = q
+    return np.array(
+        [
+            [1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)],
+            [2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)],
+            [2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)],
+        ]
+    )
+
+
+def _node_matrix(node) -> np.ndarray:
+    if "matrix" in node:
+        return np.array(node["matrix"], dtype=float).reshape(4, 4).T  # column-major
+    m = np.eye(4)
+    s = np.array(node.get("scale", [1, 1, 1]), dtype=float)
+    r = _quat_matrix(node.get("rotation", [0, 0, 0, 1]))
+    m[:3, :3] = r * s
+    m[:3, 3] = node.get("translation", [0, 0, 0])
+    return m
+
+
+def read_glb(path: str | Path) -> list[tuple[str, np.ndarray, np.ndarray]]:
+    """(node name, vertices (N,3) in glTF world, triangles (M,3)) per primitive; an unnamed node is named after its nearest named ancestor."""
+    data = Path(path).read_bytes()
+    magic, _version, _length = struct.unpack_from("<III", data, 0)
+    if magic != 0x46546C67:
+        raise ValueError(f"{path}: not a GLB")
+    off = 12
+    doc, binary = None, b""
+    while off < len(data):
+        clen, ctype = struct.unpack_from("<II", data, off)
+        chunk = data[off + 8 : off + 8 + clen]
+        if ctype == 0x4E4F534A:
+            doc = json.loads(chunk)
+        elif ctype == 0x004E4942:
+            binary = chunk
+        off += 8 + clen
+    assert doc is not None
+
+    def accessor(i):
+        a = doc["accessors"][i]
+        bv = doc["bufferViews"][a["bufferView"]]
+        dtype = _COMPONENT[a["componentType"]]
+        n = _COUNT[a["type"]]
+        start = bv.get("byteOffset", 0) + a.get("byteOffset", 0)
+        stride = bv.get("byteStride", 0)
+        item = np.dtype(dtype).itemsize * n
+        if stride and stride != item:
+            raw = np.frombuffer(binary, dtype=np.uint8, count=stride * a["count"], offset=start).reshape(a["count"], stride)[:, :item]
+            return np.frombuffer(raw.tobytes(), dtype=dtype).reshape(a["count"], n)
+        return np.frombuffer(binary, dtype=dtype, count=a["count"] * n, offset=start).reshape(a["count"], n)
+
+    out = []
+
+    def visit(i, parent, inherited=""):
+        node = doc["nodes"][i]
+        m = parent @ _node_matrix(node)
+        # an unnamed node takes its nearest named ancestor's name (a UHD body's interface feature
+        # marker is an unnamed mesh under a node named after the interface)
+        name = node.get("name") or inherited
+        if "mesh" in node:
+            for prim in doc["meshes"][node["mesh"]]["primitives"]:
+                if prim.get("mode", 4) != 4:
+                    continue
+                v = accessor(prim["attributes"]["POSITION"]).astype(float)
+                f = accessor(prim["indices"]).reshape(-1, 3).astype(np.int64) if "indices" in prim else np.arange(len(v)).reshape(-1, 3)
+                v = v @ m[:3, :3].T + m[:3, 3]
+                out.append((name, v, f))
+        for c in node.get("children", []):
+            visit(c, m, name)
+
+    scene = doc["scenes"][doc.get("scene", 0)]
+    for n in scene["nodes"]:
+        visit(n, np.eye(4))
+    return out
+
+
+def to_cad_mm(v_gltf: np.ndarray) -> np.ndarray:
+    """glTF (m, Y up) -> CAD (mm, Z up): the viewer's cadWrapper (rotate +90 deg about X, x1000)."""
+    return np.stack([v_gltf[:, 0], -v_gltf[:, 2], v_gltf[:, 1]], axis=1) * 1000.0
+
+
+def to_gltf_m(v_mm: np.ndarray) -> np.ndarray:
+    return np.stack([v_mm[:, 0], v_mm[:, 2], -v_mm[:, 1]], axis=1) / 1000.0
+
+
+def _hex_rgba(c: str) -> list[float]:
+    c = c.lstrip("#")
+    r, g, b = (int(c[i : i + 2], 16) / 255.0 for i in (0, 2, 4))
+    # sRGB -> linear for glTF baseColorFactor
+    lin = lambda x: x / 12.92 if x <= 0.04045 else ((x + 0.055) / 1.055) ** 2.4
+    return [round(lin(r), 5), round(lin(g), 5), round(lin(b), 5), 1.0]
+
+
+def write_glb(path: str | Path, groups: dict[str, list[dict]]) -> None:
+    """groups: {group name: [{name, vertices (mm, CAD), faces, color, metallic, roughness}]}."""
+    doc = {"asset": {"version": "2.0", "generator": "protoboard ext-harness-cad"}, "scene": 0, "scenes": [{"nodes": []}], "nodes": [], "meshes": [], "materials": [], "accessors": [], "bufferViews": [], "buffers": []}
+    blob = bytearray()
+    materials: dict[tuple, int] = {}
+
+    def view(arr: np.ndarray, target: int) -> int:
+        while len(blob) % 4:
+            blob.append(0)
+        off = len(blob)
+        blob.extend(arr.tobytes())
+        doc["bufferViews"].append({"buffer": 0, "byteOffset": off, "byteLength": arr.nbytes, "target": target})
+        return len(doc["bufferViews"]) - 1
+
+    for gname, meshes in groups.items():
+        children = []
+        for m in meshes:
+            v = to_gltf_m(np.asarray(m["vertices"], dtype=float)).astype(np.float32)
+            f = np.asarray(m["faces"], dtype=np.uint32).reshape(-1)
+            # flat-ish normals per vertex (area weighted)
+            tri = v[f.reshape(-1, 3)]
+            fn = np.cross(tri[:, 1] - tri[:, 0], tri[:, 2] - tri[:, 0])
+            vn = np.zeros_like(v)
+            for k in range(3):
+                np.add.at(vn, f.reshape(-1, 3)[:, k], fn)
+            vn /= np.maximum(np.linalg.norm(vn, axis=1, keepdims=True), 1e-12)
+            key = (m["color"], m.get("metallic", 0.0), m.get("roughness", 0.6))
+            if key not in materials:
+                doc["materials"].append({"name": m.get("material", m["color"]), "pbrMetallicRoughness": {"baseColorFactor": _hex_rgba(m["color"]), "metallicFactor": key[1], "roughnessFactor": key[2]}})
+                materials[key] = len(doc["materials"]) - 1
+            pv = view(v, 34962)
+            doc["accessors"].append({"bufferView": pv, "componentType": 5126, "count": len(v), "type": "VEC3", "min": v.min(axis=0).tolist(), "max": v.max(axis=0).tolist()})
+            pa = len(doc["accessors"]) - 1
+            nv = view(vn.astype(np.float32), 34962)
+            doc["accessors"].append({"bufferView": nv, "componentType": 5126, "count": len(vn), "type": "VEC3"})
+            na = len(doc["accessors"]) - 1
+            iv = view(f, 34963)
+            doc["accessors"].append({"bufferView": iv, "componentType": 5125, "count": len(f), "type": "SCALAR"})
+            ia = len(doc["accessors"]) - 1
+            doc["meshes"].append({"name": m["name"], "primitives": [{"attributes": {"POSITION": pa, "NORMAL": na}, "indices": ia, "material": materials[key]}]})
+            doc["nodes"].append({"name": m["name"], "mesh": len(doc["meshes"]) - 1})
+            children.append(len(doc["nodes"]) - 1)
+        doc["nodes"].append({"name": gname, "children": children})
+        doc["scenes"][0]["nodes"].append(len(doc["nodes"]) - 1)
+    while len(blob) % 4:
+        blob.append(0)
+    doc["buffers"].append({"byteLength": len(blob)})
+    js = json.dumps(doc, separators=(",", ":")).encode()
+    while len(js) % 4:
+        js += b" "
+    out = struct.pack("<III", 0x46546C67, 2, 12 + 8 + len(js) + 8 + len(blob))
+    out += struct.pack("<II", len(js), 0x4E4F534A) + js
+    out += struct.pack("<II", len(blob), 0x004E4942) + bytes(blob)
+    Path(path).write_bytes(out)