altium-to-circuit-json 0.0.21 → 0.0.23

package/README.md

@@ -94,6 +94,10 @@ bun run test:update-svg
 
 Every imported reference used by the test suite has a side-by-side SVG snapshot. The committed fixtures are generated from pinned upstream URLs and are not stored in this repository.
 
+The real-world PCB corpus covers NodeMCU ESP-12, EBAZ4205, HERON Payload SSM,
+SimpleFOC Mini, and SimpleFOC Shield V3. The schematic corpus covers NodeMCU,
+HERON PAY-SSM and Systems PCB, SimpleFOC Mini, and SimpleFOC Shield V3.
+
 The TI SPRCAL9 / TMDS62LEVM Rev. B regression corpus includes all 57
 schematic sheets and a top-copper PCB comparison. Its large downloaded source
 files are checksum-verified and cached in CI. To also write the complete

package/dist/index.js

@@ -1,17 +1,224 @@
 // lib/convert-altium-pcb-doc-to-circuit-json.ts
 import {
-  AltiumArcRecord,
+  AltiumArcRecord as AltiumArcRecord2,
   AltiumFillRecord,
+  AltiumPadRecord as AltiumPadRecord2,
+  AltiumRegionRecord as AltiumRegionRecord2,
+  AltiumTextRecord,
+  AltiumTrackRecord as AltiumTrackRecord2,
+  AltiumViaRecord as AltiumViaRecord2,
+  getAltiumBounds as getAltiumBounds2,
+  getPcbLayerStack,
+  getPcbRegionGeometry as getPcbRegionGeometry2,
+  parseAltiumMeasurementToMils
+} from "altiumts";
+
+// lib/pcb/get-board-outline.ts
+import {
+  AltiumArcRecord,
   AltiumPadRecord,
   AltiumRegionRecord,
-  AltiumTextRecord,
   AltiumTrackRecord,
   AltiumViaRecord,
   getAltiumBounds,
-  getPcbLayerStack,
-  getPcbRegionGeometry,
-  parseAltiumMeasurementToMils
+  getPcbRegionGeometry
 } from "altiumts";
+
+// lib/pcb/stitch-connected-paths.ts
+function stitchConnectedAltiumPaths({
+  paths,
+  maxEndpointGapMils
+}) {
+  const remaining = paths.map((path) => [...path]);
+  const stitchedPaths = [];
+  while (remaining.length > 0) {
+    const path = remaining.shift();
+    if (!path) break;
+    while (appendConnectedPath({ path, remaining, maxEndpointGapMils })) {
+    }
+    stitchedPaths.push(path);
+  }
+  return stitchedPaths;
+}
+function appendConnectedPath({
+  path,
+  remaining,
+  maxEndpointGapMils
+}) {
+  const pathStart = path[0];
+  const pathEnd = path.at(-1);
+  if (!pathStart || !pathEnd) return false;
+  for (const [index, candidate] of remaining.entries()) {
+    const candidateStart = candidate[0];
+    const candidateEnd = candidate.at(-1);
+    if (!candidateStart || !candidateEnd) continue;
+    if (pointsApproximatelyEqual({
+      left: pathEnd,
+      right: candidateStart,
+      maxEndpointGapMils
+    })) {
+      path.push(...candidate.slice(1));
+    } else if (pointsApproximatelyEqual({
+      left: pathEnd,
+      right: candidateEnd,
+      maxEndpointGapMils
+    })) {
+      path.push(...candidate.toReversed().slice(1));
+    } else if (pointsApproximatelyEqual({
+      left: pathStart,
+      right: candidateEnd,
+      maxEndpointGapMils
+    })) {
+      path.unshift(...candidate.slice(0, -1));
+    } else if (pointsApproximatelyEqual({
+      left: pathStart,
+      right: candidateStart,
+      maxEndpointGapMils
+    })) {
+      path.unshift(...candidate.toReversed().slice(0, -1));
+    } else {
+      continue;
+    }
+    remaining.splice(index, 1);
+    return true;
+  }
+  return false;
+}
+function pointsApproximatelyEqual({
+  left,
+  right,
+  maxEndpointGapMils
+}) {
+  return Math.abs(left.x - right.x) <= maxEndpointGapMils && Math.abs(left.y - right.y) <= maxEndpointGapMils;
+}
+
+// lib/pcb/get-board-outline.ts
+var MAX_ENDPOINT_GAP_MILS = 5;
+var MAX_PLACEMENT_OVERHANG_MILS = 100;
+var MIN_STALE_OUTLINE_AREA_RATIO = 1.25;
+function getPreferredPcbBoardOutline(document) {
+  const declaredOutline = document.boardGeometry.outline.points;
+  const keepoutOutline = getTightestEnclosingKeepoutOutline(document);
+  if (!keepoutOutline) return declaredOutline;
+  const declaredBounds = getAltiumBounds(declaredOutline);
+  const keepoutBounds = getAltiumBounds(keepoutOutline);
+  if (!keepoutBounds) return declaredOutline;
+  if (!declaredBounds || declaredOutline.length < 3) return keepoutOutline;
+  const declaredArea = getBoundsArea(declaredBounds);
+  const keepoutArea = getBoundsArea(keepoutBounds);
+  const declaredOutlineIsStale = declaredArea >= keepoutArea * MIN_STALE_OUTLINE_AREA_RATIO;
+  return declaredOutlineIsStale ? keepoutOutline : declaredOutline;
+}
+function getTightestEnclosingKeepoutOutline(document) {
+  const closedOutlines = [];
+  const openPaths = [];
+  for (const record of document.records) {
+    if (!isKeepoutLayer(record.getDecoded("LAYER"))) continue;
+    if (document.getComponentForRecord(record)) continue;
+    if (record instanceof AltiumRegionRecord) {
+      const outline = getPcbRegionGeometry(record).outline.points;
+      if (outline.length >= 3) closedOutlines.push(removeClosingPoint(outline));
+      continue;
+    }
+    if (record instanceof AltiumTrackRecord && record.start && record.end) {
+      openPaths.push([record.start, record.end]);
+      continue;
+    }
+    if (record instanceof AltiumArcRecord) {
+      const points = getArcPoints(record);
+      if (points.length >= 2) openPaths.push(points);
+    }
+  }
+  for (const path of stitchConnectedAltiumPaths({
+    paths: openPaths,
+    maxEndpointGapMils: MAX_ENDPOINT_GAP_MILS
+  })) {
+    if (!isClosedPath(path)) continue;
+    closedOutlines.push(removeClosingPoint(path));
+  }
+  const placedBounds = getPlacedContentBounds(document);
+  const candidates = closedOutlines.flatMap((outline) => {
+    const bounds = getAltiumBounds(outline);
+    if (!bounds || outline.length < 3) return [];
+    if (placedBounds && !boundsContainWithTolerance({
+      container: bounds,
+      contained: placedBounds,
+      tolerance: MAX_PLACEMENT_OVERHANG_MILS
+    })) {
+      return [];
+    }
+    return [{ bounds, outline }];
+  });
+  candidates.sort((left, right) => {
+    const areaDifference = getBoundsArea(left.bounds) - getBoundsArea(right.bounds);
+    return placedBounds ? areaDifference : -areaDifference;
+  });
+  return candidates[0]?.outline;
+}
+function getPlacedContentBounds(document) {
+  const points = [];
+  for (const record of document.records) {
+    if (record instanceof AltiumPadRecord || record instanceof AltiumViaRecord) {
+      if (record.position) points.push(record.position);
+      continue;
+    }
+    if (record instanceof AltiumTrackRecord && isCopperLayer(record.layer) && record.start && record.end) {
+      points.push(record.start, record.end);
+    }
+  }
+  return getAltiumBounds(points);
+}
+function getArcPoints(record) {
+  const center = record.center;
+  const radius = record.radiusMils;
+  if (!center || !radius) return [];
+  const rawSweep = record.endAngle - record.startAngle;
+  const sweep = rawSweep === 0 || Math.abs(rawSweep) >= 360 ? 360 : (rawSweep % 360 + 360) % 360;
+  const segmentCount = Math.max(8, Math.ceil(sweep / 7.5));
+  return Array.from({ length: segmentCount + 1 }, (_, index) => {
+    const angle = record.startAngle + sweep * index / segmentCount;
+    const radians = angle * Math.PI / 180;
+    return {
+      x: center.x + Math.cos(radians) * radius,
+      y: center.y + Math.sin(radians) * radius
+    };
+  });
+}
+function boundsContainWithTolerance({
+  container,
+  contained,
+  tolerance
+}) {
+  return contained.minX >= container.minX - tolerance && contained.maxX <= container.maxX + tolerance && contained.minY >= container.minY - tolerance && contained.maxY <= container.maxY + tolerance;
+}
+function getBoundsArea(bounds) {
+  return (bounds.maxX - bounds.minX) * (bounds.maxY - bounds.minY);
+}
+function isClosedPath(points) {
+  const first = points[0];
+  const last = points.at(-1);
+  return Boolean(first && last && pointsApproximatelyEqual2(first, last));
+}
+function removeClosingPoint(points) {
+  const first = points[0];
+  const last = points.at(-1);
+  return first && last && pointsApproximatelyEqual2(first, last) ? points.slice(0, -1) : points;
+}
+function pointsApproximatelyEqual2(left, right) {
+  return Math.abs(left.x - right.x) <= MAX_ENDPOINT_GAP_MILS && Math.abs(left.y - right.y) <= MAX_ENDPOINT_GAP_MILS;
+}
+function isKeepoutLayer(layer) {
+  return normalizeLayer(layer) === "KEEPOUT";
+}
+function isCopperLayer(layer) {
+  const normalized = normalizeLayer(layer);
+  return normalized === "TOP" || normalized === "TOPLAYER" || normalized === "BOTTOM" || normalized === "BOTTOMLAYER" || /^(?:MID|MIDLAYER|INTERNALPLANE)\d+$/u.test(normalized);
+}
+function normalizeLayer(layer) {
+  return (layer ?? "").replace(/[\s_.-]+/gu, "").toUpperCase();
+}
+
+// lib/convert-altium-pcb-doc-to-circuit-json.ts
 var MILS_TO_MILLIMETERS = 0.0254;
 var BOARD_ID = "pcb_board_altium";
 var BOARD_GRAPHICS_COMPONENT_ID = "pcb_component_altium_board_graphics";
@@ -57,12 +264,12 @@ function convertAltiumPcbDocToCircuitJson(document, options = {}) {
     elements.push(...convertCourtyards(document));
   }
   for (const [index, record] of document.records.entries()) {
-    if (record instanceof AltiumPadRecord && options.includePads !== false) {
+    if (record instanceof AltiumPadRecord2 && options.includePads !== false) {
       const pad = convertPad(record, index);
       if (pad) elements.push(pad);
       continue;
     }
-    if (record instanceof AltiumTrackRecord) {
+    if (record instanceof AltiumTrackRecord2) {
       if (isCourtyardLayer(record.layer)) continue;
       if (isOverlayLayer(record.layer)) {
         if (options.includeSilkscreen === false) continue;
@@ -74,7 +281,7 @@ function convertAltiumPcbDocToCircuitJson(document, options = {}) {
       }
       continue;
     }
-    if (record instanceof AltiumViaRecord && options.includeVias !== false) {
+    if (record instanceof AltiumViaRecord2 && options.includeVias !== false) {
       const via = convertVia(record, index);
       if (via) elements.push(via);
       continue;
@@ -82,7 +289,7 @@ function convertAltiumPcbDocToCircuitJson(document, options = {}) {
     if (options.includeSilkscreen === false || !isOverlayLayer(getLayer(record))) {
       continue;
     }
-    if (record instanceof AltiumArcRecord) {
+    if (record instanceof AltiumArcRecord2) {
       const path = convertSilkscreenArc(record, index);
       if (path) elements.push(path);
     } else if (record instanceof AltiumFillRecord) {
@@ -114,13 +321,13 @@ function convertCourtyards(document) {
       componentId: ownedComponentId,
       layer: mapCourtyardLayer(layer),
       points,
-      strokeWidthMils: record instanceof AltiumTrackRecord || record instanceof AltiumArcRecord ? record.widthMils ?? 4 : 0
+      strokeWidthMils: record instanceof AltiumTrackRecord2 || record instanceof AltiumArcRecord2 ? record.widthMils ?? 4 : 0
     });
   }
   const courtyards = [];
   for (const path of stitchCourtyardPaths(paths)) {
     if (!isClosedAltiumPath(path.points)) continue;
-    const outline = removeClosingPoint(path.points).map(toMillimeterPoint);
+    const outline = removeClosingPoint2(path.points).map(toMillimeterPoint);
     if (outline.length < 3) continue;
     courtyards.push({
       type: "pcb_courtyard_outline",
@@ -133,10 +340,10 @@ function convertCourtyards(document) {
   return courtyards;
 }
 function getCourtyardRecordPoints(record) {
-  if (record instanceof AltiumTrackRecord) {
+  if (record instanceof AltiumTrackRecord2) {
     return record.start && record.end ? [record.start, record.end] : [];
   }
-  if (record instanceof AltiumArcRecord) {
+  if (record instanceof AltiumArcRecord2) {
     return record.center && record.radiusMils ? approximateArc({
       center: record.center,
       radius: record.radiusMils,
@@ -144,8 +351,8 @@ function getCourtyardRecordPoints(record) {
       endAngle: record.endAngle
     }) : [];
   }
-  if (record instanceof AltiumRegionRecord) {
-    return getPcbRegionGeometry(record).outline.points;
+  if (record instanceof AltiumRegionRecord2) {
+    return getPcbRegionGeometry2(record).outline.points;
   }
   return [];
 }
@@ -164,41 +371,12 @@ function stitchCourtyardPaths(paths) {
   return [...groups.values()].flatMap(stitchCourtyardPathGroup);
 }
 function stitchCourtyardPathGroup(group) {
-  const remaining = [...group];
-  const stitched = [];
-  while (remaining.length > 0) {
-    const first = remaining.shift();
-    if (!first) break;
-    const path = { ...first, points: [...first.points] };
-    while (appendConnectedCourtyardPath(path, remaining)) {
-    }
-    stitched.push(path);
-  }
-  return stitched;
-}
-function appendConnectedCourtyardPath(stitched, remaining) {
-  const stitchedStart = stitched.points[0];
-  const stitchedEnd = stitched.points.at(-1);
-  if (!stitchedStart || !stitchedEnd) return false;
-  for (const [index, candidate] of remaining.entries()) {
-    const candidateStart = candidate.points[0];
-    const candidateEnd = candidate.points.at(-1);
-    if (!candidateStart || !candidateEnd) continue;
-    if (altiumPointsApproximatelyEqual(stitchedEnd, candidateStart)) {
-      stitched.points.push(...candidate.points.slice(1));
-    } else if (altiumPointsApproximatelyEqual(stitchedEnd, candidateEnd)) {
-      stitched.points.push(...candidate.points.toReversed().slice(1));
-    } else if (altiumPointsApproximatelyEqual(stitchedStart, candidateEnd)) {
-      stitched.points.unshift(...candidate.points.slice(0, -1));
-    } else if (altiumPointsApproximatelyEqual(stitchedStart, candidateStart)) {
-      stitched.points.unshift(...candidate.points.toReversed().slice(0, -1));
-    } else {
-      continue;
-    }
-    remaining.splice(index, 1);
-    return true;
-  }
-  return false;
+  const first = group[0];
+  if (!first) return [];
+  return stitchConnectedAltiumPaths({
+    paths: group.map((path) => path.points),
+    maxEndpointGapMils: 0.01
+  }).map((points) => ({ ...first, points }));
 }
 function deduplicateCourtyardPaths(paths) {
   const signatures = /* @__PURE__ */ new Set();
@@ -225,7 +403,7 @@ function isClosedAltiumPath(points) {
   const last = points.at(-1);
   return Boolean(first && last && altiumPointsApproximatelyEqual(first, last));
 }
-function removeClosingPoint(points) {
+function removeClosingPoint2(points) {
   const first = points[0];
   const last = points.at(-1);
   return first && last && altiumPointsApproximatelyEqual(first, last) ? points.slice(0, -1) : points;
@@ -234,8 +412,9 @@ function altiumPointsApproximatelyEqual(left, right) {
   return Math.abs(left.x - right.x) <= 0.01 && Math.abs(left.y - right.y) <= 0.01;
 }
 function createBoard(document) {
-  const outline = document.boardGeometry.outline.points.map(toMillimeterPoint);
-  const bounds = getAltiumBounds(document.boardGeometry.outline.points) ?? getFallbackPcbBounds(document.records);
+  const altiumOutline = getPreferredPcbBoardOutline(document);
+  const outline = altiumOutline.map(toMillimeterPoint);
+  const bounds = getAltiumBounds2(altiumOutline) ?? getFallbackPcbBounds(document.records);
   const width = Math.max(milsToMillimeters(bounds.maxX - bounds.minX), 0.1);
   const height = Math.max(milsToMillimeters(bounds.maxY - bounds.minY), 0.1);
   const numLayers = document.board ? Math.max(
@@ -262,14 +441,14 @@ function createBoard(document) {
 function getFallbackPcbBounds(records) {
   const points = [];
   for (const record of records) {
-    if (record instanceof AltiumPadRecord || record instanceof AltiumViaRecord) {
+    if (record instanceof AltiumPadRecord2 || record instanceof AltiumViaRecord2) {
       if (record.position) points.push(record.position);
-    } else if (record instanceof AltiumTrackRecord) {
+    } else if (record instanceof AltiumTrackRecord2) {
       if (record.start) points.push(record.start);
       if (record.end) points.push(record.end);
     }
   }
-  return getAltiumBounds(points) ?? { minX: 0, minY: 0, maxX: 1e3, maxY: 800 };
+  return getAltiumBounds2(points) ?? { minX: 0, minY: 0, maxX: 1e3, maxY: 800 };
 }
 function convertTrack(record, index) {
   const start = record.start;
@@ -584,7 +763,7 @@ function mapTextAnchor(justification) {
   return "center";
 }
 function mapCopperLayer(layer) {
-  const normalized = normalizeLayer(layer);
+  const normalized = normalizeLayer2(layer);
   if (normalized === "TOP" || normalized === "TOPLAYER") return "top";
   if (normalized === "BOTTOM" || normalized === "BOTTOMLAYER") return "bottom";
   const innerMatch = /^(?:MID|MIDLAYER|INTERNALPLANE)(\d+)$/u.exec(normalized);
@@ -593,23 +772,23 @@ function mapCopperLayer(layer) {
   return `inner${innerNumber}`;
 }
 function isOverlayLayer(layer) {
-  const normalized = normalizeLayer(layer);
+  const normalized = normalizeLayer2(layer);
   return normalized === "TOPOVERLAY" || normalized === "BOTTOMOVERLAY";
 }
 function isCourtyardLayer(layer) {
-  const normalized = normalizeLayer(layer);
+  const normalized = normalizeLayer2(layer);
   return normalized === "MECHANICAL15" || normalized === "MECHANICAL16";
 }
 function mapCourtyardLayer(layer) {
-  return normalizeLayer(layer) === "MECHANICAL16" ? "bottom" : "top";
+  return normalizeLayer2(layer) === "MECHANICAL16" ? "bottom" : "top";
 }
 function mapOverlayLayer(layer) {
-  return normalizeLayer(layer) === "BOTTOMOVERLAY" ? "bottom" : "top";
+  return normalizeLayer2(layer) === "BOTTOMOVERLAY" ? "bottom" : "top";
 }
 function getLayer(record) {
   return record.getDecoded("LAYER");
 }
-function normalizeLayer(layer) {
+function normalizeLayer2(layer) {
   return (layer ?? "").replace(/[\s_.-]+/gu, "").toUpperCase();
 }
 function normalizeShape(shape) {
@@ -1130,35 +1309,56 @@ function createSourceComponent(params) {
     source_component_id: sourceComponentId
   };
   if (classification === "resistor") {
-    const parsed = source_simple_resistor.safeParse({
-      ...common,
-      display_resistance: value || void 0,
-      ftype: "simple_resistor",
-      resistance: primaryValue || 0
+    const resistance = parseFiniteComponentValue({
+      componentUnit: "\u03A9",
+      componentValue: primaryValue
     });
-    if (parsed.success) return parsed.data;
+    if (resistance !== void 0) {
+      const parsed = source_simple_resistor.safeParse({
+        ...common,
+        display_resistance: value || void 0,
+        ftype: "simple_resistor",
+        resistance
+      });
+      if (parsed.success) return parsed.data;
+    }
   }
   if (classification === "capacitor") {
-    const parsed = source_simple_capacitor.safeParse({
-      ...common,
-      display_capacitance: value || void 0,
-      ftype: "simple_capacitor",
-      capacitance: primaryValue || 0
+    const capacitance = parseFiniteComponentValue({
+      componentUnit: "F",
+      componentValue: primaryValue
     });
-    if (parsed.success) return parsed.data;
+    if (capacitance !== void 0) {
+      const parsed = source_simple_capacitor.safeParse({
+        ...common,
+        display_capacitance: value || void 0,
+        ftype: "simple_capacitor",
+        capacitance
+      });
+      if (parsed.success) return parsed.data;
+    }
   }
   if (classification === "inductor") {
-    const parsed = source_simple_inductor.safeParse({
-      ...common,
-      display_inductance: value || void 0,
-      ftype: "simple_inductor",
-      inductance: primaryValue || 0
+    const inductance = parseFiniteComponentValue({
+      componentUnit: "H",
+      componentValue: primaryValue
     });
-    if (parsed.success) return parsed.data;
+    if (inductance !== void 0) {
+      const parsed = source_simple_inductor.safeParse({
+        ...common,
+        display_inductance: value || void 0,
+        ftype: "simple_inductor",
+        inductance
+      });
+      if (parsed.success) return parsed.data;
+    }
   }
   if (classification === "crystal" && (pinCount === 2 || pinCount === 4)) {
-    const frequency = parseAndConvertSiUnit(value, "Hz").value;
-    if (typeof frequency === "number" && Number.isFinite(frequency)) {
+    const frequency = parseFiniteComponentValue({
+      componentUnit: "Hz",
+      componentValue: value
+    });
+    if (frequency !== void 0) {
       const parsed = source_simple_crystal.safeParse({
         ...common,
         frequency,
@@ -1182,6 +1382,19 @@ function createSourceComponent(params) {
     ftype
   };
 }
+function parseFiniteComponentValue({
+  componentUnit,
+  componentValue
+}) {
+  const parsedComponentValue = parseAndConvertSiUnit(
+    componentValue,
+    componentUnit
+  ).value;
+  if (typeof parsedComponentValue !== "number" || !Number.isFinite(parsedComponentValue)) {
+    return void 0;
+  }
+  return parsedComponentValue;
+}
 function createComponentText(params) {
   const { anchor, component, id, position, text } = params;
   return {