KiCad library scripts

KiCad Board Outline Generator

This directory contains small scripts that generate/maintain pieces of the KiCad libraries under pcb/libraries/.

• License: MIT (see pcb/libraries/scripts/LICENSE).

Board outline footprint generator (generate_board_outline.py)

What this tool is

generate_board_outline.py generates KiCad footprint files (.kicad_mod) that act as a “board outline template”:

• A rectangular board outline drawn on Edge.Cuts
• Optional rounded corners on the outline (filleted rectangle)
• Optional corner mounting holes (M2 or M3) as NPTH pads
• A small set of helper graphics (courtyard circles and comment circles) to make the outline easier to see/select

The generator writes the footprints into the footprint library:

• pcb/libraries/footprints/Ojisan-BoardOutlines.pretty/

That means you can add Ojisan-BoardOutlines.pretty as a KiCad footprint library and then place a board outline like any other footprint.

Why this exists (and when to use it)

Using a board-outline footprint is handy when:

• You frequently make boards of a few standard sizes (e.g. 50×60 mm).
• You want mounting holes to be consistent and repeatable across projects.
• You want a “blank board canvas” you can drop into a new design quickly without manually drawing edges every time.
• You want outline + mounting holes to stay “together” as a single locked object during early layout.

When not to use it:

• If your outline is non-rectangular or needs complex arcs/slots/chamfers beyond a simple filleted rectangle (draw Edge.Cuts manually in the PCB editor).
• If hole locations must follow an enclosure’s datum that isn’t symmetric about the board center (you’ll likely need custom geometry).

Requirements

• Python: Python 3.x (standard library only; no extra packages).

• KiCad: The generator emits footprints with:

  • (generator_version "9.0")
  • (version 20241229)

  Practically, that means KiCad 9 is required to open/edit these generated footprints. (KiCad 8 may not read this footprint format.)

Unit tests

This repo includes unittest coverage for the board-outline generator in:

• pcb/libraries/scripts/test_generate_board_outline.py

You can run tests from either location:

From the repository root:

python3 -m unittest -v pcb.libraries.scripts.test_generate_board_outline

From pcb/libraries/scripts/:

python3 -m unittest -v test_generate_board_outline

Quick start

From the repository root:

# Generate a 50mm x 60mm outline with M3 corner holes
python3 pcb/libraries/scripts/generate_board_outline.py 50 60 M3

# Generate a 40mm x 50mm outline with M2 corner holes
python3 pcb/libraries/scripts/generate_board_outline.py 40 50 M2

# Generate a 20mm x 20mm outline with no holes
python3 pcb/libraries/scripts/generate_board_outline.py 20 20 none

# Generate a 45mm x 55mm outline with M2 corner holes and rounded corners (default radius)
python3 pcb/libraries/scripts/generate_board_outline.py 45 55 M2 --corner-radius

# Generate the same outline with a specific rounded-corner radius
python3 pcb/libraries/scripts/generate_board_outline.py 45 55 M2 --corner-radius 3

Expected output:

• pcb/libraries/footprints/Ojisan-BoardOutlines.pretty/50mm x 60mm board outline with M3 holes.kicad_mod
• pcb/libraries/footprints/Ojisan-BoardOutlines.pretty/40mm x 50mm board outline with M2 holes.kicad_mod
• pcb/libraries/footprints/Ojisan-BoardOutlines.pretty/20mm x 20mm board outline no holes.kicad_mod
• pcb/libraries/footprints/Ojisan-BoardOutlines.pretty/45mm x 55mm board outline with M2 holes R2mm.kicad_mod
• pcb/libraries/footprints/Ojisan-BoardOutlines.pretty/45mm x 55mm board outline with M2 holes R3mm.kicad_mod

Command-line interface (detailed)

python3 generate_board_outline.py WIDTH HEIGHT HOLE_TYPE [-o OUTPUT_DIR] [--corner-radius [MM]] [--group-elements]

• WIDTH: board width in mm (X dimension)
• HEIGHT: board height in mm (Y dimension)
• HOLE_TYPE: one of:
  • M2 (four M2 corner holes)
  • M3 (four M3 corner holes)
  • none (no holes)
• -o / --output-dir (optional): output directory
  • If omitted, defaults to: pcb/libraries/footprints/Ojisan-BoardOutlines.pretty
• --corner-radius [MM] (optional): enable rounded corners
  • If MM is provided, it sets the rounded-corner radius in mm
  • If MM is omitted, the default radius is 2.0 mm
  • If --corner-radius is not provided, corners are sharp (plain rectangle)
  • Backwards compatibility: --rounded is accepted as a deprecated alias for --corner-radius (default radius)
• --group-elements (optional): wrap generated primitives in a KiCad (group ...) block

Notes:

• The script accepts floats. The footprint/file name uses dimensions rounded to 0.1mm (e.g. 50.04 → 50mm, 50.05 → 50.1mm).
  • A trailing .0 is omitted (e.g. 50.0 → 50mm).
• If the output file already exists, it will be overwritten.
• When rounding is enabled, the generator appends a suffix to the footprint/file name:
  • ... R2mm (or ... R2.5mm) to avoid colliding with the sharp-corner variant.

Geometry conventions (important)

Generated geometry is centered at the footprint origin:

• The rectangle outline is:
  • Lower-left corner: ((-W/2,,-H/2))
  • Upper-right corner: ((W/2,,H/2))
• If holes are enabled, hole centers are placed at:

[
(\pm(W/2 - m),\ \pm(H/2 - m))
]

Where (m) is the hole margin from the board edge:

• M2: margin (m = 2.75) mm
• M3: margin (m = 3.75) mm

Hole drill sizes:

• M2: 2.2 mm NPTH
• M3: 3.2 mm NPTH

These values are encoded in HOLE_SPECS inside generate_board_outline.py.

Using the generated outline in KiCad (step-by-step)

1) Add the outline footprint library

Add the library pcb/libraries/footprints/Ojisan-BoardOutlines.pretty in KiCad:

• Preferences → Manage Footprint Libraries… (global), or
• Project → Project Settings → Footprint Libraries (project-only)

Pick a nickname such as Ojisan-BoardOutlines.

2) Place an outline footprint in your PCB

In the PCB editor:

• Place → Add Footprint…
• Search for board outline and choose the desired size/hole variant.

Recommended placement:

• Place the footprint at (0, 0) to keep the board centered about the origin.
• Then lock it so you don’t accidentally move the outline:
  • Right-click footprint → Lock Footprint

3) Confirm the board outline is on Edge.Cuts

The footprint contains Edge.Cuts geometry. After placing it:

• Ensure you can see the outline on the Edge.Cuts layer.
• If your board already has an outline drawn, you should delete one of them.
  • Multiple overlapping/different Edge.Cuts shapes can cause CAM/DRC issues.

4) Confirm mounting holes behave as intended (if enabled)

If you generated M2/M3 holes:

• The footprint includes four NPTH pads at the corners.
• When you generate fabrication outputs, verify:
  • Drill file includes the holes
  • Holes appear in the board viewer / 3D viewer as expected

5) Keep it out of BOM/assembly outputs (recommended)

For M2/M3 variants generated by the script, the footprint is marked:

• board_only
• exclude_from_bom

For the none variant, the script currently marks the footprint as plain smd.
If you want the no-hole outline to also be excluded from BOM/position files, set the footprint’s exclude flags in KiCad after placement (footprint properties).

Regenerating / adding new sizes safely

Recommended workflow when adding a new outline:

1. Run the generator for the desired dimensions/hole type.
2. Open the resulting footprint in KiCad’s footprint viewer/editor and sanity-check:
   • The outline measures (W \times H)
   • Hole centers are the expected distance from edges
3. Place the new outline in a test PCB (or a scratch project) and verify:
   • Edge.Cuts is recognized as the board edge
   • Drill outputs contain the NPTH holes

If you regenerate an outline with the same name as an existing footprint, remember:

• The generator writes centered footprints.
• Older footprints in this repo may have been authored with a different origin/offset.

So if you replace an existing outline footprint in a design, verify placement after swapping footprints (the outline might shift relative to your board origin).

Troubleshooting

• “python3: command not found”
  • Install Python 3 and re-run with python3.
• KiCad can’t open the generated footprint
  • Use KiCad 9.x (the generated file format targets KiCad 9).
• I placed the footprint but my board outline is still missing
  • Confirm the footprint actually exists on the PCB (not just in the schematic).
  • Confirm Edge.Cuts is visible and not filtered/hidden.
  • Confirm you didn’t already have a conflicting Edge.Cuts outline elsewhere.
• Mounting holes don’t appear in drill outputs
  • Confirm you generated M2 or M3 (not none).
  • Confirm the pads are np_thru_hole in the footprint.
  • Re-plot drill files and check the drill map/viewer.