altium-toolkit 0.1.20 → 0.1.21

package/package.json

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

package/src/core/altium/AltiumParser.mjs

@@ -26,6 +26,7 @@ import { SchematicBusEntryParser } from './SchematicBusEntryParser.mjs'
 import { SchematicImageParser } from './SchematicImageParser.mjs'
 import { SchematicNetlistBuilder } from './SchematicNetlistBuilder.mjs'
 import { SchematicComponentTextResolver } from './SchematicComponentTextResolver.mjs'
+import { SchematicStreamExtractor } from './SchematicStreamExtractor.mjs'
 const {
     countMatchingKeys,
     getDisplayText,
@@ -65,7 +66,13 @@ export class AltiumParser {
         const records = AsciiRecordParser.parse(arrayBuffer)
         const fileType = AltiumParser.#sniffFileType(fileName, records)
         if (fileType === 'SchDoc') {
-            return AltiumParser.#parseSchematic(fileName, records, arrayBuffer)
+            const schematicExtraction =
+                SchematicStreamExtractor.extractFromArrayBuffer(arrayBuffer)
+            return AltiumParser.#parseSchematic(
+                fileName,
+                schematicExtraction?.records || records,
+                arrayBuffer
+            )
         }
         if (fileType === 'PcbDoc') {
             const pcbExtraction =
@@ -270,13 +277,15 @@ export class AltiumParser {
                 color: toColor(record.fields.Color, '#a44a1b'),
                 width: parseNumericField(record.fields, 'LineWidth') || 1,
                 lineStyle: parseNumericField(record.fields, 'LineStyle') || 0,
+                recordType: getField(record.fields, 'RECORD') || undefined,
                 renderOrder:
                     parseNumericField(record.fields, 'IndexInSheet') ?? index,
                 ownerIndex: getField(record.fields, 'OwnerIndex') || undefined
             })),
             ...polylineRecords.flatMap((record, index) =>
                 parseSchematicPolyline(record.fields, {
-                    isBus: getField(record.fields, 'RECORD') === '26'
+                    isBus: getField(record.fields, 'RECORD') === '26',
+                    recordType: getField(record.fields, 'RECORD') || undefined
                 }).map((line, segmentIndex) => ({
                     ...line,
                     renderOrder:
@@ -291,6 +300,8 @@ export class AltiumParser {
                 parseSchematicPolygon(record.fields).map(
                     (line, segmentIndex) => ({
                         ...line,
+                        recordType:
+                            getField(record.fields, 'RECORD') || undefined,
                         renderOrder:
                             (parseNumericField(record.fields, 'IndexInSheet') ??
                                 index) +
@@ -379,7 +390,8 @@ export class AltiumParser {
                     texts,
                     normalizedLines,
                     pins,
-                    ports
+                    ports,
+                    rectangles
                 ),
                 normalizedLines,
                 pins,

package/src/core/altium/PcbFontMetricsParser.mjs

@@ -9,7 +9,7 @@ export class PcbFontMetricsParser {
     /**
      * Parses font-family metrics from a TrueType/OpenType sfnt payload.
      * @param {Uint8Array | ArrayBuffer} bytes
-     * @returns {{ format: 'truetype' | 'opentype' | 'unknown', unitsPerEm?: number, ascent?: number, descent?: number, lineGap?: number, cellHeight?: number, emScaleFromPcbHeight?: number, capHeight?: number, averageAdvanceWidth?: number, weightClass?: number, widthClass?: number }}
+     * @returns {{ format: 'truetype' | 'opentype' | 'unknown', unitsPerEm?: number, ascent?: number, descent?: number, lineGap?: number, windowsAscent?: number, windowsDescent?: number, cellHeight?: number, emScaleFromPcbHeight?: number, capHeight?: number, averageAdvanceWidth?: number, weightClass?: number, widthClass?: number }}
      */
     static parse(bytes) {
         const normalizedBytes = PcbFontMetricsParser.#toUint8Array(bytes)
@@ -43,10 +43,7 @@ export class PcbFontMetricsParser {
             tables.get('hmtx'),
             hhea.numberOfHMetrics
         )
-        const cellHeight =
-            Number.isFinite(hhea.ascent) && Number.isFinite(hhea.descent)
-                ? hhea.ascent + Math.abs(hhea.descent)
-                : undefined
+        const cellHeight = PcbFontMetricsParser.#resolvePcbCellHeight(hhea, os2)
         const metrics = {
             format,
             ...head,
@@ -177,7 +174,7 @@ export class PcbFontMetricsParser {
      * Reads typography metadata from the `OS/2` table.
      * @param {DataView} view
      * @param {{ offset: number, length: number } | undefined} table
-     * @returns {{ averageAdvanceWidth?: number, weightClass?: number, widthClass?: number, capHeight?: number }}
+     * @returns {{ averageAdvanceWidth?: number, weightClass?: number, widthClass?: number, windowsAscent?: number, windowsDescent?: number, capHeight?: number }}
      */
     static #readOs2Table(view, table) {
         if (!PcbFontMetricsParser.#tableHasBytes(table, 8)) {
@@ -203,10 +200,40 @@ export class PcbFontMetricsParser {
                 table.offset + 88
             )
         }
+        if (PcbFontMetricsParser.#tableHasBytes(table, 78)) {
+            metrics.windowsAscent = PcbFontMetricsParser.#readUint16(
+                view,
+                table.offset + 74
+            )
+            metrics.windowsDescent = PcbFontMetricsParser.#readUint16(
+                view,
+                table.offset + 76
+            )
+        }
 
         return metrics
     }
 
+    /**
+     * Resolves the TrueType cell height used by Altium PCB text placement.
+     * @param {{ ascent?: number, descent?: number }} hhea
+     * @param {{ windowsAscent?: number, windowsDescent?: number }} os2
+     * @returns {number | undefined}
+     */
+    static #resolvePcbCellHeight(hhea, os2) {
+        if (
+            Number.isFinite(os2.windowsAscent) &&
+            Number.isFinite(os2.windowsDescent) &&
+            os2.windowsAscent + os2.windowsDescent > 0
+        ) {
+            return os2.windowsAscent + os2.windowsDescent
+        }
+
+        return Number.isFinite(hhea.ascent) && Number.isFinite(hhea.descent)
+            ? hhea.ascent + Math.abs(hhea.descent)
+            : undefined
+    }
+
     /**
      * Reads horizontal advance data from the `hmtx` table.
      * @param {DataView} view

package/src/core/altium/PcbModelParser.mjs

@@ -93,6 +93,7 @@ export class PcbModelParser {
         const primitiveLayers = AltiumLayoutParser.parsePrimitiveLayerNames(
             boardRecords.map((record) => record.fields)
         )
+        const appearance3d = PcbModelParser.#parseAppearance3d(boardRecords)
         const nets = PcbModelParser.#parseNetRecords(records)
         const netNameByIndex = PcbModelParser.#buildNetNameMap(nets)
         const classes = PcbModelParser.#parseClassRecords(records)
@@ -392,6 +393,7 @@ export class PcbModelParser {
                 layerSubstacks,
                 boardRegionContexts,
                 primitiveLayers,
+                appearance3d,
                 nets,
                 classes,
                 rules,
@@ -558,6 +560,86 @@ export class PcbModelParser {
         return netNameByIndex
     }
 
+    /**
+     * Extracts authored Altium 3D appearance colors from board metadata.
+     * @param {{ fields: Record<string, string | string[]> }[]} boardRecords
+     * @returns {{ boardCoreColor?: number, solderMaskTopColor?: number, solderMaskBottomColor?: number, copperColor?: number, silkscreenTopColor?: number, silkscreenBottomColor?: number } | null}
+     */
+    static #parseAppearance3d(boardRecords) {
+        const configText = (Array.isArray(boardRecords) ? boardRecords : [])
+            .map((record) => getField(record.fields, '3DCONFIGURATION'))
+            .find(Boolean)
+        if (!configText) {
+            return null
+        }
+
+        const config = PcbModelParser.#parseConfigurationFields(configText)
+        const appearance = {
+            boardCoreColor: PcbModelParser.#parseAltiumBgrColor(
+                config.get('CFG3D.BOARDCORECOLOR')
+            ),
+            solderMaskTopColor: PcbModelParser.#parseAltiumBgrColor(
+                config.get('CFG3D.TOPSOLDERMASKCOLOR')
+            ),
+            solderMaskBottomColor: PcbModelParser.#parseAltiumBgrColor(
+                config.get('CFG3D.BOTSOLDERMASKCOLOR')
+            ),
+            copperColor: PcbModelParser.#parseAltiumBgrColor(
+                config.get('CFG3D.COPPERCOLOR')
+            ),
+            silkscreenTopColor: PcbModelParser.#parseAltiumBgrColor(
+                config.get('CFG3D.TOPSILKSCREENCOLOR')
+            ),
+            silkscreenBottomColor: PcbModelParser.#parseAltiumBgrColor(
+                config.get('CFG3D.BOTSILKSCREENCOLOR')
+            )
+        }
+
+        return Object.values(appearance).some(Number.isInteger)
+            ? appearance
+            : null
+    }
+
+    /**
+     * Parses backtick-delimited Altium configuration key/value fields.
+     * @param {string} value
+     * @returns {Map<string, string>}
+     */
+    static #parseConfigurationFields(value) {
+        const fields = new Map()
+
+        String(value || '')
+            .split('`')
+            .forEach((segment) => {
+                const separatorIndex = segment.indexOf('=')
+                if (separatorIndex <= 0) {
+                    return
+                }
+
+                fields.set(
+                    segment.slice(0, separatorIndex).toUpperCase(),
+                    segment.slice(separatorIndex + 1)
+                )
+            })
+
+        return fields
+    }
+
+    /**
+     * Converts Altium decimal BGR color storage into an RGB integer.
+     * @param {string | undefined} value
+     * @returns {number | undefined}
+     */
+    static #parseAltiumBgrColor(value) {
+        const parsed = Number.parseInt(String(value ?? '').trim(), 10)
+        if (!Number.isFinite(parsed)) {
+            return undefined
+        }
+
+        const bgr = parsed & 0xffffff
+        return ((bgr & 0xff) << 16) | (bgr & 0xff00) | (bgr >> 16)
+    }
+
     /**
      * Adds resolved net names to decoded primitives without changing geometry.
      * @param {{ netIndex?: number | string | null }[]} primitives

package/src/core/altium/PcbTextPrimitiveParser.mjs

@@ -17,7 +17,7 @@ export class PcbTextPrimitiveParser {
      * @param {Uint8Array | ArrayBuffer} headerBytes
      * @param {Uint8Array | ArrayBuffer} dataBytes
      * @param {{ wideStrings?: Map<number | string, string> | Record<string, string> | { byIndex?: Record<string, string> } }} [options]
-     * @returns {{ text: string, x: number, y: number, height: number, layerId: number, ownerIndex: number | null, kind: number, visibilityFlags: number, rotation: number, strokeFontType?: number, strokeWidth?: number, fontType?: number, fontTypeName?: string, fontName?: string, fontFamily?: string, isBold?: boolean, isItalic?: boolean, fontWeight?: number, fontStyle?: string, wideStringIndex?: number, textSource?: string, role?: string, isDesignator?: boolean, isComment?: boolean, isPlaceholder?: boolean, componentIndex?: number }[]}
+     * @returns {{ text: string, x: number, y: number, height: number, layerId: number, ownerIndex: number | null, kind: number, visibilityFlags: number, rotation: number, mirrored: boolean, strokeFontType?: number, strokeWidth?: number, fontType?: number, fontTypeName?: string, fontName?: string, fontFamily?: string, isBold?: boolean, isItalic?: boolean, fontWeight?: number, fontStyle?: string, isInverted?: boolean, marginBorderWidth?: number, wideStringIndex?: number, useInvertedRectangle?: boolean, textboxRectWidth?: number, textboxRectHeight?: number, textboxRectJustification?: number, textSource?: string, role?: string, isDesignator?: boolean, isComment?: boolean, isPlaceholder?: boolean, componentIndex?: number }[]}
      */
     static parseTextStream(headerBytes, dataBytes, options = {}) {
         const count = PcbTextPrimitiveParser.#readRecordCount(headerBytes)
@@ -106,7 +106,7 @@ export class PcbTextPrimitiveParser {
      * @param {DataView} payload
      * @param {Uint8Array} textBytes
      * @param {Map<string, string>} wideStrings
-     * @returns {{ text: string, x: number, y: number, height: number, layerId: number, ownerIndex: number | null, kind: number, visibilityFlags: number, rotation: number, strokeFontType?: number, strokeWidth?: number, fontType?: number, fontTypeName?: string, fontName?: string, fontFamily?: string, isBold?: boolean, isItalic?: boolean, fontWeight?: number, fontStyle?: string, wideStringIndex?: number, textSource?: string, role?: string, isDesignator?: boolean, isComment?: boolean, isPlaceholder?: boolean, componentIndex?: number } | null}
+     * @returns {{ text: string, x: number, y: number, height: number, layerId: number, ownerIndex: number | null, kind: number, visibilityFlags: number, rotation: number, mirrored: boolean, strokeFontType?: number, strokeWidth?: number, fontType?: number, fontTypeName?: string, fontName?: string, fontFamily?: string, isBold?: boolean, isItalic?: boolean, fontWeight?: number, fontStyle?: string, isInverted?: boolean, marginBorderWidth?: number, wideStringIndex?: number, useInvertedRectangle?: boolean, textboxRectWidth?: number, textboxRectHeight?: number, textboxRectJustification?: number, textSource?: string, role?: string, isDesignator?: boolean, isComment?: boolean, isPlaceholder?: boolean, componentIndex?: number } | null}
      */
     static #parseTextRecord(payload, textBytes, wideStrings) {
         if (
@@ -157,6 +157,10 @@ export class PcbTextPrimitiveParser {
                 visibilityFlags,
                 hasExtendedFontFields
             ),
+            mirrored: PcbTextPrimitiveParser.#resolveTextMirrored(
+                payload,
+                hasExtendedFontFields
+            ),
             ...extendedText,
             ...resolvedText.metadata,
             ...role,
@@ -171,7 +175,7 @@ export class PcbTextPrimitiveParser {
      * Parses extended TrueType/barcode font metadata when the payload carries
      * the modern PCB text field block.
      * @param {DataView} payload
-     * @returns {{ strokeFontType?: number, strokeWidth?: number, fontType?: number, fontTypeName?: string, fontName?: string, fontFamily?: string, isBold?: boolean, isItalic?: boolean, fontWeight?: number, fontStyle?: string, wideStringIndex?: number }}
+     * @returns {{ strokeFontType?: number, strokeWidth?: number, fontType?: number, fontTypeName?: string, fontName?: string, fontFamily?: string, isBold?: boolean, isItalic?: boolean, fontWeight?: number, fontStyle?: string, isInverted?: boolean, marginBorderWidth?: number, wideStringIndex?: number, useInvertedRectangle?: boolean, textboxRectWidth?: number, textboxRectHeight?: number, textboxRectJustification?: number }}
      */
     static #parseExtendedTextFields(payload) {
         if (payload.byteLength < 110) {
@@ -201,9 +205,36 @@ export class PcbTextPrimitiveParser {
             fontStyle: isItalic ? 'italic' : 'normal'
         }
 
+        if (payload.byteLength >= 111) {
+            extendedFields.isInverted = payload.getUint8(110) !== 0
+        }
+        if (payload.byteLength >= 115) {
+            extendedFields.marginBorderWidth = PcbTextPrimitiveParser.#readMil(
+                payload,
+                111
+            )
+        }
         if (payload.byteLength >= 119) {
             extendedFields.wideStringIndex = payload.getUint32(115, true)
         }
+        if (payload.byteLength >= 124) {
+            extendedFields.useInvertedRectangle = payload.getUint8(123) !== 0
+        }
+        if (payload.byteLength >= 128) {
+            extendedFields.textboxRectWidth = PcbTextPrimitiveParser.#readMil(
+                payload,
+                124
+            )
+        }
+        if (payload.byteLength >= 132) {
+            extendedFields.textboxRectHeight = PcbTextPrimitiveParser.#readMil(
+                payload,
+                128
+            )
+        }
+        if (payload.byteLength >= 133) {
+            extendedFields.textboxRectJustification = payload.getUint8(132)
+        }
 
         return extendedFields
     }
@@ -455,6 +486,20 @@ export class PcbTextPrimitiveParser {
         return PcbTextPrimitiveParser.#textRotationFromFlags(visibilityFlags)
     }
 
+    /**
+     * Resolves text mirroring from the explicit modern text byte.
+     * @param {DataView} payload
+     * @param {boolean} hasExtendedFontFields
+     * @returns {boolean}
+     */
+    static #resolveTextMirrored(payload, hasExtendedFontFields) {
+        if (hasExtendedFontFields && payload.byteLength >= 36) {
+            return payload.getUint8(35) !== 0
+        }
+
+        return false
+    }
+
     /**
      * Normalizes supported WideStrings6 lookup shapes into a string-keyed map.
      * @param {Map<number | string, string> | Record<string, string> | { byIndex?: Record<string, string> } | undefined} wideStrings