altium-toolkit 0.1.23 → 1.0.1

package/src/core/netlist-query/QueryNetlistBuilder.mjs

@@ -0,0 +1,180 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ComponentGrouping } from './ComponentGrouping.mjs'
+
+/**
+ * Builds compact query netlists from normalized toolkit document models.
+ */
+export class QueryNetlistBuilder {
+    /**
+     * Builds the query netlist for one document model.
+     * @param {object} documentModel Document model.
+     * @returns {{ nets: object, components: object }}
+     */
+    static build(documentModel) {
+        const components =
+            QueryNetlistBuilder.#buildComponentDetails(documentModel)
+        const nets = {}
+
+        for (const net of documentModel?.schematic?.nets || []) {
+            const netName = String(net?.name || '').trim()
+            if (!netName) continue
+
+            for (const pin of net.pins || []) {
+                const refdes = QueryNetlistBuilder.#resolvePinRefdes(
+                    pin,
+                    components
+                )
+                const pinNumber = QueryNetlistBuilder.#resolvePinNumber(pin)
+                if (!refdes || !pinNumber) continue
+
+                nets[netName] ||= {}
+                const existing = nets[netName][refdes]
+                nets[netName][refdes] = QueryNetlistBuilder.#appendPin(
+                    existing,
+                    pinNumber
+                )
+                components[refdes] ||= { pins: {} }
+                components[refdes].pins[pinNumber] =
+                    QueryNetlistBuilder.#pinEntry(pinNumber, pin?.name, netName)
+            }
+        }
+
+        return { nets, components }
+    }
+
+    /**
+     * Builds component metadata from schematic, PCB, and BOM records.
+     * @param {object} documentModel Document model.
+     * @returns {object}
+     */
+    static #buildComponentDetails(documentModel) {
+        const components = {}
+
+        for (const component of documentModel?.schematic?.components || []) {
+            const refdes = String(component?.designator || '').trim()
+            if (!refdes) continue
+            components[refdes] = {
+                ...components[refdes],
+                value: component.value || components[refdes]?.value,
+                description:
+                    component.description || components[refdes]?.description,
+                comment: component.comment || components[refdes]?.comment,
+                ownerIndex:
+                    component.ownerIndex || components[refdes]?.ownerIndex,
+                dns:
+                    component.dns ||
+                    component.excludeFromBom ||
+                    components[refdes]?.dns,
+                excludeFromBom:
+                    component.excludeFromBom ||
+                    components[refdes]?.excludeFromBom,
+                pins: components[refdes]?.pins || {}
+            }
+        }
+
+        for (const component of documentModel?.pcb?.components || []) {
+            const refdes = String(component?.designator || '').trim()
+            if (!refdes) continue
+            components[refdes] = {
+                ...components[refdes],
+                description:
+                    component.description ||
+                    component.pattern ||
+                    components[refdes]?.description,
+                value: component.value || components[refdes]?.value,
+                comment: component.comment || components[refdes]?.comment,
+                pins: components[refdes]?.pins || {}
+            }
+        }
+
+        for (const row of documentModel?.bom || []) {
+            for (const refdes of row.designators || []) {
+                const normalizedRefdes = String(refdes || '').trim()
+                if (!normalizedRefdes) continue
+                components[normalizedRefdes] = {
+                    ...components[normalizedRefdes],
+                    mpn: row.pattern || components[normalizedRefdes]?.mpn,
+                    description:
+                        row.source || components[normalizedRefdes]?.description,
+                    value: row.value || components[normalizedRefdes]?.value,
+                    pins: components[normalizedRefdes]?.pins || {}
+                }
+            }
+        }
+
+        return components
+    }
+
+    /**
+     * Resolves a pin's owning reference designator.
+     * @param {object} pin Net pin.
+     * @param {object} components Component details.
+     * @returns {string}
+     */
+    static #resolvePinRefdes(pin, components) {
+        const direct = String(
+            pin?.refdes ||
+                pin?.componentRefdes ||
+                pin?.componentDesignator ||
+                pin?.ownerDesignator ||
+                ''
+        ).trim()
+        if (direct) return direct
+
+        const ownerIndex = String(pin?.ownerIndex || '').trim()
+        if (!ownerIndex) return ''
+
+        return (
+            Object.entries(components).find(([, component]) => {
+                return String(component.ownerIndex || '') === ownerIndex
+            })?.[0] || ''
+        )
+    }
+
+    /**
+     * Resolves a pin number.
+     * @param {object} pin Net pin.
+     * @returns {string}
+     */
+    static #resolvePinNumber(pin) {
+        return String(
+            pin?.pinNumber || pin?.number || pin?.designator || ''
+        ).trim()
+    }
+
+    /**
+     * Appends a pin to a compact net connection value.
+     * @param {string | string[] | undefined} existing Existing pins.
+     * @param {string} pinNumber Pin number.
+     * @returns {string | string[]}
+     */
+    static #appendPin(existing, pinNumber) {
+        if (!existing) return pinNumber
+        const pins = Array.isArray(existing) ? existing : [existing]
+        if (!pins.includes(pinNumber)) {
+            pins.push(pinNumber)
+        }
+        return ComponentGrouping.compactArray(
+            pins.sort(ComponentGrouping.naturalSort)
+        )
+    }
+
+    /**
+     * Builds a compact pin entry.
+     * @param {string} pinNumber Pin number.
+     * @param {string | undefined} pinName Pin name.
+     * @param {string} netName Net name.
+     * @returns {string | { name: string, net: string }}
+     */
+    static #pinEntry(pinNumber, pinName, netName) {
+        const normalizedName = String(pinName || '').trim()
+        if (normalizedName && normalizedName !== pinNumber) {
+            return { name: normalizedName, net: netName }
+        }
+
+        return netName
+    }
+}

package/src/core/netlist-query/RegexPattern.mjs

@@ -0,0 +1,89 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Regex helpers for netlist query tools.
+ */
+export class RegexPattern {
+    /**
+     * Parses a user regex pattern into a JavaScript RegExp.
+     * @param {string} pattern User-provided pattern.
+     * @param {string} [flags] RegExp flags.
+     * @returns {{ regex: RegExp } | { error: string }}
+     */
+    static parse(pattern, flags = 'i') {
+        const normalizedPattern = RegexPattern.#normalizeInlineFlags(pattern)
+        const normalizedFlags = RegexPattern.#normalizeFlags(
+            flags,
+            normalizedPattern.forceIgnoreCase
+        )
+
+        try {
+            return {
+                regex: new RegExp(normalizedPattern.pattern, normalizedFlags)
+            }
+        } catch (error) {
+            return {
+                error:
+                    'Invalid regex pattern ' +
+                    JSON.stringify(String(pattern || '')) +
+                    ': ' +
+                    (error instanceof Error ? error.message : String(error))
+            }
+        }
+    }
+
+    /**
+     * Returns true when a pattern matches every candidate value.
+     * @param {string} pattern User-provided pattern.
+     * @param {string[]} candidates Candidate values.
+     * @returns {boolean}
+     */
+    static rejectsBroadMatch(pattern, candidates) {
+        const parsed = RegexPattern.parse(pattern)
+        if (parsed.error || !Array.isArray(candidates) || !candidates.length) {
+            return false
+        }
+
+        return candidates.every((candidate) => {
+            parsed.regex.lastIndex = 0
+            return parsed.regex.test(String(candidate || ''))
+        })
+    }
+
+    /**
+     * Normalizes a leading `(?i)` flag into JavaScript RegExp flags.
+     * @param {string} pattern User-provided pattern.
+     * @returns {{ pattern: string, forceIgnoreCase: boolean }}
+     */
+    static #normalizeInlineFlags(pattern) {
+        const source = String(pattern || '')
+        if (source.startsWith('(?i)')) {
+            return {
+                pattern: source.slice(4),
+                forceIgnoreCase: true
+            }
+        }
+
+        return {
+            pattern: source,
+            forceIgnoreCase: false
+        }
+    }
+
+    /**
+     * Adds the ignore-case flag when requested.
+     * @param {string} flags RegExp flags.
+     * @param {boolean} forceIgnoreCase Whether to force `i`.
+     * @returns {string}
+     */
+    static #normalizeFlags(flags, forceIgnoreCase) {
+        const uniqueFlags = new Set(String(flags || '').split(''))
+        if (forceIgnoreCase) {
+            uniqueFlags.add('i')
+        }
+
+        return [...uniqueFlags].join('')
+    }
+}

package/src/netlist-query.mjs

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+export { RegexPattern } from './core/netlist-query/RegexPattern.mjs'
+export {
+    ComponentGrouping,
+    MPN_MISSING_NOTE
+} from './core/netlist-query/ComponentGrouping.mjs'
+export { CircuitTraversal } from './core/netlist-query/CircuitTraversal.mjs'
+export { QueryNetlistBuilder } from './core/netlist-query/QueryNetlistBuilder.mjs'
+export { LoadedDesignNetlistService } from './core/netlist-query/LoadedDesignNetlistService.mjs'

package/src/parser.mjs

@@ -11,6 +11,8 @@ export { AltiumLayoutParser } from './core/altium/AltiumLayoutParser.mjs'
 export { AsciiRecordParser } from './core/altium/AsciiRecordParser.mjs'
 export { ParserUtils } from './core/altium/ParserUtils.mjs'
 export { NormalizedModelSchema } from './core/altium/NormalizedModelSchema.mjs'
+export { CircuitJsonModelSchema } from './core/circuit-json/CircuitJsonModelSchema.mjs'
+export { CircuitJsonModelAdapter } from './core/circuit-json/CircuitJsonModelAdapter.mjs'
 export { PcbBinaryPrimitiveParser } from './core/altium/PcbBinaryPrimitiveParser.mjs'
 export { PcbBoardRegionSemanticsParser } from './core/altium/PcbBoardRegionSemanticsParser.mjs'
 export { PcbComponentPrimitiveIndexer } from './core/altium/PcbComponentPrimitiveIndexer.mjs'

package/src/ui/PcbScene3dBoardOutlineRefiner.mjs

@@ -0,0 +1,402 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Refines Altium 3D board outlines when parser recovery emitted a rasterized
+ * stair-step contour even though the document still carries a smoother board
+ * region contour.
+ */
+export class PcbScene3dBoardOutlineRefiner {
+    static #MIN_RASTERIZED_SEGMENTS = 16
+    static #MIN_SHORT_SEGMENT_RATIO = 0.35
+    static #MIN_AXIS_ALIGNED_RATIO = 0.9
+    static #SHORT_SEGMENT_MAX_MIL = 24
+    static #POINT_EPSILON_MIL = 0.25
+    static #AREA_RATIO_MIN = 0.75
+    static #AREA_RATIO_MAX = 1.25
+
+    /**
+     * Returns a scene description with a refined board outline when a better
+     * board-region contour is available.
+     * @param {object} sceneDescription Built scene description.
+     * @param {object} documentModel Source PCB document model.
+     * @returns {object}
+     */
+    static refine(sceneDescription, documentModel) {
+        const board = sceneDescription?.board
+        const segments = Array.isArray(board?.segments) ? board.segments : []
+
+        if (
+            !PcbScene3dBoardOutlineRefiner.#isRasterizedManhattanOutline(
+                segments
+            )
+        ) {
+            return sceneDescription
+        }
+
+        const currentOutline =
+            documentModel?.pcb?.boardOutline || sceneDescription?.board || {}
+        const candidate = PcbScene3dBoardOutlineRefiner.#selectCandidate(
+            documentModel?.pcb?.boardRegions,
+            currentOutline
+        )
+
+        if (!candidate) {
+            return sceneDescription
+        }
+
+        return {
+            ...sceneDescription,
+            board: {
+                ...board,
+                minX: candidate.minX,
+                minY: candidate.minY,
+                widthMil: candidate.widthMil,
+                heightMil: candidate.heightMil,
+                centerX: candidate.minX + candidate.widthMil / 2,
+                centerY: candidate.minY + candidate.heightMil / 2,
+                segments: candidate.segments
+            }
+        }
+    }
+
+    /**
+     * Returns true when an outline looks like a raster-grid recovery of a
+     * curved board route instead of authored geometric segments.
+     * @param {Array<Record<string, number | string>>} segments Outline segments.
+     * @returns {boolean}
+     */
+    static #isRasterizedManhattanOutline(segments) {
+        if (
+            segments.length <
+            PcbScene3dBoardOutlineRefiner.#MIN_RASTERIZED_SEGMENTS
+        ) {
+            return false
+        }
+
+        if (segments.some((segment) => segment.type === 'arc')) {
+            return false
+        }
+
+        let axisAlignedCount = 0
+        let shortSegmentCount = 0
+
+        for (const segment of segments) {
+            const dx = Math.abs(
+                Number(segment.x2 || 0) - Number(segment.x1 || 0)
+            )
+            const dy = Math.abs(
+                Number(segment.y2 || 0) - Number(segment.y1 || 0)
+            )
+            const length = Math.hypot(dx, dy)
+
+            if (dx <= 0.001 || dy <= 0.001) {
+                axisAlignedCount += 1
+            }
+            if (
+                length <= PcbScene3dBoardOutlineRefiner.#SHORT_SEGMENT_MAX_MIL
+            ) {
+                shortSegmentCount += 1
+            }
+        }
+
+        return (
+            axisAlignedCount / segments.length >=
+                PcbScene3dBoardOutlineRefiner.#MIN_AXIS_ALIGNED_RATIO &&
+            shortSegmentCount / segments.length >=
+                PcbScene3dBoardOutlineRefiner.#MIN_SHORT_SEGMENT_RATIO
+        )
+    }
+
+    /**
+     * Chooses the best compatible board-region contour.
+     * @param {object[] | undefined} regions Candidate board regions.
+     * @param {object} currentOutline Current outline bounds and segments.
+     * @returns {object | null}
+     */
+    static #selectCandidate(regions, currentOutline) {
+        const currentBounds =
+            PcbScene3dBoardOutlineRefiner.#resolveOutlineBounds(currentOutline)
+        if (!currentBounds) {
+            return null
+        }
+
+        const currentArea = Math.abs(
+            PcbScene3dBoardOutlineRefiner.#computeAreaFromSegments(
+                currentOutline?.segments || []
+            )
+        )
+        const candidates = (Array.isArray(regions) ? regions : [])
+            .filter((region) =>
+                PcbScene3dBoardOutlineRefiner.#isBoardRegionCandidate(region)
+            )
+            .map((region) =>
+                PcbScene3dBoardOutlineRefiner.#buildOutlineFromPoints(
+                    region.points
+                )
+            )
+            .filter(Boolean)
+            .filter((outline) =>
+                PcbScene3dBoardOutlineRefiner.#boundsAreCompatible(
+                    currentBounds,
+                    outline
+                )
+            )
+            .filter((outline) =>
+                PcbScene3dBoardOutlineRefiner.#areaIsCompatible(
+                    currentArea,
+                    outline
+                )
+            )
+            .map((outline) => ({
+                outline,
+                score: PcbScene3dBoardOutlineRefiner.#scoreBounds(
+                    currentBounds,
+                    outline
+                )
+            }))
+            .sort((left, right) => left.score - right.score)
+
+        return candidates[0]?.outline || null
+    }
+
+    /**
+     * Returns true when a region can represent the board body boundary.
+     * @param {object} region Source board region.
+     * @returns {boolean}
+     */
+    static #isBoardRegionCandidate(region) {
+        return (
+            Array.isArray(region?.points) &&
+            region.points.length >= 3 &&
+            (region?.objectKind === 'BoardRegion' ||
+                region?.isBoardCutout === true ||
+                Number.isInteger(region?.boardRegionIndex))
+        )
+    }
+
+    /**
+     * Converts one point loop into outline bounds and line segments.
+     * @param {{ x?: number, y?: number }[] | undefined} points Source points.
+     * @returns {object | null}
+     */
+    static #buildOutlineFromPoints(points) {
+        const normalizedPoints =
+            PcbScene3dBoardOutlineRefiner.#normalizePointLoop(points)
+
+        if (normalizedPoints.length < 3) {
+            return null
+        }
+
+        let minX = Number.POSITIVE_INFINITY
+        let minY = Number.POSITIVE_INFINITY
+        let maxX = Number.NEGATIVE_INFINITY
+        let maxY = Number.NEGATIVE_INFINITY
+
+        for (const point of normalizedPoints) {
+            minX = Math.min(minX, point.x)
+            minY = Math.min(minY, point.y)
+            maxX = Math.max(maxX, point.x)
+            maxY = Math.max(maxY, point.y)
+        }
+
+        const segments = normalizedPoints.map((point, index) => {
+            const next = normalizedPoints[(index + 1) % normalizedPoints.length]
+
+            return {
+                type: 'line',
+                x1: point.x,
+                y1: point.y,
+                x2: next.x,
+                y2: next.y
+            }
+        })
+
+        return {
+            minX,
+            minY,
+            widthMil: maxX - minX,
+            heightMil: maxY - minY,
+            segments
+        }
+    }
+
+    /**
+     * Normalizes finite points and drops duplicated adjacent points.
+     * @param {{ x?: number, y?: number }[] | undefined} points Source points.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #normalizePointLoop(points) {
+        const output = []
+
+        for (const point of Array.isArray(points) ? points : []) {
+            const nextPoint = {
+                x: Number(point?.x),
+                y: Number(point?.y)
+            }
+
+            if (
+                !Number.isFinite(nextPoint.x) ||
+                !Number.isFinite(nextPoint.y)
+            ) {
+                continue
+            }
+
+            if (
+                output.length &&
+                PcbScene3dBoardOutlineRefiner.#distanceBetween(
+                    output[output.length - 1],
+                    nextPoint
+                ) <= PcbScene3dBoardOutlineRefiner.#POINT_EPSILON_MIL
+            ) {
+                continue
+            }
+
+            output.push(nextPoint)
+        }
+
+        if (
+            output.length > 1 &&
+            PcbScene3dBoardOutlineRefiner.#distanceBetween(
+                output[0],
+                output[output.length - 1]
+            ) <= PcbScene3dBoardOutlineRefiner.#POINT_EPSILON_MIL
+        ) {
+            output.pop()
+        }
+
+        return output
+    }
+
+    /**
+     * Resolves bounds from an outline object.
+     * @param {object} outline Outline-like object.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number, widthMil: number, heightMil: number } | null}
+     */
+    static #resolveOutlineBounds(outline) {
+        const minX = Number(outline?.minX)
+        const minY = Number(outline?.minY)
+        const widthMil = Number(outline?.widthMil)
+        const heightMil = Number(outline?.heightMil)
+
+        if (
+            !Number.isFinite(minX) ||
+            !Number.isFinite(minY) ||
+            !Number.isFinite(widthMil) ||
+            !Number.isFinite(heightMil) ||
+            widthMil <= 0 ||
+            heightMil <= 0
+        ) {
+            return null
+        }
+
+        return {
+            minX,
+            minY,
+            maxX: minX + widthMil,
+            maxY: minY + heightMil,
+            widthMil,
+            heightMil
+        }
+    }
+
+    /**
+     * Returns true when a candidate's envelope matches the current board.
+     * @param {object} current Current outline bounds.
+     * @param {object} candidate Candidate outline bounds.
+     * @returns {boolean}
+     */
+    static #boundsAreCompatible(current, candidate) {
+        const tolerance = Math.max(
+            Math.max(current.widthMil, current.heightMil) * 0.06,
+            40
+        )
+        const candidateBounds =
+            PcbScene3dBoardOutlineRefiner.#resolveOutlineBounds(candidate)
+
+        if (!candidateBounds) {
+            return false
+        }
+
+        return (
+            Math.abs(current.minX - candidateBounds.minX) <= tolerance &&
+            Math.abs(current.minY - candidateBounds.minY) <= tolerance &&
+            Math.abs(current.maxX - candidateBounds.maxX) <= tolerance &&
+            Math.abs(current.maxY - candidateBounds.maxY) <= tolerance
+        )
+    }
+
+    /**
+     * Returns true when the candidate area is close enough to the fallback.
+     * @param {number} currentArea Current outline area.
+     * @param {object} candidate Candidate outline.
+     * @returns {boolean}
+     */
+    static #areaIsCompatible(currentArea, candidate) {
+        if (!currentArea) {
+            return true
+        }
+
+        const candidateArea = Math.abs(
+            PcbScene3dBoardOutlineRefiner.#computeAreaFromSegments(
+                candidate?.segments || []
+            )
+        )
+        const ratio = candidateArea / currentArea
+
+        return (
+            ratio >= PcbScene3dBoardOutlineRefiner.#AREA_RATIO_MIN &&
+            ratio <= PcbScene3dBoardOutlineRefiner.#AREA_RATIO_MAX
+        )
+    }
+
+    /**
+     * Scores how closely candidate bounds match current bounds.
+     * @param {object} current Current outline bounds.
+     * @param {object} candidate Candidate outline bounds.
+     * @returns {number}
+     */
+    static #scoreBounds(current, candidate) {
+        const candidateBounds =
+            PcbScene3dBoardOutlineRefiner.#resolveOutlineBounds(candidate)
+
+        if (!candidateBounds) {
+            return Number.POSITIVE_INFINITY
+        }
+
+        return (
+            Math.abs(current.minX - candidateBounds.minX) +
+            Math.abs(current.minY - candidateBounds.minY) +
+            Math.abs(current.maxX - candidateBounds.maxX) +
+            Math.abs(current.maxY - candidateBounds.maxY)
+        )
+    }
+
+    /**
+     * Computes signed area from line segments.
+     * @param {Array<Record<string, number | string>>} segments Outline segments.
+     * @returns {number}
+     */
+    static #computeAreaFromSegments(segments) {
+        let area = 0
+
+        for (const segment of segments) {
+            area +=
+                Number(segment.x1 || 0) * Number(segment.y2 || 0) -
+                Number(segment.x2 || 0) * Number(segment.y1 || 0)
+        }
+
+        return area / 2
+    }
+
+    /**
+     * Measures the distance between two points.
+     * @param {{ x: number, y: number }} left First point.
+     * @param {{ x: number, y: number }} right Second point.
+     * @returns {number}
+     */
+    static #distanceBetween(left, right) {
+        return Math.hypot(right.x - left.x, right.y - left.y)
+    }
+}