circuitjson-toolkit 1.0.3 → 1.0.16

package/src/core/CircuitJsonPcbHolePrimitiveModel.mjs

@@ -0,0 +1,172 @@
+import { CircuitJsonUnits } from './CircuitJsonUnits.mjs'
+import { CircuitJsonPcbPrimitiveGeometry } from './CircuitJsonPcbPrimitiveGeometry.mjs'
+
+/**
+ * Normalizes drilled PCB elements into shared primitive geometry.
+ */
+export class CircuitJsonPcbHolePrimitiveModel {
+    /**
+     * Builds shape and bounds metadata for a drilled PCB element.
+     * @param {object} element Drilled PCB element.
+     * @param {{ x: number, y: number }} center Drill center.
+     * @returns {object}
+     */
+    static build(element, center) {
+        const shape = CircuitJsonPcbHolePrimitiveModel.#outerShape(element)
+        const points = CircuitJsonPcbHolePrimitiveModel.#outerPoints(element)
+        const size = CircuitJsonPcbHolePrimitiveModel.#outerSize(element, shape)
+        const hole = CircuitJsonPcbHolePrimitiveModel.#holeSize(
+            element,
+            shape,
+            size
+        )
+        const bounds = points.length
+            ? CircuitJsonPcbPrimitiveGeometry.pointsBounds(points)
+            : CircuitJsonPcbPrimitiveGeometry.centerBounds(
+                  center,
+                  size.width,
+                  size.height
+              )
+
+        return {
+            shape,
+            width: size.width,
+            height: size.height,
+            diameter: Math.max(size.width, size.height),
+            holeShape: hole.shape,
+            holeDiameter: hole.diameter,
+            holeWidth: hole.width,
+            holeHeight: hole.height,
+            rotation: CircuitJsonUnits.angle(
+                element.ccw_rotation ?? element.rotation,
+                0
+            ),
+            points,
+            bounds
+        }
+    }
+
+    /**
+     * Resolves the visible copper or board hole shape.
+     * @param {object} element Drilled PCB element.
+     * @returns {'circle' | 'pill' | 'polygon' | 'rect'}
+     */
+    static #outerShape(element) {
+        const raw = CircuitJsonPcbHolePrimitiveModel.#shapeText(
+            element.shape || element.hole_shape
+        )
+        if (raw.includes('polygon')) return 'polygon'
+        if (raw.includes('rect')) return 'rect'
+        if (
+            raw.includes('pill') ||
+            raw.includes('slot') ||
+            raw.includes('oval')
+        )
+            return 'pill'
+        return 'circle'
+    }
+
+    /**
+     * Resolves the outer rendered size.
+     * @param {object} element Drilled PCB element.
+     * @param {string} shape Normalized outer shape.
+     * @returns {{ width: number, height: number }}
+     */
+    static #outerSize(element, shape) {
+        const diameter = CircuitJsonUnits.length(
+            element.diameter ?? element.outer_diameter,
+            0.6
+        )
+        const width = CircuitJsonUnits.length(
+            element.rect_pad_width ?? element.pad_width ?? element.width,
+            diameter
+        )
+        const height = CircuitJsonUnits.length(
+            element.rect_pad_height ?? element.pad_height ?? element.height,
+            shape === 'circle' ? width : diameter
+        )
+
+        return {
+            width,
+            height: shape === 'circle' ? width : height
+        }
+    }
+
+    /**
+     * Resolves polygonal outer pad points.
+     * @param {object} element Drilled PCB element.
+     * @returns {{ x: number, y: number }[]}
+     */
+    static #outerPoints(element) {
+        return (Array.isArray(element?.pad_outline) ? element.pad_outline : [])
+            .map((point) => CircuitJsonUnits.optionalPoint(point))
+            .filter(Boolean)
+    }
+
+    /**
+     * Resolves the drilled opening size.
+     * @param {object} element Drilled PCB element.
+     * @param {string} outerShape Normalized outer shape.
+     * @param {{ width: number, height: number }} outerSize Outer size.
+     * @returns {{ shape: 'circle' | 'pill' | 'rect', diameter: number, width: number, height: number }}
+     */
+    static #holeSize(element, outerShape, outerSize) {
+        const shape = CircuitJsonPcbHolePrimitiveModel.#holeShape(
+            element,
+            outerShape
+        )
+        const fallbackDiameter =
+            shape === 'circle'
+                ? Math.min(outerSize.width, outerSize.height) * 0.45
+                : Math.min(outerSize.width, outerSize.height)
+        const diameter = CircuitJsonUnits.length(
+            element.hole_diameter ??
+                element.holeDiameter ??
+                element.drill_diameter,
+            fallbackDiameter
+        )
+        const width = CircuitJsonUnits.length(
+            element.hole_width,
+            shape === 'circle' ? diameter : outerSize.width
+        )
+        const height = CircuitJsonUnits.length(
+            element.hole_height,
+            shape === 'circle' ? diameter : outerSize.height
+        )
+
+        return { shape, diameter, width, height }
+    }
+
+    /**
+     * Resolves the drilled opening shape.
+     * @param {object} element Drilled PCB element.
+     * @param {string} outerShape Normalized outer shape.
+     * @returns {'circle' | 'pill' | 'rect'}
+     */
+    static #holeShape(element, outerShape) {
+        const raw = CircuitJsonPcbHolePrimitiveModel.#shapeText(
+            element.hole_shape || element.shape
+        )
+        if (raw === 'round') return 'circle'
+        if (raw.includes('rect') && !raw.includes('rect_pad')) return 'rect'
+        if (
+            raw.includes('pill') ||
+            raw.includes('slot') ||
+            raw.includes('oval')
+        )
+            return 'pill'
+        if (raw.includes('circular') || raw.includes('circle')) return 'circle'
+        return element.type === 'pcb_hole' ? outerShape : 'circle'
+    }
+
+    /**
+     * Normalizes a shape string.
+     * @param {unknown} value Shape value.
+     * @returns {string}
+     */
+    static #shapeText(value) {
+        return String(value || '')
+            .trim()
+            .toLowerCase()
+    }
+}

package/src/core/CircuitJsonPcbNetMetadata.mjs

@@ -0,0 +1,247 @@
+/**
+ * Normalizes PCB net metadata and applies it to PCB primitive rows.
+ */
+export class CircuitJsonPcbNetMetadata {
+    /**
+     * Decorates primitive rows with explicit net metadata when available.
+     * @param {object[]} primitives Primitive rows.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @returns {object[]}
+     */
+    static decoratePrimitives(primitives, index) {
+        const lookup = CircuitJsonPcbNetMetadata.#lookup(index)
+        return primitives.map((primitive) =>
+            CircuitJsonPcbNetMetadata.#decoratePrimitive(primitive, lookup)
+        )
+    }
+
+    /**
+     * Builds unique net rows from explicit metadata and primitive usage.
+     * @param {object[]} primitives Primitive rows.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @returns {object[]}
+     */
+    static nets(primitives, index) {
+        const entries = CircuitJsonPcbNetMetadata.#entries(index)
+        const byName = new Map(entries.map((entry) => [entry.name, entry]))
+
+        for (const primitive of primitives) {
+            const name = String(primitive.netName || '').trim()
+            if (name && !byName.has(name)) byName.set(name, { name })
+        }
+
+        return [...byName.values()]
+    }
+
+    /**
+     * Applies metadata to one primitive row.
+     * @param {object} primitive Primitive row.
+     * @param {Map<string, object>} lookup Net lookup map.
+     * @returns {object}
+     */
+    static #decoratePrimitive(primitive, lookup) {
+        const entry = CircuitJsonPcbNetMetadata.#primitiveNetEntry(
+            primitive,
+            lookup
+        )
+        if (!entry) return primitive
+
+        return {
+            ...primitive,
+            netName: entry.name || primitive.netName,
+            sourceNetId: entry.sourceNetId || primitive.sourceNetId || '',
+            pcbNetId: entry.pcbNetId || primitive.pcbNetId || '',
+            groupIds: CircuitJsonPcbNetMetadata.#uniqueStrings([
+                ...(primitive.groupIds || []),
+                ...(entry.groupIds || [])
+            ]),
+            ...(entry.highlightColor ? { netColor: entry.highlightColor } : {})
+        }
+    }
+
+    /**
+     * Resolves the explicit net entry matching one primitive.
+     * @param {object} primitive Primitive row.
+     * @param {Map<string, object>} lookup Net lookup map.
+     * @returns {object | null}
+     */
+    static #primitiveNetEntry(primitive, lookup) {
+        for (const candidate of [
+            primitive.netName,
+            primitive.sourceNetId,
+            primitive.pcbNetId,
+            primitive.source?.source_net_id,
+            primitive.source?.pcb_net_id
+        ]) {
+            const key = String(candidate || '').trim()
+            if (key && lookup.has(key)) return lookup.get(key)
+        }
+        return null
+    }
+
+    /**
+     * Builds a lookup keyed by net names and source IDs.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @returns {Map<string, object>}
+     */
+    static #lookup(index) {
+        const lookup = new Map()
+        for (const entry of CircuitJsonPcbNetMetadata.#entries(index)) {
+            for (const key of [entry.name, entry.sourceNetId, entry.pcbNetId]) {
+                const text = String(key || '').trim()
+                if (text) lookup.set(text, entry)
+            }
+        }
+        return lookup
+    }
+
+    /**
+     * Builds explicit net entries from source and PCB net rows.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @returns {object[]}
+     */
+    static #entries(index) {
+        const sourceRows = CircuitJsonPcbNetMetadata.#all(index, 'source_net')
+        const pcbRows = CircuitJsonPcbNetMetadata.#all(index, 'pcb_net')
+        const pcbBySourceId = new Map(
+            pcbRows
+                .map((row) => [String(row.source_net_id || '').trim(), row])
+                .filter(([id]) => id)
+        )
+        const entries = []
+
+        for (const source of sourceRows) {
+            const sourceNetId = String(source.source_net_id || '').trim()
+            const pcbNet = pcbBySourceId.get(sourceNetId) || {}
+            const entry = CircuitJsonPcbNetMetadata.#entry(source, pcbNet)
+            if (entry) entries.push(entry)
+        }
+
+        for (const pcbNet of pcbRows) {
+            const sourceNetId = String(pcbNet.source_net_id || '').trim()
+            if (sourceNetId && pcbBySourceId.has(sourceNetId)) continue
+            const entry = CircuitJsonPcbNetMetadata.#entry({}, pcbNet)
+            if (entry) entries.push(entry)
+        }
+
+        return entries
+    }
+
+    /**
+     * Builds one explicit net entry.
+     * @param {object} source Source net row.
+     * @param {object} pcbNet PCB net row.
+     * @returns {object | null}
+     */
+    static #entry(source, pcbNet) {
+        const sourceNetId = String(
+            source.source_net_id || pcbNet.source_net_id || ''
+        ).trim()
+        const pcbNetId = String(pcbNet.pcb_net_id || '').trim()
+        const name = String(
+            pcbNet.name ||
+                pcbNet.net ||
+                source.name ||
+                source.net ||
+                sourceNetId ||
+                pcbNetId ||
+                ''
+        ).trim()
+        if (!name) return null
+
+        return CircuitJsonPcbNetMetadata.#clean({
+            name,
+            sourceNetId,
+            pcbNetId,
+            groupIds: CircuitJsonPcbNetMetadata.#groupIds(source, pcbNet),
+            highlightColor: CircuitJsonPcbNetMetadata.#safeColor(
+                pcbNet.highlight_color || pcbNet.highlightColor || pcbNet.color
+            )
+        })
+    }
+
+    /**
+     * Resolves group ids from explicit net metadata.
+     * @param {object} source Source net row.
+     * @param {object} pcbNet PCB net row.
+     * @returns {string[]}
+     */
+    static #groupIds(source, pcbNet) {
+        return CircuitJsonPcbNetMetadata.#uniqueStrings(
+            [source, pcbNet].flatMap((row) => [
+                row?.source_group_id,
+                row?.pcb_group_id,
+                row?.schematic_group_id,
+                row?.group_id,
+                row?.member_source_group_id,
+                row?.member_pcb_group_id,
+                row?.member_schematic_group_id,
+                row?.member_group_id,
+                ...CircuitJsonPcbNetMetadata.#arrayValues(row?.group_ids),
+                ...CircuitJsonPcbNetMetadata.#arrayValues(
+                    row?.member_source_group_ids
+                ),
+                ...CircuitJsonPcbNetMetadata.#arrayValues(
+                    row?.member_pcb_group_ids
+                ),
+                ...CircuitJsonPcbNetMetadata.#arrayValues(
+                    row?.member_schematic_group_ids
+                ),
+                ...CircuitJsonPcbNetMetadata.#arrayValues(row?.member_group_ids)
+            ])
+        )
+    }
+
+    /**
+     * Returns array values when the candidate is an array.
+     * @param {unknown} value Candidate value.
+     * @returns {unknown[]}
+     */
+    static #arrayValues(value) {
+        return Array.isArray(value) ? value : []
+    }
+
+    /**
+     * Resolves unique non-empty strings.
+     * @param {unknown[]} values Candidate values.
+     * @returns {string[]}
+     */
+    static #uniqueStrings(values) {
+        return [...new Set(values.map((value) => String(value || '').trim()))]
+            .filter(Boolean)
+            .sort((left, right) => left.localeCompare(right))
+    }
+
+    /**
+     * Removes empty metadata fields.
+     * @param {object} entry Net entry.
+     * @returns {object}
+     */
+    static #clean(entry) {
+        return Object.fromEntries(
+            Object.entries(entry).filter(([_key, value]) =>
+                String(value || '').trim()
+            )
+        )
+    }
+
+    /**
+     * Resolves indexed element rows.
+     * @param {{ elementsByType: Map<string, object[]> }} index Element index.
+     * @param {string} type Element type.
+     * @returns {object[]}
+     */
+    static #all(index, type) {
+        return index.elementsByType.get(type) || []
+    }
+
+    /**
+     * Returns a color safe for SVG attributes and CSS variables.
+     * @param {unknown} value Color candidate.
+     * @returns {string}
+     */
+    static #safeColor(value) {
+        const text = String(value || '').trim()
+        return /^#[0-9a-f]{3,8}$/iu.test(text) ? text : ''
+    }
+}

package/src/core/CircuitJsonPcbPadPrimitiveModel.mjs

@@ -0,0 +1,70 @@
+import { CircuitJsonUnits } from './CircuitJsonUnits.mjs'
+
+/**
+ * Normalizes SMT pad shape metadata for PCB primitive builders.
+ */
+export class CircuitJsonPcbPadPrimitiveModel {
+    /**
+     * Resolves a normalized SMT pad shape value.
+     * @param {object} element Pad element.
+     * @returns {string}
+     */
+    static shape(element) {
+        return String(element.shape || 'rect')
+            .trim()
+            .toLowerCase()
+    }
+
+    /**
+     * Resolves a pad corner radius from explicit or shape-derived metadata.
+     * @param {object} element Pad element.
+     * @param {string} shape Normalized pad shape.
+     * @param {number} width Pad width.
+     * @param {number} height Pad height.
+     * @returns {number}
+     */
+    static radius(element, shape, width, height) {
+        const explicitRadius =
+            CircuitJsonPcbPadPrimitiveModel.explicitRadius(element)
+        return (
+            explicitRadius ??
+            CircuitJsonPcbPadPrimitiveModel.#defaultRadius(shape, width, height)
+        )
+    }
+
+    /**
+     * Resolves an explicit pad corner radius.
+     * @param {object} element Pad element.
+     * @returns {number | null}
+     */
+    static explicitRadius(element) {
+        return CircuitJsonUnits.optionalLength(
+            element.radius ??
+                element.corner_radius ??
+                element.cornerRadius ??
+                element.border_radius ??
+                element.borderRadius
+        )
+    }
+
+    /**
+     * Resolves a default corner radius for pad shape variants.
+     * @param {string} shape Normalized pad shape.
+     * @param {number} width Pad width.
+     * @param {number} height Pad height.
+     * @returns {number}
+     */
+    static #defaultRadius(shape, width, height) {
+        if (
+            shape === 'circle' ||
+            shape === 'pill' ||
+            shape === 'rotated_pill'
+        ) {
+            return Math.min(width, height) / 2
+        }
+        if (shape === 'rounded_rect') {
+            return Math.min(width, height) * 0.18
+        }
+        return 0
+    }
+}