apertures module#

Aperture templates, macro construction, and D-code assignment.

A flash cannot rotate or mirror its aperture - LM/LR/LS exist but are poorly supported downstream - so the transform is carried by the aperture itself. Rotation is an AM parameter ($1) supplied by the AD, which is why one macro serves every rotation of a shape; mirroring changes the vertex list, so a mirrored shape is simply different macro content.

Everything built here flashes. A pad shape a macro cannot express exactly is composed from primitives or linearized, never turned into a region: 4.10 requires that all pads are flashed and all flashes are pads, so a G36 surface is not a pad as far as CAM is concerned whatever it looks like.

MAX_OUTLINE_VERTICES = 5000#

4.5.1.6’s per-primitive ceiling, counted as coordinate pairs minus one.

A macro may hold any number of primitives, so a shape needing more can be decomposed; nothing real should come close. Pours are not affected - a pour is a region, and regions carry no vertex limit, which is why 4.5.1.6 directs them there.

ROTATION = '$1'#

Every primitive takes the macro’s rotation argument, so a composition rotates as one shape about the flash point.

exception ApertureError[source]#

Bases: ValueError

A shape cannot be expressed as an aperture.

comment(text)[source]#

A code 0 primitive line.

Return type:

str

Parameters:

text (str)

circle(diameter, x=0.0, y=0.0, *, on=True, rotation='$1')[source]#

A code 1 circle primitive, rotated about the macro origin.

Return type:

str

Parameters:
center_line(width, height, x=0.0, y=0.0, *, on=True, rotation='$1')[source]#

A code 21 center line primitive: a rectangle about (x, y).

Return type:

str

Parameters:
vector_line(width, start, end, *, on=True, rotation='$1')[source]#

A code 20 vector line primitive: a stroke with square ends.

Return type:

str

Parameters:
outline(points, *, on=True, rotation='$1')[source]#

A code 4 outline primitive from a closed ring of straight segments.

The ring is closed here if the caller has not closed it. Straight segments only: a macro outline has no arc, which is the single real limit of the aperture system.

Raises:

ApertureError – fewer than three distinct points, or more vertices than 4.5.1.6 allows in one primitive.

Return type:

str

Parameters:
polygon(diameter, vertices, x=0.0, y=0.0, *, on=True, rotation='$1')[source]#

A code 5 regular polygon primitive.

Return type:

str

Parameters:
thermal(outer, inner, gap, x=0.0, y=0.0, *, rotation='$1')[source]#

A code 7 thermal primitive. It has no exposure parameter.

Return type:

str

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

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

Return type:

Aperture

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

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

Return type:

Aperture

Parameters:
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:
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:
BAKED = '0'#

The primitive rotation of a baked macro.

rotate(points, rotation)[source]#

Points rotated counterclockwise about the macro origin, in degrees, which is what a reader does with a macro’s rotation argument.

Return type:

list[tuple[float, float]]

Parameters:
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:
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

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

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

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

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

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:
regular_polygon_points(diameter, vertices)[source]#

The vertex ring of a regular polygon, for callers that need it as an outline rather than as the P template.

Return type:

list[tuple[float, float]]

Parameters:
aperture_key(aperture)[source]#

The sort key that fixes an aperture’s D-code.

Sorting rather than first-intern order is what keeps golden files stable under a design edit: with first-use numbering one added pad renumbers every aperture after it.

Return type:

tuple[str, str]

Parameters:

aperture (Aperture)

assign(apertures)[source]#

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

Return type:

dict[Aperture, int]

Parameters:

apertures (set[Aperture])

macros(apertures)[source]#

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

Return type:

list[Macro]

Parameters:

apertures (set[Aperture])