altium-toolkit 1.1.30 → 1.1.32

package/src/ui/AltiumPcbBottomViewMirror.mjs

@@ -0,0 +1,394 @@
+/**
+ * Mirrors Altium PCB render models into the same bottom-view frame used by
+ * the 3D bottom preset.
+ */
+export class AltiumPcbBottomViewMirror {
+    /**
+     * Mirrors a side-resolved Altium PCB model horizontally around the board.
+     * @param {object | null} documentModel Side-resolved PCB document model.
+     * @returns {object | null}
+     */
+    static apply(documentModel) {
+        const pcb = documentModel?.pcb
+        const outline = pcb?.boardOutline
+        if (!pcb || !outline) {
+            return documentModel || null
+        }
+
+        const mirrorX = AltiumPcbBottomViewMirror.#buildMirrorX(outline)
+
+        return {
+            ...documentModel,
+            pcb: {
+                ...pcb,
+                boardOutline: AltiumPcbBottomViewMirror.#mirrorOutline(
+                    outline,
+                    mirrorX
+                ),
+                polygons: AltiumPcbBottomViewMirror.#mirrorPolygons(
+                    pcb.polygons,
+                    mirrorX
+                ),
+                fills: AltiumPcbBottomViewMirror.#mirrorFills(
+                    pcb.fills,
+                    mirrorX
+                ),
+                tracks: AltiumPcbBottomViewMirror.#mirrorTracks(
+                    pcb.tracks,
+                    mirrorX
+                ),
+                arcs: AltiumPcbBottomViewMirror.#mirrorArcs(pcb.arcs, mirrorX),
+                regions: AltiumPcbBottomViewMirror.#mirrorRegions(
+                    pcb.regions,
+                    mirrorX
+                ),
+                shapeBasedRegions: AltiumPcbBottomViewMirror.#mirrorRegions(
+                    pcb.shapeBasedRegions,
+                    mirrorX
+                ),
+                boardRegions: AltiumPcbBottomViewMirror.#mirrorRegions(
+                    pcb.boardRegions,
+                    mirrorX
+                ),
+                vias: AltiumPcbBottomViewMirror.#mirrorVias(pcb.vias, mirrorX),
+                pads: AltiumPcbBottomViewMirror.#mirrorPads(pcb.pads, mirrorX),
+                texts: AltiumPcbBottomViewMirror.#mirrorTexts(pcb.texts),
+                textGroupTransform:
+                    AltiumPcbBottomViewMirror.#buildTextGroupTransform(outline),
+                components: AltiumPcbBottomViewMirror.#mirrorComponents(
+                    pcb.components,
+                    mirrorX
+                )
+            }
+        }
+    }
+
+    /**
+     * Builds the board-space X-axis mirror function.
+     * @param {{ minX?: number, widthMil?: number }} outline Board outline.
+     * @returns {(value: unknown) => number}
+     */
+    static #buildMirrorX(outline) {
+        const minX = Number(outline?.minX || 0)
+        const maxX = minX + Number(outline?.widthMil || 0)
+
+        return (value) => minX + maxX - Number(value || 0)
+    }
+
+    /**
+     * Builds the SVG text-layer mirror used by the bottom 3D preset.
+     * @param {{ minX?: number, widthMil?: number }} outline Board outline.
+     * @returns {{ translateX: number, translateY: number, scaleX: number, scaleY: number }}
+     */
+    static #buildTextGroupTransform(outline) {
+        const minX = Number(outline?.minX || 0)
+        const maxX = minX + Number(outline?.widthMil || 0)
+
+        return {
+            translateX: minX + maxX,
+            translateY: 0,
+            scaleX: -1,
+            scaleY: 1
+        }
+    }
+
+    /**
+     * Mirrors the board outline segment coordinates.
+     * @param {object} outline Board outline.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object}
+     */
+    static #mirrorOutline(outline, mirrorX) {
+        return {
+            ...outline,
+            segments: AltiumPcbBottomViewMirror.#mirrorSegments(
+                outline?.segments,
+                mirrorX
+            )
+        }
+    }
+
+    /**
+     * Mirrors polygon segment coordinates.
+     * @param {readonly object[] | undefined} polygons Polygon primitives.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorPolygons(polygons, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(polygons).map((polygon) => ({
+            ...polygon,
+            segments: AltiumPcbBottomViewMirror.#mirrorSegments(
+                polygon?.segments,
+                mirrorX
+            )
+        }))
+    }
+
+    /**
+     * Mirrors path segment X coordinates.
+     * @param {readonly object[] | undefined} segments Path segments.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorSegments(segments, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(segments).map((segment) => ({
+            ...segment,
+            x1: mirrorX(segment?.x1),
+            x2: mirrorX(segment?.x2),
+            ...(segment?.cx === null || segment?.cx === undefined
+                ? {}
+                : { cx: mirrorX(segment.cx) })
+        }))
+    }
+
+    /**
+     * Mirrors rectangular fill extents.
+     * @param {readonly object[] | undefined} fills Fill primitives.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorFills(fills, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(fills).map((fill) => ({
+            ...fill,
+            x1: mirrorX(fill?.x1),
+            x2: mirrorX(fill?.x2),
+            points: AltiumPcbBottomViewMirror.#mirrorPointList(
+                fill?.points,
+                mirrorX
+            ),
+            holes: AltiumPcbBottomViewMirror.#mirrorHoleLists(
+                fill?.holes,
+                mirrorX
+            )
+        }))
+    }
+
+    /**
+     * Mirrors line track endpoints.
+     * @param {readonly object[] | undefined} tracks Track primitives.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorTracks(tracks, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(tracks).map((track) => ({
+            ...track,
+            x1: mirrorX(track?.x1),
+            x2: mirrorX(track?.x2)
+        }))
+    }
+
+    /**
+     * Mirrors arc centers and angular spans.
+     * @param {readonly object[] | undefined} arcs Arc primitives.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorArcs(arcs, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(arcs).map((arc) => ({
+            ...arc,
+            x: mirrorX(arc?.x),
+            startAngle: AltiumPcbBottomViewMirror.#mirrorAngleX(
+                arc?.startAngle
+            ),
+            endAngle: AltiumPcbBottomViewMirror.#mirrorAngleX(arc?.endAngle)
+        }))
+    }
+
+    /**
+     * Mirrors filled region contours and holes.
+     * @param {readonly object[] | undefined} regions Region primitives.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorRegions(regions, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(regions).map((region) => ({
+            ...region,
+            points: AltiumPcbBottomViewMirror.#mirrorPointList(
+                region?.points,
+                mirrorX
+            ),
+            holes: AltiumPcbBottomViewMirror.#mirrorHoleLists(
+                region?.holes,
+                mirrorX
+            ),
+            ...(Array.isArray(region?.bendingLines)
+                ? {
+                      bendingLines:
+                          AltiumPcbBottomViewMirror.#mirrorBendingLines(
+                              region.bendingLines,
+                              mirrorX
+                          )
+                  }
+                : {})
+        }))
+    }
+
+    /**
+     * Mirrors via centers.
+     * @param {readonly object[] | undefined} vias Via primitives.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorVias(vias, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(vias).map((via) => ({
+            ...via,
+            x: mirrorX(via?.x)
+        }))
+    }
+
+    /**
+     * Mirrors pad centers and X-axis local offsets.
+     * @param {readonly object[] | undefined} pads Pad primitives.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorPads(pads, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(pads).map((pad) => ({
+            ...pad,
+            x: mirrorX(pad?.x),
+            rotation: AltiumPcbBottomViewMirror.#mirrorRotation(pad?.rotation),
+            holeRotation:
+                pad?.holeRotation === null || pad?.holeRotation === undefined
+                    ? (pad?.holeRotation ?? null)
+                    : AltiumPcbBottomViewMirror.#mirrorRotation(
+                          pad.holeRotation
+                      ),
+            ...(pad?.offsetTopX === null || pad?.offsetTopX === undefined
+                ? {}
+                : { offsetTopX: -Number(pad.offsetTopX || 0) })
+        }))
+    }
+
+    /**
+     * Preserves PCB text insertion points for the mirrored text layer.
+     * @param {readonly object[] | undefined} texts Text primitives.
+     * @returns {object[]}
+     */
+    static #mirrorTexts(texts) {
+        return AltiumPcbBottomViewMirror.#array(texts).map((text) => ({
+            ...text
+        }))
+    }
+
+    /**
+     * Mirrors component origins and package rotations.
+     * @param {readonly object[] | undefined} components Component records.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorComponents(components, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(components).map(
+            (component) => ({
+                ...component,
+                x: mirrorX(component?.x),
+                rotation: AltiumPcbBottomViewMirror.#mirrorRotation(
+                    component?.rotation
+                )
+            })
+        )
+    }
+
+    /**
+     * Mirrors a list of point objects.
+     * @param {readonly object[] | undefined} points Point list.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorPointList(points, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(points).map((point) => ({
+            ...point,
+            x: mirrorX(point?.x),
+            ...(point?.centerX === null || point?.centerX === undefined
+                ? {}
+                : { centerX: mirrorX(point.centerX) }),
+            ...(point?.startAngle === null || point?.startAngle === undefined
+                ? {}
+                : {
+                      startAngle: AltiumPcbBottomViewMirror.#mirrorAngleX(
+                          point.startAngle
+                      )
+                  }),
+            ...(point?.endAngle === null || point?.endAngle === undefined
+                ? {}
+                : {
+                      endAngle: AltiumPcbBottomViewMirror.#mirrorAngleX(
+                          point.endAngle
+                      )
+                  })
+        }))
+    }
+
+    /**
+     * Mirrors nested hole point lists.
+     * @param {readonly object[][] | undefined} holes Hole point lists.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[][]}
+     */
+    static #mirrorHoleLists(holes, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(holes).map((hole) =>
+            AltiumPcbBottomViewMirror.#mirrorPointList(hole, mirrorX)
+        )
+    }
+
+    /**
+     * Mirrors board-region bending-line X endpoints.
+     * @param {readonly object[] | undefined} bendingLines Bending lines.
+     * @param {(value: unknown) => number} mirrorX X-axis mirror function.
+     * @returns {object[]}
+     */
+    static #mirrorBendingLines(bendingLines, mirrorX) {
+        return AltiumPcbBottomViewMirror.#array(bendingLines).map((line) => ({
+            ...line,
+            x1:
+                line?.x1 === null || line?.x1 === undefined
+                    ? (line?.x1 ?? null)
+                    : mirrorX(line.x1),
+            x2:
+                line?.x2 === null || line?.x2 === undefined
+                    ? (line?.x2 ?? null)
+                    : mirrorX(line.x2)
+        }))
+    }
+
+    /**
+     * Mirrors an object rotation across the board X axis.
+     * @param {unknown} angle Rotation angle in degrees.
+     * @returns {number}
+     */
+    static #mirrorRotation(angle) {
+        return AltiumPcbBottomViewMirror.#normalizeAngle(
+            180 - Number(angle || 0)
+        )
+    }
+
+    /**
+     * Mirrors a polar angle across the board X axis.
+     * @param {unknown} angle Angle in degrees.
+     * @returns {number}
+     */
+    static #mirrorAngleX(angle) {
+        return AltiumPcbBottomViewMirror.#normalizeAngle(
+            180 - Number(angle || 0)
+        )
+    }
+
+    /**
+     * Normalizes one angle into the [0, 360) range.
+     * @param {number} angle Angle in degrees.
+     * @returns {number}
+     */
+    static #normalizeAngle(angle) {
+        const normalized = Number(angle || 0) % 360
+
+        return normalized < 0 ? normalized + 360 : normalized
+    }
+
+    /**
+     * Returns an array copy for transform operations.
+     * @param {readonly object[] | undefined} value Input collection.
+     * @returns {object[]}
+     */
+    static #array(value) {
+        return Array.isArray(value) ? Array.from(value) : []
+    }
+}

package/src/ui/AltiumScene3dAuthoredBodyAnchorAdapter.mjs

@@ -0,0 +1,300 @@
+/**
+ * Preserves Altium component-body anchors that intentionally differ from the
+ * resolved footprint owner origin.
+ */
+export class AltiumScene3dAuthoredBodyAnchorAdapter {
+    static #MIN_OWNER_OFFSET_MIL = 25
+    static #BODY_ANCHOR_TOLERANCE_MIL = 5
+    static #AUTHORED_SOURCE = 'authored-body-anchor'
+    static #AUTHORED_ANCHOR_IDENTITY_PATTERN =
+        /(?:^|[^a-z0-9])(?:antenna|coax|connector|edge|header|jack|mechanical|module|mount|shield|sma|socket|usb)(?:$|[^a-z0-9])/i
+
+    /**
+     * Marks off-anchor explicit Altium body placements so the runtime does not
+     * recenter them by loaded model bounds.
+     * @param {object} sceneDescription Built scene description.
+     * @returns {object}
+     */
+    static apply(sceneDescription) {
+        if (
+            String(sceneDescription?.sourceFormat || '').toLowerCase() !==
+                'altium' ||
+            !Array.isArray(sceneDescription?.externalPlacements)
+        ) {
+            return sceneDescription
+        }
+
+        const componentByDesignator =
+            AltiumScene3dAuthoredBodyAnchorAdapter.#componentByDesignator(
+                sceneDescription?.components
+            )
+        if (!componentByDesignator.size) {
+            return sceneDescription
+        }
+
+        let changed = false
+        const externalPlacements = sceneDescription.externalPlacements.map(
+            (placement) => {
+                const component = componentByDesignator.get(
+                    String(placement?.designator || '')
+                )
+                if (
+                    !AltiumScene3dAuthoredBodyAnchorAdapter.#shouldMarkPlacement(
+                        placement,
+                        component,
+                        sceneDescription?.board
+                    )
+                ) {
+                    return placement
+                }
+
+                changed = true
+                return AltiumScene3dAuthoredBodyAnchorAdapter.#markPlacement(
+                    placement,
+                    component,
+                    sceneDescription?.board
+                )
+            }
+        )
+
+        return changed
+            ? {
+                  ...sceneDescription,
+                  externalPlacements
+              }
+            : sceneDescription
+    }
+
+    /**
+     * Builds a designator lookup for scene components.
+     * @param {object[] | undefined} components Scene components.
+     * @returns {Map<string, object>}
+     */
+    static #componentByDesignator(components) {
+        return new Map(
+            (Array.isArray(components) ? components : [])
+                .map((component) => [
+                    String(component?.designator || ''),
+                    component
+                ])
+                .filter(([designator]) => designator)
+        )
+    }
+
+    /**
+     * Checks whether one placement should bypass runtime pad-fallback
+     * recentering.
+     * @param {object} placement External placement.
+     * @param {object | undefined} component Matched scene component.
+     * @param {object | undefined} board Scene board.
+     * @returns {boolean}
+     */
+    static #shouldMarkPlacement(placement, component, board) {
+        if (
+            !component ||
+            String(placement?.projection?.source || '').toLowerCase() !==
+                'pad-fallback' ||
+            !placement?.positionMil ||
+            !placement?.bodyPositionMil
+        ) {
+            return false
+        }
+
+        const bodyPosition = AltiumScene3dAuthoredBodyAnchorAdapter.#point(
+            placement.bodyPositionMil
+        )
+        const placementPosition =
+            AltiumScene3dAuthoredBodyAnchorAdapter.#absolutePlacementPosition(
+                placement,
+                board
+            )
+        const ownerPosition =
+            AltiumScene3dAuthoredBodyAnchorAdapter.#ownerPosition(
+                component,
+                board
+            )
+        const ownerOffset = AltiumScene3dAuthoredBodyAnchorAdapter.#distance(
+            bodyPosition,
+            ownerPosition
+        )
+
+        if (
+            ownerOffset <
+            AltiumScene3dAuthoredBodyAnchorAdapter.#MIN_OWNER_OFFSET_MIL
+        ) {
+            return false
+        }
+
+        if (
+            AltiumScene3dAuthoredBodyAnchorAdapter.#distance(
+                placementPosition,
+                bodyPosition
+            ) >
+            AltiumScene3dAuthoredBodyAnchorAdapter.#BODY_ANCHOR_TOLERANCE_MIL
+        ) {
+            return false
+        }
+
+        return AltiumScene3dAuthoredBodyAnchorAdapter.#hasAuthoredAnchorIdentity(
+            placement,
+            component
+        )
+    }
+
+    /**
+     * Checks whether package metadata suggests the offset is an authored
+     * connector/mechanical anchor instead of a package source-origin bias.
+     * @param {object} placement External placement.
+     * @param {object} component Matched scene component.
+     * @returns {boolean}
+     */
+    static #hasAuthoredAnchorIdentity(placement, component) {
+        return AltiumScene3dAuthoredBodyAnchorAdapter.#AUTHORED_ANCHOR_IDENTITY_PATTERN.test(
+            AltiumScene3dAuthoredBodyAnchorAdapter.#identityText(
+                placement,
+                component
+            )
+        )
+    }
+
+    /**
+     * Builds searchable package metadata for anchor-preservation checks.
+     * @param {object} placement External placement.
+     * @param {object} component Matched scene component.
+     * @returns {string}
+     */
+    static #identityText(placement, component) {
+        return [
+            placement?.designator,
+            placement?.externalModel?.name,
+            placement?.externalModel?.relativePath,
+            component?.pattern,
+            component?.source,
+            component?.description,
+            component?.body?.family,
+            ...Object.values(component?.parameters || {})
+        ]
+            .map((value) => String(value || ''))
+            .join(' ')
+    }
+
+    /**
+     * Marks one placement as authored-anchor based.
+     * @param {object} placement External placement.
+     * @param {object} component Matched scene component.
+     * @param {object | undefined} board Scene board.
+     * @returns {object}
+     */
+    static #markPlacement(placement, component, board) {
+        return {
+            ...placement,
+            projection: {
+                ...(placement.projection || {}),
+                source: AltiumScene3dAuthoredBodyAnchorAdapter.#AUTHORED_SOURCE,
+                reason: 'Altium component body uses an authored model-origin anchor offset from the owner footprint.'
+            },
+            modelTransform: {
+                ...(placement.modelTransform || {}),
+                ownerAnchorOffsetMil:
+                    AltiumScene3dAuthoredBodyAnchorAdapter.#ownerAnchorOffset(
+                        placement,
+                        component,
+                        board
+                    )
+            }
+        }
+    }
+
+    /**
+     * Resolves the source body offset from its owner footprint anchor.
+     * @param {object} placement External placement.
+     * @param {object} component Matched scene component.
+     * @param {object | undefined} board Scene board.
+     * @returns {{ x: number, y: number }}
+     */
+    static #ownerAnchorOffset(placement, component, board) {
+        const bodyPosition = AltiumScene3dAuthoredBodyAnchorAdapter.#point(
+            placement.bodyPositionMil
+        )
+        const ownerPosition =
+            AltiumScene3dAuthoredBodyAnchorAdapter.#ownerPosition(
+                component,
+                board
+            )
+
+        return {
+            x: bodyPosition.x - ownerPosition.x,
+            y: bodyPosition.y - ownerPosition.y
+        }
+    }
+
+    /**
+     * Resolves a placement position in board coordinates.
+     * @param {object} placement External placement.
+     * @param {object | undefined} board Scene board.
+     * @returns {{ x: number, y: number }}
+     */
+    static #absolutePlacementPosition(placement, board) {
+        return {
+            x:
+                Number(placement?.positionMil?.x || 0) +
+                Number(board?.centerX || 0),
+            y:
+                Number(placement?.positionMil?.y || 0) +
+                Number(board?.centerY || 0)
+        }
+    }
+
+    /**
+     * Resolves a scene component position in board coordinates.
+     * @param {object} component Scene component.
+     * @param {object | undefined} board Scene board.
+     * @returns {{ x: number, y: number }}
+     */
+    static #ownerPosition(component, board) {
+        const boardPosition = component?.boardPositionMil
+        if (
+            Number.isFinite(Number(boardPosition?.x)) &&
+            Number.isFinite(Number(boardPosition?.y))
+        ) {
+            return {
+                x: Number(boardPosition.x),
+                y: Number(boardPosition.y)
+            }
+        }
+
+        return {
+            x:
+                Number(component?.positionMil?.x || 0) +
+                Number(board?.centerX || 0),
+            y:
+                Number(component?.positionMil?.y || 0) +
+                Number(board?.centerY || 0)
+        }
+    }
+
+    /**
+     * Normalizes a partial point.
+     * @param {object | undefined} point Source point.
+     * @returns {{ x: number, y: number }}
+     */
+    static #point(point) {
+        return {
+            x: Number(point?.x || 0),
+            y: Number(point?.y || 0)
+        }
+    }
+
+    /**
+     * 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)
+        )
+    }
+}