kicad-to-circuit-json 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tscircuit Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# kicad-to-circuit-json
+
+Convert KiCad schematic and PCB files to Circuit JSON format.
+
+## Installation
+
+```bash
+npm install kicad-to-circuit-json
+# or
+bun install kicad-to-circuit-json
+```
+
+## Usage
+
+```typescript
+import { KicadToCircuitJsonConverter } from "kicad-to-circuit-json"
+import fs from "fs"
+
+// Create a converter instance
+const converter = new KicadToCircuitJsonConverter()
+
+// Add KiCad files
+const pcbContent = fs.readFileSync("path/to/file.kicad_pcb", "utf-8")
+const schContent = fs.readFileSync("path/to/file.kicad_sch", "utf-8")
+
+converter.addFile("example.kicad_pcb", pcbContent)
+converter.addFile("example.kicad_sch", schContent)
+
+// Run the conversion
+converter.runUntilFinished()
+
+// Get the Circuit JSON output
+const circuitJson = converter.getOutput()
+console.log(JSON.stringify(circuitJson, null, 2))
+
+// Get diagnostics
+console.log("Warnings:", converter.getWarnings())
+console.log("Stats:", converter.getStats())
+```
+
+## Architecture
+
+The converter uses a staged pipeline architecture that mirrors the circuit-json-to-kicad converter:
+
+### Schematic Pipeline
+
+1. **InitializeSchematicContextStage** - Sets up coordinate transformations (KiCad → Circuit JSON)
+2. **CollectLibrarySymbolsStage** - Extracts symbols and creates `source_component` + `schematic_component` entries
+3. **CollectSchematicTracesStage** - Converts wires and junctions to `schematic_trace` elements
+
+### PCB Pipeline
+
+1. **InitializePcbContextStage** - Sets up PCB coordinate transformations
+2. **CollectNetsStage** - Builds net number to name mappings
+3. **CollectFootprintsStage** - Converts footprints to `pcb_component` with pads/holes
+4. **CollectTracesStage** - Converts segments to `pcb_trace` elements
+5. **CollectViasStage** - Converts vias to `pcb_via` elements
+6. **CollectGraphicsStage** - Extracts board outline and silkscreen graphics
+
+## Coordinate Transformations
+
+The converter handles coordinate system differences between KiCad and Circuit JSON:
+
+- **Schematic**: `scale(1/15, -1/15)` with translation (inverse of CJ→KiCad transform)
+- **PCB**: `scale(1, -1)` with translation
+
+## Supported Features
+
+### Schematic
+- ✅ Symbols/Components
+- ✅ Symbol ports/pins
+- ✅ Wires/traces
+- ✅ Junctions
+- ✅ Component properties (Reference, Value)
+- ⚠️ Net labels (partial)
+- ⚠️ Power symbols (partial)
+
+### PCB
+- ✅ Footprints/Components
+- ✅ SMD pads
+- ✅ Through-hole pads (plated holes)
+- ✅ NPTH holes
+- ✅ Traces/Segments
+- ✅ Vias
+- ✅ Board outline (Edge.Cuts)
+- ✅ Silkscreen graphics
+- ✅ Net mappings
+
+## MVP Limitations
+
+This is an MVP implementation. Some limitations include:
+
+- Component sizes are estimated (not derived from actual symbol geometry)
+- Port positions are simplified (not fully transformed relative to component)
+- Trace routing is basic (segments grouped by net/layer)
+- Some pad shapes may not map perfectly
+- Power symbols and net labels need enhancement
+- Multi-sheet schematics not fully tested
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Type check
+bunx tsc --noEmit
+
+# Test
+bun test
+```
+
+## Related Projects
+
+- [circuit-json-to-kicad](https://github.com/tscircuit/circuit-json-to-kicad) - Convert Circuit JSON to KiCad (reverse direction)
+- [circuit-to-svg](https://github.com/tscircuit/circuit-to-svg) - Render Circuit JSON as SVG
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import { CircuitJsonUtilObjects } from '@tscircuit/circuit-json-util';
+import { KicadPcb, KicadSch } from 'kicadts';
+import { Matrix } from 'transformation-matrix';
+
+interface ConverterContext {
+    db: CircuitJsonUtilObjects;
+    kicadPcb?: KicadPcb;
+    kicadSch?: KicadSch;
+    k2cMatSch?: Matrix;
+    k2cMatPcb?: Matrix;
+    netNumToName?: Map<number, string>;
+    footprintUuidToComponentId?: Map<string, string>;
+    symbolUuidToComponentId?: Map<string, string>;
+    warnings?: string[];
+    stats?: {
+        components?: number;
+        pads?: number;
+        vias?: number;
+        traces?: number;
+        labels?: number;
+    };
+}
+/**
+ * Base class for converter stages that process KiCad data into Circuit JSON.
+ * Each stage performs a specific transformation step and can run iteratively.
+ */
+declare abstract class ConverterStage {
+    protected ctx: ConverterContext;
+    protected MAX_ITERATIONS: number;
+    protected iterationCount: number;
+    finished: boolean;
+    constructor(ctx: ConverterContext);
+    /**
+     * Perform one step of the conversion process.
+     * Returns true if the stage has more work to do, false if finished.
+     */
+    abstract step(): boolean;
+    /**
+     * Run this stage until completion or max iterations reached.
+     */
+    runUntilFinished(): void;
+}
+
+declare class KicadToCircuitJsonConverter {
+    fsMap: Record<string, string>;
+    ctx?: ConverterContext;
+    currentStageIndex: number;
+    pipeline?: ConverterStage[];
+    get currentStage(): ConverterStage | undefined;
+    addFile(filePath: string, content: string): void;
+    _findFileWithExtension(extension: string): string | null;
+    initializePipeline(): void;
+    step(): boolean;
+    runUntilFinished(): void;
+    getOutput(): any[];
+    getOutputString(): string;
+    getWarnings(): string[];
+    getStats(): {
+        components?: number;
+        pads?: number;
+        vias?: number;
+        traces?: number;
+        labels?: number;
+    };
+}
+
+/**
+ * InitializeSchematicContextStage sets up the coordinate transformation
+ * from KiCad schematic space to Circuit JSON space.
+ *
+ * KiCad→CJ schematic transform (inverse of CJ→KiCad):
+ * - CJ→KiCad used: translate(KICAD_CENTER) ∘ scale(15, -15) ∘ translate(-center)
+ * - KiCad→CJ uses: translate(center) ∘ scale(1/15, -1/15) ∘ translate(-KICAD_CENTER)
+ */
+declare class InitializeSchematicContextStage extends ConverterStage {
+    step(): boolean;
+}
+
+/**
+ * CollectLibrarySymbolsStage extracts KiCad schematic symbols and creates:
+ * - source_component entries (with ftype inferred from library id)
+ * - schematic_component entries with positions
+ * - schematic_port entries for each pin
+ */
+declare class CollectLibrarySymbolsStage extends ConverterStage {
+    private processedSymbols;
+    step(): boolean;
+    private processSymbol;
+    private getProperty;
+    private inferFtype;
+    private getRotation;
+    private estimateSize;
+    private createPorts;
+    private inferPinDirection;
+}
+
+/**
+ * CollectSchematicTracesStage converts KiCad schematic wires and junctions
+ * into Circuit JSON schematic_trace elements.
+ */
+declare class CollectSchematicTracesStage extends ConverterStage {
+    step(): boolean;
+    private processWire;
+    private processJunction;
+}
+
+/**
+ * InitializePcbContextStage sets up the coordinate transformation
+ * from KiCad PCB space to Circuit JSON space.
+ *
+ * KiCad→CJ PCB transform (inverse of CJ→KiCad):
+ * - CJ→KiCad used: translate(100, 100) ∘ scale(1, -1)
+ * - KiCad→CJ uses: scale(1, -1) ∘ translate(-100, -100)
+ */
+declare class InitializePcbContextStage extends ConverterStage {
+    step(): boolean;
+    private calculateBoardCenter;
+}
+
+/**
+ * CollectNetsStage builds a mapping from KiCad net numbers to meaningful net names.
+ * Prefers KiCad's actual net names, falls back to "Net-<n>" for unnamed nets.
+ */
+declare class CollectNetsStage extends ConverterStage {
+    step(): boolean;
+}
+
+/**
+ * CollectFootprintsStage converts KiCad footprints into Circuit JSON pcb_components,
+ * along with their associated pads (SMT, plated holes, NPTH) and silkscreen text.
+ */
+declare class CollectFootprintsStage extends ConverterStage {
+    private processedFootprints;
+    step(): boolean;
+}
+
+/**
+ * CollectTracesStage converts KiCad PCB segments (traces) into Circuit JSON pcb_trace elements.
+ * Each segment becomes its own trace with a simple 2-point route.
+ */
+declare class CollectTracesStage extends ConverterStage {
+    step(): boolean;
+    private createTraceFromSegment;
+    private mapLayer;
+}
+
+/**
+ * CollectViasStage converts KiCad vias into Circuit JSON pcb_via elements.
+ */
+declare class CollectViasStage extends ConverterStage {
+    step(): boolean;
+    private processVia;
+    private mapLayer;
+}
+
+/**
+ * CollectGraphicsStage processes KiCad graphics elements:
+ * - gr_line on Edge.Cuts → pcb_board.outline
+ * - gr_text on silk layers → pcb_silkscreen_text
+ * - gr_line on silk layers → pcb_silkscreen_path
+ */
+declare class CollectGraphicsStage extends ConverterStage {
+    step(): boolean;
+    private createBoardOutline;
+    private createSilkscreenPath;
+    private createSilkscreenText;
+    private mapLayer;
+    private pointsEqual;
+    private calculateWidth;
+    private calculateHeight;
+}
+
+export { CollectFootprintsStage, CollectGraphicsStage, CollectLibrarySymbolsStage, CollectNetsStage, CollectSchematicTracesStage, CollectTracesStage, CollectViasStage, type ConverterContext, ConverterStage, InitializePcbContextStage, InitializeSchematicContextStage, KicadToCircuitJsonConverter };