altium-toolkit 1.1.32 → 1.1.35

package/src/core/altium/AltiumLibraryRecordBuilder.mjs

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-3.0-or-later
 
+import { AltiumGeneratedLibraryRecordBuilder } from './AltiumGeneratedLibraryRecordBuilder.mjs'
+
 /**
  * Builds deterministic textual and byte records for generated Altium libraries.
  */
@@ -22,6 +24,17 @@ export class AltiumLibraryRecordBuilder {
         })
     }
 
+    /**
+     * Builds a full schematic component data record stream.
+     * @param {object} bundle Normalized component bundle.
+     * @returns {string}
+     */
+    static buildSchematicComponentDataRecord(bundle) {
+        return AltiumGeneratedLibraryRecordBuilder.buildSchematicComponentData(
+            bundle
+        )
+    }
+
     /**
      * Builds a PCB footprint record.
      * @param {object} bundle Normalized component bundle.
@@ -35,10 +48,24 @@ export class AltiumLibraryRecordBuilder {
             DisplayName: bundle.name,
             PadCount: String(bundle.footprint.pads.length),
             TrackCount: String(bundle.footprint.tracks.length),
+            ArcCount: String(bundle.footprint.arcs.length),
+            FillCount: String(bundle.footprint.fills.length),
+            TextCount: String(bundle.footprint.texts.length),
             ModelCount: String(bundle.models.length)
         })
     }
 
+    /**
+     * Counts generated footprint primitives.
+     * @param {object} bundle Normalized bundle.
+     * @returns {number}
+     */
+    static footprintPrimitiveCount(bundle) {
+        return AltiumGeneratedLibraryRecordBuilder.footprintPrimitiveCount(
+            bundle.footprint
+        )
+    }
+
     /**
      * Builds a PcbLib Library/Data stream.
      * @param {object[]} bundles Normalized component bundles.
@@ -113,7 +140,10 @@ export class AltiumLibraryRecordBuilder {
      */
     static buildFootprintData(bundle) {
         return AltiumLibraryRecordBuilder.concatBytes([
-            AltiumLibraryRecordBuilder.createStringBlock(bundle.footprint.name)
+            AltiumLibraryRecordBuilder.createStringBlock(bundle.footprint.name),
+            ...AltiumGeneratedLibraryRecordBuilder.buildFootprintPrimitiveRecords(
+                bundle.footprint
+            )
         ])
     }
 
@@ -133,7 +163,7 @@ export class AltiumLibraryRecordBuilder {
 
     /**
      * Builds model metadata entries.
-     * @param {{ model: object, id: string, checksum: number }[]} models Model rows.
+     * @param {{ bundle: object, model: object, id: string, checksum: number }[]} models Model rows.
      * @returns {Uint8Array}
      */
     static buildModelsData(models) {
@@ -141,7 +171,12 @@ export class AltiumLibraryRecordBuilder {
             models.map((row) =>
                 AltiumLibraryRecordBuilder.createLengthPrefixedAscii(
                     AltiumLibraryRecordBuilder.#pipeRecord({
+                        EMBED: 'TRUE',
+                        MODELSOURCE: 'Undefined',
                         ID: row.id,
+                        ...AltiumLibraryRecordBuilder.#modelMetadataTransform(
+                            row
+                        ),
                         NAME: row.model.name,
                         CHECKSUM: String(row.checksum),
                         FORMAT: row.model.format
@@ -151,6 +186,23 @@ export class AltiumLibraryRecordBuilder {
         )
     }
 
+    /**
+     * Builds component-body placement records for embedded model rows.
+     * @param {{ bundle: object, model: object, id: string, checksum: number }[]} models Model rows.
+     * @returns {Uint8Array}
+     */
+    static buildComponentBodiesData(models) {
+        return AltiumLibraryRecordBuilder.concatBytes(
+            models.map((row) =>
+                new TextEncoder().encode(
+                    AltiumLibraryRecordBuilder.#pipeRecord(
+                        AltiumLibraryRecordBuilder.#componentBodyFields(row)
+                    ) + '\u0000'
+                )
+            )
+        )
+    }
+
     /**
      * Creates a little-endian count header.
      * @param {number} count Count value.
@@ -249,6 +301,238 @@ export class AltiumLibraryRecordBuilder {
         )
     }
 
+    /**
+     * Builds model metadata transform fields.
+     * @param {{ bundle: object, model: object }} row Model row.
+     * @returns {Record<string, string>}
+     */
+    static #modelMetadataTransform(row) {
+        const rotation = AltiumLibraryRecordBuilder.#modelRotation(
+            row.model,
+            AltiumLibraryRecordBuilder.#rowComponent(row)
+        )
+
+        return {
+            ROTX: AltiumLibraryRecordBuilder.#numberText(rotation.x),
+            ROTY: AltiumLibraryRecordBuilder.#numberText(rotation.y),
+            ROTZ: AltiumLibraryRecordBuilder.#numberText(rotation.z),
+            DZ: AltiumLibraryRecordBuilder.#milText(
+                AltiumLibraryRecordBuilder.#modelDzMil(row.model)
+            )
+        }
+    }
+
+    /**
+     * Builds one component-body placement record.
+     * @param {{ bundle: object, model: object, id: string, checksum: number }} row Model row.
+     * @returns {Record<string, string>}
+     */
+    static #componentBodyFields(row) {
+        const offset = AltiumLibraryRecordBuilder.#modelOffsetMil(row.model)
+        const rotation = AltiumLibraryRecordBuilder.#modelRotation(
+            row.model,
+            AltiumLibraryRecordBuilder.#rowComponent(row)
+        )
+
+        return {
+            V7_LAYER: 'MECHANICAL1',
+            KIND: '0',
+            SUBPOLYINDEX: '-1',
+            UNIONINDEX: '0',
+            ISSHAPEBASED: 'FALSE',
+            STANDOFFHEIGHT: '0mil',
+            OVERALLHEIGHT: '0mil',
+            IDENTIFIER: AltiumLibraryRecordBuilder.#identifierBytes(
+                row.bundle?.footprint?.name || row.model?.name || row.id
+            ),
+            MODELID: row.id,
+            'MODEL.CHECKSUM': String(row.checksum),
+            'MODEL.EMBED': 'TRUE',
+            'MODEL.NAME': row.model.name,
+            'MODEL.2D.X': AltiumLibraryRecordBuilder.#milText(offset.x),
+            'MODEL.2D.Y': AltiumLibraryRecordBuilder.#milText(offset.y),
+            'MODEL.2D.ROTATION': '0',
+            'MODEL.3D.ROTX': AltiumLibraryRecordBuilder.#numberText(rotation.x),
+            'MODEL.3D.ROTY': AltiumLibraryRecordBuilder.#numberText(rotation.y),
+            'MODEL.3D.ROTZ': AltiumLibraryRecordBuilder.#numberText(rotation.z),
+            'MODEL.3D.DZ': AltiumLibraryRecordBuilder.#milText(
+                AltiumLibraryRecordBuilder.#modelDzMil(row.model)
+            ),
+            'MODEL.MODELSOURCE': 'Undefined'
+        }
+    }
+
+    /**
+     * Resolves the source component attached to a model row.
+     * @param {{ bundle?: object }} row Model row.
+     * @returns {object}
+     */
+    static #rowComponent(row) {
+        return (
+            row?.bundle?.footprint?.component ||
+            row?.bundle?.footprint?.raw?.component ||
+            {}
+        )
+    }
+
+    /**
+     * Resolves one model transform object.
+     * @param {object} model Model asset.
+     * @returns {object}
+     */
+    static #modelTransform(model) {
+        return model?.transform || model?.raw?.transform || {}
+    }
+
+    /**
+     * Resolves model offset in mils.
+     * @param {object} model Model asset.
+     * @returns {{ x: number, y: number }}
+     */
+    static #modelOffsetMil(model) {
+        const transform = AltiumLibraryRecordBuilder.#modelTransform(model)
+        const offsetMil = transform.offsetMil || {}
+
+        return {
+            x: AltiumLibraryRecordBuilder.#round(
+                AltiumLibraryRecordBuilder.#number(
+                    offsetMil.x ?? transform.dxMil,
+                    0
+                )
+            ),
+            y: AltiumLibraryRecordBuilder.#round(
+                AltiumLibraryRecordBuilder.#number(
+                    offsetMil.y ?? transform.dyMil,
+                    0
+                )
+            )
+        }
+    }
+
+    /**
+     * Resolves one model Z offset in mils.
+     * @param {object} model Model asset.
+     * @returns {number}
+     */
+    static #modelDzMil(model) {
+        const transform = AltiumLibraryRecordBuilder.#modelTransform(model)
+        const offsetMil = transform.offsetMil || {}
+
+        return AltiumLibraryRecordBuilder.#round(
+            AltiumLibraryRecordBuilder.#number(
+                offsetMil.z ?? transform.dzMil,
+                0
+            )
+        )
+    }
+
+    /**
+     * Resolves model 3D rotation in footprint-local degrees.
+     * @param {object} model Model asset.
+     * @param {object} component Selected footprint component origin.
+     * @returns {{ x: number, y: number, z: number }}
+     */
+    static #modelRotation(model, component) {
+        const transform = AltiumLibraryRecordBuilder.#modelTransform(model)
+        const rotation = transform.rotationDeg || {}
+        const generatedRotation =
+            AltiumLibraryRecordBuilder.#generatedFrameRotation(model, component)
+
+        return {
+            x: AltiumLibraryRecordBuilder.#round(
+                AltiumLibraryRecordBuilder.#number(rotation.x, 0) +
+                    generatedRotation.x
+            ),
+            y: AltiumLibraryRecordBuilder.#round(
+                AltiumLibraryRecordBuilder.#number(rotation.y, 0) +
+                    generatedRotation.y
+            ),
+            z: AltiumLibraryRecordBuilder.#round(
+                AltiumLibraryRecordBuilder.#number(rotation.z, 0) +
+                    generatedRotation.z
+            )
+        }
+    }
+
+    /**
+     * Resolves correction for generated stitched STEP files.
+     * @param {object} model Model asset.
+     * @param {object} component Selected footprint component origin.
+     * @returns {{ x: number, y: number, z: number }}
+     */
+    static #generatedFrameRotation(model, component) {
+        if (model?.generated !== true && model?.raw?.generated !== true) {
+            return { x: 0, y: 0, z: 0 }
+        }
+
+        return {
+            x: -90,
+            y: 0,
+            z: AltiumLibraryRecordBuilder.#normalizeAngle(
+                -AltiumLibraryRecordBuilder.#number(component?.rotation, 0)
+            )
+        }
+    }
+
+    /**
+     * Encodes one Altium identifier as comma-separated character codes.
+     * @param {string} text Source text.
+     * @returns {string}
+     */
+    static #identifierBytes(text) {
+        return [...String(text || '')]
+            .map((character) => character.charCodeAt(0))
+            .join(',')
+    }
+
+    /**
+     * Formats a model distance in mils.
+     * @param {number} value Value in mils.
+     * @returns {string}
+     */
+    static #milText(value) {
+        return AltiumLibraryRecordBuilder.#numberText(value) + 'mil'
+    }
+
+    /**
+     * Formats one numeric record field.
+     * @param {number} value Numeric value.
+     * @returns {string}
+     */
+    static #numberText(value) {
+        return String(AltiumLibraryRecordBuilder.#round(value))
+    }
+
+    /**
+     * Reads a finite number with fallback.
+     * @param {unknown} value Candidate value.
+     * @param {number} fallback Fallback value.
+     * @returns {number}
+     */
+    static #number(value, fallback) {
+        const number = Number(value)
+        return Number.isFinite(number) ? number : fallback
+    }
+
+    /**
+     * Rounds generated numeric fields.
+     * @param {number} value Numeric value.
+     * @returns {number}
+     */
+    static #round(value) {
+        const rounded = Number(Number(value || 0).toFixed(6))
+        return Object.is(rounded, -0) ? 0 : rounded
+    }
+
+    /**
+     * Normalizes a degree angle to the 0-360 range.
+     * @param {number} angle Angle in degrees.
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        return ((angle % 360) + 360) % 360
+    }
+
     /**
      * Builds one pipe-delimited record.
      * @param {Record<string, string>} fields Record fields.

package/src/core/altium/AltiumPcbLibExporter.mjs

@@ -42,7 +42,9 @@ export class AltiumPcbLibExporter {
             )
             streams.set(
                 storageName + '/Header',
-                AltiumLibraryRecordBuilder.createCountHeader(0)
+                AltiumLibraryRecordBuilder.createCountHeader(
+                    AltiumLibraryRecordBuilder.footprintPrimitiveCount(bundle)
+                )
             )
             streams.set(
                 storageName + '/Parameters',
@@ -65,6 +67,10 @@ export class AltiumPcbLibExporter {
                 'Models/Data',
                 AltiumLibraryRecordBuilder.buildModelsData(modelRows)
             )
+            streams.set(
+                'ComponentBodies6/Data',
+                AltiumLibraryRecordBuilder.buildComponentBodiesData(modelRows)
+            )
             modelRows.forEach((row, index) => {
                 streams.set('Models/' + index, row.model.bytes)
             })
@@ -76,11 +82,12 @@ export class AltiumPcbLibExporter {
     /**
      * Collects model rows with deterministic generated ids.
      * @param {object[]} bundles Normalized bundles.
-     * @returns {{ model: object, id: string, checksum: number }[]}
+     * @returns {{ bundle: object, model: object, id: string, checksum: number }[]}
      */
     static #collectModels(bundles) {
         return bundles.flatMap((bundle, bundleIndex) =>
             bundle.models.map((model, modelIndex) => ({
+                bundle,
                 model,
                 id: 'model-' + bundleIndex + '-' + modelIndex,
                 checksum: AltiumLibraryRecordBuilder.checksumBytes(model.bytes)

package/src/core/altium/AltiumSchLibExporter.mjs

@@ -34,7 +34,7 @@ export class AltiumSchLibExporter {
                     ) +
                     '/Data',
                 new TextEncoder().encode(
-                    AltiumLibraryRecordBuilder.buildSchematicComponentRecord(
+                    AltiumLibraryRecordBuilder.buildSchematicComponentDataRecord(
                         bundle
                     )
                 )

package/src/core/altium/PcbComponentBodyPlacementNormalizer.mjs

@@ -20,23 +20,128 @@ export class PcbComponentBodyPlacementNormalizer {
         const mirrorY = (value) =>
             Number(boardOutline?.minY || 0) + maxY - Number(value || 0)
 
-        return componentBodies.map((componentBody) => ({
-            ...componentBody,
-            positionMil: {
-                x: Number(componentBody.positionMil?.x || 0),
-                y: mirrorY(componentBody.positionMil?.y || 0)
-            },
-            rotationDeg: PcbComponentBodyPlacementNormalizer.#normalizeAngle(
-                360 - Number(componentBody.rotationDeg || 0)
-            ),
-            modelRotationDeg: {
-                x: Number(componentBody.modelRotationDeg?.x || 0),
-                y: Number(componentBody.modelRotationDeg?.y || 0),
-                z: PcbComponentBodyPlacementNormalizer.#normalizeAngle(
-                    360 - Number(componentBody.modelRotationDeg?.z || 0)
-                )
+        return componentBodies.map((componentBody) => {
+            const normalizedBody = {
+                ...componentBody,
+                positionMil: {
+                    x: Number(componentBody.positionMil?.x || 0),
+                    y: mirrorY(componentBody.positionMil?.y || 0)
+                },
+                rotationDeg:
+                    PcbComponentBodyPlacementNormalizer.#normalizeAngle(
+                        360 - Number(componentBody.rotationDeg || 0)
+                    ),
+                modelRotationDeg: {
+                    x: Number(componentBody.modelRotationDeg?.x || 0),
+                    y: Number(componentBody.modelRotationDeg?.y || 0),
+                    z: PcbComponentBodyPlacementNormalizer.#normalizeAngle(
+                        360 - Number(componentBody.modelRotationDeg?.z || 0)
+                    )
+                }
             }
+            const staticGeometry =
+                PcbComponentBodyPlacementNormalizer.#normalizeStaticGeometry(
+                    componentBody,
+                    mirrorY
+                )
+
+            return staticGeometry
+                ? {
+                      ...normalizedBody,
+                      staticGeometry
+                  }
+                : normalizedBody
+        })
+    }
+
+    /**
+     * Mirrors source-coordinate static geometry into the viewer coordinate
+     * system.
+     * @param {{ positionMil?: { x?: number, y?: number }, staticGeometry?: object }} componentBody Component body.
+     * @param {(value: number | string | undefined) => number} mirrorY Source Y mirror.
+     * @returns {object | undefined}
+     */
+    static #normalizeStaticGeometry(componentBody, mirrorY) {
+        const staticGeometry = componentBody?.staticGeometry
+        if (!staticGeometry || typeof staticGeometry !== 'object') {
+            return staticGeometry
+        }
+
+        const vertices = Array.isArray(staticGeometry.verticesMil)
+            ? staticGeometry.verticesMil
+            : []
+        if (
+            !PcbComponentBodyPlacementNormalizer.#shouldMirrorStaticVertices(
+                componentBody,
+                vertices
+            )
+        ) {
+            return staticGeometry
+        }
+
+        return {
+            ...staticGeometry,
+            verticesMil: vertices.map((vertex) => ({
+                ...vertex,
+                x: Number(vertex?.x || 0),
+                y: mirrorY(vertex?.y || 0)
+            }))
+        }
+    }
+
+    /**
+     * Checks whether polygon vertices share the body source-coordinate frame.
+     * @param {{ positionMil?: { x?: number, y?: number } }} componentBody Component body.
+     * @param {{ x?: number, y?: number }[]} vertices Static polygon vertices.
+     * @returns {boolean}
+     */
+    static #shouldMirrorStaticVertices(componentBody, vertices) {
+        if (vertices.length < 3) {
+            return false
+        }
+
+        const center =
+            PcbComponentBodyPlacementNormalizer.#polygonBoundsCenter(vertices)
+        const source = {
+            x: Number(componentBody?.positionMil?.x || 0),
+            y: Number(componentBody?.positionMil?.y || 0)
+        }
+
+        return (
+            PcbComponentBodyPlacementNormalizer.#distance(center, source) <= 5
+        )
+    }
+
+    /**
+     * Resolves an axis-aligned polygon bounds center.
+     * @param {{ x?: number, y?: number }[]} vertices Static polygon vertices.
+     * @returns {{ x: number, y: number }}
+     */
+    static #polygonBoundsCenter(vertices) {
+        const points = vertices.map((vertex) => ({
+            x: Number(vertex?.x || 0),
+            y: Number(vertex?.y || 0)
         }))
+        const xs = points.map((point) => point.x)
+        const ys = points.map((point) => point.y)
+
+        return {
+            x: (Math.min(...xs) + Math.max(...xs)) / 2,
+            y: (Math.min(...ys) + Math.max(...ys)) / 2
+        }
+    }
+
+    /**
+     * Measures XY distance between two points.
+     * @param {{ x?: number, y?: number }} first First point.
+     * @param {{ x?: number, y?: number }} second Second point.
+     * @returns {number}
+     */
+    static #distance(first, second) {
+        return Math.hypot(
+            Number(first?.x || 0) - Number(second?.x || 0),
+            Number(first?.y || 0) - Number(second?.y || 0)
+        )
     }
 
     /**

package/src/core/altium/PcbEmbeddedModelExtractor.mjs

@@ -419,12 +419,23 @@ export class PcbEmbeddedModelExtractor {
                     ? undefined
                     : PcbEmbeddedModelExtractor.#decodeBodyColor(bodyColorRaw),
             bodyOpacity:
-                bodyOpacity === null || !Number.isFinite(bodyOpacity)
-                    ? undefined
-                    : bodyOpacity
+                PcbEmbeddedModelExtractor.#normalizeBodyOpacity(bodyOpacity)
         })
     }
 
+    /**
+     * Normalizes native body opacity metadata to authored translucency only.
+     * @param {number | null} bodyOpacity Native body opacity value.
+     * @returns {number | undefined}
+     */
+    static #normalizeBodyOpacity(bodyOpacity) {
+        if (!Number.isFinite(bodyOpacity) || Number(bodyOpacity) <= 0) {
+            return undefined
+        }
+
+        return bodyOpacity
+    }
+
     /**
      * Maps a numeric body model type to a stable semantic label.
      * @param {number} modelType Numeric model type.
@@ -498,7 +509,14 @@ export class PcbEmbeddedModelExtractor {
                 componentBody.dzMil
             ].join('\u0000')
 
-            if (!uniqueBodies.has(key)) {
+            const existingBody = uniqueBodies.get(key)
+            if (
+                !existingBody ||
+                PcbEmbeddedModelExtractor.#shouldPreferComponentBody(
+                    componentBody,
+                    existingBody
+                )
+            ) {
                 uniqueBodies.set(key, componentBody)
             }
         }
@@ -506,6 +524,36 @@ export class PcbEmbeddedModelExtractor {
         return [...uniqueBodies.values()]
     }
 
+    /**
+     * Checks whether one component-body row carries better static geometry.
+     * @param {{ staticGeometry?: object }} candidate Candidate body row.
+     * @param {{ staticGeometry?: object }} existing Existing body row.
+     * @returns {boolean}
+     */
+    static #shouldPreferComponentBody(candidate, existing) {
+        return (
+            PcbEmbeddedModelExtractor.#staticGeometryRank(candidate) >
+            PcbEmbeddedModelExtractor.#staticGeometryRank(existing)
+        )
+    }
+
+    /**
+     * Ranks static geometry completeness for duplicate body rows.
+     * @param {{ staticGeometry?: object }} componentBody Component body row.
+     * @returns {number}
+     */
+    static #staticGeometryRank(componentBody) {
+        if (componentBody?.staticGeometry?.status === 'complete') {
+            return 2
+        }
+
+        if (componentBody?.staticGeometry) {
+            return 1
+        }
+
+        return 0
+    }
+
     /**
      * Builds model metadata and payload integrity diagnostics.
      * @param {object[]} metadataRows Parsed model metadata rows.