components module#

Components: the X3 component layers and the index every other layer needs.

Three jobs, split so that only the first of them needs a design.

The walk resolves every soldered component to a Placed record: where it sits, which way round it is, what its pins are and where its outline comes from. That is the only part that touches the design API.

The emission turns a Placed into §6.9’s component-layer objects - a ComponentMain flash carrying the .Cxxx characteristics, an outline drawn from the courtyard or the pad bounding box, and a ComponentPin flash at every pin with the key pin marked. Every aperture on these layers is mandated by 5.6.10 rather than chosen, which is precisely the kind of property worth testing without a design in the way.

The index is what the rest of the extract layer reads. TO.C belongs on component pads, on the soldermask openings and paste deposits of a component, and on legend objects that belong to one, and TO.P belongs on component pads - none of which is reachable without knowing which component owns a given design path. The index answers that two ways: an exact lookup for a pad, which also carries the pin identity, and a path-prefix lookup for anything else a component contains.

Pads: TypeAlias = 'list[tuple[Trace, Pad]]'#

A component’s pads in visit tree order, which is also pin order.

VALUE_LABEL = '>VALUE'#

The label placeholders silkscreen text carries through the runtime round trip, for an exporter to resolve against the component that owns them.

MAIN_DIAMETER = 0.3#

5.6.10 mandates %ADDnnC,0.300*% for ComponentMain in millimeters.

PIN_DIAMETER = 0.1#

5.6.10 mandates %ADDnnC,0.1*% for every pin that is not the key pin.

KEY_PIN_DIAMETER = 0.36#

5.6.10 mandates %ADDnnP,0.360X4X0.0*%, a diamond, for the key pin.

OUTLINE_WIDTH = 0.1#

5.6.10 mandates %ADDnnC,0.100*% for every ComponentOutline draw.

FOOTPRINT = 'Footprint'#

The two ComponentOutline types this exporter can source.

Courtyard comes from jitx.feature.Courtyard, which is documented as land pattern bounds and whose __post_init__ rejects polylines, so it is always closed. The bounding box of the pads is labeled Footprint and not Courtyard because that is what it is: an approximation from the copper, with no keep-out margin in it. Body and lead-to-lead outlines have no source in the design API and are not emitted.

SMD = 'SMD'#

The two .CMnt values a JITX design can distinguish.

Pressfit and Other are the rest of 5.6.16’s enumeration and have no source here: a pad with a cutout is through-hole and a pad without one is surface mount, which is the whole of what the design says.

main_aperture()[source]#

The mandated ComponentMain aperture.

Return type:

Aperture

pin_aperture(*, key)[source]#

The mandated ComponentPin aperture: a diamond for the key pin.

Return type:

Aperture

Parameters:

key (bool)

pin_attribute(refdes, number, function)[source]#

TO.P,<refdes>,<number>[,<function>], one spelling for both layers.

The optional third field is the pin function. It is emitted wherever the design knows it, on the component layer and on the copper layer alike, so the two cannot disagree about what a pin is.

Return type:

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

Parameters:
  • refdes (str)

  • number (str)

  • function (str | None)

outline_aperture(kind)[source]#

The mandated outline aperture, carrying its outline type.

Return type:

Aperture

Parameters:

kind (str)

class Pin(number, x, y, net, function=None)[source]#

Bases: object

One component pin, placed.

Parameters:
  • number (str) – the pin number, which 5.6.15 allows to be any name.

  • net (tuple[str, tuple[str, ...]]) – the TO.N attribute for the pin. .N is optional on a ComponentPin, but a component layer that names the net at every pin is the one a pick-and-place check can actually use.

  • function (str | None) – the pin function, when the design says what it is. 5.6.15 strongly recommends it alongside the number: it is less error-prone than a number and the redundancy is what catches a reversed diode or electrolytic.

  • x (float)

  • y (float)

number: str#
x: float#
y: float#
net: tuple[str, tuple[str, ...]]#
function: str | None = None#
attribute(refdes)[source]#

TO.P,<refdes>,<number>[,<function>].

Return type:

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

Parameters:

refdes (str)

ref(refdes, layer)[source]#

The copper-layer view of this pin.

The copper layer’s .P is derived from the component layer’s pin rather than resolved a second time, so the two files cannot describe one pin differently - which they could while the number and the function were looked up independently on each side.

Return type:

PinRef

Parameters:
class Outline(kind, contours)[source]#

Bases: object

A component outline and which of 5.6.10’s four types it is.

Parameters:
kind: str#
contours: tuple[Contour, ...]#
class Placed(refdes, side, x, y, rotation, mount, footprint, pins=(), outline=None, mpn=None, manufacturer=None, value=None)[source]#

Bases: object

One component, resolved to everything its component layer needs.

Parameters:
  • rotation (float) – the .CRot angle, already converted to the Gerber convention by rotation.

  • mount (str) – the .CMnt value, TH or SMD.

  • footprint (str) – the .CFtp land pattern name.

  • pins (tuple[Pin, ...]) – in pin order. The first is the key pin.

  • refdes (str)

  • side (Side)

  • x (float)

  • y (float)

  • outline (Outline | None)

  • mpn (str | None)

  • manufacturer (str | None)

  • value (str | None)

refdes: str#
side: Side#
x: float#
y: float#
rotation: float#
mount: str#
footprint: str#
pins: tuple[Pin, ...] = ()#
outline: Outline | None = None#
mpn: str | None = None#
manufacturer: str | None = None#
value: str | None = None#
identity()[source]#

TO.C,<refdes>, which every object of this component carries.

Return type:

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

characteristics()[source]#

The .Cxxx attributes of the ComponentMain flash.

.CHgt, .CPgN, .CPgD, .CLbN, .CLbD and .CSup are the rest of 5.6.16 and have no source in the design API, so they are omitted rather than guessed at. The others are only valid on ComponentMain - 5.6.16 says they are ignored elsewhere - so nothing else carries them.

Return type:

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

emit(file, part)[source]#

Write one component onto a component layer.

Order follows 6.9’s worked example: the main flash, then the outline, then the pins with the key pin first. .C goes on the flash and on every outline draw, which 5.6.14 requires and is what links an outline back to the component it belongs to.

Return type:

None

Parameters:
angle(value)[source]#

A .CRot decimal with no trailing zeros, since people read it.

Return type:

str

Parameters:

value (float)

rotation(placed)[source]#

The .CRot angle of a placement, in degrees CCW viewed from the top.

5.6.16 defines rotation zero for a top-side component as IPC-7351B’s, and for a bottom-side component by flipping that zero along the X axis, which is the scale S(1,-1). A JITX bottom placement is T * R(r) * S(-1,1) and S(-1,1) = R(180) * S(1,-1), so the same placement reads as T * R(r + 180) * S(1,-1) against the Gerber zero: a bottom component’s angle is its own rotation plus a half turn.

The mirror is read off the composed transform and nowhere else, which is the rule the whole extract layer follows: a bottom-side Placement already carries its mirror, so anything that applies a second side flip composes two mirrors into none.

Return type:

float

Parameters:

placed (Transform)

class PinRef(refdes, number, layer, function=None)[source]#

Bases: object

What a pad on a copper layer needs to name itself.

Parameters:
  • layer (int) – the absolute conductor index the component sits on. .P is restricted to component layers and the copper layers carrying the components, so the inner-layer rings of a through-hole pad must not carry it even though they are the same pad.

  • refdes (str)

  • number (str)

  • function (str | None)

refdes: str#
number: str#
layer: int#
function: str | None = None#
attribute()[source]#

TO.P,<refdes>,<number>[,<function>].

Return type:

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

class ComponentIndex(files=dict(), pins=dict(), owners=dict(), labels=dict())[source]#

Bases: object

The component layers, plus who owns what in the design tree.

Parameters:
  • files (dict[Side, GerberFile]) – one file per populated side.

  • pins (dict[str, PinRef]) – pad design path to the pin it is, for TO.P.

  • owners (dict[str, str]) – component design path to reference designator, for the TO.C that mask, paste and legend objects carry.

  • labels (dict[str, dict[str, str]])

files: dict[Side, GerberFile]#
pins: dict[str, PinRef]#
owners: dict[str, str]#
labels: dict[str, dict[str, str]]#
ordered()[source]#

The component files, top before bottom.

Return type:

list[GerberFile]

pin(path)[source]#

The pin identity of a pad, by its full design path.

Return type:

PinRef | None

Parameters:

path (str)

owner(path)[source]#

The reference designator of the component containing a path.

The longest matching component path wins, so a component nested in another attributes to the inner one.

Return type:

str | None

Parameters:

path (str)

labels_for(path)[source]#

The label substitutions for a feature at a design path.

Taken from the innermost component enclosing it, the same rule owner uses. Empty when no exported component owns the feature.

Return type:

dict[str, str]

Parameters:

path (str)

component_attribute(path)[source]#

TO.C for an object at a design path, when a component owns it.

Return type:

Optional[tuple[str, tuple[str, …]]]

Parameters:

path (str)

build(design, model, nets)[source]#

Walk the soldered components into component layers and the index.

Runs before the copper, feature and padstack walks: they attach TO.C and TO.P off the index it returns, so there is no order in which it can run beside them.

Return type:

ComponentIndex

Parameters:
pin_functions(comp)[source]#

Each pad’s pin function: the path of the port it is mapped to.

A pad maps to exactly one port while a port may map to several pads, so the pad side of the relation is a function and several pads can share one name - which is what a multi-pad ground looks like and is correct.

PadMapping already keeps the inverse, including the default mapping the runtime synthesizes when a component declares none, so nothing is computed here that the design does not already hold. The port paths come from a walk rooted at the component, so a bundle member reads as its own dotted path (VIN.Vp) rather than as the bundle.

Return type:

dict[Pad, str]

Parameters:

comp (Component)