jitxlib.gerber.format package#

Standalone Gerber X2/X3, XNC and gbrjob writer.

No JITX imports anywhere in this package: it models and serializes the fabrication data set and is unit-testable without a runtime.

Everything is metric. Gerber files declare %FSLAX46Y46*% with %MOMM*%, so a coordinate integer is a nanometer, and XNC writes decimal millimeters off the same integers - a point shared by a copper file and a drill file serializes identically in both.

class Aperture(template, params=(), attrs=())[source]#

Bases: object

An AD instantiation of a standard template or a macro.

Parameters:
  • template (str | Macro) – a standard template letter (C, R, O, P) or the macro to instantiate.

  • params (tuple[float, ...]) – the AD modifiers in order, joined with X on emission. For a macro this includes the rotation argument.

  • attrs (tuple[tuple[str, tuple[str, ...]], ...]) – aperture attributes, applied to this aperture alone.

template: str | Macro#
params: tuple[float, ...] = ()#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
property template_name: str#
property macro: Macro | None#
exception ApertureError[source]#

Bases: ValueError

A shape cannot be expressed as an aperture.

class ArcObj(x1, y1, x2, y2, cx, cy, ccw, aperture, attrs=())[source]#

Bases: object

A D01 in circular mode, stroked from (x1, y1) to (x2, y2).

The center is absolute; the emitter derives the signed I/J offsets. ccw selects G03 over G02. A sweep over 180 degrees is split by the emitter, and a coincident start and end is a full circle, which the emitter also splits rather than emitting as the spec’s zero-length form.

Parameters:
x1: float#
y1: float#
x2: float#
y2: float#
cx: float#
cy: float#
ccw: bool#
aperture: Aperture#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
class Compat(bake_macro_rotation=False)[source]#

Bases: object

The set of adjustments in effect for one export.

Parameters:

bake_macro_rotation (bool) – write rotated pads as macros with the rotation applied to the primitive coordinates and no rotation parameter, for readers that mishandle the macro rotation argument. Each distinct angle of a shape becomes its own macro.

bake_macro_rotation: bool = False#
classmethod from_names(names)[source]#

The adjustments named, as on the command line (bake-macro-rotation).

Raises:

ValueError – a name is not a known adjustment, listing the known ones.

Return type:

Compat

Parameters:

names (Iterable[str])

property names: tuple[str, ...]#

The command-line names of the adjustments in effect, sorted.

class Component(index, side)[source]#

Bases: object

Component,L<index>,<side>, the X3 assembly layer for one side.

Parameters:
index: int#
side: Side#
kind = 'component'#
render()[source]#
Return type:

str

class Contour(start, segments)[source]#

Bases: object

One closed contour of a region.

Parameters:
  • start (tuple[float, float]) – the D02 point the contour opens on.

  • segments (tuple[Seg | CurveSeg, ...]) – must return to start; the emitter closes nothing implicitly, it only checks that the closure holds on the output grid.

start: tuple[float, float]#
segments: tuple[Seg | CurveSeg, ...]#
exception ContourError[source]#

Bases: ValueError

A contour cannot be made to satisfy 4.10.3.

class Copper(index, side, conductors, type=None)[source]#

Bases: object

Copper,L<index>,<side>[,<type>].

Parameters:
  • index (int) – 1-based conductor index, counted from the top.

  • side (Side) – Top for index 1, Bot for the last conductor, Inr otherwise.

  • conductors (int) – total conductor count, for naming schemes that vary with board size. Not part of the rendered attribute.

  • type (CopperType | None) – emitted only when set; a plain signal layer leaves it off.

index: int#
side: Side#
conductors: int#
type: CopperType | None = None#
kind = 'copper'#
render()[source]#
Return type:

str

class CopperType(*values)[source]#

Bases: StrEnum

SIGNAL = 'Signal'#
PLANE = 'Plane'#
MIXED = 'Mixed'#
class CurveSeg(x, y, cx, cy, ccw)[source]#

Bases: object

An arc contour segment ending at (x, y) around an absolute center.

Parameters:
x: float#
y: float#
cx: float#
cy: float#
ccw: bool#
class Draw(x1, y1, x2, y2, aperture, attrs=())[source]#

Bases: object

A D01 in linear mode: a straight stroke with round caps.

Parameters:
x1: float#
y1: float#
x2: float#
y2: float#
aperture: Aperture#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
class Drill(first, last, hole, plated=True, content=None, format=DrillFormat.GERBER)[source]#

Bases: object

(Plated|NonPlated),<from>,<to>,<hole type>[,<content>].

Parameters:
  • first (int) – 1-based conductor index the span starts at.

  • last (int) – 1-based conductor index the span ends at.

  • hole (HoleType) – PTH/NPTH for a span crossing the whole board, Blind or Buried otherwise.

  • plated (bool) – selects the Plated or NonPlated keyword. Plating is a file attribute by design, which is why plated and non-plated hits cannot share a file.

  • content (DrillContent | None) – Drill, Rout or Mixed; omitted when the file is plain hits.

  • format (DrillFormat) – which format the file is written in. Not part of the rendered attribute - it decides the file’s extension and its gbrjob FileFormat, so naming and the job writer branch on it rather than on an extension they would otherwise have to guess.

first: int#
last: int#
hole: HoleType#
plated: bool = True#
content: DrillContent | None = None#
format: DrillFormat = 'gerber'#
kind = 'drill'#
render()[source]#
Return type:

str

class DrillContent(*values)[source]#

Bases: StrEnum

DRILL = 'Drill'#
ROUT = 'Rout'#
MIXED = 'Mixed'#
class DrillFormat(*values)[source]#

Bases: StrEnum

Which format a drill file is written in.

One format per data set, never both: a job file listing an XNC and a Gerber drill file for the same span gives a CAM system every reason to drill the holes twice.

Gerber is the spec’s own recommendation - 6.6, “use Gerber rather than an NC format for drill and rout layers … mixing formats is asking for problems, especially in registration” - with XNC as the NC fallback it endorses, “the only one that is clearly specified and targeted to CAD to CAM data transfer”.

Gerber is the default. XNC remains available for a consumer whose intake wants an NC file, selected with –drill-format xnc.

XNC = 'xnc'#
GERBER = 'gerber'#
class DrillFile(function, hits=list(), slots=list())[source]#

Bases: object

One XNC file: one plating, one span.

Hits and slots are emitted in the order added, grouped into the drill and rout sections the XNC grammar requires.

Parameters:
function: Drill#
hits: list[Hit]#
slots: list[Slot]#
property tools: list[Tool]#

Every distinct tool used, in sorted emission order.

class DescriptiveNaming[source]#

Bases: object

The neutral scheme: names say what the file is.

Every name is <stem>-<description><extension>, except the job file, whose extension is its whole identity.

name(function, stem, file_set)[source]#
Return type:

str | None

Parameters:
  • function (FileFunction)

  • stem (str)

  • file_set (Sequence[FileFunction])

class FileEntry(path, function, polarity=None, file_format=None)[source]#

Bases: object

One FilesAttributes entry.

Parameters:
  • path (str) – the resolved filename, as written to disk.

  • file_format (str | None) – XNC for a drill file; omitted for Gerber, whose format is implied.

  • function (FileFunction)

  • polarity (FilePolarity | None)

path: str#
function: Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job#
polarity: FilePolarity | None = None#
file_format: str | None = None#
class FileKind(*values)[source]#

Bases: StrEnum

The primary branch a naming scheme and the overwrite guard key on.

COPPER = 'copper'#
SOLDERMASK = 'soldermask'#
LEGEND = 'legend'#
PASTE = 'paste'#
PROFILE = 'profile'#
DRILL = 'drill'#
COMPONENT = 'component'#
JOB = 'job'#
class FileNaming(*args, **kwargs)[source]#

Bases: Protocol

A strategy that turns a file function into a filename.

Implement name and register the class under a scheme name. A scheme is free to return None for any file it has no convention for; the caller falls back to descriptive rather than inventing a name.

name(function, stem, file_set)[source]#

The complete filename for one file, or None to defer.

Parameters:
  • function (Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job) – what the file is, as the structured description it already carries for its TF.FileFunction attribute, so a scheme branches on data rather than on a rendered string.

  • stem (str) – the scrubbed design name. Conventions that replace the extension entirely need it, which is why the strategy returns a whole filename rather than a suffix.

  • file_set (Sequence[Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job]) – every file function in the set being written, in emission order. Real conventions are not per-file functions of one file - whether a drill name needs decorating depends on whether the other drill file exists - so the set is passed even though many schemes will ignore it.

Return type:

str | None

class FileMeta(software, creation_date, project, compat=Compat(bake_macro_rotation=False))[source]#

Bases: object

The per-run identity every file in the set repeats.

Injected by the caller rather than read from a clock inside an emitter, so output is reproducible.

Parameters:
  • creation_date (str) – ISO 8601 with a time zone.

  • compat (Compat) – the output adjustments in effect, which every file names in a comment so it shows how it was written.

  • software (GenerationSoftware)

  • project (ProjectId)

software: GenerationSoftware#
creation_date: str#
project: ProjectId#
compat: Compat = Compat(bake_macro_rotation=False)#
class FilePolarity(*values)[source]#

Bases: StrEnum

POSITIVE = 'Positive'#
NEGATIVE = 'Negative'#
class Flash(x, y, aperture, attrs=())[source]#

Bases: object

A D03: one aperture stamped at a point.

Every pad is a flash and every flash is a pad (spec 4.10), so nothing else may use this.

Parameters:
x: float#
y: float#
aperture: Aperture#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
class GenerationSoftware(vendor, application, version)[source]#

Bases: object

TF.GenerationSoftware and the gbrjob Header object of the same name, which spells the same three fields as JSON.

Parameters:
  • vendor (str)

  • application (str)

  • version (str)

vendor: str#
application: str#
version: str#
class GerberFile(function, polarity=FilePolarity.POSITIVE, objects=list())[source]#

Bases: object

One Gerber image: its file function, polarity and object list.

There is no aperture table here on purpose. Every object carries the aperture it uses, apertures are values rather than registry entries, and §7 assigns D-codes by sorted key once the set is complete - so the table is derived at emission and cannot drift out of step with the objects.

Parameters:
function: Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job#
polarity: FilePolarity = 'Positive'#
objects: list[Flash | Draw | ArcObj | Region | Surface]#
add(obj)[source]#

Append an object to the image.

Return type:

None

Parameters:

obj (Flash | Draw | ArcObj | Region | Surface)

class Hit(x, y, tool, attrs=())[source]#

Bases: object

A drill hit of the selected tool.

Parameters:
x: float#
y: float#
tool: Tool#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
class HoleType(*values)[source]#

Bases: StrEnum

PTH = 'PTH'#
NPTH = 'NPTH'#
BLIND = 'Blind'#
BURIED = 'Buried'#
class Job[source]#

Bases: object

The .gbrjob file.

It is not a Gerber file and carries no TF.FileFunction, but it is part of the written set, so naming and the overwrite guard need a handle for it.

kind = 'job'#
render()[source]#
Return type:

str

class JobFile(size, conductors, thickness=None, stackup=list(), files=list())[source]#

Bases: object

The job file model.

Parameters:
  • size (tuple[float, float]) – board extent (X, Y) in mm, from the profile bounding box.

  • conductors (int) – LayerNumber, the conductor count.

  • thickness (float | None) – BoardThickness in mm, summed over the stackup where every material declares one.

  • stackup (list[StackupRow])

  • files (list[FileEntry])

size: tuple[float, float]#
conductors: int#
thickness: float | None = None#
stackup: list[StackupRow]#
files: list[FileEntry]#
class Legend(side)[source]#

Bases: object

Legend,<side>.

Parameters:

side (Side)

side: Side#
kind = 'legend'#
render()[source]#
Return type:

str

class Macro(body)[source]#

Bases: object

An AM template, named from its content.

Parameters:

body (tuple[str, ...]) – primitive and variable lines without their trailing *, already rendered with $1 wherever the rotation belongs.

body: tuple[str, ...]#
property name: str#

The generated JITX<hash> template name.

exception NamingError[source]#

Bases: LookupError

No such naming scheme.

exception OutputError[source]#

Bases: Exception

The output set cannot be written safely.

class OutputFile(name, function, content)[source]#

Bases: object

One resolved file: its final name, what it is, and its text.

Parameters:
  • name (str) – a plain filename, already resolved by the naming layer.

  • function (Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job) – what the file is, which is what the overwrite guard keys on.

  • content (str)

name: str#
function: Copper | Soldermask | Legend | Paste | Profile | Drill | Component | Job#
content: str#
class Paste(side)[source]#

Bases: object

Paste,<side>.

Parameters:

side (Side)

side: Side#
kind = 'paste'#
render()[source]#
Return type:

str

class Polarity(*values)[source]#

Bases: StrEnum

Object polarity: dark adds to the image, clear erases from it.

DARK = 'D'#
CLEAR = 'C'#
class Profile(plated=False)[source]#

Bases: object

Profile,(P|NP). JITX has no edge plating, so NP in practice.

Parameters:

plated (bool)

plated: bool = False#
kind = 'profile'#
render()[source]#
Return type:

str

class ProjectId(name, guid, revision='rev?')[source]#

Bases: object

TF.ProjectId: a name, an RFC 4122 GUID and a revision.

revision is rev? when the design carries none.

Parameters:
name: str#
guid: str#
revision: str = 'rev?'#
class Region(contours, polarity=Polarity.DARK, attrs=(), aper_attrs=())[source]#

Bases: object

A G36/G37 statement: the union of its contours’ filled areas.

All contours share one polarity, since polarity is a property of a graphic object. Holes are separate clear regions, not contours here.

Parameters:
  • aper_attrs (tuple[tuple[str, tuple[str, ...]], ...]) – aperture attributes. A region has no aperture, so it takes these from the attribute dictionary as it stands at G36 (5.3.1); this is how a pour carries Conductor and a net tie carries EtchedComponent.

  • contours (tuple[Contour, ...])

  • polarity (Polarity)

  • attrs (tuple[tuple[str, tuple[str, ...]], ...])

contours: tuple[Contour, ...]#
polarity: Polarity = 'D'#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
aper_attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
class Seg(x, y)[source]#

Bases: object

A straight contour segment ending at (x, y).

Parameters:
x: float#
y: float#
class Side(*values)[source]#

Bases: StrEnum

TOP = 'Top'#
INNER = 'Inr'#
BOTTOM = 'Bot'#
class Slot(start, segments, tool, attrs=())[source]#

Bases: object

A rout path: tool down at start, one segment per step, tool up.

Arc segments span at most 180 degrees; XNC carries a radius rather than a center, so the emitter derives it and the direction comes from ccw.

Parameters:
start: tuple[float, float]#
segments: tuple[Seg | CurveSeg, ...]#
tool: Tool#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
class Soldermask(side)[source]#

Bases: object

Soldermask,<side>. Images the openings, so the file is negative.

Parameters:

side (Side)

side: Side#
kind = 'soldermask'#
render()[source]#
Return type:

str

class StackupRow(type, thickness=None, name=None, material=None, dielectric_constant=None, loss_tangent=None)[source]#

Bases: object

One MaterialStackup entry, top to bottom. Thickness in mm.

Parameters:
type: StackupType#
thickness: float | None = None#
name: str | None = None#
material: str | None = None#
dielectric_constant: float | None = None#
loss_tangent: float | None = None#
class StackupType(*values)[source]#

Bases: StrEnum

MaterialStackup row types.

Soldermask and legend rows exist so a stackup layer that declares itself one is not mislabeled dielectric, which is what a “everything that is not a conductor is a dielectric” walk produces.

COPPER = 'Copper'#
DIELECTRIC = 'Dielectric'#
SOLDERMASK = 'SolderMask'#
LEGEND = 'Legend'#
SURFACE_FINISH = 'SurfaceFinish'#
class Surface(island, holes=(), attrs=(), aper_attrs=())[source]#

Bases: object

An island with the holes that belong to it, kept together.

The grouping is the unit any ordering moves, so an island can never be separated from a hole that would erase it. The emitter expands it into a dark region followed by one clear region per hole; island is also the outer ring a containment ordering sorts on.

Parameters:
island: Contour#
holes: tuple[Contour, ...] = ()#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
aper_attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
class Tool(diameter, attrs=())[source]#

Bases: object

One XNC tool.

Parameters:
  • diameter (float) – the finished hole diameter after plating, in mm. The exporter never applies a plating allowance in either direction; the fabricator picks the bit.

  • attrs (tuple[tuple[str, tuple[str, ...]], ...]) – tool attributes, chiefly the bare TA.AperFunction value. Plating is not part of it - that is the file’s attribute.

diameter: float#
attrs: tuple[tuple[str, tuple[str, ...]], ...] = ()#
assign(apertures)[source]#

Give every aperture a D-code, from 10 upwards, by sorted key.

Return type:

dict[Aperture, int]

Parameters:

apertures (set[Aperture])

attr(name, *values)[source]#

One attribute for an AttrSet.

Return type:

tuple[str, tuple[str, ...]]

Parameters:
circle_aperture(diameter, *, hole=None, attrs=())[source]#

C,<diameter>[X<hole>]. Rotation is irrelevant to a circle.

Return type:

Aperture

Parameters:
closed_ring(points)[source]#

A contour from a point ring, closing it if the caller has not.

The convention this package fixes, because the spec leaves it open and §8’s polarity simulator needs one to interpret: outer contours run counter-clockwise, holes clockwise. This helper does not reorder; it is the callers that owe the convention.

Return type:

Contour

Parameters:

points (list[tuple[float, float]])

coord(value)[source]#

Format a millimeter value as a Gerber coordinate field (X, Y, I, J).

Return type:

str

Parameters:

value (float)

decimal(value)[source]#

Format a millimeter or degree value as a Gerber decimal.

Used for AD parameters, AM primitive parameters and XNC tool diameters, all of which take decimals rather than coordinate integers.

Return type:

str

Parameters:

value (float)

donut(outer, inner, attrs=())[source]#

An annular pad: a circle with a smaller centered round hole.

The hole is transparent, not clear - 4.4.6, “holes do not clear the objects under them” - so a donut pad over a same-net pour leaves the pour showing through the middle, which is the real copper.

Return type:

Aperture

Parameters:
emit_gerber(file, meta)[source]#

The complete text of one Gerber file, M02* included.

Return type:

str

Parameters:
emit_jobfile(job, meta)[source]#

The complete text of the .gbrjob file.

Return type:

str

Parameters:
emit_drill_gerber(file, meta)[source]#

The complete text of one drill file in Gerber format, M02* included.

Return type:

str

Parameters:
emit_xnc(file, meta)[source]#

The complete text of one XNC file, M30 included.

Raises:

XncError – the file needs more distinct tools than XNC can number.

Return type:

str

Parameters:
escape_field(value)[source]#

Escape a string for use as an attribute field.

Reserved characters and everything outside printable ASCII become uXXXX (or UXXXXXXXX above the BMP), so the whole file stays 7-bit printable ASCII and a user net name cannot break the syntax.

Return type:

str

Parameters:

value (str)

grid(value)[source]#

Snap a millimeter value to the nearest representable grid point.

Return type:

float

Parameters:

value (float)

legal_stem(name)[source]#

Scrub a design name into a filename stem.

Restricted to ASCII on purpose, and as a portability rule rather than a fab-specific one: upload forms and older CAM tooling are known to reject filenames they cannot read as plain English, so a design name with non-ASCII characters must not be able to reach one.

The dot goes with them, for the same reason rather than a cosmetic one. A design name is a dotted module path in practice, so keeping dots would put several of them in every filename, and an upload form that reads the extension off the first dot rather than the last then sees a file it has no idea what to do with.

Return type:

str

Parameters:

name (str)

macro_aperture(body, params, rotation, attrs=())[source]#

Instantiate a macro built from primitive lines.

rotation is appended as the last AD modifier, which is the $1 the primitives reference. None is a baked macro: its primitives reference no rotation and the AD carries none.

Return type:

Aperture

Parameters:
macros(apertures)[source]#

Every macro the apertures instantiate, deduplicated by content and ordered by generated name.

Return type:

list[Macro]

Parameters:

apertures (set[Aperture])

nm(value)[source]#

Quantize a millimeter value onto the 1 nm output grid.

Raises:

ValueError – the value is not finite.

Return type:

int

Parameters:

value (float)

obround_aperture(width, height, *, hole=None, attrs=())[source]#

O,<w>X<h>[X<hole>], axis-aligned; a capsule at 0 or 90 degrees.

Return type:

Aperture

Parameters:
outline_aperture(points, rotation, attrs=(), *, mirrored=False, baked=False)[source]#

A straight-edged outline in the aperture’s own frame.

Parameters:
  • points (Sequence[tuple[float, float]]) – the ring, in the unrotated aperture frame.

  • mirrored (bool) – mirror the vertex list across the Y axis. Mirroring cannot be an AD parameter the way rotation can, so it becomes different macro content - which is the normal case, since every bottom-side placement is mirrored.

  • baked (bool) – apply the rotation to the coordinates rather than pass it to the macro.

  • rotation (float)

  • attrs (AttrSet)

Return type:

Aperture

outlines_aperture(islands, rotation, attrs=(), *, label='outline', baked=False)[source]#

Straight-edged outlines with holes, in the aperture’s own frame.

Parameters:
Return type:

Aperture

polygon_aperture(diameter, vertices, rotation=0.0, *, hole=None, attrs=())[source]#

P,<outer>X<n>[X<rot>[X<hole>]], the only rotatable standard template.

Raises:

ApertureError – the vertex count is outside 3 to 12.

Return type:

Aperture

Parameters:
project_guid(name)[source]#

A stable GUID for a design name.

uuid5 gives determinism across reruns, but the spec requires an RFC 4122 version 1 or 4 GUID and a uuid5 carries a version 5 nibble, so the version and variant nibbles are forced to v4 afterwards.

Return type:

str

Parameters:

name (str)

rect_aperture(width, height, *, hole=None, attrs=())[source]#

R,<w>X<h>[X<hole>], axis-aligned.

Return type:

Aperture

Parameters:
resolve(functions, stem, scheme='descriptive')[source]#

Resolve a whole file set to filenames, parallel to functions.

A scheme that returns None for a file defers to descriptive, which is why descriptive must be total. Collision checking is deliberately not here: it belongs to the writer, which sees the archive name as well and is where a collision has to stop the run.

Return type:

list[str]

Parameters:
rotated_capsule(width, height, rotation, attrs=(), *, baked=False)[source]#

A capsule (obround) at an arbitrary angle, exact rather than linearized: a rectangular body between two end circles.

Parameters:
  • width (float) – length of the enclosing box along X.

  • height (float) – length along Y. The smaller dimension is the cap diameter.

  • baked (bool) – apply the rotation to the coordinates rather than pass it to the macro.

  • rotation (float)

  • attrs (AttrSet)

Return type:

Aperture

rotated_rect(width, height, rotation, attrs=(), *, baked=False)[source]#

A rectangle at an arbitrary angle.

Prefer rect_aperture at 0 or 90 degrees; the standard template is what every consumer handles best.

Parameters:
  • baked (bool) – apply the rotation to the coordinates rather than pass it to the macro.

  • width (float)

  • height (float)

  • rotation (float)

  • attrs (AttrSet)

Return type:

Aperture

rounded_rect(width, height, radius, rotation, attrs=(), *, baked=False)[source]#

A rectangle with round corners, exact: two overlapping center lines plus a circle at each corner. This is how the official sample_macro.gbr builds one, and it avoids linearizing a shape that has a closed form.

Parameters:
  • baked (bool) – apply the rotation to the coordinates rather than pass it to the macro.

  • width (float)

  • height (float)

  • radius (float)

  • rotation (float)

  • attrs (AttrSet)

Raises:

ApertureError – the radius does not fit in the rectangle.

Return type:

Aperture

scrub(contour)[source]#

Put a contour on the output grid and make it satisfy 4.10.3.

Snaps every coordinate, drops zero-length and collinear straight segments, turns sub-resolution arcs into straight segments, splits arcs over 180 degrees, and verifies the closure holds after rounding rather than before it.

Raises:

ContourError – nothing survives the scrubbing, or the contour does not close on the grid.

Return type:

Contour

Parameters:

contour (Contour)

signed_area(contour)[source]#

Twice the signed polygon area of a contour’s vertices, in mm².

Positive is counter-clockwise. Arc bulges are ignored, so this is for checking and fixing winding, not for measuring.

Return type:

float

Parameters:

contour (Contour)

validate(contour)[source]#

Check a scrubbed contour against 4.10.3.

Self-intersection is not checked here; it needs real geometry and the format layer carries no shapely dependency, so §8’s polarity layer owns it.

Raises:

ContourError – a zero-length segment, a collinear vertex or an open contour survived.

Return type:

None

Parameters:

contour (Contour)

is_archive(output)[source]#

Whether an output path asks for a zip rather than a directory.

The suffix is the whole switch. An output path is a destination the user named, so board.zip says what they want as plainly as a flag would and cannot disagree with one.

Return type:

bool

Parameters:

output (Path)

write_set(files, output, software, *, overwrite=False)[source]#

Write the file set to output and return the paths written.

Parameters:
  • output (Path) – a directory to write the files into, or a path ending in .zip, which writes exactly that archive with the files at its root - the layout fab upload forms expect - and nothing beside it. The archive is built from the content in memory, so it never contains itself.

  • software (GenerationSoftware) – the identity the guard looks for when deciding whether an existing file is a previous export of ours.

  • files (Sequence[OutputFile])

  • overwrite (bool)

Return type:

list[Path]

Returns:

One path per file for a directory, or the single archive path.

Raises:

OutputError – a name is not a plain filename, two files resolve to one name, a target exists without overwrite, or a target exists that does not look like our own output.

to_gerber(file)[source]#

The Gerber image of a drill file, hits first and then rout paths.

Object order follows emit_xnc so the two formats produce the same image in the same sequence and a golden test can compare them.

Return type:

GerberFile

Parameters:

file (DrillFile)

xnc_decimal(value)[source]#

Format a millimeter value for an XNC coordinate or tool diameter.

The value comes off the 1 nm grid, so a drill hit and the copper around it agree exactly. Trailing zeros are trimmed, but never the decimal point: XNC permits a bare integer (“zero therefore must be encoded as 0”, 2.6), and readers descended from legacy Excellon reject one, because in that format a coordinate without a decimal point needs a number format the file does not carry. Writing 30.0 rather than 30 is a decimal either way and costs nothing.

Return type:

str

Parameters:

value (float)

exception XncError[source]#

Bases: ValueError

A drill file cannot be expressed in XNC.

Submodules#