model module#

Data model for a Gerber X2/X3 fabrication data set.

Coordinates and sizes are millimeters; the emitters put them on the 1 nm grid (units). Rotations are degrees counter-clockwise, the Gerber convention. Object order within a file is the image order: a clear object erases everything emitted before it, so the order a caller builds is the order that reaches the file.

AttrSet: TypeAlias = 'tuple[Attribute, ...]'#

Attribute names (with their leading dot for standard names) and values.

A tuple rather than a mapping so it can take part in an aperture key. An empty value tuple emits a bare %TO.Name*%; a single empty string emits the reserved empty value %TO.N,*%.

attr(name, *values)[source]#

One attribute for an AttrSet.

Return type:

tuple[str, tuple[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)

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 Side(*values)[source]#

Bases: StrEnum

TOP = 'Top'#
INNER = 'Inr'#
BOTTOM = 'Bot'#
class CopperType(*values)[source]#

Bases: StrEnum

SIGNAL = 'Signal'#
PLANE = 'Plane'#
MIXED = 'Mixed'#
class HoleType(*values)[source]#

Bases: StrEnum

PTH = 'PTH'#
NPTH = 'NPTH'#
BLIND = 'Blind'#
BURIED = 'Buried'#
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 DrillContent(*values)[source]#

Bases: StrEnum

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

Bases: StrEnum

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

DARK = 'D'#
CLEAR = 'C'#
class FilePolarity(*values)[source]#

Bases: StrEnum

POSITIVE = 'Positive'#
NEGATIVE = 'Negative'#
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 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 Legend(side)[source]#

Bases: object

Legend,<side>.

Parameters:

side (Side)

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

str

class Paste(side)[source]#

Bases: object

Paste,<side>.

Parameters:

side (Side)

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

str

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 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 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 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 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.

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#
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 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 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 Seg(x, y)[source]#

Bases: object

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

Parameters:
x: float#
y: float#
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 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, ...]#
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 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 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 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 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 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 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, ...]], ...] = ()#
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 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 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.

render_attrs(attrs)[source]#

A stable text rendering of an attribute set, for sorting and keying.

Return type:

str

Parameters:

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