circuit-json-to-altium

Convert Circuit JSON schematic and PCB content into an Altium Designer project archive.

Installation

bun add circuit-json-to-altium

Usage

import { CircuitJsonToAltiumConverter } from "circuit-json-to-altium"

const converter = new CircuitJsonToAltiumConverter(circuitJson, {
  projectName: "motor-controller",
})

converter.runUntilFinished()

const { pcb, project, schematics } = converter.getOutput()
const archiveBytes = await converter.getOutputZip()

The converter follows the same inspectable pipeline pattern as circuit-json-to-kicad. Call step() to advance one stage at a time, inspect currentStage, or use runUntilFinished() for ordinary conversion. The stages build the PCB, schematics, and project before validating every generated document.

For callers that only need an archive, the convenience function wraps the same pipeline:

import { convertCircuitJsonToAltiumZip } from "circuit-json-to-altium"

const archiveBytes = await convertCircuitJsonToAltiumZip(
  circuitJson,
  "motor-controller",
)

await Bun.write("motor-controller-altium.zip", archiveBytes)

The returned ZIP archive contains:

• a native binary .PcbDoc
• one native binary .SchDoc per Circuit JSON schematic sheet
• a native binary .PrjPcb
• a short conversion note

The converter validates its generated PCB and schematic documents before returning the archive. Invalid geometry is rejected with a descriptive error instead of producing a corrupt project.

Supported content

The current converter handles board outlines, components, pads, plated and non-plated holes, routed copper with vias, nets, PCB silkscreen, schematic components, custom component symbol graphics, component pins, intentionally unconnected source ports, off-sheet ports, labels, native power ports, junctions, traces, and free-standing schematic sheet text and graphics. It also preserves multiple schematic sheets and sanitizes Altium field and filename text.

altiumts owns the Altium document model, parsing, and native binary serialization. This package owns the Circuit JSON-to-Altium mapping and archive assembly.

Development

bun install
bun run download-references
bun run check

Tests follow the tscircuit convention of one test case per test file. The suite covers archive structure, filename sanitization, PCB geometry and connectivity, schematic primitives and sheets, randomized inputs, and native binary round trips.

Five board and five schematic round-trip tests use SHA-256-pinned, permissively licensed Altium references downloaded from immutable GitHub revisions. altiumts parses each native file, a narrow test fixture projects its supported primitives into Circuit JSON, and the converter writes a new native document that altiumts parses and renders again. The PCB tests require exact primitive and rotation counts and sub-0.03 mm relative geometry drift. The corpus covers binary CFB and ASCII Altium documents without GPL or reciprocal/copyleft fixtures.

Every visual comparison embeds the unchanged source and generated SVGs side by side in one snapshot. Visual baselines live in tests/__snapshots__ so mapping regressions can be reviewed directly in a pull request.

# Update visual snapshots after reviewing an intentional rendering change
BUN_UPDATE_SNAPSHOTS=1 bun test tests/visual01-pcb-comparison.test.tsx
BUN_UPDATE_SNAPSHOTS=1 bun test tests/visual02-schematic-comparison.test.tsx
BUN_UPDATE_SNAPSHOTS=1 bun test tests/roundtrip*.test.ts

Project structure

lib/
├── circuit-json-to-altium-converter.ts  # Step-driven converter pipeline
├── converter-stage.ts                   # Shared stage contract
├── stages/                              # PCB, schematic, project, validation
├── create-pcb-document.ts               # Circuit JSON PCB mapping
└── create-schematic-document.ts         # Circuit JSON schematic mapping
tests/
├── fixtures/                            # Shared round-trip and archive helpers
└── __snapshots__/                       # Raw renderer baselines
references/                               # Downloaded test inputs and provenance
scripts/                                  # Reference download and integrity checks