API reference -- top-level package

All public symbols are importable from the root gerberdiff package; see the Python API guide for usage examples.

Parsing

Parse a Gerber RS-274X file string into a ParsedImage.

All diagnostics (errors, warnings, info) are collected on image.diagnostics. This function never raises for parse-level problems; only genuine Python-level exceptions (e.g. MemoryError) propagate.

Parse an Excellon drill file into a ParsedImage.

Tool definitions become CircleAperture entries in image.apertures. Drill hits become DrawOp(aperture_state=Flash) entries. All coordinates are normalised to inches.

Both decimal-format (KiCad modern) and integer-format (Altium, older KiCad, most CAM systems) coordinate encodings are supported. The zero-suppression convention and digit counts are read from the METRIC/INCH header line. If no format header is present, METRIC,TZ with 3.3 digit counts is assumed and a DiagnosticSeverity.Warning is emitted.

Geometry diff

Geometry-diff two directories of Gerber/Excellon layer files.

Parameters:

Name	Type	Description	Default
before_dir	Path	Directories containing the before and after layer files.	required
after_dir	Path	Directories containing the before and after layer files.	required
layers	Sequence[str] | None	If given, only layers whose names appear in this sequence are diffed.	None
move_tol_mm	float	Minimum centroid displacement (mm) for a matched pair to be reported as moved rather than unchanged.	DEFAULT_MOVE_TOL_MM
gate_radius_mm	float	Maximum centroid distance (mm) at which two ops can be considered the same object.	DEFAULT_GATE_RADIUS_MM
area_tol	float	Relative area delta within which two matched ops still count as the same dimensions (distinguishes moved from resized).	DEFAULT_AREA_TOL
dust_area_mm2	float	Boolean-difference components smaller than this (mm^2) are dropped as numeric noise.	DEFAULT_DUST_AREA_MM2
on_diagnostic	Callable[[Path, Diagnostic], None] | None	Called with (path, diagnostic) for every non-fatal parse or expansion diagnostic.	None

Raises:

Type	Description
GerberParseError	When a file contains a fatal (Error-severity) parse diagnostic.
OSError	When a layer file cannot be read.

Raster diff

Render both images to a shared viewport and compute the pixel diff.

Parameters:

Name	Type	Description	Default
image_a	ParsedImage	Parsed Gerber/Excellon images to compare.	required
image_b	ParsedImage	Parsed Gerber/Excellon images to compare.	required
width	int	Canvas dimensions in pixels.	required
height	int	Canvas dimensions in pixels.	required
alignment_offset	tuple[float, float] | None	Optional (dx, dy) inches translation applied to image_b before rendering. Used when the two board revisions have different origins.	None
min_pixel_count	int	Minimum pixel count for a region to be reported (filters noise).	4
merge_tolerance	float	Bounding-box padding (inches) used when deciding whether to merge two nearby regions into one.	0.05
overlay_callback	Callable[[ndarray, ndarray, ndarray], None] | None	Optional callable invoked with (arr_a, arr_b, xor) before the arrays are released. Use this to write a PNG overlay without keeping all three (H, W, 4) arrays live simultaneously.	None

Diff two directories of Gerber/Excellon layer files.

Parameters:

Name	Type	Description	Default
before_dir	Path	Directories containing the before and after layer files.	required
after_dir	Path	Directories containing the before and after layer files.	required
width	int	Canvas dimensions in pixels.	2048
height	int	Canvas dimensions in pixels.	2048
layers	Sequence[str] | None	If given, only layers whose names appear in this sequence are diffed.	None
alignment_offset	tuple[float, float] | None	Optional (dx, dy) inch translation applied to after_dir images before diffing.	None
min_pixel_count	int	Minimum pixel count for a region to be reported.	4
merge_tolerance	float	Bounding-box padding (inches) used when merging nearby regions.	0.05
overlay_callback	Callable[[str, ndarray, ndarray, ndarray], None] | None	Called with (layer_name, arr_a, arr_b, xor) for each matched layer. Use this to write per-layer overlay PNGs without keeping all arrays live simultaneously.	None
on_diagnostic	Callable[[Path, Diagnostic], None] | None	Called with (path, diagnostic) for every non-fatal diagnostic (Warning and Info severity) encountered while parsing.	None

Raises:

Type	Description
GerberParseError	When a file contains a fatal (Error-severity) parse diagnostic.
OSError	When a layer file cannot be read.

Rendering

Render to a numpy array of shape (H, W, 4) with dtype uint8.

Channel order is BGRA (Cairo's native ARGB32 little-endian layout).

Render parsed_image into a new cairo.ImageSurface.

The surface uses FORMAT_ARGB32 (premultiplied alpha). Transparent pixels represent the PCB substrate / background.

coordinate_offset shifts the board in world-space (inches) before rendering. Used by compute_diff to align two boards with different origins.

Fit bbox into a width x height canvas with a 10% margin.

Returns a default viewport (zoom=100, centred) when the bbox is invalid or has zero extent in either axis.

Layer matching

Match layer files between before_dir and after_dir.

Returns a list of :class:LayerPair objects sorted by layer type order then alphabetically by name.