circuit-json-to-kicad 0.0.1 → 0.0.3

package/README.md

@@ -1 +1,175 @@
 # circuit-json-to-kicad
+
+Convert [Circuit JSON](https://github.com/tscircuit/circuit-json) files to KiCad schematic (`.kicad_sch`) and PCB (`.kicad_pcb`) files.
+
+Circuit JSON is an open-source file format for describing electronic circuits. This library enables you to generate KiCad-compatible files from Circuit JSON, allowing you to use KiCad's powerful PCB design tools with circuits defined in code.
+
+## Installation
+
+```bash
+npm install circuit-json-to-kicad
+# or
+bun add circuit-json-to-kicad
+```
+
+## Usage
+
+### Converting to KiCad Schematic
+
+```typescript
+import { CircuitJsonToKicadSchConverter } from "circuit-json-to-kicad"
+
+// Assuming you have circuit JSON from tscircuit or another source
+const circuitJson = /* your circuit JSON */
+
+const converter = new CircuitJsonToKicadSchConverter(circuitJson)
+converter.runUntilFinished()
+
+// Get the KiCad schematic file content
+const kicadSchContent = converter.getOutputString()
+
+// Write to file
+Bun.write("output.kicad_sch", kicadSchContent)
+```
+
+### Converting to KiCad PCB
+
+```typescript
+import { CircuitJsonToKicadPcbConverter } from "circuit-json-to-kicad"
+
+const circuitJson = /* your circuit JSON */
+
+const converter = new CircuitJsonToKicadPcbConverter(circuitJson)
+converter.runUntilFinished()
+
+// Get the KiCad PCB file content
+const kicadPcbContent = converter.getOutputString()
+
+// Write to file
+Bun.write("output.kicad_pcb", kicadPcbContent)
+```
+
+### Complete Example with tscircuit
+
+```typescript
+import { Circuit } from "tscircuit"
+import {
+  CircuitJsonToKicadSchConverter,
+  CircuitJsonToKicadPcbConverter,
+} from "circuit-json-to-kicad"
+
+// Define your circuit
+const circuit = new Circuit()
+circuit.add(
+  <board width="10mm" height="10mm">
+    <resistor name="R1" resistance="1k" footprint="0402" />
+    <capacitor
+      name="C1"
+      capacitance="1uF"
+      footprint="0603"
+      connections={{ pin1: "R1.pin2" }}
+    />
+  </board>,
+)
+
+await circuit.renderUntilSettled()
+
+// Get Circuit JSON
+const circuitJson = circuit.getCircuitJson()
+
+// Convert to KiCad schematic
+const schConverter = new CircuitJsonToKicadSchConverter(circuitJson)
+schConverter.runUntilFinished()
+Bun.write("output.kicad_sch", schConverter.getOutputString())
+
+// Convert to KiCad PCB
+const pcbConverter = new CircuitJsonToKicadPcbConverter(circuitJson)
+pcbConverter.runUntilFinished()
+Bun.write("output.kicad_pcb", pcbConverter.getOutputString())
+```
+
+## Features
+
+- **Schematic Conversion**: Convert Circuit JSON to KiCad schematic files (`.kicad_sch`)
+  - Library symbols
+  - Component placement
+  - Wire routing
+  - Net connections
+
+- **PCB Conversion**: Convert Circuit JSON to KiCad PCB files (`.kicad_pcb`)
+  - Footprint placement
+  - Trace routing
+  - Vias
+  - Board outlines and graphics
+  - Net assignments
+
+## Development
+
+This project uses [Bun](https://bun.sh) as its runtime and package manager.
+
+### Prerequisites
+
+- Bun (latest version)
+- KiCad (for testing generated files)
+
+### Setup
+
+```bash
+# Install dependencies
+bun install
+
+# Download KiCad demo files (used for reference)
+bun run download-demos
+
+# Run tests
+bun test
+```
+
+### Testing
+
+Tests generate visual PNG snapshots for comparison:
+
+```bash
+# Run a specific test
+bun test tests/sch/basics/basics01.test.tsx
+
+# Run all tests
+bun test
+
+# Update snapshots (if needed)
+BUN_UPDATE_SNAPSHOTS=1 bun test
+```
+
+Generated debug output is saved to the `debug-output/` directory.
+
+### Project Structure
+
+```
+lib/
+├── index.ts                           # Main exports
+├── types.ts                           # Shared types
+├── schematic/
+│   ├── CircuitJsonToKicadSchConverter.ts  # Schematic converter
+│   └── stages/                        # Conversion pipeline stages
+└── pcb/
+    ├── CircuitJsonToKicadPcbConverter.ts  # PCB converter
+    └── stages/                        # Conversion pipeline stages
+```
+
+## About Circuit JSON
+
+Circuit JSON is an open-source file format for representing electronic circuits. Learn more:
+
+- [Circuit JSON on npm](https://www.npmjs.com/package/circuit-json)
+- [Circuit JSON README](https://github.com/tscircuit/circuit-json)
+- [tscircuit](https://github.com/tscircuit/tscircuit) - Create circuits using React/TSX
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+Some interoperability test artifacts are generated from assets by KiCad. See [KiCad licenses](https://www.kicad.org/about/licenses/) for more information.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { CircuitJson } from 'circuit-json';
+import { CircuitJsonUtilObjects } from '@tscircuit/circuit-json-util';
+import { KicadSch, KicadPcb } from 'kicadts';
+import { Matrix } from 'transformation-matrix';
+
+type SchematicPortId = string;
+type SchematicTraceId = string;
+type PcbPortId = string;
+interface ConverterContext {
+    db: CircuitJsonUtilObjects;
+    circuitJson: CircuitJson;
+    kicadSch?: KicadSch;
+    kicadPcb?: KicadPcb;
+    /** Circuit JSON to KiCad schematic transformation matrix */
+    c2kMatSch?: Matrix;
+    /** Circuit JSON to KiCad PCB transformation matrix */
+    c2kMatPcb?: Matrix;
+    pinPositions?: Map<SchematicPortId, {
+        x: number;
+        y: number;
+    }>;
+    wireConnections?: Map<SchematicTraceId, SchematicPortId[]>;
+    pcbPadPositions?: Map<PcbPortId, {
+        x: number;
+        y: number;
+    }>;
+    pcbNetMap?: Map<string, number>;
+}
+declare abstract class ConverterStage<Input, Output> {
+    MAX_ITERATIONS: number;
+    iteration: number;
+    finished: boolean;
+    input: Input;
+    ctx: ConverterContext;
+    constructor(input: Input, ctx: ConverterContext);
+    step(): void;
+    _step(): void;
+    runUntilFinished(): void;
+    getOutput(): Output;
+}
+
+declare class CircuitJsonToKicadSchConverter {
+    ctx: ConverterContext;
+    pipeline: ConverterStage<CircuitJson, KicadSch>[];
+    currentStageIndex: number;
+    finished: boolean;
+    get currentStage(): ConverterStage<CircuitJson, KicadSch> | undefined;
+    constructor(circuitJson: CircuitJson);
+    step(): void;
+    runUntilFinished(): void;
+    getOutput(): KicadSch;
+    /**
+     * Get the output as a string
+     */
+    getOutputString(): string;
+}
+
+declare class CircuitJsonToKicadPcbConverter {
+    ctx: ConverterContext;
+    pipeline: ConverterStage<CircuitJson, KicadPcb>[];
+    currentStageIndex: number;
+    finished: boolean;
+    get currentStage(): ConverterStage<CircuitJson, KicadPcb> | undefined;
+    constructor(circuitJson: CircuitJson);
+    step(): void;
+    runUntilFinished(): void;
+    getOutput(): KicadPcb;
+    /**
+     * Get the output as a string
+     */
+    getOutputString(): string;
+}
+
+export { CircuitJsonToKicadPcbConverter, CircuitJsonToKicadSchConverter };