altium-toolkit 1.1.26 → 1.1.31

package/package.json

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

package/src/core/altium/AltiumParser.mjs

@@ -52,6 +52,11 @@ import { SchematicBindingProvenanceParser } from './SchematicBindingProvenancePa
 import { SchematicConnectivityQaBuilder } from './SchematicConnectivityQaBuilder.mjs'
 import { SchematicQaReportBuilder } from './SchematicQaReportBuilder.mjs'
 import { SchematicWireNormalizer } from './SchematicWireNormalizer.mjs'
+import { AltiumSchematicArcAngleNormalizer } from './AltiumSchematicArcAngleNormalizer.mjs'
+import { AltiumSchematicFreeGraphicStrokeNormalizer } from './AltiumSchematicFreeGraphicStrokeNormalizer.mjs'
+import { AltiumSchematicHiddenDesignatorResolver } from './AltiumSchematicHiddenDesignatorResolver.mjs'
+import { AltiumSchematicPackedImageResolver } from './AltiumSchematicPackedImageResolver.mjs'
+import { AltiumSchematicSheetBoundsNormalizer } from './AltiumSchematicSheetBoundsNormalizer.mjs'
 import { CircuitJsonModelAdapter } from '../circuit-json/CircuitJsonModelAdapter.mjs'
 const {
     countMatchingKeys,
@@ -856,7 +861,7 @@ export class AltiumParser {
             )
         }
 
-        return NormalizedModelSchema.attach({
+        const documentModel = NormalizedModelSchema.attach({
             kind: 'schematic',
             fileType: 'SchDoc',
             fileName,
@@ -935,6 +940,34 @@ export class AltiumParser {
             },
             bom
         })
+
+        return AltiumParser.#prepareSchematicDocument(
+            documentModel,
+            arrayBuffer
+        )
+    }
+
+    /**
+     * Applies universal schematic post-processing after the parser has built
+     * the normalized renderer model.
+     * @param {object} documentModel Parsed schematic document model.
+     * @param {ArrayBuffer} arrayBuffer Source file buffer.
+     * @returns {object}
+     */
+    static #prepareSchematicDocument(documentModel, arrayBuffer) {
+        return AltiumSchematicPackedImageResolver.hydrate(
+            AltiumSchematicFreeGraphicStrokeNormalizer.normalize(
+                AltiumSchematicSheetBoundsNormalizer.normalize(
+                    AltiumSchematicArcAngleNormalizer.normalize(
+                        AltiumSchematicHiddenDesignatorResolver.annotate(
+                            documentModel,
+                            arrayBuffer
+                        )
+                    )
+                )
+            ),
+            arrayBuffer
+        )
     }
 
     /**

package/src/core/altium/AltiumSchematicArcAngleNormalizer.mjs

@@ -0,0 +1,82 @@
+/**
+ * Normalizes Altium schematic arc angles before SVG rendering.
+ */
+export class AltiumSchematicArcAngleNormalizer {
+    static #FULL_CIRCLE_TOLERANCE = 0.001
+
+    /**
+     * Rewrites non-full arcs to the shortest authored sweep.
+     * @param {object} documentModel Parsed document model.
+     * @returns {object}
+     */
+    static normalize(documentModel) {
+        const arcs = documentModel?.schematic?.arcs
+        if (!Array.isArray(arcs)) {
+            return documentModel
+        }
+
+        for (const arc of arcs) {
+            AltiumSchematicArcAngleNormalizer.#normalizeArc(arc)
+        }
+
+        return documentModel
+    }
+
+    /**
+     * Normalizes one arc's end angle while preserving full-circle arcs.
+     * @param {object} arc Arc primitive.
+     * @returns {void}
+     */
+    static #normalizeArc(arc) {
+        const startAngle = Number(arc?.startAngle)
+        const endAngle = Number(arc?.endAngle)
+        if (!Number.isFinite(startAngle) || !Number.isFinite(endAngle)) {
+            return
+        }
+
+        const delta =
+            AltiumSchematicArcAngleNormalizer.#normalizeSingleTurnDelta(
+                endAngle - startAngle
+            )
+        if (AltiumSchematicArcAngleNormalizer.#isFullCircleDelta(delta)) {
+            return
+        }
+
+        if (delta > 180) {
+            arc.endAngle = endAngle - 360
+        } else if (delta < -180) {
+            arc.endAngle = endAngle + 360
+        }
+    }
+
+    /**
+     * Keeps a delta inside one signed turn.
+     * @param {number} delta Source angle delta.
+     * @returns {number}
+     */
+    static #normalizeSingleTurnDelta(delta) {
+        let normalized = delta
+
+        while (normalized <= -360) {
+            normalized += 360
+        }
+
+        while (normalized > 360) {
+            normalized -= 360
+        }
+
+        return normalized
+    }
+
+    /**
+     * Returns true when one normalized delta describes a full circle.
+     * @param {number} delta Normalized angle delta.
+     * @returns {boolean}
+     */
+    static #isFullCircleDelta(delta) {
+        return (
+            Math.abs(Math.abs(delta) - 360) <=
+            AltiumSchematicArcAngleNormalizer.#FULL_CIRCLE_TOLERANCE
+        )
+    }
+}

package/src/core/altium/AltiumSchematicFreeGraphicStrokeNormalizer.mjs

@@ -0,0 +1,105 @@
+/**
+ * Normalizes ownerless Altium drawing primitive strokes to match app rendering.
+ */
+export class AltiumSchematicFreeGraphicStrokeNormalizer {
+    static #SOURCE_THIN_STROKE = 1
+
+    static #APP_THIN_STROKE = 0.85
+
+    /**
+     * Applies app-side stroke normalization to free schematic graphics.
+     * @param {object} documentModel Parsed document model.
+     * @returns {object}
+     */
+    static normalize(documentModel) {
+        const schematic = documentModel?.schematic
+        if (!schematic || typeof schematic !== 'object') {
+            return documentModel
+        }
+
+        AltiumSchematicFreeGraphicStrokeNormalizer.#normalizeLines(
+            schematic.lines
+        )
+        for (const family of [
+            schematic.arcs,
+            schematic.beziers,
+            schematic.pies,
+            schematic.polygons,
+            schematic.rectangles,
+            schematic.roundedRectangles,
+            schematic.ellipses
+        ]) {
+            AltiumSchematicFreeGraphicStrokeNormalizer.#normalizeFreeGraphics(
+                family
+            )
+        }
+
+        return documentModel
+    }
+
+    /**
+     * Normalizes free drawing line strokes while leaving wires and buses alone.
+     * @param {object[] | undefined} lines Parsed line primitives.
+     * @returns {void}
+     */
+    static #normalizeLines(lines) {
+        if (!Array.isArray(lines)) {
+            return
+        }
+
+        for (const line of lines) {
+            if (
+                line?.recordType === '6' &&
+                !line.ownerIndex &&
+                line.isBus !== true
+            ) {
+                AltiumSchematicFreeGraphicStrokeNormalizer.#normalizeStroke(
+                    line,
+                    'width'
+                )
+            }
+        }
+    }
+
+    /**
+     * Normalizes ownerless drawing primitive strokes.
+     * @param {object[] | undefined} primitives Primitive family.
+     * @returns {void}
+     */
+    static #normalizeFreeGraphics(primitives) {
+        if (!Array.isArray(primitives)) {
+            return
+        }
+
+        for (const primitive of primitives) {
+            if (primitive?.ownerIndex) {
+                continue
+            }
+
+            AltiumSchematicFreeGraphicStrokeNormalizer.#normalizeStroke(
+                primitive,
+                'width'
+            )
+            AltiumSchematicFreeGraphicStrokeNormalizer.#normalizeStroke(
+                primitive,
+                'lineWidth'
+            )
+        }
+    }
+
+    /**
+     * Rewrites one source thin-stroke value to the app-normalized width.
+     * @param {object} primitive Primitive object.
+     * @param {string} key Stroke key.
+     * @returns {void}
+     */
+    static #normalizeStroke(primitive, key) {
+        if (
+            Number(primitive?.[key]) ===
+            AltiumSchematicFreeGraphicStrokeNormalizer.#SOURCE_THIN_STROKE
+        ) {
+            primitive[key] =
+                AltiumSchematicFreeGraphicStrokeNormalizer.#APP_THIN_STROKE
+        }
+    }
+}

package/src/core/altium/AltiumSchematicHiddenDesignatorResolver.mjs

@@ -0,0 +1,191 @@
+import { AsciiRecordParser } from './AsciiRecordParser.mjs'
+
+/**
+ * Marks Altium schematic components whose native designator labels are hidden.
+ */
+export class AltiumSchematicHiddenDesignatorResolver {
+    /**
+     * Annotates parsed components with schematic designator visibility metadata.
+     * @param {object} documentModel Parsed document model.
+     * @param {ArrayBuffer} arrayBuffer Source document bytes.
+     * @returns {object}
+     */
+    static annotate(documentModel, arrayBuffer) {
+        if (!documentModel?.schematic?.components?.length || !arrayBuffer) {
+            return documentModel
+        }
+
+        const hiddenDesignatorIds =
+            AltiumSchematicHiddenDesignatorResolver.#hiddenDesignatorUniqueIds(
+                arrayBuffer
+            )
+
+        if (!hiddenDesignatorIds.size) {
+            return documentModel
+        }
+
+        for (const component of documentModel.schematic.components) {
+            if (hiddenDesignatorIds.has(String(component.uniqueId || ''))) {
+                component.schematicDesignatorVisible = false
+            }
+        }
+
+        return documentModel
+    }
+
+    /**
+     * Finds component IDs whose owner designator record is explicitly hidden.
+     * @param {ArrayBuffer} arrayBuffer Source document bytes.
+     * @returns {Set<string>}
+     */
+    static #hiddenDesignatorUniqueIds(arrayBuffer) {
+        let records = []
+        try {
+            records = AsciiRecordParser.parse(arrayBuffer)
+        } catch {
+            return new Set()
+        }
+
+        const hiddenUniqueIds = new Set()
+
+        for (let index = 0; index < records.length; index += 1) {
+            const record = records[index]
+            if (
+                !AltiumSchematicHiddenDesignatorResolver.#isComponentRecord(
+                    record
+                )
+            ) {
+                continue
+            }
+
+            const uniqueId =
+                AltiumSchematicHiddenDesignatorResolver.#field(
+                    record.fields,
+                    'UniqueID'
+                ) ||
+                AltiumSchematicHiddenDesignatorResolver.#field(
+                    record.fields,
+                    'UniqueId'
+                )
+            if (!uniqueId) {
+                continue
+            }
+
+            const visibility =
+                AltiumSchematicHiddenDesignatorResolver.#ownerDesignatorVisibility(
+                    records,
+                    index + 1
+                )
+            if (
+                visibility.hasHiddenDesignator &&
+                !visibility.hasVisibleDesignator
+            ) {
+                hiddenUniqueIds.add(uniqueId)
+            }
+        }
+
+        return hiddenUniqueIds
+    }
+
+    /**
+     * Resolves designator visibility in the records following one component.
+     * @param {{ fields: Record<string, string | string[]> }[]} records Parsed records.
+     * @param {number} startIndex First record after the component.
+     * @returns {{ hasHiddenDesignator: boolean, hasVisibleDesignator: boolean }}
+     */
+    static #ownerDesignatorVisibility(records, startIndex) {
+        let hasHiddenDesignator = false
+        let hasVisibleDesignator = false
+
+        for (let index = startIndex; index < records.length; index += 1) {
+            const record = records[index]
+            if (
+                AltiumSchematicHiddenDesignatorResolver.#isComponentRecord(
+                    record
+                )
+            ) {
+                break
+            }
+
+            if (
+                !AltiumSchematicHiddenDesignatorResolver.#isDesignatorRecord(
+                    record
+                )
+            ) {
+                continue
+            }
+
+            if (
+                AltiumSchematicHiddenDesignatorResolver.#isHiddenRecord(record)
+            ) {
+                hasHiddenDesignator = true
+                continue
+            }
+
+            hasVisibleDesignator = true
+        }
+
+        return { hasHiddenDesignator, hasVisibleDesignator }
+    }
+
+    /**
+     * Returns true when one raw record is a component placement.
+     * @param {{ fields?: Record<string, string | string[]> }} record Raw record.
+     * @returns {boolean}
+     */
+    static #isComponentRecord(record) {
+        return (
+            AltiumSchematicHiddenDesignatorResolver.#field(
+                record?.fields,
+                'RECORD'
+            ) === '1'
+        )
+    }
+
+    /**
+     * Returns true when one raw record is a component designator label.
+     * @param {{ fields?: Record<string, string | string[]> }} record Raw record.
+     * @returns {boolean}
+     */
+    static #isDesignatorRecord(record) {
+        return (
+            AltiumSchematicHiddenDesignatorResolver.#field(
+                record?.fields,
+                'Name'
+            )
+                .trim()
+                .toLowerCase() === 'designator'
+        )
+    }
+
+    /**
+     * Returns true when one raw record is explicitly hidden.
+     * @param {{ fields?: Record<string, string | string[]> }} record Raw record.
+     * @returns {boolean}
+     */
+    static #isHiddenRecord(record) {
+        return (
+            AltiumSchematicHiddenDesignatorResolver.#field(
+                record?.fields,
+                'IsHidden'
+            )
+                .trim()
+                .toUpperCase() === 'T'
+        )
+    }
+
+    /**
+     * Reads one string field from parser records.
+     * @param {Record<string, string | string[]> | undefined} fields Field map.
+     * @param {string} key Field key.
+     * @returns {string}
+     */
+    static #field(fields, key) {
+        const value = fields?.[key]
+        if (Array.isArray(value)) {
+            return String(value[0] || '')
+        }
+
+        return String(value || '')
+    }
+}