@tscircuit/footprinter 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+import { AnySoupElement } from '@tscircuit/soup';
+
+type FootprinterParamsBuilder<K extends string> = {
+    [P in K | "params" | "soup"]: P extends "params" | "soup" ? Footprinter[P] : (v?: number | string) => FootprinterParamsBuilder<K>;
+};
+type CommonPassiveOptionKey = "metric" | "imperial" | "tht" | "p" | "pw" | "ph" | "w" | "h";
+type Footprinter = {
+    dip: (num_pins: number) => FootprinterParamsBuilder<"w" | "p" | "id" | "od">;
+    cap: () => FootprinterParamsBuilder<CommonPassiveOptionKey>;
+    res: () => FootprinterParamsBuilder<CommonPassiveOptionKey>;
+    diode: () => FootprinterParamsBuilder<CommonPassiveOptionKey>;
+    led: () => FootprinterParamsBuilder<CommonPassiveOptionKey>;
+    lr: (num_pins: number) => FootprinterParamsBuilder<"w" | "l" | "pl" | "pr">;
+    quad: (num_pins: number) => FootprinterParamsBuilder<"w" | "l" | "square" | "pl" | "pr" | "pb" | "pt" | "p" | "pw" | "ph">;
+    bga: (num_pins: number) => FootprinterParamsBuilder<"grid" | "p" | "w" | "h" | "ball" | "pad" | "missing">;
+    params: () => any;
+    soup: () => AnySoupElement[];
+};
+declare const string: (def: string) => Footprinter;
+declare const footprinter: {
+    (): Footprinter & {
+        string: typeof string;
+    };
+    string: (def: string) => Footprinter;
+};
+declare const fp: {
+    (): Footprinter & {
+        string: typeof string;
+    };
+    string: (def: string) => Footprinter;
+};
+
+export { type Footprinter, type FootprinterParamsBuilder, footprinter, fp, string };

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tscircuit/footprinter",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "ava",
+    "build": "tsup ./src/index.ts --dts --sourcemap"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@tscircuit/soup": "^0.0.17",
+    "ava": "^6.1.3",
+    "esbuild": "^0.21.4",
+    "esbuild-register": "^3.5.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  },
+  "dependencies": {
+    "@tscircuit/mm": "^0.0.6"
+  }
+}

package/src/fn/bga.ts

@@ -0,0 +1,71 @@
+import type { AnySoupElement, PCBSMTPad } from "@tscircuit/soup"
+import { rectpad } from "../helpers/rectpad"
+import { PassiveDef, passive } from "../helpers/passive-fn"
+import { BgaDef, BgaDefInput, bga_def } from "../helpers/zod/bga-def"
+
+export const bga = (params: BgaDefInput): AnySoupElement[] => {
+  const bga_params = bga_def.parse(params)
+  let { num_pins, grid, p, w, h, ball, pad, missing } = bga_params
+
+  ball ??= (0.75 / 1.27) * p
+
+  pad ??= ball * 0.8
+
+  const pads: PCBSMTPad[] = []
+
+  const missing_pin_nums = (missing ?? []).filter((a) => typeof a === "number")
+  const num_pins_missing = grid.x * grid.y - num_pins
+
+  if (missing?.includes("center")) {
+    // Find the largest square that's square is less than
+    // the number of missing pins
+    const square_size = Math.floor(Math.sqrt(num_pins_missing))
+
+    // Find the top left coordinate of the inner square, keep
+    // in mind the full grid size is grid.x x grid.y
+    const inner_square_x = Math.floor((grid.x - square_size) / 2)
+    const inner_square_y = Math.floor((grid.y - square_size) / 2)
+
+    // Add all the missing square pin numbers to missing_pin_nums
+    for (let y = inner_square_y; y < inner_square_y + square_size; y++) {
+      for (let x = inner_square_x; x < inner_square_x + square_size; x++) {
+        missing_pin_nums.push(y * grid.x + x + 1)
+      }
+    }
+  }
+
+  if (missing?.includes("topleft")) {
+    missing_pin_nums.push(1)
+  }
+
+  if (num_pins_missing !== missing_pin_nums.length) {
+    throw new Error(
+      `not able to create bga component, unable to determine missing pins (try specifying them with "missing+1+2+..."\n\n${JSON.stringify(
+        bga_params,
+        null,
+        "  "
+      )}`
+    )
+  }
+
+  const missing_pin_nums_set = new Set(missing_pin_nums)
+
+  let missing_pins_passed = 0
+  for (let y = 0; y < grid.y; y++) {
+    for (let x = 0; x < grid.x; x++) {
+      let pin_num = y * grid.x + x + 1
+      if (missing_pin_nums_set.has(pin_num)) {
+        missing_pins_passed++
+        continue
+      }
+      pin_num -= missing_pins_passed
+
+      const pad_x = (x - (grid.x - 1) / 2) * p
+      const pad_y = -(y - (grid.y - 1) / 2) * p
+
+      pads.push(rectpad(pin_num, pad_x, pad_y, pad, pad))
+    }
+  }
+
+  return [...pads]
+}

package/src/fn/cap.ts

@@ -0,0 +1,7 @@
+import type { AnySoupElement } from "@tscircuit/soup"
+import { rectpad } from "../helpers/rectpad"
+import { PassiveDef, passive } from "../helpers/passive-fn"
+
+export const cap = (params: PassiveDef): AnySoupElement[] => {
+  return passive(params)
+}

package/src/fn/diode.ts

@@ -0,0 +1,8 @@
+import type { AnySoupElement } from "@tscircuit/soup"
+
+export const diode = (params: {
+  tht: boolean
+  p: number
+}): AnySoupElement[] => {
+  return []
+}

package/src/fn/dip.ts

@@ -0,0 +1,56 @@
+import type { AnySoupElement } from "@tscircuit/soup"
+import { platedhole } from "../helpers/platedhole"
+
+export const getCcwDipCoords = (
+  pinCount: number,
+  pn: number,
+  w: number,
+  p: number
+) => {
+  /** pin height */
+  const ph = pinCount / 2
+  const isLeft = pn <= ph
+
+  /** Number of gaps between pins on each side, e.g. 4 pins = 3 spaces */
+  const leftPinGaps = ph - 1
+
+  /** gap size (pitch) */
+  const gs = p
+
+  const h = gs * leftPinGaps
+
+  if (isLeft) {
+    // The y position starts at h/2, then goes down by gap size
+    // for each pin
+    return { x: -w / 2, y: h / 2 - (pn - 1) * gs }
+  } else {
+    // The y position starts at -h/2, then goes up by gap size
+    return { x: w / 2, y: -h / 2 + (pn - ph - 1) * gs }
+  }
+}
+
+/**
+ * Returns the plated holes for a DIP package.
+ */
+export const dip = (params: {
+  dip: true
+  num_pins: number
+  w: number
+  p?: number
+  id?: string | number
+  od?: string | number
+}): AnySoupElement[] => {
+  const platedHoles: AnySoupElement[] = []
+  for (let i = 0; i < params.num_pins; i++) {
+    const { x, y } = getCcwDipCoords(
+      params.num_pins,
+      i + 1,
+      params.w,
+      params.p ?? 2.54
+    )
+    platedHoles.push(
+      platedhole(i + 1, x, y, params.id ?? "0.8mm", params.od ?? "1mm")
+    )
+  }
+  return platedHoles
+}

package/src/fn/led.ts

@@ -0,0 +1,6 @@
+import type { AnySoupElement } from "@tscircuit/soup"
+import { PassiveDef, passive } from "../helpers/passive-fn"
+
+export const led = (params: PassiveDef): AnySoupElement[] => {
+  return passive(params)
+}

package/src/fn/res.ts

@@ -0,0 +1,6 @@
+import type { AnySoupElement } from "@tscircuit/soup"
+import { passive, PassiveDef } from "../helpers/passive-fn"
+
+export const res = (params: PassiveDef): AnySoupElement[] => {
+  return passive(params)
+}

package/src/footprinter.ts

@@ -0,0 +1,102 @@
+import { dip } from "./fn/dip"
+import { diode } from "./fn/diode"
+import { cap } from "./fn/cap"
+import { led } from "./fn/led"
+import { res } from "./fn/res"
+import { bga } from "./fn/bga"
+import type { AnySoupElement } from "@tscircuit/soup"
+
+export type FootprinterParamsBuilder<K extends string> = {
+  [P in K | "params" | "soup"]: P extends "params" | "soup"
+    ? Footprinter[P]
+    : (v?: number | string) => FootprinterParamsBuilder<K>
+}
+
+type CommonPassiveOptionKey =
+  | "metric"
+  | "imperial"
+  | "tht"
+  | "p"
+  | "pw"
+  | "ph"
+  | "w"
+  | "h"
+
+export type Footprinter = {
+  dip: (num_pins: number) => FootprinterParamsBuilder<"w" | "p" | "id" | "od">
+  cap: () => FootprinterParamsBuilder<CommonPassiveOptionKey>
+  res: () => FootprinterParamsBuilder<CommonPassiveOptionKey>
+  diode: () => FootprinterParamsBuilder<CommonPassiveOptionKey>
+  led: () => FootprinterParamsBuilder<CommonPassiveOptionKey>
+  lr: (num_pins: number) => FootprinterParamsBuilder<"w" | "l" | "pl" | "pr">
+  quad: (
+    num_pins: number
+  ) => FootprinterParamsBuilder<
+    "w" | "l" | "square" | "pl" | "pr" | "pb" | "pt" | "p" | "pw" | "ph"
+  >
+  bga: (
+    num_pins: number
+  ) => FootprinterParamsBuilder<
+    "grid" | "p" | "w" | "h" | "ball" | "pad" | "missing"
+  >
+  params: () => any
+  soup: () => AnySoupElement[]
+}
+
+export const string = (def: string): Footprinter => {
+  let fp = footprinter()
+
+  const def_parts = def.split("_").map((s) => {
+    const m = s.match(/([a-z]+)([\(\d\+].*)?/)
+    const [_, fn, v] = m ?? []
+    return { fn: m?.[1]!, v: m?.[2]! }
+  })
+
+  for (const { fn, v } of def_parts) {
+    fp = fp[fn](v)
+  }
+
+  return fp
+}
+
+export const footprinter = (): Footprinter & { string: typeof string } => {
+  const proxy = new Proxy(
+    {},
+    {
+      get: (target: any, prop) => {
+        if (prop === "soup") {
+          if ("dip" in target) return () => dip(target)
+          if ("diode" in target) return () => diode(target)
+          if ("cap" in target) return () => cap(target)
+          if ("led" in target) return () => led(target)
+          if ("res" in target) return () => res(target)
+          if ("bga" in target) return () => bga(target)
+
+          return () => {
+            // TODO improve error
+            throw new Error(
+              `No function found for footprinter, make sure to specify .dip, .lr, .p, etc. Got \"${prop}\"`
+            )
+          }
+        }
+        if (prop === "params") {
+          // TODO
+          return () => target
+        }
+        return (v: any) => {
+          if (["bga", "lr", "quad", "dip"].includes(prop as string)) {
+            target[prop] = true
+            target.num_pins = parseFloat(v)
+          } else {
+            target[prop] = v ?? true
+          }
+          return proxy
+        }
+      },
+    }
+  )
+  return proxy as any
+}
+footprinter.string = string
+
+export const fp = footprinter

package/src/helpers/passive-fn.ts

@@ -0,0 +1,175 @@
+import type { AnySoupElement } from "@tscircuit/soup"
+import { rectpad } from "../helpers/rectpad"
+import mm from "@tscircuit/mm"
+import { platedhole } from "./platedhole"
+
+type StandardSize = {
+  imperial: string
+  metric: string
+  Z_mm_min: number
+  G_mm_min: number
+  X_mm_min: number
+  C_mm_ref: number
+}
+
+// https://www.worthingtonassembly.com/perfect-0201-footprint
+// https://static1.squarespace.com/static/54982a02e4b02e9f5e5d9ca7/t/660c692f69a0d83a4afecdf0/1712089391915/Discrete+Component+Footprints.pdf
+// https://page.venkel.com/hubfs/Resources/Technical/Resistors%20Landing%20Pattern.pdf
+const sizes = [
+  {
+    imperial: "01005",
+    metric: "0402",
+    Z_mm_min: 0.58,
+    G_mm_min: 0.18,
+    X_mm_min: 0.21,
+    C_mm_ref: 0.038,
+  },
+  {
+    imperial: "0201",
+    metric: "0603",
+    Z_mm_min: 0.9,
+    G_mm_min: 0.3,
+    X_mm_min: 0.3,
+    C_mm_ref: 0.6,
+  },
+  {
+    imperial: "0402",
+    metric: "1005",
+    Z_mm_min: 1.6,
+    G_mm_min: 0.4,
+    X_mm_min: 0.7,
+    C_mm_ref: 1,
+  },
+  {
+    imperial: "0603",
+    metric: "1608",
+    Z_mm_min: 2.6,
+    G_mm_min: 0.6,
+    X_mm_min: 1.0,
+    C_mm_ref: 1.7,
+  },
+  {
+    imperial: "0805",
+    metric: "2012",
+    Z_mm_min: 3.0,
+    G_mm_min: 0.6,
+    X_mm_min: 1.2,
+    C_mm_ref: 1.9,
+  },
+  {
+    imperial: "1206",
+    metric: "3216",
+    Z_mm_min: 4.2,
+    G_mm_min: 1.2,
+    X_mm_min: 1.4,
+    C_mm_ref: 2.8,
+  },
+  {
+    imperial: "1210",
+    metric: "3225",
+    Z_mm_min: 4.2,
+    G_mm_min: 1.2,
+    X_mm_min: 2.4,
+    C_mm_ref: 2.8,
+  },
+  {
+    imperial: "2010",
+    metric: "5025",
+    Z_mm_min: 6.0,
+    G_mm_min: 2.6,
+    X_mm_min: 2.4,
+    C_mm_ref: 4.4,
+  },
+  {
+    imperial: "2512",
+    metric: "6332",
+    Z_mm_min: 7.2,
+    G_mm_min: 3.8,
+    X_mm_min: 3.0,
+    C_mm_ref: 5.6,
+  },
+]
+const metricMap: Record<string, StandardSize> = sizes.reduce((acc: any, s) => {
+  acc[s.metric] = s
+  return acc
+}, {})
+const imperialMap: Record<string, StandardSize> = sizes.reduce(
+  (acc: any, s) => {
+    acc[s.imperial] = s
+    return acc
+  },
+  {}
+)
+
+export type PassiveDef = {
+  tht: boolean
+  p: number
+  pw?: number
+  ph?: number
+  metric?: string
+  imperial?: string
+  w?: number
+  h?: number
+}
+
+const deriveXFromH = (h: number) => 0.079 * h ** 2 + 0.94 * h - 0.009
+const deriveZFromW = (w: number) => 1.09 * w + 0.6
+const deriveGFromW = (w: number) => 0.59 * w - 0.31
+const deriveCFromW = (w: number) => -0.01 * w ** 2 + 0.94 * w + 0.03
+
+export const passive = (params: PassiveDef): AnySoupElement[] => {
+  let { tht, p, pw, ph, metric, imperial, w, h } = params
+
+  if (typeof w === "string") w = mm(w)
+  if (typeof h === "string") h = mm(h)
+  if (typeof p === "string") p = mm(p)
+  if (typeof pw === "string") pw = mm(pw)
+  if (typeof ph === "string") ph = mm(ph)
+
+  if (h! > w!) {
+    throw new Error(
+      "height cannot be greater than width (rotated footprint not yet implemented)"
+    )
+  }
+
+  /** standard size */
+  let sz: StandardSize | undefined
+  if (metric) {
+    sz = metricMap[metric]
+  }
+
+  if (imperial) {
+    sz = imperialMap[imperial]
+  }
+
+  if (!sz && w && h && !pw && !ph) {
+    sz = {
+      imperial: "custom",
+      metric: "custom",
+      Z_mm_min: deriveZFromW(w),
+      G_mm_min: deriveGFromW(w),
+      X_mm_min: deriveXFromH(h),
+      C_mm_ref: deriveCFromW(w),
+    }
+  }
+
+  if (sz) {
+    w = sz.Z_mm_min
+    h = sz.X_mm_min
+    p = sz.C_mm_ref
+    pw = (sz.Z_mm_min - sz.G_mm_min) / 2
+    ph = (sz.Z_mm_min - sz.G_mm_min) / 2
+  }
+
+  if (pw === undefined) throw new Error(`could not infer pad width`)
+  if (ph === undefined) throw new Error(`could not infer pad width`)
+
+  if (tht) {
+    return [
+      platedhole(1, -p / 2, 0, pw, (pw * 1) / 0.8),
+      platedhole(2, -p / 2, 0, pw, (pw * 1) / 0.8),
+    ]
+  } else {
+    return [rectpad(1, -p / 2, 0, pw, ph), rectpad(2, p / 2, 0, pw, ph)]
+  }
+}

package/src/helpers/platedhole.ts

@@ -0,0 +1,21 @@
+import type { PCBPlatedHole, PCBSMTPad } from "@tscircuit/soup"
+import { mm } from "@tscircuit/mm"
+
+export const platedhole = (
+  pn: number,
+  x: number,
+  y: number,
+  id: number | string,
+  od: number | string
+): PCBPlatedHole => {
+  return {
+    type: "pcb_plated_hole",
+    x,
+    y,
+    hole_diameter: mm(id),
+    outer_diameter: mm(od),
+    pcb_port_id: "",
+    layers: ["top", "bottom"],
+    port_hints: [pn.toString()],
+  }
+}

package/src/helpers/rectpad.ts

@@ -0,0 +1,20 @@
+import type { PCBSMTPad } from "@tscircuit/soup"
+export const rectpad = (
+  pn: number,
+  x: number,
+  y: number,
+  w: number,
+  h: number
+): PCBSMTPad => {
+  return {
+    type: "pcb_smtpad",
+    x,
+    y,
+    width: w,
+    height: h,
+    layer: "top",
+    shape: "rect",
+    pcb_smtpad_id: "",
+    port_hints: [pn.toString()],
+  }
+}

package/src/helpers/zod/bga-def.ts

@@ -0,0 +1,48 @@
+import { z } from "zod"
+import { length, distance } from "@tscircuit/soup"
+import { dim2d } from "./dim-2d"
+import { function_call } from "./function-call"
+
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+export const bga_def = z
+  .object({
+    num_pins: z.number(),
+    grid: dim2d,
+    p: distance,
+    w: length,
+    h: length,
+    ball: length.optional().describe("ball diameter"),
+    pad: length.optional().describe("pad width/height"),
+
+    tlorigin: z.boolean().optional(),
+    blorigin: z.boolean().optional(),
+    trorigin: z.boolean().optional(),
+    brorigin: z.boolean().optional(),
+
+    missing: function_call,
+  })
+  .transform((a) => {
+    let origin: "tl" | "bl" | "tr" | "br" = "tl"
+    if (a.blorigin) origin = "bl"
+    if (a.trorigin) origin = "tr"
+    if (a.brorigin) origin = "br"
+
+    if (a.missing) {
+      a.missing = a.missing.map((s) => {
+        if (typeof s === "number") return s
+        if (s === "center") return "center"
+        if (s === "topleft") return "topleft"
+        const m = s.match(/([A-Z]+)(\d+)/)
+        if (!m) return s
+        let Y = ALPHABET.indexOf(m[1])
+        let X = parseInt(m[2]) - 1
+        return Y * a.grid.x + X + 1
+      })
+    }
+
+    return { ...a, origin }
+  })
+
+export type BgaDefInput = z.input<typeof bga_def>
+export type BgaDef = z.infer<typeof bga_def>

package/src/helpers/zod/dim-2d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod"
+
+export const dim2d = z
+  .string()
+  .transform((a) => {
+    const [x, y] = a.split(/[x ]/)
+    return {
+      x: parseFloat(x),
+      y: parseFloat(y),
+    }
+  })
+  .pipe(
+    z.object({
+      x: z.number(),
+      y: z.number(),
+    })
+  )

package/src/helpers/zod/function-call.ts

@@ -0,0 +1,16 @@
+import { z } from "zod"
+
+export const function_call = z
+  .string()
+  .or(z.array(z.any()))
+  .transform((a) => {
+    if (Array.isArray(a)) return a
+    if (a.startsWith("(") && a.endsWith(")")) {
+      a = a.slice(1, -1)
+    }
+    return a.split(",").map((v) => {
+      const numVal = Number(v)
+      return isNaN(numVal) ? v : numVal
+    })
+  })
+  .pipe(z.array(z.string().or(z.number())))

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./footprinter"

package/tests/bga.test.ts

@@ -0,0 +1,49 @@
+import test from "ava"
+import { fp } from "../src/footprinter"
+import { AnySoupElement } from "@tscircuit/soup"
+import { toPinPositionString } from "./fixtures"
+
+test("bga footprint", (t) => {
+  const soup = fp()
+    .bga(8)
+    .w("4mm")
+    .h("4mm")
+    .grid("3x3")
+    .missing("center")
+    .p(1)
+    .soup()
+  // 16pins, 4mm x 4mm, 8x8 grid, 1.27mm pitch
+  const ps = toPinPositionString(soup)
+
+  t.is(
+    ps,
+    `
+1 : -1.00  1.00
+2 :  0.00  1.00
+3 :  1.00  1.00
+4 : -1.00  0.00
+5 :  1.00  0.00
+6 : -1.00 -1.00
+7 :  0.00 -1.00
+8 :  1.00 -1.00
+  `.trim()
+  )
+})
+
+test("bga7_w8_h8_grid3x3_p1_missing(center,B1)", (t) => {
+  const soup = fp.string("bga7_w8_h8_grid3x3_p1_missing(center,B1)").soup()
+  const ps = toPinPositionString(soup)
+
+  t.is(
+    ps,
+    `
+1 : -1.00  1.00
+2 :  0.00  1.00
+3 :  1.00  1.00
+4 :  1.00  0.00
+5 : -1.00 -1.00
+6 :  0.00 -1.00
+7 :  1.00 -1.00
+  `.trim()
+  )
+})