altium-toolkit 1.1.24 → 1.1.26

package/src/core/altium/LibraryQaReportBuilder.mjs

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { LibraryCompatibilityReportBuilder } from './LibraryCompatibilityReportBuilder.mjs'
+
 /**
  * Builds deterministic QA reports across parsed schematic and PCB libraries.
  */
@@ -33,6 +35,10 @@ export class LibraryQaReportBuilder {
             schematicLibraries,
             pcbLibraries
         )
+        const compatibility = LibraryCompatibilityReportBuilder.build({
+            schematicLibraries,
+            pcbLibraries
+        })
         const mergePlan =
             LibraryQaReportBuilder.#schematicLibraryMergePlan(
                 schematicLibraries
@@ -74,7 +80,8 @@ export class LibraryQaReportBuilder {
                     diagnostic.symbolName
                 )
             ),
-            ...libraryLint.issues
+            ...libraryLint.issues,
+            ...(compatibility.issues || [])
         ]
         const issuesBySeverity =
             LibraryQaReportBuilder.#issueSeverityCounts(issues)
@@ -91,6 +98,7 @@ export class LibraryQaReportBuilder {
                 multipartMismatchCount: multipartMismatches.length,
                 mergePlanConflictCount: mergePlan.summary.conflictCount,
                 libraryLintIssueCount: libraryLint.summary.issueCount,
+                ...LibraryQaReportBuilder.#compatibilitySummary(compatibility),
                 issuesBySeverity,
                 issueCount: issues.length
             },
@@ -102,6 +110,7 @@ export class LibraryQaReportBuilder {
             missingModels,
             multipartMismatches,
             libraryLint,
+            compatibility,
             mergePlan,
             issues
         }
@@ -680,6 +689,25 @@ export class LibraryQaReportBuilder {
         return counts
     }
 
+    /**
+     * Builds optional compatibility counters for non-empty reports.
+     * @param {object} compatibility Compatibility report.
+     * @returns {object}
+     */
+    static #compatibilitySummary(compatibility) {
+        const summary = compatibility?.summary || {}
+        const issueCount = Number(summary.issueCount || 0)
+
+        if (!issueCount) return {}
+
+        return {
+            compatibilityIssueCount: issueCount,
+            hiddenPinCount: Number(summary.hiddenPinCount || 0),
+            padDiagnosticCount: Number(summary.padDiagnosticCount || 0),
+            modelSuggestionCount: Number(summary.modelSuggestionCount || 0)
+        }
+    }
+
     /**
      * Builds duplicate-symbol merge-plan rows.
      * @param {object[]} schematicLibraries Schematic libraries.

package/src/core/altium/PcbDimensionParser.mjs

@@ -173,6 +173,7 @@ export class PcbDimensionParser {
     static #normalizeKind(kindCode) {
         const normalized = String(kindCode || '').toLowerCase()
         if (/ang/u.test(normalized)) return 'angular'
+        if (/diam/u.test(normalized)) return 'diameter'
         if (/radial|radius/u.test(normalized)) return 'radial'
         if (/datum/u.test(normalized)) return 'datum'
         if (/baseline/u.test(normalized)) return 'baseline'

package/src/core/altium/PcbDimensionReportBuilder.mjs

@@ -0,0 +1,190 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+/**
+ * Builds deterministic QA summaries for recovered PCB dimension records.
+ */
+export class PcbDimensionReportBuilder {
+    static SCHEMA = 'altium-toolkit.pcb.dimensions.a1'
+
+    /**
+     * Builds a dimension QA report from a parser root or PCB model.
+     * @param {object} input Parser root, PCB model, or options object.
+     * @returns {object}
+     */
+    static build(input = {}) {
+        const pcb = PcbDimensionReportBuilder.#pcb(input)
+        const dimensions = PcbDimensionReportBuilder.#dimensions(pcb)
+        const rows = dimensions.map((dimension) =>
+            PcbDimensionReportBuilder.#dimensionRow(dimension)
+        )
+        const findings = rows.flatMap((row) =>
+            PcbDimensionReportBuilder.#findingsForRow(row)
+        )
+
+        return {
+            schema: PcbDimensionReportBuilder.SCHEMA,
+            summary: PcbDimensionReportBuilder.#summary(rows),
+            dimensions: rows,
+            findings
+        }
+    }
+
+    /**
+     * Resolves the PCB payload from a parser root or direct PCB model.
+     * @param {object} input Parser root or PCB model.
+     * @returns {object}
+     */
+    static #pcb(input) {
+        return input?.pcb || input || {}
+    }
+
+    /**
+     * Resolves normalized dimension rows from a PCB payload.
+     * @param {object} pcb PCB model.
+     * @returns {object[]}
+     */
+    static #dimensions(pcb) {
+        return Array.isArray(pcb?.dimensions) ? pcb.dimensions : []
+    }
+
+    /**
+     * Builds one public dimension report row.
+     * @param {object} dimension Normalized dimension record.
+     * @returns {object}
+     */
+    static #dimensionRow(dimension) {
+        const kind = PcbDimensionReportBuilder.#kind(dimension)
+        const references = Array.isArray(dimension?.references)
+            ? dimension.references
+            : []
+        const requiredReferenceCount =
+            PcbDimensionReportBuilder.#requiredReferenceCount(kind)
+        const status =
+            references.length >= requiredReferenceCount
+                ? 'renderable'
+                : 'unresolved'
+
+        return PcbDimensionReportBuilder.#stripEmpty({
+            dimensionIndex: PcbDimensionReportBuilder.#integerOrFallback(
+                dimension?.dimensionIndex,
+                0
+            ),
+            kind,
+            name: dimension?.name || '',
+            layer: dimension?.layer || '',
+            text: dimension?.text || '',
+            status,
+            referenceCount: references.length,
+            requiredReferenceCount,
+            hasTextLocation: Boolean(dimension?.textLocation),
+            measuredValue: dimension?.measuredValue ?? undefined,
+            angleValue: dimension?.angleValue ?? undefined,
+            unit: dimension?.unit || ''
+        })
+    }
+
+    /**
+     * Builds report findings for one dimension row.
+     * @param {object} row Dimension report row.
+     * @returns {object[]}
+     */
+    static #findingsForRow(row) {
+        if (row.status !== 'unresolved') {
+            return []
+        }
+
+        return [
+            PcbDimensionReportBuilder.#stripEmpty({
+                code: 'pcb.dimension.missing-reference',
+                severity: 'warning',
+                dimensionIndex: row.dimensionIndex,
+                kind: row.kind,
+                name: row.name,
+                referenceCount: row.referenceCount,
+                requiredReferenceCount: row.requiredReferenceCount
+            })
+        ]
+    }
+
+    /**
+     * Builds top-level dimension counters.
+     * @param {object[]} rows Dimension report rows.
+     * @returns {object}
+     */
+    static #summary(rows) {
+        const byKind = new Map()
+
+        for (const row of rows) {
+            byKind.set(row.kind, Number(byKind.get(row.kind) || 0) + 1)
+        }
+
+        return {
+            dimensionCount: rows.length,
+            renderableCount: rows.filter((row) => row.status === 'renderable')
+                .length,
+            unresolvedCount: rows.filter((row) => row.status === 'unresolved')
+                .length,
+            missingTextLocationCount: rows.filter(
+                (row) => row.hasTextLocation !== true
+            ).length,
+            byKind: [...byKind.entries()]
+                .map(([kind, count]) => ({ kind, count }))
+                .sort((left, right) =>
+                    left.kind.localeCompare(right.kind, undefined, {
+                        numeric: true
+                    })
+                )
+        }
+    }
+
+    /**
+     * Resolves the canonical dimension kind.
+     * @param {object} dimension Dimension record.
+     * @returns {string}
+     */
+    static #kind(dimension) {
+        const kind = String(dimension?.kind || '')
+            .trim()
+            .toLowerCase()
+        return kind || 'linear'
+    }
+
+    /**
+     * Returns the minimum reference count needed for deterministic rendering.
+     * @param {string} kind Dimension kind.
+     * @returns {number}
+     */
+    static #requiredReferenceCount(kind) {
+        if (kind === 'angular') {
+            return 3
+        }
+
+        return 2
+    }
+
+    /**
+     * Parses an integer with a fallback.
+     * @param {unknown} value Numeric candidate.
+     * @param {number} fallback Fallback value.
+     * @returns {number}
+     */
+    static #integerOrFallback(value, fallback) {
+        const number = Number(value)
+        return Number.isInteger(number) ? number : fallback
+    }
+
+    /**
+     * Removes undefined and blank-string values from a shallow object.
+     * @param {Record<string, unknown>} row Input row.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(row) {
+        return Object.fromEntries(
+            Object.entries(row).filter(
+                ([, value]) => value !== undefined && value !== ''
+            )
+        )
+    }
+}

package/src/core/altium/PcbEmbeddedModelExtractor.mjs

@@ -7,6 +7,7 @@
 // specifier.
 import { unzlibSync } from 'fflate'
 import { PrintableTextDecoder } from './PrintableTextDecoder.mjs'
+import { PcbShapeBasedBodyGeometryParser } from './PcbShapeBasedBodyGeometryParser.mjs'
 
 /**
  * Extracts embedded 3D model payloads and component-body placement metadata
@@ -17,7 +18,7 @@ export class PcbEmbeddedModelExtractor {
      * Extracts embedded model payloads and component-body placements from one
      * stream map.
      * @param {Map<string, Uint8Array>} streams
-     * @returns {{ models: { id: string, checksum: number, name: string, format: string, payloadText: string, sourceStream: string, transform: { rotationDeg: { x: number, y: number, z: number }, dzMil: number } }[], componentBodies: { sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null }[] }}
+     * @returns {{ models: { id: string, checksum: number, name: string, format: string, payloadText: string, sourceStream: string, transform: { rotationDeg: { x: number, y: number, z: number }, dzMil: number } }[], componentBodies: { sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null, modelType?: number, modelTypeName?: string, bodyColor?: object, bodyOpacity?: number, staticGeometry?: object }[] }}
      */
     static extractFromStreams(streams) {
         const modelStreamPrefix =
@@ -51,7 +52,7 @@ export class PcbEmbeddedModelExtractor {
                     streams.get('ComponentBodies6/Data'),
                     'ComponentBodies6/Data'
                 ),
-                ...PcbEmbeddedModelExtractor.#parseComponentBodyStream(
+                ...PcbEmbeddedModelExtractor.#parseShapeBasedComponentBodyStream(
                     streams.get('ShapeBasedComponentBodies6/Data'),
                     'ShapeBasedComponentBodies6/Data'
                 )
@@ -134,9 +135,10 @@ export class PcbEmbeddedModelExtractor {
      * Parses one component-body printable stream into model-placement records.
      * @param {Uint8Array | undefined} bytes
      * @param {string} sourceStream
-     * @returns {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null }[]}
+     * @param {{ inferStaticGeometry?: boolean }} [options]
+     * @returns {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null, modelType?: number, modelTypeName?: string, bodyColor?: object, bodyOpacity?: number, staticGeometry?: object }[]}
      */
-    static #parseComponentBodyStream(bytes, sourceStream) {
+    static #parseComponentBodyStream(bytes, sourceStream, options = {}) {
         if (!(bytes instanceof Uint8Array) || !bytes.byteLength) {
             return []
         }
@@ -153,12 +155,53 @@ export class PcbEmbeddedModelExtractor {
             .map((fields) =>
                 PcbEmbeddedModelExtractor.#normalizeComponentBody(
                     fields,
-                    sourceStream
+                    sourceStream,
+                    options.inferStaticGeometry
+                        ? {
+                              staticGeometry:
+                                  PcbShapeBasedBodyGeometryParser.buildStaticGeometry(
+                                      fields,
+                                      []
+                                  )
+                          }
+                        : {}
                 )
             )
             .filter(Boolean)
     }
 
+    /**
+     * Parses shape-based component bodies, including optional vertex payloads.
+     * @param {Uint8Array | undefined} bytes
+     * @param {string} sourceStream
+     * @returns {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null, modelType?: number, modelTypeName?: string, bodyColor?: object, bodyOpacity?: number, staticGeometry?: object }[]}
+     */
+    static #parseShapeBasedComponentBodyStream(bytes, sourceStream) {
+        if (!(bytes instanceof Uint8Array) || !bytes.byteLength) {
+            return []
+        }
+
+        const records = PcbShapeBasedBodyGeometryParser.parse(bytes)
+
+        if (records.length) {
+            return records
+                .map((record) =>
+                    PcbEmbeddedModelExtractor.#normalizeComponentBody(
+                        record.fields,
+                        sourceStream,
+                        { staticGeometry: record.staticGeometry }
+                    )
+                )
+                .filter(Boolean)
+        }
+
+        return PcbEmbeddedModelExtractor.#parseComponentBodyStream(
+            bytes,
+            sourceStream,
+            { inferStaticGeometry: true }
+        )
+    }
+
     /**
      * Parses one printable field record without requiring a specific leading
      * marker such as `|RECORD=` or `|KIND=`.
@@ -266,9 +309,10 @@ export class PcbEmbeddedModelExtractor {
      * Normalizes one component-body record into model-placement metadata.
      * @param {Record<string, string | string[]>} fields
      * @param {string} sourceStream
-     * @returns {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null } | null}
+     * @param {{ staticGeometry?: object }} [extra]
+     * @returns {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null, modelType?: number, modelTypeName?: string, bodyColor?: object, bodyOpacity?: number, staticGeometry?: object } | null}
      */
-    static #normalizeComponentBody(fields, sourceStream) {
+    static #normalizeComponentBody(fields, sourceStream, extra = {}) {
         const modelId = PcbEmbeddedModelExtractor.#getField(fields, 'MODELID')
         const name = PcbEmbeddedModelExtractor.#getField(fields, 'MODEL.NAME')
 
@@ -339,7 +383,82 @@ export class PcbEmbeddedModelExtractor {
             standoffHeightMil: PcbEmbeddedModelExtractor.#parseMilLikeField(
                 fields,
                 'STANDOFFHEIGHT'
-            )
+            ),
+            ...PcbEmbeddedModelExtractor.#shapeBodyMetadata(fields),
+            ...PcbEmbeddedModelExtractor.#stripUndefined(extra)
+        }
+    }
+
+    /**
+     * Normalizes shape-based body display metadata.
+     * @param {Record<string, string | string[]>} fields Native fields.
+     * @returns {object}
+     */
+    static #shapeBodyMetadata(fields) {
+        const modelType = PcbEmbeddedModelExtractor.#parseIntegerField(
+            fields,
+            'MODEL.MODELTYPE'
+        )
+        const bodyColorRaw = PcbEmbeddedModelExtractor.#parseIntegerField(
+            fields,
+            'BODYCOLOR3D'
+        )
+        const bodyOpacity = PcbEmbeddedModelExtractor.#parseNumberField(
+            fields,
+            'BODYOPACITY3D'
+        )
+
+        return PcbEmbeddedModelExtractor.#stripUndefined({
+            modelType: modelType === null ? undefined : modelType,
+            modelTypeName:
+                modelType === null
+                    ? undefined
+                    : PcbEmbeddedModelExtractor.#modelTypeName(modelType),
+            bodyColor:
+                bodyColorRaw === null
+                    ? undefined
+                    : PcbEmbeddedModelExtractor.#decodeBodyColor(bodyColorRaw),
+            bodyOpacity:
+                bodyOpacity === null || !Number.isFinite(bodyOpacity)
+                    ? undefined
+                    : bodyOpacity
+        })
+    }
+
+    /**
+     * Maps a numeric body model type to a stable semantic label.
+     * @param {number} modelType Numeric model type.
+     * @returns {string}
+     */
+    static #modelTypeName(modelType) {
+        const modelTypeNames = new Map([
+            [0, 'extruded-polygon'],
+            [1, 'cone'],
+            [2, 'cylinder'],
+            [3, 'sphere']
+        ])
+
+        return modelTypeNames.get(modelType) || 'unknown-' + modelType
+    }
+
+    /**
+     * Decodes one packed native RGB color value.
+     * @param {number} rawColor Packed color value.
+     * @returns {{ raw: number, hex: string, rgb: { red: number, green: number, blue: number } }}
+     */
+    static #decodeBodyColor(rawColor) {
+        const red = rawColor & 0xff
+        const green = (rawColor >> 8) & 0xff
+        const blue = (rawColor >> 16) & 0xff
+
+        return {
+            raw: rawColor,
+            hex:
+                '#' +
+                [red, green, blue]
+                    .map((component) => component.toString(16).padStart(2, '0'))
+                    .join(''),
+            rgb: { red, green, blue }
         }
     }
 
@@ -359,8 +478,8 @@ export class PcbEmbeddedModelExtractor {
 
     /**
      * Deduplicates shape-based body records shared across body streams.
-     * @param {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null }[]} componentBodies
-     * @returns {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null }[]}
+     * @param {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null, modelType?: number, modelTypeName?: string, bodyColor?: object, bodyOpacity?: number, staticGeometry?: object }[]} componentBodies
+     * @returns {{ sourceStream: string, layer: string, identifier: string, modelId: string, checksum: number | null, embedded: boolean, name: string, positionMil: { x: number, y: number }, rotationDeg: number, modelRotationDeg: { x: number, y: number, z: number }, dzMil: number, overallHeightMil: number | null, standoffHeightMil: number | null, modelType?: number, modelTypeName?: string, bodyColor?: object, bodyOpacity?: number, staticGeometry?: object }[]}
      */
     static #dedupeComponentBodies(componentBodies) {
         const uniqueBodies = new Map()
@@ -747,4 +866,15 @@ export class PcbEmbeddedModelExtractor {
                 .filter(Number.isInteger)
         )
     }
+
+    /**
+     * Removes undefined values from a normalized metadata row.
+     * @param {object} row Metadata row.
+     * @returns {object}
+     */
+    static #stripUndefined(row) {
+        return Object.fromEntries(
+            Object.entries(row).filter(([, value]) => value !== undefined)
+        )
+    }
 }