api
¶
The api
module provides simple, high-level API for rendering
Gerber X3/X2 files.
CompositeImage
¶
Image composed of multiple sub-images.
CompositePillowImage
¶
CompositeView
¶
View composed of multiple Gerber files.
Composite view is a generalized concept of a top / bottom / inner layer view extracted from a Gerber project. Usually it does not make sense to render all layers at once, as bottom layers will be simply covered by top layers.
This object can be used to render selected Gerber files to single image. It automatically performs alignment and merging of files. Files should be ordered bottom up, topmost layer last, like if adding one layer on top of previous.
render_with_pillow
¶
render_with_pillow(dpmm: int = 20) -> CompositePillowImage
Render project to raster image using Pillow.
FileTypeEnum
¶
Bases: Enum
Enumeration of possible Gerber file types.
HEATSINKMASK
class-attribute
instance-attribute
¶
Heat sink mask layer.
PEELABLEMASK
class-attribute
instance-attribute
¶
Peelable mask layer.
INFER_FROM_EXTENSION
class-attribute
instance-attribute
¶
Represents request to identify layer type from file extension.
INFER_FROM_ATTRIBUTES
class-attribute
instance-attribute
¶
Represents request to identify layer type from file attributes.
INFER
class-attribute
instance-attribute
¶
Represents request to identify layer type from file extension or attributes.
infer_from_attributes
classmethod
¶
infer_from_attributes(
file_function: Optional[str] = None,
) -> FileTypeEnum
Infer file type from file extension.
PathToGerberJobProjectNotDefinedError
¶
Bases: GerberX3APIError
Raised when path to Gerber Job project is not defined.
GerberFile
¶
Generic representation of Gerber file.
This objects provides interface for loading and parsing Gerber files.
from_file
classmethod
¶
from_file(
file_path: str | Path,
file_type: FileTypeEnum = FileTypeEnum.INFER,
) -> Self
Initialize object with Gerber source code loaded from file on disk.
Parameters:
-
file_path
(str | Path
) –Path to Gerber file on disk.
-
file_type
(FileTypeEnum
, default:INFER
) –File type classification, by default FileTypeEnum.INFER
from_str
classmethod
¶
from_str(
source_code: str,
file_type: FileTypeEnum = FileTypeEnum.INFER,
) -> Self
Initialize GerberFile object with Gerber source code from string.
Parameters:
-
source_code
(str
) –Gerber source code as
str
object. -
file_type
(FileTypeEnum
, default:INFER
) –File type classification, by default FileTypeEnum.INFER
Returns:
-
Self
–New instance of GerberFile object.
from_buffer
classmethod
¶
from_buffer(
buffer: TextIO,
file_type: FileTypeEnum = FileTypeEnum.INFER,
) -> Self
Initialize object with Gerber source code from readable buffer.
Parameters:
-
buffer
(TextIO
) –Readable buffer with Gerber source code.
-
file_type
(FileTypeEnum
, default:INFER
) –File type classification, by default FileTypeEnum.INFER
set_parser_options
¶
Set parser options for this Gerber file.
This is a window into advanced parser settings, only reason to use this method should be for advanced user to tweak parser behavior without binging more advanced PyGerber APIs into consideration.
Parameters:
-
**options
(Any
, default:{}
) –Parser options.
Returns:
-
Self
–Returns self for method chaining.
set_compiler_options
¶
Set compiler options for this Gerber file.
This is a window into advanced compiler settings, only reason to use this method should be for advanced user to tweak compiler behavior without binging more advanced PyGerber APIs into consideration.
Parameters:
-
**options
(Any
, default:{}
) –Compiler options.
Returns:
-
Self
–Returns self for method chaining
set_color_map
¶
set_color_map(color_map: COLOR_MAP_T) -> Self
Set color map for rendering of this Gerber file.
Gerber files themselves do not contain color data. Therefore only way to get colorful image is to explicitly ask rendering backend to apply particular color to image.
Parameters:
-
color_map
(COLOR_MAP_T
) –Color map to be used for rendering Gerber file. You can use one of two predefined color maps:
DEFAULT_COLOR_MAP
orDEFAULT_ALPHA_COLOR_MAP
or your own. They are both available inpygerber.gerber.api
module. In most basic cases there is no need to alter default color map, as it already includes alpha channel thus allows for image stacking.
Returns:
-
Self
–Returns self for method chaining.
render_with_pillow
¶
render_with_pillow(
style: Optional[Style] = None, dpmm: int = 20
) -> PillowImage
Render Gerber file to raster image using rendering backend based on Pillow library.
Parameters:
-
style
(Style
, default:None
) –Style (color scheme) of rendered image, if value is None,
file_type
will be used.file_type
was one ofFileTypeEnum.INFER*
attempt will be done to guessfile_type
based on extension and/or attributes, by default None -
dpmm
(int
, default:20
) –Resolution of image in dots per millimeter, by default 20
render_with_shapely
¶
render_with_shapely(
style: Optional[Style] = None,
) -> ShapelyImage
Render Gerber file to vector image using rendering backend based on Shapely library.
Parameters:
-
style
(Style
, default:None
) –Style (color scheme) of rendered image, if value is None,
file_type
will be used.file_type
was one ofFileTypeEnum.INFER*
attempt will be done to guessfile_type
based on extension and/or attributes, by default None Only foreground color is used, as all operations with clear polarity are performing actual boolean difference operations on geometry.
format
¶
Format Gerber code and write it to output
stream.
formats
¶
Format Gerber code and return it as str
object.
Image
¶
The Image
class is a base class for all rendered images returned by
GerberFile.render_with_*
methods.
ImageSpace
¶
Container for information about Gerber image space.
center_x_mm
¶
center_x_mm() -> float
Center X coordinate of image in millimeters.
This value can be negative.
center_y_mm
¶
center_y_mm() -> float
Center Y coordinate of image in millimeters.
This value can be negative.
min_x_pixels
¶
min_x_pixels() -> int
Minimum X coordinate of image in pixels.
This value can be negative.
PillowImage
¶
Bases: Image
The PillowImage
class is a rendered image returned by
GerberFile.render_with_pillow
method.
save
¶
Save result to a file or buffer in file_format
.
Parameters:
-
destination
(str | Path | BinaryIO
) –str
andPath
objects are interpreted as file paths and opened with truncation.BinaryIO
-like (files, BytesIO) objects are written to directly. -
file_format
(str
) –Format to save the image in. Supported formats vary depending on the VirtualMachine used. You can expect though that vector images will support SVG and raster images will support PNG and JPEG formats. Other formats are possible, please check the documentation of the VirtualMachine you are using.
-
kwargs
(Any
, default:{}
) –Additional keyword arguments to pass to save implementation.
save_bmp
¶
Save result to a file or buffer in BMP format.
See pillow documentation here.
Parameters:
-
destination
(str | Path | BinaryIO
) –str
andPath
objects are interpreted as file paths and opened with truncation.BinaryIO
-like (files, BytesIO) objects are written to directly. -
color
(Style
) –Color to use for SVG, background is ignored as it is always rendered as empty space, so only foreground applies, by default Style.presets.COPPER_ALPHA
-
kwargs
(Any
, default:{}
) –Additional keyword arguments to pass to
PIL.Image.save
.
save_png
¶
save_jpeg
¶
save_tiff
¶
ShapelyImage
¶
DesignRules
¶
Bases: _ModelType
Design Rules.
FilesAttributes
¶
Bases: _ModelType
Files Attributes.
GeneralSpecs
¶
Bases: _ModelType
General Specs.
GenerationSoftware
¶
Bases: _ModelType
Generation Software.
GerberJobFile
¶
Bases: _ModelType
Gerber Job File.
from_file
classmethod
¶
from_file(path: str | Path) -> GerberJobFile
to_project
¶
Convert Gerber Job File to PyGerber Project object.
Parameters:
-
path
(Optional[Path]
, default:None
) –If GerberJobFile was not loaded from file on disk, you must provide a path to where that file should be, including file name, by default None
Returns:
-
Project
–New project object containing Gerber files from Gerber Job File.
Header
¶
Bases: _ModelType
Header.
MaterialStackup
¶
Bases: _ModelType
Material Stackup.
ProjectId
¶
Bases: _ModelType
Project ID.
Size
¶
Bases: _ModelType
Size.
Options
¶
Bases: BaseModel
The Options
class aggregates configuration options for the Gerber
formatter.
indent_character
class-attribute
instance-attribute
¶
indent_character: Literal[' ', '\t'] = Field(default=' ')
Character used for indentation, by default " " (space).
macro_body_indent
class-attribute
instance-attribute
¶
Indentation of macro body, could be either a string containing desired
whitespaces or integer which will be used to create indent string based on
indent_character
, by default 0 which results in no indentation.
macro_param_indent
class-attribute
instance-attribute
¶
Indentation of macro parameters, could be either a string containing desired
whitespaces or integer which will be used to create indent string based on
indent_character
, by default 0 which results in no indentation.
macro_param_indent
indentation is added on top of macro body indentation.
macro_param_indent
has effect only when macro_split_mode
is PARAMETERS
.
macro_split_mode
class-attribute
instance-attribute
¶
macro_split_mode: MacroSplitMode = Field(
default=SplitOnPrimitives
)
Changes how macro definitions are formatted, by default
MacroSplitMode.SplitOnPrimitives
.
When NoSplit
is selected, macro definition will be formatted as a single line.
When SplitOnPrimitives
is selected, macro definition will be formatted with each
primitive in a new line.
When SplitOnParameters
is selected, macro definition will be formatted with each
primitive on a new line and each parameter of a primitive on a new line.
Use macro_body_indent
and macro_param_indent
to control indentation.
macro_end_in_new_line
class-attribute
instance-attribute
¶
macro_end_in_new_line: MacroEndInNewLine = Field(default=No)
Toggles placing % sign which marks the end of macro in new line, by default
MacroEndInNewLine.No
block_aperture_body_indent
class-attribute
instance-attribute
¶
Indentation of block aperture definition body, could be either a string
containing desired whitespaces or integer which will be used to create indent
string based indent_character
, by default 0 which results in no indentation.
This indentations stacks for nested block apertures.
step_and_repeat_body_indent
class-attribute
instance-attribute
¶
Indentation of step and repeat definition body, could be either a string
containing desired whitespaces or integer which will be used to create indent
string based indent_character
, by default 0 which results in no indentation.
This indentations stacks for nested step and repeat blocks.
float_decimal_places
class-attribute
instance-attribute
¶
float_decimal_places: int = Field(default=-1)
Limit number of decimal places shown for float values, by default -1 which means as many decimal places as needed.
float_trim_trailing_zeros
class-attribute
instance-attribute
¶
float_trim_trailing_zeros: FloatTrimTrailingZeros = Field(
default=Yes
)
Remove trailing zeros from floats, by default FloatTrimTrailingZeros.Yes
.
When this is set to FloatTrimTrailingZeros.Yes
, after floating point number is
formatted with respect to float_decimal_places
, trailing zeros are removed. If
all zeros after decimal point are removed, decimal point is also removed.
d01_indent
class-attribute
instance-attribute
¶
Custom indentation of D01 command, could be either a string
containing desired whitespaces or integer which will be used to create indent
string based indent_character
, by default 0
d02_indent
class-attribute
instance-attribute
¶
Custom indentation of D02 command, could be either a string
containing desired whitespaces or integer which will be used to create indent
string based indent_character
, by default 0
d03_indent
class-attribute
instance-attribute
¶
Custom indentation of D03 command, could be either a string
containing desired whitespaces or integer which will be used to create indent
string based indent_character
, by default 0
line_end
class-attribute
instance-attribute
¶
line_end: Literal['\n', '\r\n'] = Field(default='\n')
Line ending character, Unix or Windows style, by default "
" (Unix style)
If strip_whitespace
is enabled, this setting is ignored and no line endings are
added.
empty_line_before_polarity_switch
class-attribute
instance-attribute
¶
empty_line_before_polarity_switch: (
EmptyLineBeforePolaritySwitch
) = Field(default=No)
Add empty line before polarity switch, by default
EmptyLineBeforePolaritySwitch.Yes
Inserting empty lines before polarity switches enhances visual separation of sequences of commands with different polarities.
keep_non_standalone_codes
class-attribute
instance-attribute
¶
keep_non_standalone_codes: KeepNonStandaloneCodes = Field(
default=Keep
)
Keep non-standalone codes in the output, by default KeepNonStandaloneCodes.Keep
If this option is disabled, legacy merged code forms like G70D02*
will be divided into two separate commands, G70*
and D02*
, otherwise
they will be kept as is.
remove_g54
class-attribute
instance-attribute
¶
Remove G54 code from output, by default RemoveG54.Keep
G54 code has no effect on the output, it was used in legacy files to prefix select aperture command.
remove_g55
class-attribute
instance-attribute
¶
Remove G55 code from output, by default RemoveG55.Keep
G55 code has no effect on the output, it was used in legacy files to prefix flash command.
explicit_parenthesis
class-attribute
instance-attribute
¶
explicit_parenthesis: ExplicitParenthesis = Field(
default=KeepOriginal
)
Toggle explicit parenthesis around all mathematical expressions within macro, by
default ExplicitParenthesis.KeepOriginal
strip_whitespace
class-attribute
instance-attribute
¶
strip_whitespace: StripWhitespace = Field(default=Default)
Toggle stripping of whitespace from the output, by default
StripWhitespace.Default
which results in normal whitespace handling.
Color
¶
Bases: ModelType
Color class represents a RGBA color.
Channels are represented as integers in range 0 to 255.
from_hex
classmethod
¶
Build RGBA color object from hexadecimal string.
Parameters:
-
string
(str
) –String containing color value. Accepted formats are
RRGGBBAA
andRRGGBB
. For latter, alpha value is assumed to be 0xFF. Formats are case insensitive.#
symbol prefix for hex string is accepted.
Returns:
-
RGBA
–Color built from hexadecimal values.
from_rgba
classmethod
¶
Build RGBA color object from reg, green, blue and alpha integer values.
Parameters:
-
red
(int
) –Red chanel value as integer from 0 to 255, inclusive.
-
green
(int
) –Green chanel value as integer from 0 to 255, inclusive.
-
blue
(int
) –Blue chanel value as integer from 0 to 255, inclusive.
-
alpha
(int
, default:255
) –Alpha chanel value as integer from 0 to 255, inclusive., by default 0xFF
Returns:
-
Self
–Color built from r, g, b, a values.
from_hsv
classmethod
¶
Build RGBA color object from hue, saturation, value and alpha.
For extended information refer to Wikipedia: https://en.wikipedia.org/wiki/HSL_and_HSV
Parameters:
-
hue
(int
) –Hue of color, integer in range 0 to 360 inclusive.
-
saturation
(float
) –Saturation of color, float in range 0.0 to 100.0 inclusive.
-
value
(float
) –Value of color, float in range 0.0 to 100.0 inclusive.
-
alpha
(int
, default:255
) –Alpha of color, int in range 0 to 255 inclusive.
Returns:
-
Self
–Color built from h, s, v, a values.
as_rgba_int
¶
Return RGBA color as tuple of integers in range 0 to 255 inclusive.
as_rgb_int
¶
Return RGB color as tuple of integers in range 0 to 255 inclusive.
as_rgba_float
¶
Return RGBA color as tuple of floats in range 0.0 to 1.0 inclusive.
Style
¶
Bases: ModelType
Style class represents colors which should be used for coloring rendered image layer.
presets
¶
Bases: Namespace
Style.presets
contains predefined styles for convenience.
SILK
class-attribute
¶
SILK: Style
Default color of silk layer.
This schema provided non-transparent background, which results in images which can not be used for stacking on top of other layers, as they would completely obscure them.
SILK_ALPHA
class-attribute
¶
SILK_ALPHA: Style
Default color of silk layer with alpha channel.
This schema provides transparent background. Images using this schema can be stacked on top of each other without obscuring layers below.
COPPER
class-attribute
¶
COPPER: Style
Default color of copper layer.
This schema provided non-transparent background, which results in images which can not be used for stacking on top of other layers, as they would completely obscure them.
COPPER_ALPHA
class-attribute
¶
COPPER_ALPHA: Style
Default color of copper layer with alpha channel.
This schema provides transparent background. Images using this schema can be stacked on top of each other without obscuring layers below.
PASTE_MASK
class-attribute
¶
PASTE_MASK: Style
Default color of paste mask layer.
This schema provided non-transparent background, which results in images which can not be used for stacking on top of other layers, as they would completely obscure them.
PASTE_MASK_ALPHA
class-attribute
¶
PASTE_MASK_ALPHA: Style
Default color of paste mask layer with alpha channel.
This schema provides transparent background. Images using this schema can be stacked on top of each other without obscuring layers below.
SOLDER_MASK
class-attribute
¶
SOLDER_MASK: Style
Default color of solder mask layer.
This schema provided non-transparent background, which results in images which can not be used for stacking on top of other layers, as they would completely obscure them.
SOLDER_MASK_ALPHA
class-attribute
¶
SOLDER_MASK_ALPHA: Style
Default color of solder mask layer with alpha channel.
This schema provides transparent background. Images using this schema can be stacked on top of each other without obscuring layers below.
DEFAULT_GRAYSCALE
class-attribute
¶
DEFAULT_GRAYSCALE: Style
Default color scheme for files which were not assigned other color scheme.