@tscircuit/copper-pour-solver 0.0.33 → 0.0.35

package/README.md

@@ -1,37 +1,165 @@
 # @tscircuit/copper-pour-solver
 
-Solves for copper pour polygons
+Solves PCB copper pour regions from Circuit JSON or from a small geometry input
+format, returning `pcb_copper_pour`-ready B-Rep shapes.
 
-```tsx
-import { CopperPourPipelineSolver } from "@tscircuit/copper-pour-solver"
+## Install
 
-const solver = new CopperPourPipelineSolver({
-  // Circuit JSON including pcb_plated_hole, pcb_hole, pcb_smtpad, pcb_trace, pcb_keepout etc.
-  circuitJson
+```bash
+bun add @tscircuit/copper-pour-solver
+```
+
+This package expects TypeScript 5 as a peer dependency.
+
+## Basic Usage With Circuit JSON
+
+Initialize the geometry runtime once before solving. Then convert Circuit JSON
+into the solver input format, run the solver, and map the returned B-Rep shapes
+back into `pcb_copper_pour` elements.
+
+```ts
+import {
+  CopperPourPipelineSolver,
+  convertCircuitJsonToInputProblem,
+  initializeManifoldGeometry,
+} from "@tscircuit/copper-pour-solver"
+
+await initializeManifoldGeometry()
+
+const inputProblem = convertCircuitJsonToInputProblem(circuitJson, {
+  layer: "top",
+  source_net_name: "GND",
+  pad_margin: 0.4,
+  trace_margin: 0.2,
+  board_edge_margin: 0.1,
+  cutout_margin: 0.2,
 })
 
-solver.solve()
+const solver = new CopperPourPipelineSolver(inputProblem)
+const { brep_shapes } = solver.getOutput()
+```
+
+`convertCircuitJsonToInputProblem` reads board bounds or outline, SMT pads,
+plated holes, mechanical holes, vias, traces, and cutouts for the selected layer.
+Pads and traces connected to the selected source net are kept connected to the
+pour; unrelated geometry is subtracted using the configured margins.
 
-solver.getOutput()
-// { brepShapes }
+## Selecting The Pour Net
+
+Prefer selecting by source net name or id:
+
+```ts
+const inputProblem = convertCircuitJsonToInputProblem(circuitJson, {
+  layer: "top",
+  source_net_name: "GND",
+  pad_margin: 0.4,
+  trace_margin: 0.2,
+})
 ```
 
-## B-Rep Shapes
+You can also pass the source net's stable `subcircuit_connectivity_map_key`
+directly:
 
-We use the following representation for 2D b-rep shapes
+```ts
+const gnd = circuitJson.find(
+  (element) => element.type === "source_net" && element.name === "GND",
+)
 
-```tsx
-interface BRepShape {
-  outerRing: Ring // The outer boundary
-  innerRings: Ring // The inner cutouts
+const inputProblem = convertCircuitJsonToInputProblem(circuitJson, {
+  layer: "top",
+  subcircuit_id: gnd.subcircuit_id,
+  subcircuit_connectivity_map_key: gnd.subcircuit_connectivity_map_key,
+  pad_margin: 0.4,
+  trace_margin: 0.2,
+})
+```
+
+Pass `subcircuit_id` when selecting a net inside a subcircuit. The converter
+considers that subcircuit and its child subcircuits, but it does not treat
+matching child `subcircuit_connectivity_map_key` values as connected unless the
+Circuit JSON connectivity actually connects them. Internally, the generated
+`globalConnectivityMap` is kept separate from the scoped
+`subcircuitConnectivityMap`; scoped solver connectivity keys are prefixed with
+their subcircuit id.
+
+Do not generate or pass ids from `circuit-json-to-connectivity-map`. The
+converter handles PCB connectivity internally and normalizes it to stable
+`subcircuit_connectivity_map_key` values.
+
+## Manual Input
+
+You can skip Circuit JSON conversion and provide the solver input directly.
+
+```ts
+import {
+  CopperPourPipelineSolver,
+  initializeManifoldGeometry,
+  type InputProblem,
+} from "@tscircuit/copper-pour-solver"
+
+await initializeManifoldGeometry()
+
+const input: InputProblem = {
+  regionsForPour: [
+    {
+      shape: "rect",
+      layer: "top",
+      bounds: { minX: -10, minY: -5, maxX: 10, maxY: 5 },
+      connectivityKey: "net:GND",
+      padMargin: 0.4,
+      traceMargin: 0.2,
+      board_edge_margin: 0.1,
+    },
+  ],
+  pads: [
+    {
+      shape: "circle",
+      padId: "via_1",
+      layer: "top",
+      connectivityKey: "net:VCC",
+      x: 0,
+      y: 0,
+      radius: 0.5,
+    },
+  ],
 }
 
-interface Ring {
-  cwVertices: PointWithBulge[]
+const output = new CopperPourPipelineSolver(input).getOutput()
+```
+
+Supported input pad shapes are `rect`, `circle`, `pill`, `trace`, and `polygon`.
+Use the same `connectivityKey` as the pour for pads/traces that should connect to
+the copper island; use a different key for blockers that should be cleared.
+
+## Output
+
+`getOutput()` returns:
+
+```ts
+interface PipelineOutput {
+  brep_shapes: BRepShape[]
 }
+```
+
+Each B-Rep shape is compatible with Circuit JSON copper pour data:
 
-interface PointWithBulge {
-  x: number
-  y: number
+```ts
+interface BRepShape {
+  outer_ring: {
+    vertices: Array<{ x: number; y: number; bulge?: number }>
+  }
+  inner_rings: Array<{
+    vertices: Array<{ x: number; y: number; bulge?: number }>
+  }>
 }
 ```
+
+## Development
+
+```bash
+bun install
+bun run build
+bun test
+bun start
+bun run build:site
+```

package/cosmos.config.json

@@ -1,5 +1,6 @@
 {
   "$schema": "http://json.schemastore.org/cosmos-config",
   "plugins": ["react-cosmos-plugin-vite"],
-  "fixtureFileSuffix": "page"
+  "fixtureFileSuffix": "page",
+  "exportPath": "cosmos-export"
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { BasePipelineSolver } from '@tscircuit/solver-utils';
 import { Bounds, Point } from '@tscircuit/math-utils';
-import { BRepShape, AnyCircuitElement, LayerRef, Point as Point$1 } from 'circuit-json';
+import { BRepShape, LayerRef, Point as Point$1, AnyCircuitElement } from 'circuit-json';
 
 interface InputPourRegion {
     shape: "rect";
@@ -65,14 +65,24 @@ declare class CopperPourPipelineSolver extends BasePipelineSolver<InputProblem>
 
 declare const initializeManifoldGeometry: () => Promise<void>;
 
-declare const convertCircuitJsonToInputProblem: (circuitJson: AnyCircuitElement[], options: {
+interface ConvertCircuitJsonToInputProblemOptions {
     layer: LayerRef;
-    pour_connectivity_key: string;
+    subcircuit_id?: string;
+    source_net_id?: string;
+    source_net_name?: string;
+    subcircuit_connectivity_map_key?: string;
+    /**
+     * @deprecated Use subcircuit_connectivity_map_key, source_net_id, or
+     * source_net_name. Generated connectivity-map ids are intentionally rejected.
+     */
+    pour_connectivity_key?: string;
     pad_margin: number;
     trace_margin: number;
     board_edge_margin?: number;
     cutout_margin?: number;
     outline?: Point$1[];
-}) => InputProblem;
+}
+
+declare const convertCircuitJsonToInputProblem: (circuitJson: AnyCircuitElement[], options: ConvertCircuitJsonToInputProblemOptions) => InputProblem;
 
-export { type BaseInputPad, CopperPourPipelineSolver, type InputCircularPad, type InputPad, type InputPillPad, type InputPolygonPad, type InputPourRegion, type InputProblem, type InputRectPad, type InputTracePad, type PipelineOutput, convertCircuitJsonToInputProblem, initializeManifoldGeometry };
+export { type BaseInputPad, type ConvertCircuitJsonToInputProblemOptions, CopperPourPipelineSolver, type InputCircularPad, type InputPad, type InputPillPad, type InputPolygonPad, type InputPourRegion, type InputProblem, type InputRectPad, type InputTracePad, type PipelineOutput, convertCircuitJsonToInputProblem, initializeManifoldGeometry };

package/dist/index.js

@@ -537,19 +537,263 @@ var CopperPourPipelineSolver = class extends BasePipelineSolver {
 
 // lib/circuit-json/convert-circuit-json-to-input-problem.ts
 import { getFullConnectivityMapFromCircuitJson } from "circuit-json-to-connectivity-map";
+
+// lib/circuit-json/buildSubcircuitConnectivityLookup.ts
+import { getElementId } from "@tscircuit/circuit-json-util";
+
+// lib/circuit-json/getElementSubcircuitConnectivityKey.ts
+var getElementSubcircuitConnectivityKey = (element) => {
+  const key = element.subcircuit_connectivity_map_key;
+  return typeof key === "string" && key.length > 0 ? key : void 0;
+};
+
+// lib/circuit-json/buildSubcircuitConnectivityLookup.ts
+var getElementSubcircuitId = (element) => {
+  const subcircuitId = element.subcircuit_id;
+  return typeof subcircuitId === "string" && subcircuitId.length > 0 ? subcircuitId : void 0;
+};
+var getScopedSubcircuitConnectivityKey = (subcircuitId, subcircuitConnectivityMapKey) => subcircuitId ? `subcircuit:${subcircuitId}:connectivity:${subcircuitConnectivityMapKey}` : subcircuitConnectivityMapKey;
+var getDescendantSubcircuitIds = (circuitJson, rootSubcircuitId) => {
+  if (!rootSubcircuitId) return void 0;
+  const sourceGroupIdToSubcircuitId = {};
+  for (const element of circuitJson) {
+    if (element.type !== "source_group") continue;
+    const sourceGroupId = element.source_group_id;
+    const subcircuitId = getElementSubcircuitId(element);
+    if (typeof sourceGroupId === "string" && subcircuitId) {
+      sourceGroupIdToSubcircuitId[sourceGroupId] = subcircuitId;
+    }
+  }
+  const descendantSubcircuitIds = /* @__PURE__ */ new Set([rootSubcircuitId]);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const element of circuitJson) {
+      if (element.type !== "source_group") continue;
+      const subcircuitId = getElementSubcircuitId(element);
+      if (!subcircuitId || descendantSubcircuitIds.has(subcircuitId)) continue;
+      const parentSubcircuitId = element.parent_subcircuit_id;
+      const parentSourceGroupId = element.parent_source_group_id;
+      const parentSourceGroupSubcircuitId = typeof parentSourceGroupId === "string" ? sourceGroupIdToSubcircuitId[parentSourceGroupId] : void 0;
+      if (typeof parentSubcircuitId === "string" && descendantSubcircuitIds.has(parentSubcircuitId) || parentSourceGroupSubcircuitId && descendantSubcircuitIds.has(parentSourceGroupSubcircuitId)) {
+        descendantSubcircuitIds.add(subcircuitId);
+        changed = true;
+      }
+    }
+  }
+  return descendantSubcircuitIds;
+};
+var buildSubcircuitConnectivityLookup = (circuitJson, globalConnectivityMap, rootSubcircuitId) => {
+  const descendantSubcircuitIds = getDescendantSubcircuitIds(
+    circuitJson,
+    rootSubcircuitId
+  );
+  const idToSubcircuitConnectivityKey = {};
+  const idToSubcircuitId = {};
+  const scopedKeyToIds = {};
+  const localSubcircuitConnectivityKeys = /* @__PURE__ */ new Set();
+  for (const element of circuitJson) {
+    const id = getElementId(element);
+    const key = getElementSubcircuitConnectivityKey(element);
+    const subcircuitId = getElementSubcircuitId(element);
+    if (id) {
+      idToSubcircuitId[id] = subcircuitId;
+    }
+    if (descendantSubcircuitIds && (!subcircuitId || !descendantSubcircuitIds.has(subcircuitId))) {
+      continue;
+    }
+    if (id && key) {
+      const scopedKey = getScopedSubcircuitConnectivityKey(subcircuitId, key);
+      idToSubcircuitConnectivityKey[id] = scopedKey;
+      localSubcircuitConnectivityKeys.add(key);
+      scopedKeyToIds[scopedKey] ??= [];
+      scopedKeyToIds[scopedKey].push(id);
+    }
+  }
+  const generatedNetIdToSubcircuitConnectivityKey = {};
+  for (const [generatedNetId, connectedIds] of Object.entries(
+    globalConnectivityMap.netMap
+  )) {
+    const connectedSubcircuitKeys = new Set(
+      connectedIds.map((id) => idToSubcircuitConnectivityKey[id]).filter((key) => Boolean(key))
+    );
+    const subcircuitKey = Array.from(connectedSubcircuitKeys).sort()[0];
+    if (subcircuitKey) {
+      generatedNetIdToSubcircuitConnectivityKey[generatedNetId] = subcircuitKey;
+    }
+  }
+  const subcircuitConnectivityMap = {};
+  for (const [scopedKey, ids] of Object.entries(scopedKeyToIds)) {
+    const resolvedKeys = /* @__PURE__ */ new Set();
+    for (const id of ids) {
+      const generatedNetId = globalConnectivityMap.getNetConnectedToId(id);
+      const resolvedKey2 = generatedNetId ? generatedNetIdToSubcircuitConnectivityKey[generatedNetId] : void 0;
+      resolvedKeys.add(resolvedKey2 ?? scopedKey);
+    }
+    if (resolvedKeys.size > 1) {
+      throw new Error(
+        `subcircuit_connectivity_map_key "${scopedKey}" maps to multiple global connectivity keys: ${Array.from(resolvedKeys).join(", ")}`
+      );
+    }
+    const resolvedKey = resolvedKeys.values().next().value;
+    if (resolvedKey) {
+      subcircuitConnectivityMap[scopedKey] = resolvedKey;
+    }
+  }
+  return {
+    knownSubcircuitConnectivityKeys: /* @__PURE__ */ new Set([
+      ...Object.keys(scopedKeyToIds),
+      ...localSubcircuitConnectivityKeys
+    ]),
+    descendantSubcircuitIds,
+    getScopedSubcircuitConnectivityKey,
+    getElementSubcircuitId,
+    resolveSubcircuitConnectivityKey(subcircuitConnectivityMapKey, subcircuitId) {
+      const matchingScopedKeys = Object.keys(scopedKeyToIds).filter(
+        (scopedKey) => scopedKey === getScopedSubcircuitConnectivityKey(
+          subcircuitId,
+          subcircuitConnectivityMapKey
+        )
+      );
+      if (subcircuitId && matchingScopedKeys.length === 0 && descendantSubcircuitIds) {
+        matchingScopedKeys.push(
+          ...Object.keys(scopedKeyToIds).filter(
+            (scopedKey) => scopedKey.endsWith(`:connectivity:${subcircuitConnectivityMapKey}`)
+          )
+        );
+      }
+      if (!subcircuitId) {
+        matchingScopedKeys.push(
+          ...Object.keys(scopedKeyToIds).filter(
+            (scopedKey) => scopedKey.endsWith(`:connectivity:${subcircuitConnectivityMapKey}`)
+          )
+        );
+      }
+      const uniqueMatchingScopedKeys = Array.from(new Set(matchingScopedKeys));
+      if (uniqueMatchingScopedKeys.length === 0) {
+        if (subcircuitId && descendantSubcircuitIds) {
+          throw new Error(
+            `No subcircuit_connectivity_map_key "${subcircuitConnectivityMapKey}" found in subcircuit "${subcircuitId}" or its child subcircuits.`
+          );
+        }
+        return getScopedSubcircuitConnectivityKey(
+          subcircuitId,
+          subcircuitConnectivityMapKey
+        );
+      }
+      if (uniqueMatchingScopedKeys.length > 1) {
+        throw new Error(
+          `subcircuit_connectivity_map_key "${subcircuitConnectivityMapKey}" exists in multiple subcircuits. Pass subcircuit_id to disambiguate.`
+        );
+      }
+      return subcircuitConnectivityMap[uniqueMatchingScopedKeys[0]] ?? uniqueMatchingScopedKeys[0];
+    },
+    getSubcircuitConnectivityKeyForId(id) {
+      if (descendantSubcircuitIds) {
+        const subcircuitId = idToSubcircuitId[id];
+        if (!subcircuitId || !descendantSubcircuitIds.has(subcircuitId)) {
+          return void 0;
+        }
+      }
+      const directKey = idToSubcircuitConnectivityKey[id];
+      const generatedNetId = globalConnectivityMap.getNetConnectedToId(id);
+      if (!generatedNetId) {
+        return directKey ? subcircuitConnectivityMap[directKey] ?? directKey : void 0;
+      }
+      return generatedNetIdToSubcircuitConnectivityKey[generatedNetId] ?? (directKey ? subcircuitConnectivityMap[directKey] : void 0) ?? directKey;
+    }
+  };
+};
+
+// lib/circuit-json/resolvePourConnectivityKey.ts
+var resolvePourConnectivityKey = (circuitJson, options, subcircuitConnectivityMap) => {
+  if (options.subcircuit_connectivity_map_key) {
+    return subcircuitConnectivityMap.resolveSubcircuitConnectivityKey(
+      options.subcircuit_connectivity_map_key,
+      options.subcircuit_id
+    );
+  }
+  if (options.source_net_id) {
+    const sourceNet = circuitJson.find(
+      (element) => element.type === "source_net" && element.source_net_id === options.source_net_id
+    );
+    if (!sourceNet) {
+      throw new Error(`No source_net found with id "${options.source_net_id}"`);
+    }
+    if (!sourceNet.subcircuit_connectivity_map_key) {
+      throw new Error(
+        `source_net "${options.source_net_id}" has no subcircuit_connectivity_map_key`
+      );
+    }
+    return subcircuitConnectivityMap.resolveSubcircuitConnectivityKey(
+      sourceNet.subcircuit_connectivity_map_key,
+      sourceNet.subcircuit_id ?? options.subcircuit_id
+    );
+  }
+  if (options.source_net_name) {
+    const sourceNet = circuitJson.find(
+      (element) => element.type === "source_net" && element.name === options.source_net_name && (!options.subcircuit_id || Boolean(
+        subcircuitConnectivityMap.descendantSubcircuitIds?.has(
+          element.subcircuit_id ?? ""
+        )
+      ))
+    );
+    if (!sourceNet) {
+      throw new Error(
+        `No source_net found with name "${options.source_net_name}"`
+      );
+    }
+    if (!sourceNet.subcircuit_connectivity_map_key) {
+      throw new Error(
+        `source_net "${options.source_net_name}" has no subcircuit_connectivity_map_key`
+      );
+    }
+    return subcircuitConnectivityMap.resolveSubcircuitConnectivityKey(
+      sourceNet.subcircuit_connectivity_map_key,
+      sourceNet.subcircuit_id ?? options.subcircuit_id
+    );
+  }
+  if (options.pour_connectivity_key) {
+    if (!subcircuitConnectivityMap.knownSubcircuitConnectivityKeys.has(
+      options.pour_connectivity_key
+    )) {
+      throw new Error(
+        `pour_connectivity_key must be a subcircuit_connectivity_map_key. Use subcircuit_connectivity_map_key, source_net_id, or source_net_name instead of a generated connectivity-map id.`
+      );
+    }
+    return subcircuitConnectivityMap.resolveSubcircuitConnectivityKey(
+      options.pour_connectivity_key,
+      options.subcircuit_id
+    );
+  }
+  throw new Error(
+    "Copper pour requires source_net_id, source_net_name, or subcircuit_connectivity_map_key"
+  );
+};
+
+// lib/circuit-json/convert-circuit-json-to-input-problem.ts
 var convertCircuitJsonToInputProblem = (circuitJson, options) => {
   const pcb_board = circuitJson.find((e) => e.type === "pcb_board");
   if (!pcb_board) throw new Error("No pcb_board found in circuit json");
-  const connectivityMap = getFullConnectivityMapFromCircuitJson(circuitJson);
+  const globalConnectivityMap = getFullConnectivityMapFromCircuitJson(circuitJson);
+  const subcircuitConnectivityMap = buildSubcircuitConnectivityLookup(
+    circuitJson,
+    globalConnectivityMap,
+    options.subcircuit_id
+  );
+  const pourConnectivityKey = resolvePourConnectivityKey(
+    circuitJson,
+    options,
+    subcircuitConnectivityMap
+  );
+  const { getSubcircuitConnectivityKeyForId } = subcircuitConnectivityMap;
   const pads = [];
   for (const elm of circuitJson) {
     if (elm.type === "pcb_smtpad") {
       const smtpad = elm;
       if (smtpad.layer !== options.layer) continue;
       let connectivityKey;
-      connectivityKey = connectivityMap.getNetConnectedToId(
-        smtpad.pcb_smtpad_id
-      );
+      connectivityKey = getSubcircuitConnectivityKeyForId(smtpad.pcb_smtpad_id);
       if (!connectivityKey) {
         connectivityKey = `unconnected:${smtpad.pcb_smtpad_id}`;
       }
@@ -593,7 +837,7 @@ var convertCircuitJsonToInputProblem = (circuitJson, options) => {
     } else if (elm.type === "pcb_plated_hole") {
       const platedHole = elm;
       if (!platedHole.layers.includes(options.layer)) continue;
-      let connectivityKey = connectivityMap.getNetConnectedToId(
+      let connectivityKey = getSubcircuitConnectivityKeyForId(
         platedHole.pcb_plated_hole_id
       );
       if (!connectivityKey) {
@@ -681,7 +925,7 @@ var convertCircuitJsonToInputProblem = (circuitJson, options) => {
     } else if (elm.type === "pcb_via") {
       const via = elm;
       if (!via.layers.includes(options.layer)) continue;
-      const connectivityKey = connectivityMap.getNetConnectedToId(via.pcb_via_id) ?? `unconnected-via:${via.pcb_via_id}`;
+      const connectivityKey = getSubcircuitConnectivityKeyForId(via.pcb_via_id) ?? `unconnected-via:${via.pcb_via_id}`;
       pads.push({
         shape: "circle",
         padId: via.pcb_via_id,
@@ -693,7 +937,7 @@ var convertCircuitJsonToInputProblem = (circuitJson, options) => {
       });
     } else if (elm.type === "pcb_trace") {
       const trace = elm;
-      const connectivityKey = connectivityMap.getNetConnectedToId(
+      const connectivityKey = getSubcircuitConnectivityKeyForId(
         trace.pcb_trace_id
       );
       if (!connectivityKey) continue;
@@ -752,7 +996,7 @@ var convertCircuitJsonToInputProblem = (circuitJson, options) => {
       layer: options.layer,
       bounds,
       outline,
-      connectivityKey: options.pour_connectivity_key,
+      connectivityKey: pourConnectivityKey,
       padMargin: options.pad_margin,
       traceMargin: options.trace_margin,
       board_edge_margin: options.board_edge_margin ?? 0,

package/lib/circuit-json/ConvertCircuitJsonToInputProblemOptions.ts

@@ -0,0 +1,19 @@
+import type { LayerRef, Point } from "circuit-json"
+
+export interface ConvertCircuitJsonToInputProblemOptions {
+  layer: LayerRef
+  subcircuit_id?: string
+  source_net_id?: string
+  source_net_name?: string
+  subcircuit_connectivity_map_key?: string
+  /**
+   * @deprecated Use subcircuit_connectivity_map_key, source_net_id, or
+   * source_net_name. Generated connectivity-map ids are intentionally rejected.
+   */
+  pour_connectivity_key?: string
+  pad_margin: number
+  trace_margin: number
+  board_edge_margin?: number
+  cutout_margin?: number
+  outline?: Point[]
+}