altium-toolkit 1.4.3 → 1.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "altium-toolkit",
-    "version": "1.4.3",
+    "version": "1.4.5",
     "description": "Altium document parsing and non-interactive rendering utilities",
     "keywords": [
         "altium",

package/src/convergence/PcbSideResolvedRenderModel.mjs

@@ -13,11 +13,13 @@ export class PcbSideResolvedRenderModel {
     /**
      * Resolves a normalized PCB model for the requested board side.
      * @param {object | null} board
-     * @param {'front' | 'back' | { side?: 'front' | 'back' }} [options]
+     * @param {'front' | 'back' | { side?: 'front' | 'back', includeOppositeCopper?: boolean }} [options]
      * @returns {object | null}
      */
     static resolve(board, options = {}) {
         const side = PcbSideResolvedRenderModel.#normalizeSide(options)
+        const includeOppositeCopper =
+            PcbSideResolvedRenderModel.#includeOppositeCopper(options)
         const resolved = HistoricalPcbSideResolvedRenderModel.resolve(
             board,
             options
@@ -52,7 +54,13 @@ export class PcbSideResolvedRenderModel {
                 boardRegions: PcbSideResolvedRenderModel.#filterPrimitives(
                     pcb.boardRegions,
                     side
-                )
+                ),
+                pads: includeOppositeCopper
+                    ? PcbSideResolvedRenderModel.#prepareContextPads(
+                          board?.pcb?.pads,
+                          side
+                      )
+                    : pcb.pads
             }
         }
     }
@@ -68,7 +76,7 @@ export class PcbSideResolvedRenderModel {
 
     /**
      * Normalizes the caller side option.
-     * @param {'front' | 'back' | { side?: 'front' | 'back' }} options
+     * @param {'front' | 'back' | { side?: 'front' | 'back', includeOppositeCopper?: boolean }} options
      * @returns {'front' | 'back'}
      */
     static #normalizeSide(options) {
@@ -79,6 +87,106 @@ export class PcbSideResolvedRenderModel {
         return 'front'
     }
 
+    /**
+     * Checks whether the caller requested opposite-side copper context.
+     * @param {'front' | 'back' | { side?: 'front' | 'back', includeOppositeCopper?: boolean }} options
+     * @returns {boolean}
+     */
+    static #includeOppositeCopper(options) {
+        return Boolean(
+            options &&
+            typeof options === 'object' &&
+            options.includeOppositeCopper === true
+        )
+    }
+
+    /**
+     * Projects every copper-bearing pad into the requested composite view.
+     * @param {readonly object[] | undefined} pads Source pads.
+     * @param {'front' | 'back'} side Requested board side.
+     * @returns {object[]}
+     */
+    static #prepareContextPads(pads, side) {
+        return (pads || []).map((pad) =>
+            PcbSideResolvedRenderModel.#projectPadForTopRenderer(pad, side)
+        )
+    }
+
+    /**
+     * Projects the authored aperture for one pad into the top-oriented
+     * renderer while retaining front-only apertures as opposite-side context.
+     * @param {object} pad Source pad.
+     * @param {'front' | 'back'} side Requested board side.
+     * @returns {object}
+     */
+    static #projectPadForTopRenderer(pad, side) {
+        const layerId = PcbSideResolvedRenderModel.#effectivePadLayerId(pad)
+        const apertureSide =
+            layerId === 1 ? 'front' : layerId === 32 ? 'back' : side
+        const projectedPad = {
+            ...pad,
+            copperRenderGroup: apertureSide === side ? 'surface' : 'subsurface'
+        }
+        if (apertureSide !== 'back') return projectedPad
+
+        return {
+            ...projectedPad,
+            sizeTopX: PcbSideResolvedRenderModel.#firstFiniteValue(
+                pad.sizeBottomX,
+                pad.sizeMidX,
+                pad.sizeTopX
+            ),
+            sizeTopY: PcbSideResolvedRenderModel.#firstFiniteValue(
+                pad.sizeBottomY,
+                pad.sizeMidY,
+                pad.sizeTopY
+            ),
+            shapeTop: PcbSideResolvedRenderModel.#firstFiniteValue(
+                pad.shapeBottom,
+                pad.shapeMid,
+                pad.shapeTop
+            ),
+            roundedRectShapeTop: PcbSideResolvedRenderModel.#firstFiniteValue(
+                pad.roundedRectShapeBottom,
+                pad.roundedRectShapeMid,
+                pad.roundedRectShapeTop
+            ),
+            cornerRadiusTop: PcbSideResolvedRenderModel.#firstFiniteValue(
+                pad.cornerRadiusBottom,
+                pad.cornerRadiusMid,
+                pad.cornerRadiusTop
+            )
+        }
+    }
+
+    /**
+     * Resolves the authored Altium layer id for a pad.
+     * @param {object | null} pad Pad to inspect.
+     * @returns {number | null}
+     */
+    static #effectivePadLayerId(pad) {
+        const layerId = Number(pad?.layerId)
+        if (Number.isInteger(layerId) && layerId > 0) return layerId
+
+        const legacyLayerId = Number(pad?.legacyLayerId)
+        return Number.isInteger(legacyLayerId) && legacyLayerId > 0
+            ? legacyLayerId
+            : null
+    }
+
+    /**
+     * Returns the first finite numeric value.
+     * @param {...unknown} values Values to inspect.
+     * @returns {number | undefined}
+     */
+    static #firstFiniteValue(...values) {
+        for (const value of values) {
+            const number = Number(value)
+            if (Number.isFinite(number)) return number
+        }
+        return undefined
+    }
+
     /**
      * Filters one primitive collection to the requested surface.
      * @param {readonly object[] | undefined} primitives
@@ -115,7 +223,7 @@ export class PcbSideResolvedRenderModel {
 /**
  * Resolves a normalized PCB model for the requested board side.
  * @param {object | null} board
- * @param {'front' | 'back' | { side?: 'front' | 'back' }} [options]
+ * @param {'front' | 'back' | { side?: 'front' | 'back', includeOppositeCopper?: boolean }} [options]
  * @returns {object | null}
  */
 export function preparePcbSideResolvedRenderModel(board, options = {}) {

package/src/convergence/PcbSvgRenderer.mjs

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { PcbSvgRenderer as LegacyPcbSvgRenderer } from '../ui/PcbSvgRenderer.mjs'
+
+/**
+ * Renders native Altium PCB models through the preserved historical renderer
+ * while applying convergence-owned copper grouping semantics.
+ */
+export class PcbSvgRenderer {
+    static #SUBSURFACE_GROUP = '<g class="pcb-copper pcb-copper--subsurface">'
+    static #SURFACE_GROUP = '<g class="pcb-copper pcb-copper--surface">'
+
+    /**
+     * Renders one native Altium PCB document as SVG markup.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @param {Record<string, any>} [options] Historical renderer options.
+     * @returns {string} Rendered SVG panel markup.
+     */
+    static render(documentModel, options = {}) {
+        const markup = LegacyPcbSvgRenderer.render(documentModel, options)
+        const subsurfacePadIndexes = PcbSvgRenderer.#subsurfacePadIndexes(
+            documentModel,
+            options
+        )
+        if (subsurfacePadIndexes.length === 0) return markup
+
+        return PcbSvgRenderer.#movePadsToSubsurfaceGroup(
+            markup,
+            subsurfacePadIndexes
+        )
+    }
+
+    /**
+     * Renders one deterministic SVG entry per physical or primitive layer.
+     * Layer exports intentionally preserve the historical layer-only output.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @returns {{ layerId?: number, layerKey: string, displayName: string, role: string, svg: string }[]}
+     */
+    static renderLayerSvgs(documentModel) {
+        return LegacyPcbSvgRenderer.renderLayerSvgs(documentModel)
+    }
+
+    /**
+     * Finds pad indexes whose copper must share the contextual copper group.
+     * Layer-only exports do not use composite surface/subsurface grouping.
+     * @param {Record<string, any>} documentModel Native renderer document.
+     * @param {Record<string, any>} options Historical renderer options.
+     * @returns {number[]} Stable pad indexes.
+     */
+    static #subsurfacePadIndexes(documentModel, options) {
+        if (options?.layerView) return []
+
+        return (documentModel?.pcb?.pads || [])
+            .map((pad, index) =>
+                pad?.copperRenderGroup === 'subsurface' ? index : -1
+            )
+            .filter((index) => index >= 0)
+    }
+
+    /**
+     * Moves contextual pad groups into the same SVG group as contextual traces
+     * so the browser composites both primitives with one shared opacity.
+     * @param {string} markup Historical renderer markup.
+     * @param {number[]} padIndexes Stable pad indexes to relocate.
+     * @returns {string} Copper-group-aware markup.
+     */
+    static #movePadsToSubsurfaceGroup(markup, padIndexes) {
+        const subsurfaceStart = markup.indexOf(PcbSvgRenderer.#SUBSURFACE_GROUP)
+        const surfaceStart = markup.indexOf(PcbSvgRenderer.#SURFACE_GROUP)
+        if (subsurfaceStart < 0 || surfaceStart <= subsurfaceStart) {
+            return markup
+        }
+
+        const subsurfaceClose = markup.lastIndexOf('</g>', surfaceStart)
+        if (subsurfaceClose < subsurfaceStart) return markup
+
+        let remainingMarkup = markup
+        const relocatedPads = []
+        for (const padIndex of padIndexes) {
+            const result = PcbSvgRenderer.#extractPadGroup(
+                remainingMarkup,
+                padIndex,
+                surfaceStart
+            )
+            if (!result) continue
+            remainingMarkup = result.markup
+            relocatedPads.push(result.padMarkup)
+        }
+        if (relocatedPads.length === 0) return markup
+
+        const updatedSurfaceStart = remainingMarkup.indexOf(
+            PcbSvgRenderer.#SURFACE_GROUP
+        )
+        const updatedSubsurfaceClose = remainingMarkup.lastIndexOf(
+            '</g>',
+            updatedSurfaceStart
+        )
+        return (
+            remainingMarkup.slice(0, updatedSubsurfaceClose) +
+            relocatedPads.join('') +
+            remainingMarkup.slice(updatedSubsurfaceClose)
+        )
+    }
+
+    /**
+     * Extracts one top-level pad group from the historical surface group.
+     * Pad groups contain only leaf SVG shapes, so their first closing group is
+     * also the matching closing tag.
+     * @param {string} markup Current renderer markup.
+     * @param {number} padIndex Stable pad index.
+     * @param {number} minimumStart Earliest valid surface-group position.
+     * @returns {{ markup: string, padMarkup: string } | null} Extraction result.
+     */
+    static #extractPadGroup(markup, padIndex, minimumStart) {
+        const elementKey = 'data-element-key="pcb-pad-' + padIndex + '"'
+        const keyStart = markup.indexOf(elementKey, minimumStart)
+        if (keyStart < 0) return null
+
+        const groupStart = markup.lastIndexOf('<g', keyStart)
+        const groupEndStart = markup.indexOf('</g>', keyStart)
+        if (groupStart < minimumStart || groupEndStart < 0) return null
+
+        const groupEnd = groupEndStart + '</g>'.length
+        return {
+            markup: markup.slice(0, groupStart) + markup.slice(groupEnd),
+            padMarkup: markup.slice(groupStart, groupEnd)
+        }
+    }
+}

package/src/extensions.mjs

@@ -4,6 +4,7 @@
 export * from 'circuitjson-toolkit/extensions'
 
 export { AltiumExtensionResolver } from './convergence/AltiumExtensionResolver.mjs'
+export { PcbSvgRenderer } from './convergence/PcbSvgRenderer.mjs'
 export { SchematicSvgRenderer } from './convergence/SchematicSvgRenderer.mjs'
 export * from './legacy-parser.mjs'
 export * from './legacy-netlist-query.mjs'

package/src/styles/altium-renderers.css

@@ -270,6 +270,10 @@
     fill: var(--pcb-copper-solid-fill);
 }
 
+.pcb-copper--subsurface .pcb-pad--smd .pcb-pad__ring {
+    fill: var(--pcb-subsurface-track-color);
+}
+
 .pcb-footprint-fill {
     fill: var(--pcb-footprint-fill);
 }