Single file guide¶

Welcome to the PyGerber single file guide. This guide focuses on tools which take single Gerber file as opposed to Multi file guide guide which is concerned with operating on collections of Gerber files. Most of the functionality is exposed as methods on GerberFile class which can be imported from pygerber.gerber.api module and we will be using it throughout this document.

Creating `GerberFile` instance¶

To perform any operations on individual Gerber file(s), like rendering or formatting, you have to create GerberFile class instance wrapping actual Gerber code. Recommended way is to use one of 3 factory methods provided by GerberFile class: from_str(), from_file() or from_buffer()

from_str() creates GerberFile from str object containing Gerber code.

example_from_str.py
from pygerber.gerber.api import GerberFile

source_code = """
%FSLAX26Y26*%
%MOMM*%
%ADD100C,1.5*%
D100*
X0Y0D03*
M02*
"""

gerber_file = GerberFile.from_str(source_code)

from_file() creates GerberFile by reading a file which location is determined by first parameter passed to from_file(). You can use str or pathlib.Path to specify file location.

example_from_file.py
from pygerber.gerber.api import GerberFile
from pathlib import Path

path_to_my_gerber_file = Path().cwd() / "example.grb"

gerber_file = GerberFile.from_file(path_to_my_gerber_file)

from_buffer() creates GerberFile from io.TextIO-like object.

example_from_buffer.py
from pygerber.gerber.api import GerberFile
from pathlib import Path

with (Path().cwd() / "example.grb").open() as text_io:
    gerber_file = GerberFile.from_buffer(text_io)

Each of the factory methods listed above accept optional file_type (FileTypeEnum )parameter which can be used to explicitly set file type (e.g. copper, silkscreen). If this parameter is not set, by default PyGerber will try to guess file type based on file extension and/or file attributes.

Info

File type affects color of rendered image if color scheme is not explicitly set.

Configuring `GerberFile` object¶

Once you have GerberFile object created, you can use PyGerber features exposed as methods on this object. GerberFile allows you to customize behavior of some of underlying implementation parts. Those methods mutate GerberFile object and consecutive calls to those methods override previous configuration in its entirety.

set_color_map() can be used to override default color map.

Color map is used to map file type to predefined color style. PyGerber provides simple color schema but it is useful mostly for final renders as colors used were chosen to resemble final look of average PCB. Therefore you can easily provide your own color map.

Check out Custom color maps for more details.

set_parser_options() allows you to modify advanced parser settings. It is available to allow tweaking predefined parser behavior options. If you need more control than provided here, please check out Extending Guide. **options are intentionally not precisely defined here, as they are different for different parser implementations, only way to use this method is to already understand what you are doing.

set_compiler_options() allows you to modify advanced compiler settings. It is available to allow tweaking predefined compiler behavior options. If you need more control than provided here, please check out Extending Guide. **options are intentionally not precisely defined here, as they are different for different compiler implementations, only way to use this method is to already understand what you are doing.

Rendering Gerber file¶

Raster images¶

GerberFile object exposes render_with_pillow() method which uses Gerber file renderer implemented with Pillow (Python Imaging Library (PIL) fork) to generate raster images. Those images can be saved afterwards in PNG, JPEG etc. image formats.

render_with_pillow.py
from pygerber.gerber.api import GerberFile

from pygerber.examples import ExamplesEnum, load_example

gerber_source_code = load_example(ExamplesEnum.UCAMCO_2_11_2)

image = GerberFile.from_str(gerber_source_code).render_with_pillow()
image.get_image().save("output.png")

render_with_pillow() method accepts dpmm parameter which can be used to set custom dots-per-millimeter value, hence increase and decrease image resolution. By default this value is set to 20, which is a safe default, but quite low for small PCBs.

render_with_pillow() returns PillowImage object which wraps actual image (PIL.Image.Image object) and additional information about image coordinate space.

render_project

To retrieve image object, you can use get_image() method. Afterwards you can save it with save() method offered by PIL.Image.Image class instance or transform with other methods. To find out more please refer to Pillow documentation.

To retrieve information about image space you can use get_image_space() method. This method returns ImageSpace object which contains information about image coordinates, image size, etc, as presented below:

show_image_space.py
from pygerber.gerber.api import GerberFile

from pygerber.examples import ExamplesEnum, load_example

gerber_source_code = load_example(ExamplesEnum.UCAMCO_2_11_2)

image = GerberFile.from_str(gerber_source_code).render_with_pillow()
print(image.get_image_space())

$ python show_image_space.py

ImageSpace(
    units = Units.Millimeters,
    min_x_mm = -0.05,
    min_y_mm = -0.05,
    max_x_mm = 42.55,
    max_y_mm = 37.5,
    dpmm = 20,
)

Vector images¶

GerberFile object exposes render_with_shapely() method which uses Gerber file renderer implemented with shapely library to generate vector images. Those images can be saved afterwards in SVG format.

render_with_shapely() returns ShapelyImage object which wraps output geometry and additional information about image coordinate space. You can save the image in SVG format using save() method

example.py
from pygerber.gerber.api import GerberFile, Style

from pygerber.examples import ExamplesEnum, get_example_path

path_to_gerber_file = get_example_path(ExamplesEnum.UCAMCO_2_11_2)

image = GerberFile.from_file(path_to_gerber_file).render_with_shapely(
    Style.presets.BLACK_WHITE
)
image.save("output.svg")

render_project

Improvements in PyGerber 3.0.0

In comparison to SVG rendering engine present in PyGerber 2.4.x, shapely based implementation performs actual boolean operations on geometry, therefore resulting in cleaner geometry which can be used to create 3D models, for example in blender.

Image colors¶

There are three ways to change color of image created with render_with_*() methods.

First way is to explicitly pass Style instance as style parameter to render_with_*() method. Style class offers predefined styles which can be accessed by Style.presets.<preset-name>.

Second way is to change Gerber file type. File type can be deduced automatically but also can be explicitly set in GerberFile factory method (from_str, from_file etc.). File type will be mapped to specific Style based on color map.

Third way is to change what color map is used to convert file types to styles. This can be achieved with set_color_map(), but for more details on how to specify custom color maps see Custom color maps.

Formatting Gerber file¶

GerberFile object exposes format() and formats() methods which format Gerber code. For detailed documentation of formatting options, please refer to Formatter -> Configuration.

The difference between format() and formats() methods is that first one writes formatted code to TextIO-like object while second one returns it as a str object.

format_file.py
from pygerber.gerber.api import GerberFile, Options

source_code = """
%FSLAX26Y26*%%MOMM*%%ADD100C,1.5*%D100*X0Y0D03*M02*
"""

gerber_file = GerberFile.from_str(source_code)
formatted_code = gerber_file.formats(Options(d03_indent=2))

print(formatted_code)

$ python format_file.py

%FSLAX26Y26*%
%MOMM*%
%ADD100C,1.5*%
D100*
  X0Y0D03*
M02*