@vessel-dsp/core 0.5.0

package/src/formats/ltspice/catalog.ts

@@ -0,0 +1,181 @@
+import type { ComponentKind, Point } from '../../model/types';
+
+// LTspice's native grid uses pin spacings of ~32–64 units per component
+// (resistor pins 64 apart, BJT pins 64 apart). The schematic renderer assumes
+// components fit within a ±20 box centered on origin, so we scale every LTspice
+// coordinate uniformly at parse time so terminal positions land near the box
+// edges instead of floating outside. 0.5 puts a resistor's pin-to-pin span at
+// 32 — comfortably inside the 40-unit box. Applied symmetrically to terminal
+// local offsets here and to all parsed Points in the parser; connectivity is
+// preserved because both sides are scaled identically.
+export const LTSPICE_COORD_SCALE = 0.5;
+
+export type LtspiceTerminalDef = Readonly<{ name: string; local: Point }>;
+
+export type LtspiceSymbolDef = Readonly<{
+    symbolName: string;
+    kind: ComponentKind;
+    terminals: readonly LtspiceTerminalDef[];
+    valueProperty: string | null;
+    modelFromValue: boolean;
+    // When true, derive `properties.model` from the basename of the symbol path
+    // (e.g. SYMBOL Opamps\LM308 → model = "LM308") instead of from SYMATTR Value.
+    // LTspice manufacturer-specific opamp symbols encode the model in the path,
+    // not in a Value attribute, so this is how we capture the part number.
+    modelFromSymbolPath?: boolean;
+}>;
+
+// Per-symbol pin layouts derived empirically from the cushychicken corpus
+// (and confirmed against LTspice's bundled .asy files).
+// Each layout matches the actual PIN positions in res.asy / cap.asy / etc.,
+// so wires drawn by LTspice land exactly on our computed terminal positions.
+const RES_PINS: readonly LtspiceTerminalDef[] = [
+    { name: 'a', local: { x: 16, y: 16 } },
+    { name: 'b', local: { x: 16, y: 96 } },
+];
+
+const CAP_PINS: readonly LtspiceTerminalDef[] = [
+    { name: 'a', local: { x: 16, y: 0 } },
+    { name: 'b', local: { x: 16, y: 64 } },
+];
+
+const IND_PINS: readonly LtspiceTerminalDef[] = [
+    { name: 'a', local: { x: 16, y: 0 } },
+    { name: 'b', local: { x: 16, y: 80 } },
+];
+
+const DIODE_PINS: readonly LtspiceTerminalDef[] = [
+    { name: 'anode', local: { x: 16, y: 0 } },
+    { name: 'cathode', local: { x: 16, y: 64 } },
+];
+
+const VOLTAGE_SOURCE_PINS: readonly LtspiceTerminalDef[] = [
+    { name: '+', local: { x: 0, y: 16 } },
+    { name: '-', local: { x: 0, y: 96 } },
+];
+
+const BJT_PINS: readonly LtspiceTerminalDef[] = [
+    { name: 'collector', local: { x: 64, y: 0 } },
+    { name: 'base', local: { x: 0, y: 48 } },
+    { name: 'emitter', local: { x: 64, y: 96 } },
+];
+
+const JFET_PINS: readonly LtspiceTerminalDef[] = [
+    { name: 'drain', local: { x: 64, y: 0 } },
+    { name: 'gate', local: { x: 0, y: 32 } },
+    { name: 'source', local: { x: 64, y: 64 } },
+];
+
+const MOSFET_PINS: readonly LtspiceTerminalDef[] = [
+    { name: 'drain', local: { x: 64, y: 0 } },
+    { name: 'gate', local: { x: 0, y: 32 } },
+    { name: 'source', local: { x: 64, y: 64 } },
+    { name: 'body', local: { x: 32, y: 32 } },
+];
+
+const DEFS: readonly LtspiceSymbolDef[] = [
+    { symbolName: 'res', kind: 'resistor', terminals: RES_PINS, valueProperty: 'R', modelFromValue: false },
+    { symbolName: 'res2', kind: 'resistor', terminals: RES_PINS, valueProperty: 'R', modelFromValue: false },
+    { symbolName: 'cap', kind: 'capacitor', terminals: CAP_PINS, valueProperty: 'C', modelFromValue: false },
+    { symbolName: 'cap2', kind: 'capacitor', terminals: CAP_PINS, valueProperty: 'C', modelFromValue: false },
+    { symbolName: 'ind', kind: 'inductor', terminals: IND_PINS, valueProperty: 'L', modelFromValue: false },
+    { symbolName: 'diode', kind: 'diode', terminals: DIODE_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'led', kind: 'led', terminals: DIODE_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'zener', kind: 'diode', terminals: DIODE_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'schottky', kind: 'diode', terminals: DIODE_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'voltage', kind: 'voltage-source', terminals: VOLTAGE_SOURCE_PINS, valueProperty: 'V', modelFromValue: false },
+    { symbolName: 'current', kind: 'current-source', terminals: VOLTAGE_SOURCE_PINS, valueProperty: 'I', modelFromValue: false },
+    { symbolName: 'npn', kind: 'bjt', terminals: BJT_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'pnp', kind: 'bjt', terminals: BJT_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'njf', kind: 'jfet', terminals: JFET_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'pjf', kind: 'jfet', terminals: JFET_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'nmos', kind: 'mosfet', terminals: MOSFET_PINS, valueProperty: null, modelFromValue: true },
+    { symbolName: 'pmos', kind: 'mosfet', terminals: MOSFET_PINS, valueProperty: null, modelFromValue: true },
+];
+
+const BY_SYMBOL = new Map<string, LtspiceSymbolDef>(DEFS.map((def) => [def.symbolName, def]));
+
+// LTspice manufacturer opamps live under `Opamps\<model>` or `OpAmps/<model>` paths
+// (mixed case, both separators). Without the corresponding .asy files we don't know
+// per-model pin geometry, so the generic fallback uses an empty terminal list and
+// records the model name via modelFromSymbolPath. Wire-snapping for opamp pins is
+// best-effort until a future change parses .asy pin positions.
+const GENERIC_OPAMP_DEF: LtspiceSymbolDef = {
+    symbolName: '_generic-opamp',
+    kind: 'opamp',
+    terminals: [],
+    valueProperty: null,
+    modelFromValue: false,
+    modelFromSymbolPath: true,
+};
+
+export function normalizeLtspiceSymbolName(symbolName: string): string {
+    const pathParts = symbolName.replaceAll('\\', '/').split('/');
+    const base = pathParts[pathParts.length - 1] ?? symbolName;
+    return base.replace(/\.asy$/i, '').toLowerCase();
+}
+
+// Returns the model name from a path-style symbol identifier, preserving the
+// original case. e.g. "Opamps\\LM308" -> "LM308", "OpAmps/AD820.asy" -> "AD820".
+export function extractModelFromSymbolPath(symbolName: string): string {
+    const parts = symbolName.replaceAll('\\', '/').split('/');
+    const last = parts[parts.length - 1] ?? symbolName;
+    return last.replace(/\.asy$/i, '');
+}
+
+function isOpampPath(symbolName: string): boolean {
+    const normalized = symbolName.replaceAll('\\', '/').toLowerCase();
+    return /(^|\/)opamps\//.test(normalized);
+}
+
+export function lookupLtspiceSymbolDef(symbolName: string): LtspiceSymbolDef | undefined {
+    const direct = BY_SYMBOL.get(normalizeLtspiceSymbolName(symbolName));
+    if (direct !== undefined) {
+        return direct;
+    }
+    if (isOpampPath(symbolName)) {
+        return GENERIC_OPAMP_DEF;
+    }
+    return undefined;
+}
+
+export function mapLtspiceTerminal(local: Point, placement: Point, orientation: string): Point {
+    // Scale the per-symbol local offset; placement is scaled upstream by the parser.
+    const sx = local.x * LTSPICE_COORD_SCALE;
+    const sy = local.y * LTSPICE_COORD_SCALE;
+    const mirrored = orientation.toUpperCase().startsWith('M');
+    const degrees = parseOrientationDegrees(orientation);
+    const x = mirrored ? -sx : sx;
+    const y = sy;
+
+    // LTspice's R90 rotates the symbol 90° clockwise on screen. Because the
+    // screen y axis points down in LTspice, on-screen-CW corresponds to the
+    // math transform (x, y) → (-y, x), and R270 (CCW on screen) is (y, -x).
+    // The previous case 90 / case 270 had these swapped — every R90 component
+    // ended up with its pins on the wrong side, so wires "floated" away from
+    // terminals. Verified against the cushychicken corpus.
+    switch (degrees) {
+        case 0:
+            return { x: placement.x + x, y: placement.y + y };
+        case 90:
+            return { x: placement.x - y, y: placement.y + x };
+        case 180:
+            return { x: placement.x - x, y: placement.y - y };
+        case 270:
+            return { x: placement.x + y, y: placement.y - x };
+    }
+}
+
+function parseOrientationDegrees(orientation: string): 0 | 90 | 180 | 270 {
+    const match = orientation.toUpperCase().match(/[MR](0|90|180|270)$/);
+    if (match?.[1] === '90') {
+        return 90;
+    }
+    if (match?.[1] === '180') {
+        return 180;
+    }
+    if (match?.[1] === '270') {
+        return 270;
+    }
+    return 0;
+}

package/src/formats/ltspice/encoding.ts

@@ -0,0 +1,151 @@
+// LTspice writes .asc files in Windows-1252 on Windows builds, so lone bytes like
+// 0xB5 (µ) appear that aren't valid UTF-8. Strict UTF-8 decoding throws on those;
+// fall back to Windows-1252 (a superset of Latin-1 within the printable range we
+// care about). This is the same heuristic many cross-platform parsers use.
+export function decodeLtspiceBytes(bytes: Uint8Array): string {
+    try {
+        return decodeUtf8Strict(bytes);
+    } catch {
+        return decodeWindows1252(bytes);
+    }
+}
+
+const WINDOWS_1252_CONTROL_CODEPOINTS: readonly number[] = [
+    0x20ac,
+    0x0081,
+    0x201a,
+    0x0192,
+    0x201e,
+    0x2026,
+    0x2020,
+    0x2021,
+    0x02c6,
+    0x2030,
+    0x0160,
+    0x2039,
+    0x0152,
+    0x008d,
+    0x017d,
+    0x008f,
+    0x0090,
+    0x2018,
+    0x2019,
+    0x201c,
+    0x201d,
+    0x2022,
+    0x2013,
+    0x2014,
+    0x02dc,
+    0x2122,
+    0x0161,
+    0x203a,
+    0x0153,
+    0x009d,
+    0x017e,
+    0x0178,
+];
+
+function decodeWindows1252(bytes: Uint8Array): string {
+    const codePoints: number[] = [];
+
+    for (const byte of bytes) {
+        if (byte >= 0x80 && byte <= 0x9f) {
+            codePoints.push(WINDOWS_1252_CONTROL_CODEPOINTS[byte - 0x80] ?? byte);
+        } else {
+            codePoints.push(byte);
+        }
+    }
+
+    return codePointsToString(codePoints);
+}
+
+function decodeUtf8Strict(bytes: Uint8Array): string {
+    const codePoints: number[] = [];
+
+    for (let index = 0; index < bytes.length; ) {
+        const first = requireByte(bytes, index);
+
+        if (first <= 0x7f) {
+            codePoints.push(first);
+            index += 1;
+            continue;
+        }
+
+        if (first >= 0xc2 && first <= 0xdf) {
+            const second = continuationBits(requireByte(bytes, index + 1));
+            codePoints.push(((first & 0x1f) << 6) | second);
+            index += 2;
+            continue;
+        }
+
+        if (first >= 0xe0 && first <= 0xef) {
+            const secondByte = requireByte(bytes, index + 1);
+            const second = continuationBits(secondByte);
+            const third = continuationBits(requireByte(bytes, index + 2));
+
+            if (first === 0xe0 && secondByte < 0xa0) {
+                throw new Error('Overlong UTF-8 sequence');
+            }
+
+            if (first === 0xed && secondByte >= 0xa0) {
+                throw new Error('UTF-8 surrogate sequence');
+            }
+
+            codePoints.push(((first & 0x0f) << 12) | (second << 6) | third);
+            index += 3;
+            continue;
+        }
+
+        if (first >= 0xf0 && first <= 0xf4) {
+            const secondByte = requireByte(bytes, index + 1);
+            const second = continuationBits(secondByte);
+            const third = continuationBits(requireByte(bytes, index + 2));
+            const fourth = continuationBits(requireByte(bytes, index + 3));
+
+            if (first === 0xf0 && secondByte < 0x90) {
+                throw new Error('Overlong UTF-8 sequence');
+            }
+
+            if (first === 0xf4 && secondByte > 0x8f) {
+                throw new Error('UTF-8 code point out of range');
+            }
+
+            codePoints.push(
+                ((first & 0x07) << 18) | (second << 12) | (third << 6) | fourth,
+            );
+            index += 4;
+            continue;
+        }
+
+        throw new Error('Invalid UTF-8 sequence');
+    }
+
+    return codePointsToString(codePoints);
+}
+
+function requireByte(bytes: Uint8Array, index: number): number {
+    const byte = bytes[index];
+    if (byte === undefined) {
+        throw new Error('Truncated byte sequence');
+    }
+
+    return byte;
+}
+
+function continuationBits(byte: number): number {
+    if ((byte & 0xc0) !== 0x80) {
+        throw new Error('Invalid UTF-8 continuation byte');
+    }
+
+    return byte & 0x3f;
+}
+
+function codePointsToString(codePoints: readonly number[]): string {
+    const chunks: string[] = [];
+
+    for (let index = 0; index < codePoints.length; index += 8192) {
+        chunks.push(String.fromCodePoint(...codePoints.slice(index, index + 8192)));
+    }
+
+    return chunks.join('');
+}