@tscircuit/circuit-json-util

Previously released as @tscircuit/soup-util

This is a small utility library for working with circuit json

It reduces the amount of code to retrieve or join elements from circuit json, it also neatly handles all the typing.

Exported API

| Function | Defined in | Description | | --- | --- | --- | | cju | lib/cju.ts | Creates the primary circuit-json utility object for querying and mutating circuit json arrays. | | su | lib/cju.ts | Alias for cju. | | cjuIndexed | lib/cju-indexed.ts | Creates an indexed utility optimized for large circuit-json datasets. | | transformSchematicElement | lib/transform-soup-elements.ts | Applies a transformation matrix to a single schematic element. | | transformSchematicElements | lib/transform-soup-elements.ts | Applies a transformation matrix to schematic elements in a soup. | | transformPCBElement | lib/transform-soup-elements.ts | Applies a transformation matrix to a single PCB element. | | transformPCBElements | lib/transform-soup-elements.ts | Applies a transformation matrix to PCB elements in a soup. | | transformPcbElement | lib/transform-soup-elements.ts | Alias export for transformPCBElement. | | transformPcbElements | lib/transform-soup-elements.ts | Alias export for transformPCBElements. | | directionToVec | lib/direction-to-vec.ts | Converts a cardinal direction to a vector. | | vecToDirection | lib/direction-to-vec.ts | Converts a vector to its nearest cardinal direction. | | rotateClockwise | lib/direction-to-vec.ts | Rotates a cardinal direction clockwise. | | rotateCounterClockwise | lib/direction-to-vec.ts | Rotates a cardinal direction counter-clockwise. | | rotateDirection | lib/direction-to-vec.ts | Rotates a direction by one or more quarter turns. | | oppositeDirection | lib/direction-to-vec.ts | Returns the opposite cardinal direction. | | oppositeSide | lib/direction-to-vec.ts | Returns the opposite side string (left/right/top/bottom). | | applySelector | lib/apply-selector.ts | Applies a selector string to circuit-json elements. | | applySelectorAST | lib/apply-selector.ts | Applies a parsed selector AST to circuit-json elements. | | getElementById | lib/get-element-by-id.ts | Finds an element by its primary id field. | | getElementId | lib/get-element-id.ts | Returns an element's primary id value. | | getReadableNameForElement | lib/readable-name-functions/get-readable-name-for-element.ts | Produces a human-readable label for an element. | | getReadableNameForPcbPort | lib/readable-name-functions/get-readable-name-for-pcb-port.ts | Produces a readable label for a PCB port. | | getReadableNameForPcbSmtpad | lib/readable-name-functions/get-readable-name-for-pcb-smtpad.ts | Produces a readable label for a PCB SMT pad. | | getReadableNameForPcbTrace | lib/readable-name-functions/get-readable-name-for-pcb-trace.ts | Produces a readable label for a PCB trace. | | getBoundsOfPcbElements | lib/get-bounds-of-pcb-elements.ts | Computes aggregate XY bounds for PCB elements. | | getBoardBounds | lib/get-board-bounds.ts | Computes board bounds/size from width+height+center, or from outline points. | | findBoundsAndCenter | lib/find-bounds-and-center.ts | Computes bounds and center for a set of points. | | getPrimaryId | lib/get-primary-id.ts | Returns the name of an element type's primary id field. | | buildSubtree | lib/subtree.ts | Builds a relation-aware subtree from selected root elements. | | repositionPcbComponentTo | lib/reposition-pcb-component.ts | Repositions a PCB component and its linked PCB primitives. | | repositionPcbGroupTo | lib/reposition-pcb-group.ts | Repositions all PCB elements in a source group. | | repositionSchematicComponentTo | lib/reposition-schematic-component.ts | Repositions a schematic component and linked schematic primitives. | | repositionSchematicGroupTo | lib/reposition-schematic-group.ts | Repositions all schematic elements in a source group. | | getCircuitJsonTree | lib/getCircuitJsonTree.ts | Builds a tree representation of relation-linked circuit-json elements. | | getStringFromCircuitJsonTree | lib/getStringFromCircuitJsonTree.ts | Renders a circuit-json tree as text for debugging. | | getMinimumFlexContainer | lib/get-minimum-flex-container.ts | Computes a minimum flex container from layout constraints. | | getElementRenderLayers | lib/get-element-render-layers.ts | Returns schematic/PCB render layers used for an element. | | computeClearanceBetweenElements | lib/compute-clearance-between-elements.ts | Computes the minimum edge-to-edge clearance between two circuit elements using geometric decomposition. | | computeGapBetweenCopper | lib/compute-gap-between-copper.ts | Computes the minimum copper-to-copper gap between two circuit elements by decomposing them into primitive shapes. | | categorizeErrorOrWarning | lib/categorize-error-or-warning.ts | Categorizes DRC error/warning types into "netlist", "pin_specification", "placement", "routing", or "unknown". |

Standard Usage

import { su } from "@tscircuit/circuit-json-util"

const circuitJson = [
  /* [ { type: "source_component", ... }, ... ] */
]

const pcb_component = su(circuitJson).pcb_component.get("1234")

const source_component = su(circuitJson).source_component.getUsing({
  pcb_component_id: "123",
})

const schematic_component = su(circuitJson).schematic_component.getWhere({
  width: 1,
})

const source_traces = su(circuitJson).source_trace.list({
  source_component_id: "123",
})

Optimized Indexed Version

For large circuit json, the library provides an optimized version with indexing for faster lookups:

import { suIndexed } from "@tscircuit/circuit-json-util"

const circuitJson = [
  /* large soup with many elements */
]

// Configure the indexes you want to use
const indexedSu = suIndexed(circuitJson, {
  indexConfig: {
    byId: true, // Index by element ID for fast .get() operations
    byType: true, // Index by element type for fast .list() operations
    byRelation: true, // Index relation fields (fields ending with _id)
    bySubcircuit: true, // Index by subcircuit_id for fast subcircuit filtering
    byCustomField: ["name", "ftype"], // Index specific fields you query often
  },
})

// Use the same API as the standard version, but with much better performance
const pcb_component = indexedSu.pcb_component.get("1234") // O(1) lookup

// Fast filtering by subcircuit
const subcircuitElements = indexedSu.source_component.list({
  subcircuit_id: "main",
})

The indexed version maintains the same API as the standard version but provides significant performance improvements, especially for large circuit json arrays.

Categorize DRC Errors and Warnings

Use categorizeErrorOrWarning to map DRC result types to high-level check categories.

import { categorizeErrorOrWarning } from "@tscircuit/circuit-json-util"

categorizeErrorOrWarning("source_pin_must_be_connected_error") // "netlist"
categorizeErrorOrWarning("source_no_power_pin_defined_warning") // "pin_specification"
categorizeErrorOrWarning({ error_type: "pcb_trace_error" }) // "routing"
categorizeErrorOrWarning({
  warning_type: "pcb_connector_not_in_accessible_orientation_warning",
}) // "placement"
categorizeErrorOrWarning("some_future_error_type") // "unknown"

Repositioning PCB Components

Use repositionPcbComponentTo to move a component and all of its related elements to a new center:

import { repositionPcbComponentTo } from "@tscircuit/circuit-json-util"

repositionPcbComponentTo(circuitJson, "pc1", { x: 10, y: 5 })

All ports, pads and traces referencing the component are translated by the same offset.

Use repositionSchematicComponentTo to move a schematic component and all related elements:

import { repositionSchematicComponentTo } from "@tscircuit/circuit-json-util"

repositionSchematicComponentTo(circuitJson, "sc1", { x: 10, y: 5 })

Move all elements in a schematic source group with repositionSchematicGroupTo:

import { repositionSchematicGroupTo } from "@tscircuit/circuit-json-util"

repositionSchematicGroupTo(circuitJson, "g1", { x: 20, y: 15 })

Compute Copper Gap

Use computeGapBetweenCopper to calculate the minimum copper clearance between two PCB elements.

It decomposes each element into primitive shapes (circle, rect, polygon) and returns the minimum distance across all shape-pair combinations. If an element does not produce any supported copper shapes, the function returns Infinity.

import { computeGapBetweenCopper } from "@tscircuit/circuit-json-util"

const gap = computeGapBetweenCopper(
  {
    type: "pcb_smtpad",
    pcb_smtpad_id: "pad1",
    shape: "circle",
    x: 0,
    y: 0,
    radius: 0.5,
    layer: "top",
  },
  {
    type: "pcb_smtpad",
    pcb_smtpad_id: "pad2",
    shape: "rect",
    x: 2,
    y: 0,
    width: 1,
    height: 1,
    layer: "top",
  },
)

console.log(gap) // 1

Currently supported decomposition targets include pcb_smtpad (circle/rect/polygon), pcb_trace wire segments, pcb_via, and pcb_plated_hole.