The api module provides simple, high-level API for rendering
Gerber X3/X2 files.
Image composed of multiple sub-images.
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(dpmm: int = 20) -> CompositePillowImage
Render project to raster image using Pillow.
Bases: Enum
Enumeration of possible Gerber file types.
class-attribute
instance-attribute
¶
Heat sink mask layer.
class-attribute
instance-attribute
¶
Peelable mask layer.
class-attribute
instance-attribute
¶
Represents request to identify layer type from file extension.
class-attribute
instance-attribute
¶
Represents request to identify layer type from file attributes.
class-attribute
instance-attribute
¶
Represents request to identify layer type from file extension or attributes.
classmethod
¶
infer_from_attributes(
file_function: Optional[str] = None,
) -> FileTypeEnum
Infer file type from file extension.
Bases: GerberX3APIError
Raised when path to Gerber Job project is not defined.
Generic representation of Gerber file.
This objects provides interface for loading and parsing Gerber files.
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
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
strobject. -
file_type(FileTypeEnum, default:INFER) –File type classification, by default FileTypeEnum.INFER
Returns:
-
Self–New instance of GerberFile object.
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 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 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(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_MAPorDEFAULT_ALPHA_COLOR_MAPor your own. They are both available inpygerber.gerber.apimodule. 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(
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_typewill be used.file_typewas one ofFileTypeEnum.INFER*attempt will be done to guessfile_typebased 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(
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_typewill be used.file_typewas one ofFileTypeEnum.INFER*attempt will be done to guessfile_typebased 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 Gerber code and write it to output stream.
Format Gerber code and return it as str object.
The Image class is a base class for all rendered images returned by
GerberFile.render_with_* methods.
Container for information about Gerber image space.
center_x_mm() -> float
Center X coordinate of image in millimeters.
This value can be negative.
center_y_mm() -> float
Center Y coordinate of image in millimeters.
This value can be negative.
min_x_pixels() -> int
Minimum X coordinate of image in pixels.
This value can be negative.
Bases: Image
The ShapelyImage class is a rendered image returned by
GerberFile.render_with_shapely method.
Bases: _ModelType
Design Rules.
Bases: _ModelType
Files Attributes.
Bases: _ModelType
General Specs.
Bases: _ModelType
Generation Software.
Bases: _ModelType
Gerber Job File.
classmethod
¶
from_file(path: str | Path) -> GerberJobFile
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.
Bases: _ModelType
Header.
Bases: _ModelType
Material Stackup.
Bases: _ModelType
Project ID.
Bases: _ModelType
Size.
Bases: BaseModel
The Options class aggregates configuration options for the Gerber
formatter.
For detailed description of individual options, please visit (TODO: Add doc link).
class-attribute
instance-attribute
¶
indent_character: Literal[' ', '\t'] = Field(default=' ')
Character used for indentation, by default " " (space).
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.
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.
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.
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
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.
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.
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.
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.
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
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
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
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.
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.
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.
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.
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.
class-attribute
instance-attribute
¶
explicit_parenthesis: ExplicitParenthesis = Field(
default=KeepOriginal
)
Toggle explicit parenthesis around all mathematical expressions within macro, by
default ExplicitParenthesis.KeepOriginal
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.
Bases: ModelType
Style class represents colors which should be used for coloring rendered image layer.
Bases: Namespace
Style.presets contains predefined styles for convenience.
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.
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.
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.
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.
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.
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.
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.
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.