pygerber 2.2.0

Parsing, formatting and rendering toolkit for Gerber X3 file format

PyGerber

PyGerber is a Python implementation of Gerber X3/X2 format. It is based on Ucamco's The Gerber Layer Format Specification. Revision 2023.03 (Available on Ucamco's webpage and in this repository). The goal of this project is to provide support for wide variety of Gerber-like syntaxes, with support for most of deprecated features along with support for modern ones.

📚 See online documentation 📚

Target set of tools:

• Tokenizer
• Parser
• Optimizer
• Introspection API
• Rasterized 2D rendering engine (With Pillow)
• Vector 2D rendering engine (With drawsvg)
• Model 3D rendering engine (With Blender)
• Formatter
• Linter (eg. deprecated syntax detection)
• Gerber X3/X2 Language Server (with language-server extras)

You can view progress of development in Gerber features support section down below. All Gerber source files which can be redistributed under MIT license and included in this repository for testing purposes will be greatly appreciated.

Installation

PyGerber can be installed with pip from PyPI:

pip install pygerber

Alternatively, it is also possible to install it directly from repository:

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

Language Server

Since release 2.1.0 PyGerber now provides Gerber X3/X2 Language Server with LSP support. It can be enabled by installing PyGerber extras set language-server with following command:

pip install pygerber[language-server]

Afterwards you can use pygerber is-language-server-available to check if language server was correctly enabled. Please report all issues in PyGerber Issues section.

Command line usage

After installing pygerber, depending on your environment, it should become available in your command line:

pygerber --version

Output should be similar to one below ⇩, where x.y.z should match version of PyGerber installed.

$ pygerber --version
pygerber, version x.y.z

Use --help to display help messages with lists of subcommands and subcommand options:

pygerber raster-2d --help

To render 2D PNG image of some gerber file you can simply use:

pygerber raster-2d gerber-source.grb

Image will be saved to output.png in current working directory.

API usage

PyGerber offers a high-level API that simplifies the process of rendering Gerber files. Whether you're looking to save the rendered output to a file or directly into a buffer, PyGerber has got you covered.

• The Layer Class: At its core, the Layer class stands for a single Gerber source file, complete with its associated PyGerber configuration.

  Important Layer class represents any Gerber file, not layer of PCB. For example, silkscreen Gerber file will require one instance of Layer, paste mask will require another one, copper top yet another, etc.

• Configuration Flexibility: The configuration possibilities you get with a Layer are driven by the backend you choose to render your source file.

• Selecting a Backend: PyGerber provides specialized subclasses of the Layer class each tied to one rendering backend. For instance, if you're aiming for 2D rasterized images, Rasterized2DLayer is your go-to choice.

• Output Types: Keep in mind, the type of your output file is closely tied to the backend you select.For 2D rasterized rendering all formats supported by Pillow are accepted.

Rasterized render from file

from pygerber.gerberx3.api import (
      ColorScheme,
      Rasterized2DLayer,
      Rasterized2DLayerParams,
)

# Path to Gerber source file.
source_path = "main_cu.grb"

Rasterized2DLayer(
      options=Rasterized2DLayerParams(
            source_path=source_path,
            colors=ColorScheme.COPPER_ALPHA,
      ),
).render().save("output.png")

Example code above creates Rasterized2DLayer object, renders it with rasterized 2D backend and saves it as PNG image. Use of Rasterized2DLayer and Rasterized2DLayerOptions classes implicitly use 2D rasterized backend. To use different rendering backend with high level API, user must pick different Layer and LayerOptions subclasses. For other backends see Target set of tools section, note that only checked ones are available.

source_path option accepts str or Path pointing to local Gerber file. No special file extension is required, content is blindly loaded from specified file, so it's user responsibility to provide correct path. There are also source_code and source_buffer parameters which allow for use of raw str or bytes objects (first one) and StringIO and BytesIO or file descriptors (second one). source_code, source_buffer and source_path are mutually exclusive.

ColorScheme is a class which describes what colors should be used for rendering different parts of image. Additionally it has a few static members which contain predefined colors schemes for frequently used layer types. It is not required to use predefined schemes, creating and passing custom ColorScheme object should work perfectly fine.

Pattern of using <Class> and <Class>Options, like above, is used in many places in PyGerber. When initializing object like Rasterized2DLayer it is only valid to pass Rasterized2DLayerOptions to constructor. Passing LayerOptions or Vectorized2DLayer will cause undefined behavior, most likely yielding no result or raising exception.

Rasterized render from string

from pygerber.gerberx3.api import (
      ColorScheme,
      Rasterized2DLayer,
      Rasterized2DLayerParams,
)

source_code = """
%FSLAX26Y26*%
%MOMM*%
%ADD100R,1.5X1.0X0.5*%
%ADD200C,1.5X1.0*%
%ADD300O,1.5X1.0X0.6*%
%ADD400P,1.5X3X5.0*%
D100*
X0Y0D03*
D200*
X0Y2000000D03*
D300*
X2000000Y0D03*
D400*
X2000000Y2000000D03*
M02*
"""

Rasterized2DLayer(
      options=Rasterized2DLayerParams(
            source_code=source_code,
            colors=ColorScheme.SILK,
            dpi=3000,
      ),
).render().save("output.png")

Code above renders following image:

Documentation

Official documentations is hosted on Github Pages and can be found here.

Gerber features support

Please refer to documentation for Tokenizer, Parser, Rasterized2DBackend and Parser2 for detailed list of features which are supported/not supported.

Syntax feature requests

All deprecated features (Mainly those from X2 format) are considered optional and priority to implement them will be assigned based on number of requests form community.

If You needs support for syntax features which are not mentioned in The Gerber Layer Format Specification. Revision 2023.08 (Available on Ucamco's webpage and in this repository) and this feature is not already listed in Support paragraph, please open a new Feature request issue.

Feature request Issue should contain:

• detailed description how requested feature works,
• code samples for testing the feature,
• reference images (only applies to features changing image look).

Requests which don't comply with those guidelines will be considered low priority.

Development

To quickly set up development environment, first you have to install poetry globally:

pip install poetry

Afterwards you will be able to create development virtual environment:

poetry shell

Then You have to install dependencies into this environment:

poetry install

And pre-commit hooks:

poe install-hooks

Now you are good to go. Whenever you commit changes, pre-commit hooks will be invoked. If they fail or change files, you will have to re-add changes and commit again.

Build from source

To build PyGerber from source You have to set up Development environment first. Make sure you have poetry environment activated with:

poetry shell

With environment active it should be possible to build wheel and source distribution with:

poetry build

Check dist directory within current working directory, pygerber-x.y.z.tar.gz and pygerber-x.y.z-py3-none-any.whl should be there.

Gerber reference archive

This repository contains also archival reference files. Although new specs contain dedicated changelog section it may still be helpful in some rare cases to look through old Gerber specs. Archival files can be found here.