Metadata-Version: 2.4
Name: kicad-callouts
Version: 0.1.0
Summary: Static annotated 3D board images with labelled callouts, from a KiCad PCB.
Keywords: kicad,pcb,documentation,datasheet,render
Author: Keenan Johnson
Author-email: Keenan Johnson <keenan@breadboardfoundry.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Documentation
Requires-Dist: pillow
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/keenanjohnson/kicad-callouts
Project-URL: Issues, https://github.com/keenanjohnson/kicad-callouts/issues
Description-Content-Type: text/markdown

# kicad-callouts

Generate a static, annotated top-down 3D image of a KiCad PCB with a labelled callout for each connector (or any other footprint you choose).

Give it a `.kicad_pcb` file in which the footprints you want called out carry a `Callout` property. It renders the board with KiCad, draws a red box around each listed footprint, adds a leader line to a label box on the nearest side of the board, and adds overall board dimensions. The result is a PNG, PDF, or SVG suitable for a datasheet, README, or assembly guide.

## Install

With [uv](https://docs.astral.sh/uv/):

```
uv tool install git+https://github.com/keenanjohnson/kicad-callouts
```

## Usage

```
kicad-callouts board.kicad_pcb -o docs/connectors.png
```

Arguments and options:

| Argument | Meaning |
| --- | --- |
| `pcb` | Path to the `.kicad_pcb` file. |
| `-o`, `--out` | Output path. The extension picks the format: `.png`, `.pdf`, or `.svg`. Defaults to `connectors.png`. |
| `--dpi` | Resolution for PNG/PDF output. Defaults to 300. |
| `--title` | Title printed at the top of the image. Defaults to the PCB filename. |

If the PCB lives in a git repository, the short commit hash is printed under the title so you can tell which board revision the image was made from.

### Marking footprints for callout

Every footprint with a non-empty `Callout` property gets a callout. Two properties are read:

| Property | Meaning |
| --- | --- |
| `Callout` | Short label shown in bold next to the reference designator, such as `USB-C`. Required. |
| `Callout Description` | Longer text shown under the label. Wrapped to two lines; anything beyond that is cut. Optional. |

The easiest place to set them is the schematic: add the fields to each symbol (Symbol Properties, or the Symbol Fields Table for many at once), then run **Update PCB from Schematic**. KiCad copies symbol fields onto the footprints, and they survive later updates. Adding them directly to a footprint in the PCB editor also works, but the next update from the schematic may remove them. Either way, mark the fields as hidden so they are not drawn on the board.

### Layout

Callouts are placed in a column on whichever side of the board the footprint is closer to, ordered top to bottom by the footprint's position. Boxes that would overlap are pushed down. Callout text can be any footprint, not just connectors, so the same tool works for switches, LEDs, test points, or mounting holes.

## License

MIT. See [LICENSE](LICENSE).
