Welcome to gerbonara’s documentation!

Gerbonara is a library to read, modify and write PCB manufacturing files such as Gerber, Excellon and IPC-356 through a pythonic API. Gerbonara can open a folder of manufacturing files, and parse file names and metadata to figure out which file contains what. Gerbonara is tested using an extensive library of real-world example files from CAD tools including KiCAD, Altium, Eagle, Allegro, gEDA, Fritzing, Siemens/Mentor Graphics PADS, and Target3001!.

Gerbonara’s API is built on two principles:

Meaningful, object-oriented API

Gerbonara abstracts away the details of the underlying file format such as tool indices, coordinate notation and graphical state, and presents meaningful “graphical objects” such as a Line, Arc, or Region through its API. These objects can be easily created, manipulated or deleted from code without breaking anything else. You can even copy graphical objects between files, and Gerbonara will automatically convert coordinate format, units etc. for you. GerberFile and ExcellonFile use the same types of graphic objects, so objects can be directly copied between file types without conversion.

Unit-safety

Gerbonara embeds physical LengthUnit information in all objects. The high-level API such as LayerStack.merge() or GerberFile.offset() accepts arguments with an explicitly given unit and automatically converts them as needed. Objects can be copied between GerberFile instances and unit conversion will be handled transparently in the background.

Gerbonara was started as an extensive refactoring of the pcb-tools and pcb-tools-extension packages. Both of these have statement-based APIs, that is, they parse input files into one python object for every line in the file. This means that when saving files they can recreate the input file almost byte by byte, but manipulating a file by changing statements without breaking things is hard.

Gerbonara powers gerbolyze, a tool for converting SVG vector graphics files into Gerber, and embedding SVG into existing Gerber files exported from a normal PCB tool for artistic purposes.

Features

• File I/O * Gerber, Excellon (drill file), IPC-356 (netlist) read and write * supports file-level operations: offset, rotate, merge for all file types

• Modification API (GraphicObject)

• Rendering API (GraphicPrimitive)

• SVG export

• Full aperture macro support, including transformations (offset, rotation)

Contents:

• Gerbonara’s Command-Line Interface
  • Invocation
  • Commands and their usage
• Gerbonara API concepts
  • High-level overview
  • Apertures
  • Excellon vs. Gerber
• Examples
  • Solder mask rings
• Layers and Files
  • CamFile
  • GerberFile
  • ExcellonFile
  • Netlist
  • LayerStack
• Graphic Objects
  • GraphicObject
  • Flash
  • Line
  • Arc
  • Region
• Apertures in Gerbonara
  • Aperture generalization
  • Aperture classes
• Aperture Macros
  • ApertureMacro
  • Expression
  • UnitExpression
  • ConstantExpression
  • VariableExpression
  • OperatorExpression
  • Primitive
  • Circle
  • VectorLine
  • CenterLine
  • Polygon
  • Thermal
  • Outline
  • Comment
• Graphic Primitives
  • GraphicPrimitive
  • The five types of Graphic Primitives
• Utilities
  • Physical units
  • Format settings

Quick Start

First, install gerbonara from PyPI using pip:

pip install --user gerbonara

Then, you are ready to read and write gerber files:

from gerbonara import LayerStack

stack = LayerStack.from_directory('output/gerber')
w, h = stack.outline.size('mm')
print(f'Board size is {w:.1f} mm x {h:.1f} mm')

You can find some more elaborate examples in this doc’s Examples section.

Command-Line Interface

Gerbonara comes with a built-in command-line interface that has functions for analyzing, rendering, modifying, and merging Gerber files. To access it, use either the gerbonara command that is part of the python package, or run python -m gerbonara. For a list of functions or help on their usage, you can use:

$ python -m gerbonara --help
[...]
$ python -m gerbonara render --help

Development

Gerbonara is developed on Gitlab under the gerbolyze org:

https://gitlab.com/gerbolyze/gerbonara/

A mirror of the repository can be found at:

https://git.jaseg.de/gerbonara

Our issue tracker is also on Gitlab:

https://gitlab.com/gerbolyze/gerbonara/-/issues

A copy of this documentation can also be found at gitlab:

https://gerbolyze.gitlab.io/gerbonara/

With Gerbonara, we aim to support as many different format variants as possible. If you have a file that Gerbonara can’t open, please file an issue on our issue tracker. Even if Gerbonara can open all your files, for regression testing we are very interested in example files generated by any CAD or CAM tool that is not already on the list of supported tools.

Supported CAD Tools

Compatibility with the output of these CAD tools is tested as part of our test suite using example files generated by these tools. Note that not all of these tools come with default Gerber file naming rules, so YMMV if your Gerbers use some non-standard naming convention.

• Allegro

• Altium

• Diptrace

• Eagle

• EasyEDA

• Fritzing

• gEDA

• KiCAD

• pcb-rnd

• Siemens / Mentor Graphics Xpedition

• Siemens PADS

• Target 3001!

• Upverter

• Zuken CR-8000

Indices and tables

• Index

• Module Index

• Search Page