circuitjson-toolkit 1.0.3 → 1.0.16

package/src/core/CircuitJsonPcbPrimitiveFields.mjs

@@ -0,0 +1,233 @@
+import { CircuitJsonIndexer } from './CircuitJsonIndexer.mjs'
+import { CircuitJsonUnits } from './CircuitJsonUnits.mjs'
+import { CircuitJsonPcbPrimitiveGeometry } from './CircuitJsonPcbPrimitiveGeometry.mjs'
+
+/**
+ * Resolves shared CircuitJSON PCB primitive fields from common element shapes.
+ */
+export class CircuitJsonPcbPrimitiveFields {
+    /**
+     * Resolves board bounds from outline or size metadata.
+     * @param {object | null} board Board element.
+     * @returns {object | null}
+     */
+    static boardBounds(board) {
+        const outline = CircuitJsonPcbPrimitiveFields.points(board)
+        if (outline.length >= 3) {
+            return CircuitJsonPcbPrimitiveGeometry.pointsBounds(outline)
+        }
+
+        const width = CircuitJsonUnits.optionalLength(board?.width)
+        const height = CircuitJsonUnits.optionalLength(board?.height)
+        if (width === null || height === null || width <= 0 || height <= 0) {
+            return null
+        }
+
+        return CircuitJsonPcbPrimitiveGeometry.centerBounds(
+            CircuitJsonPcbPrimitiveFields.center(board) || { x: 0, y: 0 },
+            width,
+            height
+        )
+    }
+
+    /**
+     * Resolves merged bounds for all board rows.
+     * @param {object[]} boards Board rows.
+     * @returns {object | null}
+     */
+    static mergedBoardBounds(boards) {
+        return CircuitJsonPcbPrimitiveGeometry.mergedPrimitiveBounds(
+            boards
+                .map((board) => ({
+                    bounds: CircuitJsonPcbPrimitiveFields.boardBounds(board)
+                }))
+                .filter((row) => row.bounds)
+        )
+    }
+
+    /**
+     * Builds copper layer rows from board metadata.
+     * @param {object | null} board Board element.
+     * @returns {object[]}
+     */
+    static layers(board) {
+        const count = Math.max(
+            1,
+            Math.round(CircuitJsonUnits.length(board?.num_layers, 2))
+        )
+        const keys =
+            count === 1
+                ? ['top']
+                : [
+                      'top',
+                      ...Array.from(
+                          { length: Math.max(count - 2, 0) },
+                          (_entry, index) => 'inner' + (index + 1)
+                      ),
+                      'bottom'
+                  ]
+
+        return keys.map((key, index) => ({
+            key,
+            id: key,
+            layer: key,
+            name: key,
+            number: index + 1,
+            side: key === 'top' ? 'top' : key === 'bottom' ? 'bottom' : 'inner',
+            type: 'copper',
+            sourceFormat: 'circuitjson'
+        }))
+    }
+
+    /**
+     * Resolves a center point.
+     * @param {object} element Element row.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static center(element) {
+        return CircuitJsonPcbPrimitiveFields.point(element?.center || element)
+    }
+
+    /**
+     * Resolves one point.
+     * @param {object | null | undefined} value Point candidate.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static point(value) {
+        return CircuitJsonUnits.optionalPoint(value)
+    }
+
+    /**
+     * Resolves polygon points from common fields.
+     * @param {object} element Element row.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static points(element) {
+        return (
+            (Array.isArray(element?.points) && element.points) ||
+            (Array.isArray(element?.outline) && element.outline) ||
+            (Array.isArray(element?.vertices) && element.vertices) ||
+            (Array.isArray(element?.route) && element.route) ||
+            (Array.isArray(element?.path) && element.path) ||
+            (Array.isArray(element?.shape?.points) && element.shape.points) ||
+            []
+        )
+            .map((point) => CircuitJsonPcbPrimitiveFields.point(point))
+            .filter(Boolean)
+    }
+
+    /**
+     * Resolves open line/path points from common detail geometry fields.
+     * @param {object} element Element row.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static linePoints(element) {
+        const points = CircuitJsonPcbPrimitiveFields.points(element)
+        if (points.length > 1) return points
+
+        return [
+            CircuitJsonPcbPrimitiveFields.point({
+                x: element.x1 ?? element.start?.x,
+                y: element.y1 ?? element.start?.y
+            }),
+            CircuitJsonPcbPrimitiveFields.point({
+                x: element.x2 ?? element.end?.x,
+                y: element.y2 ?? element.end?.y
+            })
+        ].filter(Boolean)
+    }
+
+    /**
+     * Resolves the center of a point list.
+     * @param {{ x: number, y: number }[]} points Points.
+     * @returns {{ x: number, y: number } | null}
+     */
+    static pointsCenter(points) {
+        const bounds = CircuitJsonPcbPrimitiveGeometry.pointsBounds(points)
+        return bounds
+            ? {
+                  x: bounds.minX + bounds.width / 2,
+                  y: bounds.minY + bounds.height / 2
+              }
+            : null
+    }
+
+    /**
+     * Resolves a normalized layer key.
+     * @param {unknown} value Layer candidate.
+     * @returns {string}
+     */
+    static layer(value) {
+        const raw =
+            typeof value === 'object' && value !== null ? value.name : value
+        const text = String(raw ?? '').trim()
+        const lowered = text.toLowerCase()
+        if (['top', 'front', 'f.cu', '1'].includes(lowered)) return 'top'
+        if (['bottom', 'back', 'b.cu', '32'].includes(lowered)) return 'bottom'
+        return text
+    }
+
+    /**
+     * Resolves the side from a layer key.
+     * @param {string} layer Layer key.
+     * @returns {'top' | 'bottom' | ''}
+     */
+    static side(layer) {
+        const text = String(layer || '').toLowerCase()
+        if (/\b(bottom|back)\b|\bb[._-]/u.test(text)) return 'bottom'
+        if (/\b(top|front)\b|\bf[._-]/u.test(text)) return 'top'
+        return ''
+    }
+
+    /**
+     * Resolves a net name from common fields.
+     * @param {object} element Element row.
+     * @param {string | null} fallback Fallback net name.
+     * @returns {string}
+     */
+    static netName(element, fallback = '') {
+        return String(
+            element?.netName ??
+                element?.net ??
+                element?.net_name ??
+                element?.source_net_id ??
+                fallback ??
+                ''
+        ).trim()
+    }
+
+    /**
+     * Resolves first valid length from candidates.
+     * @param {unknown[]} values Candidate values.
+     * @returns {number | null}
+     */
+    static optionalLength(values) {
+        for (const value of values) {
+            const length = CircuitJsonUnits.optionalLength(value)
+            if (length !== null) return length
+        }
+        return null
+    }
+
+    /**
+     * Resolves an id for original or derived shape primitives.
+     * @param {object} element Element row.
+     * @returns {string}
+     */
+    static derivedId(element) {
+        const id = CircuitJsonIndexer.getElementId(element)
+        const suffix = String(element.derived_id_suffix || '').trim()
+        return id && suffix ? id + ':' + suffix : id
+    }
+
+    /**
+     * Resolves unique non-empty string values.
+     * @param {unknown[]} values Candidate values.
+     * @returns {string[]}
+     */
+    static uniqueStrings(values) {
+        return [...new Set(values.map((value) => String(value || '').trim()))]
+            .filter(Boolean)
+            .sort()
+    }
+}

package/src/core/CircuitJsonPcbPrimitiveGeometry.mjs

@@ -0,0 +1,142 @@
+/**
+ * Provides shared geometry helpers for CircuitJSON PCB primitive builders.
+ */
+export class CircuitJsonPcbPrimitiveGeometry {
+    /**
+     * Builds a normalized bounds record.
+     * @param {number} minX Minimum x.
+     * @param {number} minY Minimum y.
+     * @param {number} maxX Maximum x.
+     * @param {number} maxY Maximum y.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number, width: number, height: number }}
+     */
+    static bounds(minX, minY, maxX, maxY) {
+        return {
+            minX,
+            minY,
+            maxX,
+            maxY,
+            width: maxX - minX,
+            height: maxY - minY
+        }
+    }
+
+    /**
+     * Builds bounds from a center and dimensions.
+     * @param {{ x: number, y: number }} center Center point.
+     * @param {number} width Width.
+     * @param {number} height Height.
+     * @returns {object}
+     */
+    static centerBounds(center, width, height) {
+        return CircuitJsonPcbPrimitiveGeometry.bounds(
+            center.x - width / 2,
+            center.y - height / 2,
+            center.x + width / 2,
+            center.y + height / 2
+        )
+    }
+
+    /**
+     * Builds segment bounds.
+     * @param {{ x: number, y: number }} start Start point.
+     * @param {{ x: number, y: number }} end End point.
+     * @param {number} width Segment width.
+     * @returns {object}
+     */
+    static segmentBounds(start, end, width) {
+        const margin = Math.max(width / 2, 0)
+        return CircuitJsonPcbPrimitiveGeometry.bounds(
+            Math.min(start.x, end.x) - margin,
+            Math.min(start.y, end.y) - margin,
+            Math.max(start.x, end.x) + margin,
+            Math.max(start.y, end.y) + margin
+        )
+    }
+
+    /**
+     * Builds bounds for a point list.
+     * @param {{ x: number, y: number }[]} points Points.
+     * @returns {object | null}
+     */
+    static pointsBounds(points) {
+        return points.reduce(
+            (bounds, point) =>
+                bounds
+                    ? CircuitJsonPcbPrimitiveGeometry.bounds(
+                          Math.min(bounds.minX, point.x),
+                          Math.min(bounds.minY, point.y),
+                          Math.max(bounds.maxX, point.x),
+                          Math.max(bounds.maxY, point.y)
+                      )
+                    : CircuitJsonPcbPrimitiveGeometry.bounds(
+                          point.x,
+                          point.y,
+                          point.x,
+                          point.y
+                      ),
+            null
+        )
+    }
+
+    /**
+     * Builds merged primitive bounds.
+     * @param {object[]} primitives Primitive rows.
+     * @returns {object | null}
+     */
+    static mergedPrimitiveBounds(primitives) {
+        return primitives.reduce((bounds, primitive) => {
+            if (!primitive.bounds) return bounds
+            if (!bounds) return primitive.bounds
+            return CircuitJsonPcbPrimitiveGeometry.bounds(
+                Math.min(bounds.minX, primitive.bounds.minX),
+                Math.min(bounds.minY, primitive.bounds.minY),
+                Math.max(bounds.maxX, primitive.bounds.maxX),
+                Math.max(bounds.maxY, primitive.bounds.maxY)
+            )
+        }, null)
+    }
+
+    /**
+     * Builds corner anchors for bounds.
+     * @param {object} bounds Bounds record.
+     * @returns {object[]}
+     */
+    static cornerAnchors(bounds) {
+        return CircuitJsonPcbPrimitiveGeometry.boundsAnchors(bounds)
+    }
+
+    /**
+     * Builds corner, edge-center, and center anchors for bounds.
+     * @param {object} bounds Bounds record.
+     * @returns {object[]}
+     */
+    static boundsAnchors(bounds) {
+        const centerX = CircuitJsonPcbPrimitiveGeometry.#round(
+            bounds.minX + bounds.width / 2
+        )
+        const centerY = CircuitJsonPcbPrimitiveGeometry.#round(
+            bounds.minY + bounds.height / 2
+        )
+        return [
+            { point: { x: bounds.minX, y: bounds.minY } },
+            { point: { x: centerX, y: bounds.minY } },
+            { point: { x: bounds.maxX, y: bounds.minY } },
+            { point: { x: bounds.maxX, y: centerY } },
+            { point: { x: bounds.maxX, y: bounds.maxY } },
+            { point: { x: centerX, y: bounds.maxY } },
+            { point: { x: bounds.minX, y: bounds.maxY } },
+            { point: { x: bounds.minX, y: centerY } },
+            { point: { x: centerX, y: centerY } }
+        ]
+    }
+
+    /**
+     * Rounds computed geometry values to stable precision.
+     * @param {number} value Numeric value.
+     * @returns {number}
+     */
+    static #round(value) {
+        return Math.round(Number(value || 0) * 1_000_000) / 1_000_000
+    }
+}

package/src/core/CircuitJsonPcbPrimitiveGroups.mjs

@@ -0,0 +1,305 @@
+import { CircuitJsonUnits } from './CircuitJsonUnits.mjs'
+import { CircuitJsonPcbPrimitiveGeometry } from './CircuitJsonPcbPrimitiveGeometry.mjs'
+
+/**
+ * Builds PCB group rows and group-anchor overlays from element arrays.
+ */
+export class CircuitJsonPcbPrimitiveGroups {
+    /**
+     * Builds group metadata and decorated primitive rows.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @param {object[]} primitives Primitive rows.
+     * @param {object[]} components Component rows.
+     * @returns {{ primitives: object[], groups: object[], anchorOffsets: object[] }}
+     */
+    static build(index, primitives, components) {
+        const groups = CircuitJsonPcbPrimitiveGroups.#groups(
+            index,
+            primitives,
+            components
+        )
+        const componentGroups =
+            CircuitJsonPcbPrimitiveGroups.#componentGroupIds(components)
+        return {
+            primitives: primitives.map((primitive) =>
+                CircuitJsonPcbPrimitiveGroups.#withGroupIds(
+                    primitive,
+                    index,
+                    componentGroups
+                )
+            ),
+            groups,
+            anchorOffsets: CircuitJsonPcbPrimitiveGroups.#anchorOffsets(
+                groups,
+                components
+            )
+        }
+    }
+
+    /**
+     * Builds PCB group rows.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @param {object[]} primitives Primitive rows.
+     * @param {object[]} components Component rows.
+     * @returns {object[]}
+     */
+    static #groups(index, primitives, components) {
+        return CircuitJsonPcbPrimitiveGroups.#all(index, 'pcb_group')
+            .map((group) =>
+                CircuitJsonPcbPrimitiveGroups.#groupRow(
+                    group,
+                    primitives,
+                    components
+                )
+            )
+            .filter(Boolean)
+    }
+
+    /**
+     * Builds one group row.
+     * @param {object} group Source group element.
+     * @param {object[]} primitives Primitive rows.
+     * @param {object[]} components Component rows.
+     * @returns {object | null}
+     */
+    static #groupRow(group, primitives, components) {
+        const id = String(group.pcb_group_id || '').trim()
+        if (!id) return null
+        const componentIds = components
+            .filter(
+                (component) =>
+                    String(component.pcb_group_id || '').trim() === id
+            )
+            .map((component) => component.pcbComponentId)
+            .filter(Boolean)
+        return {
+            id,
+            type: 'pcb_group',
+            name: String(group.name || id),
+            bounds: CircuitJsonPcbPrimitiveGroups.#groupBounds(
+                group,
+                primitives
+            ),
+            sourceGroupId: String(group.source_group_id || '').trim(),
+            subcircuitId: String(group.subcircuit_id || '').trim(),
+            componentIds,
+            memberIds: CircuitJsonPcbPrimitiveGroups.#memberIds(
+                id,
+                primitives,
+                componentIds
+            ),
+            anchor: CircuitJsonUnits.optionalPoint(group.anchor_position),
+            depth: Number.isFinite(Number(group.depth))
+                ? Number(group.depth)
+                : 0,
+            ...CircuitJsonPcbPrimitiveGroups.#optionalGroupMetadata(group)
+        }
+    }
+
+    /**
+     * Builds optional group metadata for inspection.
+     * @param {object} group Source group element.
+     * @returns {object}
+     */
+    static #optionalGroupMetadata(group) {
+        return {
+            ...CircuitJsonPcbPrimitiveGroups.#optionalStringField(
+                'anchorAlignment',
+                group.anchor_alignment
+            ),
+            ...CircuitJsonPcbPrimitiveGroups.#optionalStringField(
+                'positionMode',
+                group.position_mode
+            ),
+            ...CircuitJsonPcbPrimitiveGroups.#optionalStringField(
+                'childLayoutMode',
+                group.child_layout_mode
+            ),
+            ...CircuitJsonPcbPrimitiveGroups.#optionalStringField(
+                'layoutMode',
+                group.layout_mode
+            ),
+            ...CircuitJsonPcbPrimitiveGroups.#optionalLengthField(
+                'autorouterTraceClearance',
+                group.autorouter_configuration?.trace_clearance
+            )
+        }
+    }
+
+    /**
+     * Builds an optional string field.
+     * @param {string} key Output key.
+     * @param {unknown} value Candidate value.
+     * @returns {object}
+     */
+    static #optionalStringField(key, value) {
+        const text = String(value || '').trim()
+        return text ? { [key]: text } : {}
+    }
+
+    /**
+     * Builds an optional length field.
+     * @param {string} key Output key.
+     * @param {unknown} value Candidate value.
+     * @returns {object}
+     */
+    static #optionalLengthField(key, value) {
+        const number = CircuitJsonUnits.optionalLength(value)
+        return number === null ? {} : { [key]: number }
+    }
+
+    /**
+     * Resolves group bounds from explicit size or grouped primitives.
+     * @param {object} group Group element.
+     * @param {object[]} primitives Primitive rows.
+     * @returns {object | null}
+     */
+    static #groupBounds(group, primitives) {
+        const center = CircuitJsonUnits.optionalPoint(group.center || group)
+        const size = CircuitJsonUnits.optionalSize(group.size || group)
+        if (center && size) {
+            return CircuitJsonPcbPrimitiveGeometry.centerBounds(
+                center,
+                size.width,
+                size.height
+            )
+        }
+
+        return CircuitJsonPcbPrimitiveGeometry.mergedPrimitiveBounds(
+            primitives.filter(
+                (primitive) =>
+                    String(primitive.source?.pcb_group_id || '').trim() ===
+                    String(group.pcb_group_id || '').trim()
+            )
+        )
+    }
+
+    /**
+     * Builds member ids from components and primitives.
+     * @param {string} groupId Group id.
+     * @param {object[]} primitives Primitive rows.
+     * @param {string[]} componentIds Component ids.
+     * @returns {string[]}
+     */
+    static #memberIds(groupId, primitives, componentIds) {
+        const ids = [...componentIds]
+        for (const primitive of primitives) {
+            if (
+                String(primitive.source?.pcb_group_id || '').trim() !== groupId
+            ) {
+                continue
+            }
+            if (primitive.id && !ids.includes(primitive.id)) {
+                ids.push(primitive.id)
+            }
+        }
+        return ids
+    }
+
+    /**
+     * Builds group ids for each component id.
+     * @param {object[]} components Component rows.
+     * @returns {Map<string, string[]>}
+     */
+    static #componentGroupIds(components) {
+        return new Map(
+            components.map((component) => [
+                String(component.pcbComponentId || ''),
+                CircuitJsonPcbPrimitiveGroups.#unique(component.groupIds || [])
+            ])
+        )
+    }
+
+    /**
+     * Decorates one primitive with group and subcircuit ids.
+     * @param {object} primitive Primitive row.
+     * @param {{ sourceComponentById?: Map<string, object> }} index Element index.
+     * @param {Map<string, string[]>} componentGroups Component group lookup.
+     * @returns {object}
+     */
+    static #withGroupIds(primitive, index, componentGroups) {
+        const sourceComponent = index.sourceComponentById?.get(
+            String(primitive.component?.source_component_id || '').trim()
+        )
+        const groupIds = CircuitJsonPcbPrimitiveGroups.#unique([
+            ...(primitive.groupIds || []),
+            primitive.source?.pcb_group_id,
+            primitive.source?.source_group_id,
+            primitive.component?.pcb_group_id,
+            primitive.component?.positioned_relative_to_pcb_group_id,
+            primitive.component?.source_group_id,
+            primitive.component?.sourceGroupId,
+            sourceComponent?.source_group_id,
+            ...(componentGroups.get(String(primitive.componentId || '')) || [])
+        ])
+        const subcircuitIds = CircuitJsonPcbPrimitiveGroups.#unique([
+            ...(primitive.subcircuitIds || []),
+            primitive.source?.subcircuit_id,
+            primitive.source?.subcircuitId,
+            primitive.component?.subcircuit_id,
+            primitive.component?.subcircuitId,
+            ...(primitive.component?.subcircuitIds || []),
+            sourceComponent?.subcircuit_id
+        ])
+        return {
+            ...primitive,
+            groupIds,
+            subcircuitIds
+        }
+    }
+
+    /**
+     * Builds visual anchor offsets for grouped component placements.
+     * @param {object[]} groups Group rows.
+     * @param {object[]} components Component rows.
+     * @returns {object[]}
+     */
+    static #anchorOffsets(groups, components) {
+        return groups.flatMap((group) => {
+            if (!group.anchor) return []
+            return group.componentIds.flatMap((componentId) => {
+                const component = components.find(
+                    (row) => row.pcbComponentId === componentId
+                )
+                if (!component) return []
+                return [
+                    {
+                        id: 'anchor-offset:' + group.id + ':' + componentId,
+                        kind: 'group-anchor-offset',
+                        sourceId: group.id,
+                        targetId: componentId,
+                        targetType: 'component',
+                        start: group.anchor,
+                        end: { x: component.x, y: component.y },
+                        label: component.componentKey
+                    }
+                ]
+            })
+        })
+    }
+
+    /**
+     * Returns indexed elements by type.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @param {string} type Element type.
+     * @returns {object[]}
+     */
+    static #all(index, type) {
+        return index.elementsByType.get(type) || []
+    }
+
+    /**
+     * Resolves unique non-empty strings.
+     * @param {unknown[]} values Candidate values.
+     * @returns {string[]}
+     */
+    static #unique(values) {
+        return [...new Set(values.map((value) => String(value || '').trim()))]
+            .filter(Boolean)
+            .sort((left, right) => {
+                const leftPcb = left.startsWith('pcb_') ? 0 : 1
+                const rightPcb = right.startsWith('pcb_') ? 0 : 1
+                return leftPcb - rightPcb || left.localeCompare(right)
+            })
+    }
+}