altium-scripts/README.md

Altium Scripts

Convention: All Python scripts use .env for input/output paths (and optional settings); you can override any value via CLI. All scripts write JSON output to the outputs/ folder by default. Copy .env.example to .env and edit.

---

Capacitors by net pair

Script: CapacitorsByNetPair.pas

Finds all two-pad components on the PCB that share the same two nets (e.g. decoupling capacitors between VCC and GND). Outputs a JSON file with:

• Key: net pair (e.g. "GND|VCC"), sorted so the same pair is always grouped
• Value: for each net pair:
  • List of capacitors: designator, value string, package (footprint), and capacitance in farads
  • Total capacitance for that net pair (sum of all caps between those two nets)

How to run

1. Open your PcbDoc in Altium Designer.
2. DXP → Run Script… (or File → Run Script… depending on version).
3. Browse to CapacitorsByNetPair.pas and run it.
4. Choose a save location for the JSON file when prompted.

JSON output format

{
  "GND|VCC": {
    "total_capacitance_F": 2.2e-05,
    "total_capacitance_str": "22uF",
    "capacitors": [
      {
        "designator": "C1",
        "value": "10uF",
        "package": "0805",
        "capacitance_F": 1e-05
      },
      {
        "designator": "C2",
        "value": "12uF",
        "package": "0805",
        "capacitance_F": 1.2e-05
      }
    ]
  },
  "GND|VDD": {
    "total_capacitance_F": 1e-06,
    "total_capacitance_str": "1uF",
    "capacitors": [
      {
        "designator": "C10",
        "value": "1uF",
        "package": "0603",
        "capacitance_F": 1e-06
      }
    ]
  }
}

KiCad .kicad_pcb (Python script)

Script: capacitors_by_net_pair.py — KiCad only. Reads a .kicad_pcb file and outputs the same JSON (net pair → capacitors with designator, value, package, total capacitance).

Usage:

python3 capacitors_by_net_pair.py board.kicad_pcb
python3 capacitors_by_net_pair.py board.kicad_pcb -o outputs/capacitors_by_net_pair.json

Input/output from .env: Set INPUT_FILE and OUTPUT_FILE; CLI overrides. Default output: outputs/capacitors_by_net_pair.json.

---

Compare component locations (two KiCad files)

Script: compare_protel_locations.py

Loads two KiCad .kicad_pcb files and reports which components have moved between them. Component position is the centroid of pad (at x y) coordinates. Output is written to outputs/compare_locations.json by default.

• Moved: designators with different (x, y) in file2, with old position, new position, and distance.
• Only in file1 / only in file2: components that appear in just one file.

Usage:

python3 compare_protel_locations.py board_v1.kicad_pcb board_v2.kicad_pcb
python3 compare_protel_locations.py board_v1.kicad_pcb board_v2.kicad_pcb -o outputs/compare_locations.json

Use .env (optional): set FILE1, FILE2, and COMPARE_OUTPUT; CLI arguments override them. Use --threshold N to set the minimum position change to count as moved (default 1.0).

---

Spreadsheet diff by designator

Script: diff_spreadsheets.py

Compares two spreadsheets (.xlsx or .csv) on a designator column. Data is read from row 10 by default (first 9 rows skipped). Outputs which designators are only in file1, only in file2, or in both.

Usage:

pip install pandas openpyxl
python3 diff_spreadsheets.py sheet1.xlsx sheet2.xlsx -o outputs/spreadsheet_diff.json

Options: --designator-col 0 (0-based column index), --start-row 9 (0-based; 9 = row 10). Env: SHEET1, SHEET2, DIFF_OUTPUT.

Test: tests/sheet1.csv and tests/sheet2.csv (designators from row 10):

python3 diff_spreadsheets.py tests/sheet1.csv tests/sheet2.csv --start-row 9

---

Find bottom termination parts (QFN, DFN, BGA) by description

Script: find_bottom_termination_parts.py

Reads the same spreadsheet format (designator column, data from row 10) plus description and optionally package columns. Finds components whose description or package indicates bottom termination, including:

• Package types: QFN, DFN, BGA, LGA, SON, MLF, MLP, WDFN, WQFN, VQFN, etc.
• Generic: “bottom termination” (e.g. with 0201 or 0402)

Outputs matching designators, description, package, and the matched pattern to outputs/bottom_termination_parts.json.

Usage:

python3 find_bottom_termination_parts.py sheet.xlsx --description-col 1
python3 find_bottom_termination_parts.py sheet.xlsx --description-col 3

Env: SHEET, BOTTOM_TERM_OUTPUT, DESCRIPTION_COL (default 1), START_ROW (default 9). No package column; only description is searched.

Test: tests/sheet_with_descriptions.csv (description col 3):

python3 find_bottom_termination_parts.py tests/sheet_with_descriptions.csv --description-col 3 --start-row 9

Notes

• Only components with exactly two pads (each on a net) and designator starting with C are included (treated as capacitors). To include all two-pad parts, edit the script and remove the And (UpperCase(Copy(Component.Name.Text, 1, 1)) = 'C') condition.
• Capacitance is parsed from the component Value parameter (e.g. 10uF, 100nF, 22pF) and totalled in farads. Supported suffixes: F, mF, uF/µF, nF, pF.
• Package is taken from the component’s Pattern (footprint) name.
• If your Altium version uses different parameter or footprint property names, you may need to adjust the script (e.g. DM_ComponentParameterName / DM_ComponentParameterValue, or Pattern vs Footprint).