PyGerber

📖 Overview

PyGerber is a collection of tools aimed at simplifying the use of the Gerber X3 format. It is based on Ucamco's The Gerber Layer Format Specification. Revision 2024.05 (Available on Ucamco's webpage.

PyGerber can be used both as a executable (with command line interface) and as a Python library.

PyGerber supports modern features available in the latest version of the standard (2024.05). At the same time, it includes the implementation of many of outdated and removed functionalities for backwards compatibility. This allows it to be used not only with files compliant with the X3 standard but also with those compliant with X2, RS-274X, and RS-274D. Due to limited access to files in older standards and ambiguities within them, there is a risk that some older functionalities may behave incorrectly.

If you have found a bug in the PyGerber library, please file a bug report with use of one of issue templates available on Create new issue page in PyGerber repository. We will be glad to examine your report and possibly fix the problem.

If you have any questions or suggestions, please open a new discussion thread in the Discussions section of our repository. We will be happy to help you and discuss your ideas.

📦 Installation

PyGerber can be installed with pip from PyPI:

pip install pygerber

This way only the core of PyGerber features will be installed. It will not include language server, SVG rendering support and other optional features. If you want to install all available features, include all extras set in installation request, like this:

pip install pygerber[all]

To install latest development version of PyGerber, you can use URL of the Github repository with git+ prefix:

pip install git+https://github.com/Argmaster/pygerber

📚 Documentation

PyGerber has a online documentation hosted on Github Pages. It will be a great starting point for your journey with PyGerber. You can it here. If you are looking for documentation of older version of PyGerber, please use version selector dropdown available next to the title in top bar menu.

📜 License

PyGerber is licensed under MIT license. You can find full text of the license in the LICENSE file in the root directory of the repository.

Some of the testing assets may be licensed under different licenses. License files for those assets are available alongside those files.

Some of the example files shipped with PyGerber may be licensed under different licenses. In particular, files from KiCad demo projects are licensed under CC BY-SA 4.0 license. Copy of the license file is provided alongside those files.

🛠 Tools

Collection of tools available in PyGerber constantly grows. Some of the tools can be accessed only with API, others provide command line interface too. Below you can find list of all currently available ones:

• Image renderer (PNG/JPEG) [API] [CLI]
• Code formatter [API] [CLI]
• Code generation [API]
• Language server (requires language_server extras) (Visual Studio Code extension available) [CLI]
• Pygments Gerber syntax lexer plugin (requires pygments extras) [CLI]

🖮 PyGerber APIs

PyGerber provides APIs for accessing most of its functionalities. There are selected modules designed to be used as libraries, they reexport public parts of implementation in a convenient way. Avoid importing stuff from modules not listed below and not mentioned in documentation, as this may inflict suffering and damnation upon you 💀 (Just joking, but they may get deleted/moved at any time, so you know 😼).

Below you can find list of available APIs:

• pygerber.gerber.api (open issue)
• pygerber.gerber.ast (open issue)
• pygerber.gerber.ast.nodes (open issue)
• pygerber.gerber.compiler (open issue)
• pygerber.gerber.parser (open issue)
• pygerber.gerber.formatter (open issue)
• pygerber.builder.gerber (open issue)
• pygerber.builder.rvmc (open issue)
• pygerber.vm (open issue)
• pygerber.vm.commands (open issue)
• pygerber.vm.types (open issue)
• pygerber.vm.pillow (open issue)
• pygerber.vm.shapely (open issue)

If you need a symbol that is not reexported from those modules, eg. some exception class you need to catch, please open an issue with corresponding open issue link so we can evaluate that issue and possibly add missing reexport. Don't worry about template being for bugs, we will figure that out in the process, just fill the fields in template according to guidelines contained in it.

If you have found a bug in a particular part of PyGerber, please use open issue link next to module name above to open issue submission form. Alternatively you can choose one of the issue templates on Create new issue page in PyGerber repository. Please fill the template according to guidelines contained in it to simplify process of reproducing the issue for maintainers. If there is no dedicated template, use PyGerber Bug Report template.

💻 PyGerber CLI

PyGerber provides non-interactive command line interface which provides means to access some of its features. pygerber command is available after installation and can be used to access tools with use of subcommands.

To check version of PyGerber available in your environment, you can use:

pygerber --version

To convert Gerber file to PNG image you can use pygerber gerber convert png command. Assuming that your Gerber file is named source.gbr representing a copper layer and you want to convert it to PNG image with DPMM of 600, command would look like this:

pygerber gerber convert png source.gbr -o output.png -d 600 -s copper_alpha

This will create output.png file in current working directory. Depending on your image size you may need to adjust -d (--dpmm) parameter to increase or decrease the resolution of image.

Here is an example result of converting a Gerber file to PNG image:

There are more export target formats available, like JPEG, TIFF or SVG to name some of them. Use --help flag to get list of available conversion commands:

pygerber gerber convert --help

For more detailed command line interface documentation please visit Gerber -> Command Line section in documentation.

§ Language Server

PyGerber provides Gerber X3/X2 Language Server conforming to Language Servere Protocol defined by Microsoft. It can be enabled by installing PyGerber extras set language-server with following command:

pip install pygerber[language-server]

Afterwards you can use following command to check if PyGerber correctly recognized that language server feature should be enabled:

pygerber is-language-server-available

If you have encountered a problem with language server please report it in the Issues section of Github repository of this project.

If you have a suggestion for improvement, please open a new discussion thread in the Discussions section of our repository.

To fully utilize power of this language server you can use Visual Studio Code extension Gerber X3/X2 Format Support (argmaster.gerber-x3-x2-format-support). Repository of this extension is available here. If you encounter any problems with that extension, please report them in the Issues section of its repository. If you are not sure whether the problem is caused by extension or by language server, please report it in the Issues section of the extension, we will move it to PyGerber repository if necessary.

Development

For development guidelines please visit documentation Development section here.

Acknowledgments

I would like to thank Professor Janusz Młodzianowski from the University of Gdańsk, who inspired me with the idea to implement the Gerber format at the beginning of my bachelor's degree. I would like to also express my gratitude to Karel Tavernier, the long-time steward of the Gerber format, for his support and expert guidance during my work on this project. Without them, this project would have never come to life. Finally, I would like to thank all the people who have contributed, are contributing and will contribute to PyGerber. Your help is invaluable and I am grateful for it.