Package: pygerber
PyGerberPyGerber is a Python implementation of Gerber X3/X2 format. It is based on Ucamco'sThe Gerber Layer Format Specification. Revision 2023.03(Available onUcamco's webpageand inthis 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:TokenizerParserOptimizerIntrospection APIRasterized 2D rendering engine (WithPillow)Vector 2D rendering engine (Withdrawsvg)Model 3D rendering engine (WithBlender)FormatterLinter (eg. deprecated syntax detection)Gerber X3/X2 Language Server (withlanguage-serverextras)You can view progress of development inGerber features supportsection 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.InstallationPyGerber can be installed withpipfrom PyPI:pip install pygerberAlternatively, it is also possible to install it directly from repository:pip install git+https://github.com/Argmaster/pygerberLanguage ServerSince release 2.1.0 PyGerber now provides Gerber X3/X2 Language Server withLSPsupport. It can be enabled
by installing PyGerber extras setlanguage-serverwith following command:pip install pygerber[language-server]Afterwards you can usepygerber is-language-server-availableto check if language
server was correctly enabled. Please report all issues inPyGerber Issuessection.Command line usageAfter installingpygerber, depending on your environment, it should become available
in your command line:pygerber--versionOutput should be similar to one below⇩, wherex.y.zshould match version of
PyGerber installed.$ pygerber --version
pygerber, version x.y.zUse--helpto display help messages with lists of subcommands and subcommand options:pygerber raster-2d --helpTo render 2D PNG image of some gerber file you can simply use:pygerber raster-2d gerber-source.grbImage will be saved tooutput.pngin current working directory.API usagePyGerber 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.TheLayerClass: At its core, theLayerclass stands for a single Gerber
source file, complete with its associated PyGerber configuration.ImportantLayerclass representsanyGerber file,notlayer of PCB. For
example, silkscreen Gerber file will require one instance ofLayer, paste mask will
require another one, copper top yet another, etc.Configuration Flexibility: The configuration possibilities you get with aLayerare driven by the backend you choose to render your source file.Selecting a Backend: PyGerber provides specialized subclasses of theLayerclass
each tied to one rendering backend. For instance, if you're aiming for 2D rasterized
images,Rasterized2DLayeris 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 renderingall formats supported by Pilloware accepted.Rasterized render from filefrompygerber.gerberx3.apiimport(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 createsRasterized2DLayerobject, renders it with rasterized 2D
backend and saves it asPNGimage. Use ofRasterized2DLayerandRasterized2DLayerOptionsclasses implicitly use 2D rasterized backend. To use
different rendering backend with high level API, user must pick differentLayerandLayerOptionssubclasses. For other backends seeTarget set of toolssection, note that only checked ones are
available.source_pathoption acceptsstrorPathpointing 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 alsosource_codeandsource_bufferparameters which allow for use of rawstrorbytesobjects (first one) andStringIOandBytesIOor file descriptors (second one).source_code,source_bufferandsource_pathare mutually exclusive.ColorSchemeis 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 customColorSchemeobject should work
perfectly fine.Pattern of using<Class>and<Class>Options, like above, is used in many places in
PyGerber. When initializing object likeRasterized2DLayerit is only valid to passRasterized2DLayerOptionsto constructor. PassingLayerOptionsorVectorized2DLayerwill cause undefined behavior, most likely yielding no result or raising exception.Rasterized render from stringfrompygerber.gerberx3.apiimport(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:DocumentationOfficial documentations is hosted on Github Pages and can be foundhere.Gerber features supportPlease refer to documentation forTokenizer,Parser,Rasterized2DBackend,Parser2,SvgRenderer2,for detailed list of features which are supported/not supported by each tool.Syntax feature requestsAll 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 inThe Gerber Layer Format Specification. Revision 2023.08(Available onUcamco's webpageand inthis 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.DevelopmentTo quickly set up development environment, first you have to installpoetryglobally:pip install poetryAfterwards you will be able to create development virtual environment:poetry shellThen You have to install dependencies into this environment:poetry installAnd pre-commit hooks:poe install-hooksNow 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 sourceTo build PyGerber from source You have to set upDevelopmentenvironment
first. Make sure you havepoetryenvironment activated with:poetry shellWith environment active it should be possible to build wheel and source distribution
with:poetry buildCheckdistdirectory within current working directory,pygerber-x.y.z.tar.gzandpygerber-x.y.z-py3-none-any.whlshould be there.Gerber reference archiveThis 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 foundhere.