circuit-to-svg

A TypeScript library for converting Circuit JSON to Schematic, PCB and Assembly SVG representations.

Getting Started Contributor Video

npm add circuit-to-svg
# or...
bun add circuit-to-svg

Overview

This library provides functionality to convert Circuit JSON into SVG (Scalable Vector Graphics) representations. It supports both schematic and PCB (Printed Circuit Board), and Assembly layouts.

Installation

npm install circuit-to-svg

Usage

import { readFileSync, writeFileSync } from 'fs'
import { convertCircuitJsonToSchematicSvg } from 'circuit-to-svg'

const circuitJson = JSON.parse(readFileSync('circuit.json', 'utf8'))
const schematicSvg = convertCircuitJsonToSchematicSvg(circuitJson)

writeFileSync('schematic.svg', schematicSvg)

Explore the API sections below to render PCB, assembly, pinout, simulation, and solder paste views.

API

convertCircuitJsonToSchematicSvg

convertCircuitJsonToSchematicSvg(circuitJson: AnyCircuitElement[], options?): string

Converts a schematic circuit description to an SVG string.

import { convertCircuitJsonToSchematicSvg } from 'circuit-to-svg'

const schematicSvg = convertCircuitJsonToSchematicSvg(circuitJson, {
  includeVersion: true,
})

Options

• width and height – dimensions of the output SVG. Defaults to 1200x600.
• grid – enable a schematic grid (true) or configure cell size and labels.
• labeledPoints – annotate specific coordinates with helper labels.
• colorOverrides – override portions of the schematic color palette.
• includeVersion – if true, add a data-circuit-to-svg-version attribute to the root <svg>.

convertCircuitJsonToPcbSvg

convertCircuitJsonToPcbSvg(circuitJson: AnyCircuitElement[], options?): string

Converts a PCB layout description to an SVG string.

import { convertCircuitJsonToPcbSvg } from 'circuit-to-svg'

const pcbSvg = convertCircuitJsonToPcbSvg(circuitJson, {
  matchBoardAspectRatio: true,
  backgroundColor: '#1e1e1e',
})

Options

• width and height – dimensions of the output SVG. Defaults to 800x600.
• matchBoardAspectRatio – if true, adjust the SVG dimensions so the resulting aspect ratio matches the pcb_board found in the circuit JSON.
• backgroundColor – fill color for the SVG background rectangle. Defaults to "#000".
• drawPaddingOutsideBoard – if false, omit the board outline and extra padding around it. Defaults to true.

• shouldDrawErrors – if true, display visual error indicators (red diamonds with text) for error elements in the circuit JSON. Supports:

  • pcb_trace_error – errors related to PCB traces
  • pcb_footprint_overlap_error – errors for overlapping pads, plated holes, and holes (displays error indicators at each affected element with connecting lines)

  Defaults to false.

• includeVersion – if true, add a data-circuit-to-svg-version attribute to the root <svg>.

convertCircuitJsonToAssemblySvg

Converts circuit JSON into an assembly view of the board and components.

import { convertCircuitJsonToAssemblySvg } from 'circuit-to-svg'

const assemblySvg = convertCircuitJsonToAssemblySvg(circuitJson, {
  includeVersion: false,
})

Options

• width and height – dimensions of the output SVG. Defaults to 800x600.
• includeVersion – if true, add a data-circuit-to-svg-version attribute to the root <svg>.

convertCircuitJsonToPinoutSvg

Generates pinout diagrams that call out ports, pads, and holes for boards or modules.

import { convertCircuitJsonToPinoutSvg } from 'circuit-to-svg'

const pinoutSvg = convertCircuitJsonToPinoutSvg(circuitJson)

Options

• width and height – dimensions of the output SVG. Defaults to 800x600.
• includeVersion – if true, add a data-circuit-to-svg-version attribute to the root <svg>.

convertCircuitJsonToSchematicSimulationSvg

Overlays simulation results directly on the rendered schematic for easy debugging.

import { convertCircuitJsonToSchematicSimulationSvg } from 'circuit-to-svg'

const schematicSimulationSvg = convertCircuitJsonToSchematicSimulationSvg({
  circuitJson,
  simulation_experiment_id: 'simulation-experiment-id',
  simulation_transient_voltage_graph_ids: ['transient-graph-id'],
  schematicHeightRatio: 0.6,
})

Options

• width and height – overall SVG dimensions. Defaults to 1200x1200.
• schematicHeightRatio – ratio of the SVG dedicated to the schematic view. Defaults to 0.55.
• schematicOptions – forward additional schematic rendering options (except width, height, and includeVersion).
• includeVersion – if true, add a data-circuit-to-svg-version attribute to the root <svg>.

convertCircuitJsonToSimulationGraphSvg

Creates standalone graphs for circuit simulation experiments.

import { convertCircuitJsonToSimulationGraphSvg } from 'circuit-to-svg'

const simulationGraphSvg = convertCircuitJsonToSimulationGraphSvg({
  circuitJson,
  simulation_experiment_id: 'simulation-experiment-id',
  simulation_transient_voltage_graph_ids: ['transient-graph-id'],
})

Options

• width and height – SVG dimensions for the graph. Defaults to 1200x600.
• includeVersion – if true, add a data-circuit-to-svg-version attribute to the root <svg>.

convertCircuitJsonToSolderPasteMask

convertCircuitJsonToSolderPasteMask(circuitJson: AnyCircuitElement[], options: { layer: 'top' | 'bottom'; width?; height?; includeVersion? }): string

Produces top and bottom solder paste mask renderings suitable for stencil generation.

import { convertCircuitJsonToSolderPasteMask } from 'circuit-to-svg'

const solderPasteMaskSvg = convertCircuitJsonToSolderPasteMask(circuitJson, {
  layer: 'top',
})

Options

• layer – 'top' | 'bottom', chooses which solder paste layer to render. Defaults to 'top'.
• width and height – dimensions of the output SVG. Defaults to 800x600.
• includeVersion – if true, add a data-circuit-to-svg-version attribute to the root <svg>.