altium-toolkit 1.1.33 → 1.1.36

package/AGENTS.md

@@ -33,8 +33,8 @@
 ## Library Scope
 
 - Include parser, OLE/binary helpers, schematic SVG rendering, PCB SVG
-  rendering, BOM HTML rendering, 3D scene-description builders, and static 3D
-  summary rendering.
+  rendering, BOM HTML rendering, selected-part library export adapters, 3D
+  scene-description builders, and static 3D summary rendering.
 - Do not add host app interaction to this library: no pan/zoom controllers, DOM
   event orchestration, OrbitControls runtime, picking, download UI, or app state.
 - Keep parser and renderer fixes universal. Never special-case a specific file

package/docs/model-format.md

@@ -80,9 +80,8 @@ The legacy renderer compatibility contract is published as a JSON Schema at
 [`docs/schemas/altium_toolkit/normalized_model_a1.schema.json`](schemas/altium_toolkit/normalized_model_a1.schema.json).
 Compatibility fields expose the same id through the top-level `schema` field,
 and consumers can compare it with `NormalizedModelSchema.CURRENT_SCHEMA_ID`.
-The serialized parser return value follows the upstream
-[`tscircuit/circuit-json`](https://github.com/tscircuit/circuit-json) element
-array convention.
+The serialized parser return value follows the Circuit JSON element-array
+convention.
 
 ## Parser Utility Reports
 

package/package.json

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

package/src/core/altium/AltiumLibraryRecordBuilder.mjs

@@ -163,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) {
@@ -171,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
@@ -181,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.
@@ -279,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

@@ -67,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)
             })
@@ -78,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/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.

package/src/core/altium/PcbShapeBasedBodyGeometryParser.mjs

@@ -121,10 +121,11 @@ export class PcbShapeBasedBodyGeometryParser {
         }
 
         const textBytes = bytes.subarray(offset + 22, offset + 22 + textLength)
-        const text = PrintableTextDecoder.decodeBytes(textBytes).replaceAll(
-            '\u0000',
-            ''
-        )
+        const payload =
+            PcbShapeBasedBodyGeometryParser.#splitInlineVertexPayload(textBytes)
+        const text = PrintableTextDecoder.decodeBytes(
+            payload.fieldBytes
+        ).replaceAll('\u0000', '')
 
         if (
             !text.includes('MODEL.') ||
@@ -133,11 +134,17 @@ export class PcbShapeBasedBodyGeometryParser {
             return null
         }
 
-        const fields =
-            PcbShapeBasedBodyGeometryParser.#parseFieldRecordBytes(textBytes)
+        const fields = PcbShapeBasedBodyGeometryParser.#parseFieldRecordBytes(
+            payload.fieldBytes
+        )
+        const textEndOffset = offset + 22 + textLength
+        const vertexBlockOffset =
+            payload.inlineVertexBlockOffset === null
+                ? textEndOffset
+                : offset + 22 + payload.inlineVertexBlockOffset
         const vertexBlock = PcbShapeBasedBodyGeometryParser.#parseVertexBlock(
             bytes,
-            offset + 22 + textLength
+            vertexBlockOffset
         )
 
         return {
@@ -146,13 +153,80 @@ export class PcbShapeBasedBodyGeometryParser {
                 fields,
                 vertexBlock.verticesMil
             ),
-            nextOffset:
-                vertexBlock.nextOffset > offset
-                    ? vertexBlock.nextOffset
-                    : offset + 22 + textLength
+            nextOffset: Math.max(vertexBlock.nextOffset, textEndOffset)
+        }
+    }
+
+    /**
+     * Splits printable fields from Altium records whose text length also
+     * covers an inline binary vertex block after a NUL terminator.
+     * @param {Uint8Array} textBytes Declared text payload bytes.
+     * @returns {{ fieldBytes: Uint8Array, inlineVertexBlockOffset: number | null }}
+     */
+    static #splitInlineVertexPayload(textBytes) {
+        const inlineVertexBlockOffset =
+            PcbShapeBasedBodyGeometryParser.#inlineVertexBlockOffset(textBytes)
+        if (inlineVertexBlockOffset === null) {
+            return { fieldBytes: textBytes, inlineVertexBlockOffset: null }
+        }
+
+        return {
+            fieldBytes: textBytes.subarray(0, inlineVertexBlockOffset - 1),
+            inlineVertexBlockOffset
         }
     }
 
+    /**
+     * Finds the inline vertex-count offset inside a declared text payload.
+     * @param {Uint8Array} textBytes Declared text payload bytes.
+     * @returns {number | null}
+     */
+    static #inlineVertexBlockOffset(textBytes) {
+        for (let index = 0; index < textBytes.byteLength; index += 1) {
+            if (textBytes[index] !== 0) {
+                continue
+            }
+
+            const vertexBlockOffset = index + 1
+            if (
+                PcbShapeBasedBodyGeometryParser.#hasPlausibleVertexBlock(
+                    textBytes,
+                    vertexBlockOffset
+                )
+            ) {
+                return vertexBlockOffset
+            }
+        }
+
+        return null
+    }
+
+    /**
+     * Checks whether one byte offset points to a complete vertex block.
+     * @param {Uint8Array} bytes Candidate payload bytes.
+     * @param {number} offset Candidate vertex-count offset.
+     * @returns {boolean}
+     */
+    static #hasPlausibleVertexBlock(bytes, offset) {
+        if (offset + 4 > bytes.byteLength) {
+            return false
+        }
+
+        const view = new DataView(
+            bytes.buffer,
+            bytes.byteOffset,
+            bytes.byteLength
+        )
+        const vertexCount = view.getInt32(offset, true)
+        const dataOffset = offset + 4
+
+        return (
+            vertexCount >= 3 &&
+            vertexCount <= 10000 &&
+            dataOffset + vertexCount * 37 <= bytes.byteLength
+        )
+    }
+
     /**
      * Parses the optional coordinate block after a shape-body field record.
      * @param {Uint8Array} bytes Stream bytes.

package/src/core/altium/PrintableTextDecoder.mjs

@@ -215,7 +215,8 @@ export class PrintableTextDecoder {
      * @returns {boolean}
      */
     static #hasWindows1252PreferredBytes(bytes) {
-        for (const byte of bytes) {
+        for (let index = 0; index < bytes.length; index += 1) {
+            const byte = bytes[index]
             if (
                 PrintableTextDecoder.#WINDOWS_1252_PRINTABLE_CONTROL_BYTES.has(
                     byte
@@ -223,11 +224,29 @@ export class PrintableTextDecoder {
             ) {
                 return true
             }
+
+            if (
+                byte >= 0xc0 &&
+                byte <= 0xff &&
+                (PrintableTextDecoder.#isAsciiLetter(bytes[index - 1]) ||
+                    PrintableTextDecoder.#isAsciiLetter(bytes[index + 1]))
+            ) {
+                return true
+            }
         }
 
         return false
     }
 
+    /**
+     * Returns true when one byte is an ASCII letter.
+     * @param {number | undefined} byte Byte value.
+     * @returns {boolean}
+     */
+    static #isAsciiLetter(byte) {
+        return (byte >= 0x41 && byte <= 0x5a) || (byte >= 0x61 && byte <= 0x7a)
+    }
+
     /**
      * Trims ASCII whitespace from one byte range.
      * @param {Uint8Array} bytes