altium-toolkit 1.0.7 → 1.0.9

package/src/core/altium/SchematicOwnershipGraphParser.mjs

@@ -0,0 +1,195 @@
+// SPDX-FileCopyrightText: 2026 André Fiedler
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import { ParserUtils } from './ParserUtils.mjs'
+
+const { getField, parseNumericField } = ParserUtils
+
+/**
+ * Builds a read-only ownership graph from schematic record owner indexes.
+ */
+export class SchematicOwnershipGraphParser {
+    static SCHEMA_ID = 'altium-toolkit.schematic.ownership.a1'
+
+    /**
+     * Parses record parent/child links from raw schematic records.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }[]} records Schematic records.
+     * @returns {{ schema: string, records: object[], recordsByIndexInSheet: Record<string, object>, childrenByParentKey: Record<string, object[]>, parentsByChildKey: Record<string, object> }}
+     */
+    static parse(records) {
+        const entries = (records || []).map((record, fallbackIndex) =>
+            SchematicOwnershipGraphParser.#recordEntry(record, fallbackIndex)
+        )
+        const ownerLookup =
+            SchematicOwnershipGraphParser.#buildOwnerLookup(entries)
+        const childrenByParentKey = {}
+        const parentsByChildKey = {}
+
+        for (const entry of entries) {
+            if (!entry.ownerIndex) {
+                continue
+            }
+
+            const parent = ownerLookup.get(entry.ownerIndex)
+            if (!parent || parent.key === entry.key) {
+                continue
+            }
+
+            if (!childrenByParentKey[parent.key]) {
+                childrenByParentKey[parent.key] = []
+            }
+
+            childrenByParentKey[parent.key].push(
+                SchematicOwnershipGraphParser.#childDescriptor(entry)
+            )
+            parentsByChildKey[entry.key] = {
+                parentKey: parent.key,
+                ownerIndex: entry.ownerIndex
+            }
+        }
+
+        return {
+            schema: SchematicOwnershipGraphParser.SCHEMA_ID,
+            records: entries.map((entry) =>
+                SchematicOwnershipGraphParser.#publicRecord(entry)
+            ),
+            recordsByIndexInSheet:
+                SchematicOwnershipGraphParser.#recordsByIndexInSheet(entries),
+            childrenByParentKey,
+            parentsByChildKey
+        }
+    }
+
+    /**
+     * Normalizes one raw schematic record into a sidecar row.
+     * @param {{ fields: Record<string, string | string[]>, recordIndex?: number }} record Source record.
+     * @param {number} fallbackIndex Fallback record index.
+     * @returns {object}
+     */
+    static #recordEntry(record, fallbackIndex) {
+        const recordIndex = Number.isInteger(record?.recordIndex)
+            ? record.recordIndex
+            : fallbackIndex
+        const indexInSheet = parseNumericField(record?.fields, 'IndexInSheet')
+
+        return {
+            key: 'schematic-record-' + recordIndex,
+            recordIndex,
+            recordType: getField(record?.fields, 'RECORD'),
+            indexInSheet,
+            ownerIndex: getField(record?.fields, 'OwnerIndex'),
+            uniqueId:
+                getField(record?.fields, 'UniqueID') ||
+                getField(record?.fields, 'UniqueId'),
+            name: getField(record?.fields, 'Name'),
+            text: getField(record?.fields, 'Text')
+        }
+    }
+
+    /**
+     * Builds tolerant owner-index lookup keys for record parents.
+     * @param {object[]} entries Record sidecar rows.
+     * @returns {Map<string, object>}
+     */
+    static #buildOwnerLookup(entries) {
+        const lookup = new Map()
+
+        for (const entry of entries) {
+            for (const key of SchematicOwnershipGraphParser.#ownerKeys(entry)) {
+                if (!lookup.has(key)) {
+                    lookup.set(key, entry)
+                }
+            }
+        }
+
+        return lookup
+    }
+
+    /**
+     * Returns candidate owner-index keys for one record.
+     * @param {object} entry Record sidecar row.
+     * @returns {string[]}
+     */
+    static #ownerKeys(entry) {
+        const keys = new Set([
+            String(entry.recordIndex),
+            String(entry.recordIndex + 1)
+        ])
+
+        if (Number.isInteger(entry.indexInSheet)) {
+            keys.add(String(entry.indexInSheet))
+            keys.add(String(entry.indexInSheet + 1))
+        }
+
+        return [...keys]
+    }
+
+    /**
+     * Builds a compact public record row.
+     * @param {object} entry Internal record row.
+     * @returns {object}
+     */
+    static #publicRecord(entry) {
+        return SchematicOwnershipGraphParser.#stripEmpty({
+            key: entry.key,
+            recordIndex: entry.recordIndex,
+            recordType: entry.recordType,
+            indexInSheet: entry.indexInSheet,
+            ownerIndex: entry.ownerIndex,
+            uniqueId: entry.uniqueId,
+            name: entry.name,
+            text: entry.text
+        })
+    }
+
+    /**
+     * Builds a compact child descriptor for grouped owner lists.
+     * @param {object} entry Internal record row.
+     * @returns {object}
+     */
+    static #childDescriptor(entry) {
+        return SchematicOwnershipGraphParser.#stripEmpty({
+            key: entry.key,
+            recordIndex: entry.recordIndex,
+            recordType: entry.recordType,
+            ownerIndex: entry.ownerIndex,
+            indexInSheet: entry.indexInSheet,
+            name: entry.name
+        })
+    }
+
+    /**
+     * Indexes records by native IndexInSheet values.
+     * @param {object[]} entries Record sidecar rows.
+     * @returns {Record<string, object>}
+     */
+    static #recordsByIndexInSheet(entries) {
+        const index = {}
+
+        for (const entry of entries) {
+            if (Number.isInteger(entry.indexInSheet)) {
+                index[String(entry.indexInSheet)] =
+                    SchematicOwnershipGraphParser.#publicRecord(entry)
+            }
+        }
+
+        return index
+    }
+
+    /**
+     * Drops empty object fields while preserving numeric zero.
+     * @param {Record<string, unknown>} value Candidate object.
+     * @returns {Record<string, unknown>}
+     */
+    static #stripEmpty(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(
+                ([, entryValue]) =>
+                    entryValue !== null &&
+                    entryValue !== undefined &&
+                    entryValue !== ''
+            )
+        )
+    }
+}

package/src/core/altium/SchematicPinParser.mjs

@@ -409,6 +409,14 @@ export class SchematicPinParser {
 
         const segments = []
         const lineStyle = SchematicPinParser.#resolveSchematicLineStyle(fields)
+        const startMarker = SchematicPinParser.#resolvePolylineMarker(
+            fields,
+            'Start'
+        )
+        const endMarker = SchematicPinParser.#resolvePolylineMarker(
+            fields,
+            'End'
+        )
 
         for (let index = 1; index < points.length; index += 1) {
             const previous = points[index - 1]
@@ -433,7 +441,11 @@ export class SchematicPinParser {
                 isBus: options.isBus === true ? true : undefined,
                 recordType: options.recordType || undefined,
                 omittedEndpointAxis: omittedEndpointAxis || undefined,
-                sourceLocationCount: points.length
+                sourceLocationCount: points.length,
+                ...(index === 1 && startMarker ? { startMarker } : {}),
+                ...(index === points.length - 1 && endMarker
+                    ? { endMarker }
+                    : {})
             })
         }
 
@@ -525,6 +537,77 @@ export class SchematicPinParser {
             : '#a44a1b'
     }
 
+    /**
+     * Resolves one authored polyline endpoint marker.
+     * @param {Record<string, string | string[]>} fields Source record fields.
+     * @param {'Start' | 'End'} edge Endpoint prefix.
+     * @returns {{ shape: number, shapeName: string, size: number } | null}
+     */
+    static #resolvePolylineMarker(fields, edge) {
+        const shape = SchematicPinParser.#parseFirstNumericField(fields, [
+            edge + 'LineShape',
+            edge + 'LineMarker',
+            edge + 'MarkerShape',
+            edge + 'ArrowKind'
+        ])
+
+        if (shape === null || shape <= 0) {
+            return null
+        }
+
+        const size =
+            SchematicPinParser.#parseFirstNumericField(fields, [
+                edge + 'LineShapeSize',
+                edge + 'LineMarkerSize',
+                edge + 'MarkerSize',
+                edge + 'ArrowSize'
+            ]) || 6
+
+        return {
+            shape,
+            shapeName:
+                SchematicPinParser.#resolvePolylineMarkerShapeName(shape),
+            size
+        }
+    }
+
+    /**
+     * Parses the first present numeric field from a candidate list.
+     * @param {Record<string, string | string[]>} fields Source record fields.
+     * @param {string[]} names Candidate field names.
+     * @returns {number | null}
+     */
+    static #parseFirstNumericField(fields, names) {
+        for (const name of names) {
+            const value = ParserUtils.parseNumericField(fields, name)
+            if (value !== null) {
+                return value
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Maps native polyline marker codes onto stable renderer labels.
+     * @param {number} shape Numeric marker code.
+     * @returns {string}
+     */
+    static #resolvePolylineMarkerShapeName(shape) {
+        switch (shape) {
+            case 1:
+                return 'arrow'
+            case 2:
+                return 'filled-arrow'
+            case 3:
+                return 'circle'
+            case 4:
+                return 'square'
+            default:
+                return 'marker-' + shape
+        }
+    }
+
     /**
      * Collects a schematic point list, carrying forward a missing coordinate
      * axis from the preceding point when Altium omitted an unchanged value.

package/src/core/altium/SchematicPrimitiveParser.mjs

@@ -32,6 +32,24 @@ export class SchematicPrimitiveParser {
         )
     }
 
+    /**
+     * Returns true when one record belongs to the rounded-rectangle primitive.
+     * @param {Record<string, string | string[]>} fields
+     * @returns {boolean}
+     */
+    static isRoundedRectangleRecord(fields) {
+        return getField(fields, 'RECORD') === '10'
+    }
+
+    /**
+     * Returns true when one record belongs to the schematic IEEE-symbol family.
+     * @param {Record<string, string | string[]>} fields
+     * @returns {boolean}
+     */
+    static isIeeeSymbolRecord(fields) {
+        return getField(fields, 'RECORD') === '3'
+    }
+
     /**
      * Returns true when one point-listed primitive describes an axis-aligned
      * rectangle instead of an arbitrary polyline.
@@ -117,6 +135,215 @@ export class SchematicPrimitiveParser {
             .filter(Boolean)
     }
 
+    /**
+     * Normalizes record-5 cubic Bezier primitives.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @returns {{ points: { x: number, y: number }[], segments: { start: { x: number, y: number }, control1: { x: number, y: number }, control2: { x: number, y: number }, end: { x: number, y: number } }[], color: string, width: number, lineStyle: number, renderOrder: number, ownerIndex?: string }[]}
+     */
+    static parseSchematicBeziers(records) {
+        return records
+            .map((record, index) => {
+                const points = SchematicPrimitiveParser.#collectPolygonPoints(
+                    record.fields
+                )
+                const segments =
+                    SchematicPrimitiveParser.#buildBezierSegments(points)
+
+                if (!segments.length) {
+                    return null
+                }
+
+                return SchematicPrimitiveParser.#stripUndefined({
+                    points,
+                    segments,
+                    color: toColor(record.fields.Color, '#000000'),
+                    width: parseNumericField(record.fields, 'LineWidth') || 1,
+                    lineStyle:
+                        parseNumericField(record.fields, 'LineStyle') || 0,
+                    renderOrder: SchematicPrimitiveParser.#resolveRenderOrder(
+                        record.fields,
+                        index
+                    ),
+                    ownerIndex:
+                        getField(record.fields, 'OwnerIndex') || undefined
+                })
+            })
+            .filter(Boolean)
+    }
+
+    /**
+     * Normalizes record-9 pie/wedge primitives.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @returns {{ x: number, y: number, radius: number, radiusY: number, startAngle: number, endAngle: number, color: string, fill: string, isSolid: boolean, transparent: boolean, lineWidth: number, renderOrder: number, ownerIndex?: string }[]}
+     */
+    static parseSchematicPies(records) {
+        return records
+            .map((record, index) => {
+                const x = parseNumericFieldWithFraction(
+                    record.fields,
+                    'Location.X'
+                )
+                const y = parseNumericFieldWithFraction(
+                    record.fields,
+                    'Location.Y'
+                )
+                const radius = parseNumericFieldWithFraction(
+                    record.fields,
+                    'Radius'
+                )
+                const radiusY =
+                    parseNumericFieldWithFraction(
+                        record.fields,
+                        'SecondaryRadius'
+                    ) ?? radius
+
+                if (
+                    x === null ||
+                    y === null ||
+                    radius === null ||
+                    radius <= 0 ||
+                    radiusY === null ||
+                    radiusY <= 0
+                ) {
+                    return null
+                }
+
+                return SchematicPrimitiveParser.#stripUndefined({
+                    x,
+                    y,
+                    radius,
+                    radiusY,
+                    startAngle:
+                        parseNumericField(record.fields, 'StartAngle') ?? 0,
+                    endAngle:
+                        parseNumericField(record.fields, 'EndAngle') ?? 360,
+                    color: toColor(record.fields.Color, '#000000'),
+                    fill: toColor(record.fields.AreaColor, '#ffffff'),
+                    isSolid: parseBoolean(record.fields.IsSolid),
+                    transparent: parseBoolean(record.fields.Transparent),
+                    lineWidth:
+                        parseNumericField(record.fields, 'LineWidth') || 1,
+                    renderOrder: SchematicPrimitiveParser.#resolveRenderOrder(
+                        record.fields,
+                        index
+                    ),
+                    ownerIndex:
+                        getField(record.fields, 'OwnerIndex') || undefined
+                })
+            })
+            .filter(Boolean)
+    }
+
+    /**
+     * Normalizes record-10 rounded rectangle primitives.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @returns {{ x: number, y: number, width: number, height: number, radius: number, color: string, fill: string, isSolid: boolean, transparent: boolean, lineWidth: number, lineStyle: number, renderOrder: number, ownerIndex?: string, recordId?: string }[]}
+     */
+    static parseSchematicRoundedRectangles(records) {
+        return records
+            .map((record, index) => {
+                const x1 = parseNumericField(record.fields, 'Location.X')
+                const y1 = parseNumericField(record.fields, 'Location.Y')
+                const x2 = parseNumericField(record.fields, 'Corner.X')
+                const y2 = parseNumericField(record.fields, 'Corner.Y')
+
+                if (x1 === null || y1 === null || x2 === null || y2 === null) {
+                    return null
+                }
+
+                const width = Math.abs(x2 - x1)
+                const height = Math.abs(y2 - y1)
+
+                return SchematicPrimitiveParser.#stripUndefined({
+                    x: Math.min(x1, x2),
+                    y: Math.min(y1, y2),
+                    width,
+                    height,
+                    radius: SchematicPrimitiveParser.#resolveCornerRadius(
+                        record.fields,
+                        width,
+                        height
+                    ),
+                    color: toColor(record.fields.Color, '#a44a1b'),
+                    fill: toColor(record.fields.AreaColor, '#ffffff'),
+                    isSolid: parseBoolean(record.fields.IsSolid),
+                    transparent: parseBoolean(record.fields.Transparent),
+                    lineWidth:
+                        parseNumericField(record.fields, 'LineWidth') || 1,
+                    lineStyle:
+                        parseNumericField(record.fields, 'LineStyle') || 0,
+                    renderOrder: SchematicPrimitiveParser.#resolveRenderOrder(
+                        record.fields,
+                        index
+                    ),
+                    ownerIndex:
+                        getField(record.fields, 'OwnerIndex') || undefined,
+                    recordId:
+                        getField(record.fields, 'UniqueID') ||
+                        getField(record.fields, 'UniqueId') ||
+                        undefined
+                })
+            })
+            .filter(Boolean)
+    }
+
+    /**
+     * Normalizes record-3 IEEE-style schematic symbol primitives.
+     * @param {{ fields: Record<string, string | string[]> }[]} records
+     * @returns {{ x: number, y: number, symbol: number, symbolName: string, size: number, color: string, lineWidth: number, renderOrder: number, ownerIndex?: string, recordId?: string }[]}
+     */
+    static parseSchematicIeeeSymbols(records) {
+        return records
+            .map((record, index) => {
+                const x = parseNumericFieldWithFraction(
+                    record.fields,
+                    'Location.X'
+                )
+                const y = parseNumericFieldWithFraction(
+                    record.fields,
+                    'Location.Y'
+                )
+
+                if (x === null || y === null) {
+                    return null
+                }
+
+                const symbol =
+                    parseNumericField(record.fields, 'Symbol') ??
+                    parseNumericField(record.fields, 'SymbolKind') ??
+                    parseNumericField(record.fields, 'IeeeSymbol') ??
+                    0
+
+                return SchematicPrimitiveParser.#stripUndefined({
+                    x,
+                    y,
+                    symbol,
+                    symbolName:
+                        SchematicPrimitiveParser.#ieeeSymbolName(symbol),
+                    size: Math.max(
+                        parseNumericField(record.fields, 'Size') ||
+                            parseNumericField(record.fields, 'Radius') ||
+                            12,
+                        1
+                    ),
+                    color: toColor(record.fields.Color, '#000000'),
+                    lineWidth:
+                        parseNumericField(record.fields, 'LineWidth') || 1,
+                    renderOrder: SchematicPrimitiveParser.#resolveRenderOrder(
+                        record.fields,
+                        index
+                    ),
+                    ownerIndex:
+                        getField(record.fields, 'OwnerIndex') || undefined,
+                    recordId:
+                        getField(record.fields, 'UniqueID') ||
+                        getField(record.fields, 'UniqueId') ||
+                        undefined
+                })
+            })
+            .filter(Boolean)
+    }
+
     /**
      * Normalizes record-14 body primitives into drawable rectangles.
      * @param {{ fields: Record<string, string | string[]> }[]} records
@@ -429,6 +656,80 @@ export class SchematicPrimitiveParser {
         return fallbackOrder
     }
 
+    /**
+     * Builds cubic Bezier spans from Altium's `4 + 3n` point sequence.
+     * @param {{ x: number, y: number }[]} points Source control points.
+     * @returns {{ start: { x: number, y: number }, control1: { x: number, y: number }, control2: { x: number, y: number }, end: { x: number, y: number } }[]}
+     */
+    static #buildBezierSegments(points) {
+        if (!Array.isArray(points) || points.length < 4) {
+            return []
+        }
+
+        const segments = []
+        for (let index = 0; index + 3 < points.length; index += 3) {
+            segments.push({
+                start: points[index],
+                control1: points[index + 1],
+                control2: points[index + 2],
+                end: points[index + 3]
+            })
+        }
+
+        return segments
+    }
+
+    /**
+     * Removes undefined fields from a primitive object.
+     * @param {object} value Source object.
+     * @returns {object}
+     */
+    static #stripUndefined(value) {
+        return Object.fromEntries(
+            Object.entries(value || {}).filter(
+                ([, entryValue]) => entryValue !== undefined
+            )
+        )
+    }
+
+    /**
+     * Resolves a stable rounded-rectangle corner radius.
+     * @param {Record<string, string | string[]>} fields Source fields.
+     * @param {number} width Width in schematic units.
+     * @param {number} height Height in schematic units.
+     * @returns {number}
+     */
+    static #resolveCornerRadius(fields, width, height) {
+        const radius =
+            parseNumericField(fields, 'CornerRadius') ??
+            parseNumericField(fields, 'Radius') ??
+            parseNumericField(fields, 'CornerRadius.X') ??
+            Math.min(width, height) / 5
+
+        return Math.max(Math.min(radius, width / 2, height / 2), 0)
+    }
+
+    /**
+     * Maps native IEEE symbol codes to stable display names.
+     * @param {number} symbol Native symbol code.
+     * @returns {string}
+     */
+    static #ieeeSymbolName(symbol) {
+        return (
+            {
+                1: 'and',
+                2: 'or',
+                3: 'xor',
+                4: 'inverter',
+                5: 'buffer',
+                6: 'clock',
+                7: 'schmitt',
+                8: 'open-collector',
+                9: 'open-emitter'
+            }[Number(symbol)] || 'unknown'
+        )
+    }
+
     /**
      * Builds one stable geometry-key queue for rectangle source metadata.
      * @param {{ fields: Record<string, string | string[]> }[]} records