"""Derive the CPL orientation correction for a part from its LCSC footprint.
JLCPCB takes a catalogue part's own footprint as its zero-degree orientation,
so the correction a design needs is the rotation that brings its landpattern
onto the EasyEDA footprint of the part being ordered. This module fetches
that footprint and measures the rotation.
Pad positions decide the angle. Pad names are consulted only when the
positions admit more than one answer, which is exactly when the pad cloud is
rotationally symmetric. See plans/jlcpcb-cpl-orientation-plan.md.
Fetching reaches the network, so nothing here runs unless a part needs an
orientation that neither the design nor the lock file already supplies.
"""
from __future__ import annotations
import json
import math
import os
from dataclasses import dataclass
from logging import getLogger
from pathlib import Path
from typing import TYPE_CHECKING, Any, Iterable, Sequence
import jitx.log
if TYPE_CHECKING:
from jitx.run import RuntimeDesign
logger = getLogger(__name__)
# EasyEDA copper layers that a part is picked and placed against: 1 is top
# copper, 11 is the multi-layer pseudo-layer that through-hole pads live on.
# A pad on neither is not visible from the top and says nothing about the
# orientation the machine places the part in.
TOP_LAYERS = frozenset({1, 11})
CACHE_DIR = Path(
os.environ.get("JLCPCB_EASYEDA_CACHE")
or Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
/ "jitxlib-jlcpcb"
/ "easyeda"
)
"""Where fetched footprints are kept.
An accelerator only. The lock file is what the export reads; this merely
keeps a re-run that adds one part off the network for the others.
"""
SNAP = 90.0
"""Measured angles are rounded to a multiple of this many degrees.
A landpattern and the catalogue footprint of the same part are rarely
dimensionally identical: pad sizes and positions differ a little, so the
fitted angle lands near a right angle rather than on it. C7593 fits at
89.372 degrees against a landpattern that is plainly a quarter turn from the
catalogue drawing. The fraction is measurement noise and recording it would
put a number in the lock file that looks more precise than it is.
"""
SNAP_TOLERANCE = 5.0
"""How far in degrees a measured angle may be from a multiple of `SNAP`.
A part measured further off than this is not a near miss of a right angle,
and needs an explicit orientation rather than a guess.
"""
TIE = 1.15
"""A runner-up scoring within this factor of the best is treated as a tie.
Symmetric packages produce genuinely equal fits, and floating point plus
EasyEDA's 4-decimal millimetres keep them from being bit-identical.
"""
[docs]
class OrientationError(Exception):
"""A part whose orientation cannot be resolved."""
[docs]
@dataclass(frozen=True)
class Point:
"""One pad, reduced to what the solver needs.
Args:
label: pin number as the source states it, or None when it has none.
x: millimetres, y-up frame, relative to the cloud's own centroid.
y: millimetres, y-up frame, relative to the cloud's own centroid.
"""
label: str | None
x: float
y: float
@property
def angle(self) -> float:
return math.atan2(self.y, self.x)
@property
def radius(self) -> float:
return math.hypot(self.x, self.y)
[docs]
@dataclass(frozen=True)
class Solution:
"""The orientation correction for one part, with its provenance.
Args:
angle: correction in counter-clockwise degrees, in [0, 360), rounded
to a multiple of `SNAP`. Add it to the placement rotation, which
is what `LCSCPart(orientation=...)` does. This is the inverse of
the rotation that fits the two pad clouds, not that rotation
itself.
residual: RMS pad mismatch in millimetres after applying the angle.
symmetry: how many rotations fit the pad positions equally well. 1 is
an unambiguous shape; n > 1 is an n-fold symmetric one, where the
positions alone cannot say which way round the part goes.
resolved_by: what chose among those rotations, "geometry" when there
was only one, "names" when pad names did, "pin-1" when only the
first-pad/pin-1 identity did, or None when nothing could.
name_agreement: fraction of pads whose names agree under the chosen
angle, or None when the two sides share no naming vocabulary.
names_disagree: the names contradict the geometry. The angle is still
the geometric one; this is a flag to investigate, not a fallback.
pads: pads on each side, which `solve` requires to be equal.
mirrored_better: the mirror of the EasyEDA cloud fits better than the
cloud itself, which means the two are not the same footprint.
notes: anything a human should read before trusting the angle.
"""
angle: float
residual: float
symmetry: int
resolved_by: str | None
name_agreement: float | None
names_disagree: bool
pads: int
mirrored_better: bool = False
notes: tuple[str, ...] = ()
@property
def ambiguous(self) -> bool:
"""Whether more than one rotation fits and nothing could choose."""
return self.symmetry > 1 and self.resolved_by is None
@property
def confident(self) -> bool:
"""Whether the fit is unambiguous and close enough to act on."""
return (
not self.ambiguous
and not self.mirrored_better
and not self.names_disagree
and self.residual < 0.15
)
[docs]
def report(self, name: str = "") -> str:
"""One human-readable block, for the script's own output."""
head = f"{name}: " if name else ""
lines = [
f"{head}orientation={self.angle:g} deg "
f"(residual={self.residual:.4f} mm over {self.pads} pads, "
f"{self.symmetry}-fold symmetric, "
f"resolved by {self.resolved_by or 'nothing'})"
]
if self.ambiguous:
lines.append(
f" ambiguous: {self.symmetry} rotations fit equally well "
"and neither pad names nor pin 1 could choose between them; "
"if the part is genuinely symmetric any of them is correct"
)
if self.names_disagree:
lines.append(
" pad names contradict the geometry: the two sides number "
"this part differently, which is worth understanding before "
"trusting either"
)
if self.mirrored_better:
lines.append(
" the mirrored footprint fits better; the JITX landpattern "
"and the catalogue part are probably not the same footprint"
)
lines.extend(f" {note}" for note in self.notes)
return "\n".join(lines)
# --------------------------------------------------------------------------
# EasyEDA side
# --------------------------------------------------------------------------
[docs]
def fetch(
lcsc: str, cache_dir: Path | None = None, refresh: bool = False
) -> list[dict[str, Any]]:
"""Fetch a part's EasyEDA footprint pads, caching the result on disk.
The cache is an accelerator only: it holds the pads as fetched and has no
bearing on the computed orientation, so a stale entry cannot change an
answer, only how long it takes.
Args:
lcsc: LCSC C-number.
cache_dir: where to keep fetched pads. Defaults to `CACHE_DIR`.
refresh: ignore any cached entry and refetch.
Raises:
OrientationError: the part has no CAD data, or easyeda2kicad is not
installed.
"""
cache_dir = CACHE_DIR if cache_dir is None else cache_dir
path = cache_dir / f"{lcsc}.json"
if not refresh and path.is_file():
return json.loads(path.read_text())["pads"]
try:
from easyeda2kicad.easyeda.easyeda_api import EasyedaApi
from easyeda2kicad.easyeda.easyeda_importer import EasyedaFootprintImporter
except ImportError as exc:
raise OrientationError(
"easyeda2kicad is required to look up footprints; pip install easyeda2kicad"
) from exc
data = EasyedaApi().get_cad_data_of_component(lcsc_id=lcsc)
if not data:
raise OrientationError(f"{lcsc} has no EasyEDA CAD data")
footprint = EasyedaFootprintImporter(easyeda_cp_cad_data=data).get_footprint()
# The bbox is the footprint origin and every consumer subtracts it; the
# importer leaves the pads in absolute canvas millimetres.
pads = [
{
"number": str(pad.number),
"x": pad.center_x - footprint.bbox.x,
"y": pad.center_y - footprint.bbox.y,
"layer": int(pad.layer_id),
"rotation": float(pad.rotation),
"width": float(pad.width),
"height": float(pad.height),
"hole_radius": float(pad.hole_radius),
}
for pad in footprint.pads
]
record = {"lcsc": lcsc, "name": footprint.info.name, "pads": pads}
cache_dir.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(record, indent=2))
return pads
[docs]
def easyeda_cloud(pads: Iterable[dict[str, Any]]) -> list[Point]:
"""Reduce EasyEDA pads to centroid-centred points in a y-up frame.
Pads on layers other than top copper and the through-hole pseudo-layer are
dropped: they are not what the part is placed against.
"""
# EasyEDA's y axis points down, as KiCad's does, and JITX's points up.
# This negation is a reflection rather than a sign convention, so getting
# it wrong yields a mirror image, not a small error. solve() scores the
# mirror as well so that a systematic mistake here is visible.
return _centre(
Point(label=_normalize(pad["number"]), x=float(pad["x"]), y=-float(pad["y"]))
for pad in pads
if int(pad["layer"]) in TOP_LAYERS
)
# --------------------------------------------------------------------------
# JITX side
# --------------------------------------------------------------------------
[docs]
def jitx_cloud(component: Any) -> list[Point]:
"""Reduce a JITX component's pads to centroid-centred points.
Order is `visit(component, Pad)` order, so the first element is the
component's first pad in the sense the orientation pass uses.
Raises:
OrientationError: the component has no pads, or a pad has no position.
"""
from jitx.inspect import visit
from jitx.landpattern import Pad
points: list[Point] = []
for trace, pad in visit(component, Pad):
# Trace.transform is documented as excluding the element's own
# transform, so the pad's placement has to be composed on explicitly;
# without it every pad collapses onto the landpattern origin.
transform = trace.transform
place = getattr(pad, "transform", None)
if transform is not None and place is not None:
transform = transform * place
elif transform is None:
transform = place
if transform is None:
raise OrientationError(f"pad {trace.path} has no position")
x, y = transform.translation[0], transform.translation[1]
points.append(Point(label=_path_label(trace.path), x=x, y=y))
if not points:
raise OrientationError("component has no pads")
return _centre(points)
def _path_label(path: Any) -> str | None:
"""A pad name reduced to a comparable form.
JITX pad names are arbitrary. Linear numbering gives `p[1]`, whose pin
number is the subscript; BGA-style `AlphaNumericNumbering` gives fields
named `A1`, `B12` and so on, whose name *is* the pin designation and must
survive whole. Reading a trailing number off `B12` would yield "12" and
silently discard the row, mapping every pad in column 12 onto one label.
So: a subscripted name yields its subscript, and any other name is taken
as written.
"""
text = str(path).strip()
text = text.rsplit(".", 1)[-1]
if text.endswith("]") and "[" in text:
text = text[text.rindex("[") + 1 : -1]
text = text.strip("'\" ")
return text.upper() or None
# --------------------------------------------------------------------------
# Solver
# --------------------------------------------------------------------------
[docs]
def solve(jitx: Sequence[Point], easyeda: Sequence[Point]) -> Solution:
"""Find the rotation that brings the JITX pads onto the EasyEDA pads.
Pad positions decide the angle. Pad names are consulted only when the
positions admit more than one answer, which happens exactly when the pad
cloud is rotationally symmetric, and are otherwise used only to check the
geometric answer rather than to override it.
Both clouds must already be centred on their own centroids, which
`jitx_cloud` and `easyeda_cloud` do.
Args:
jitx: the component's pads, in `visit` order.
easyeda: the catalogue footprint's pads.
Raises:
OrientationError: the clouds are empty, hold different numbers of
pads, the first JITX pad defines no angle, or the angle is not
close to a multiple of `SNAP`.
"""
if not jitx:
raise OrientationError("no JITX pads")
if not easyeda:
raise OrientationError("no EasyEDA pads")
if len(jitx) != len(easyeda):
raise OrientationError(
f"the landpattern has {len(jitx)} placed pads and the catalogue "
f"footprint has {len(easyeda)}, so they are not the same "
"footprint and no rotation relates them. A catalogue part with "
"one pad more is usually an exposed thermal pad; on a generated "
"landpattern add it with the ThermalPadGeneratorMixin, "
"`.thermal_pad(shape)`, which QFN, QFP, SON, SOP, SOT and SOIC "
"all carry"
)
tied = _candidates(jitx, easyeda)
symmetry = len(tied)
notes: list[str] = []
scored = [(angle, score, _agreement(jitx, easyeda, angle)) for angle, score in tied]
shared = any(agreement is not None for _, _, agreement in scored)
if symmetry == 1:
angle, residual, agreement = scored[0]
resolved_by = "geometry"
else:
# The positions cannot choose, so the names get their turn. This is
# the BGA case: a full ball grid is four-fold symmetric and only the
# A1 corner says which way round it goes.
named = [(a, r, g) for a, r, g in scored if g is not None]
top = max((g for _, _, g in named), default=0.0)
leaders = [row for row in named if row[2] == top]
if top > 0.0 and len(leaders) == 1:
angle, residual, agreement = leaders[0]
resolved_by = "names"
notes.append(
f"{symmetry} rotations fit the pad positions equally well; "
f"pad names chose between them, agreeing on "
f"{agreement:.0%} of pads"
)
else:
chosen = _pin_one(jitx, easyeda, scored)
if chosen is not None:
angle, residual, agreement = chosen
resolved_by = "pin-1"
notes.append(
f"{symmetry} rotations fit the pad positions equally "
"well; pad names could not choose, and the first pad "
"landing on pin 1 did"
)
else:
angle, residual, agreement = scored[0]
resolved_by = None
names_disagree = bool(symmetry == 1 and agreement is not None and agreement < 1.0)
if names_disagree:
notes.append(
f"pad names agree on only {agreement:.0%} of pads at the angle "
"the positions require"
)
if not shared:
notes.append(
"the two sides share no pad naming vocabulary, so names could "
"neither choose nor confirm"
)
mirrored = _candidates(jitx, _mirror(easyeda))
# The fit answers "what turns our landpattern onto their footprint". The
# CPL wants the part's orientation in JLCPCB's frame, where their
# footprint is zero, which is the inverse of that. Negating is the whole
# of the conversion, and getting it wrong is invisible on any part fitted
# near a quarter turn, where a negation and a half turn agree.
return Solution(
angle=_snap(-_degrees(angle)),
residual=residual,
symmetry=symmetry,
resolved_by=resolved_by,
name_agreement=agreement,
names_disagree=names_disagree,
pads=len(jitx),
mirrored_better=bool(mirrored) and mirrored[0][1] < residual * 0.5,
notes=tuple(notes),
)
[docs]
def orientation(
lcsc: str, component: Any, cache_dir: Path | None = None, refresh: bool = False
) -> Solution:
"""The CPL orientation correction for a component ordered as an LCSC part.
Args:
lcsc: LCSC C-number of the catalogue part.
component: the JITX component instance.
cache_dir: where fetched footprints are cached.
refresh: refetch the footprint rather than using the cache.
"""
return solve(jitx_cloud(component), easyeda_cloud(fetch(lcsc, cache_dir, refresh)))
def _candidates(
jitx: Sequence[Point], easyeda: Sequence[Point]
) -> list[tuple[float, float]]:
"""The rotations that fit the pad positions best, as (radians, residual).
Candidates are exactly the angles that put the first JITX pad onto some
EasyEDA pad, so an N-pad footprint has at most N of them and no search is
needed.
More than one is returned when several fit equally well, which is not a
failure of the fit but a property of the part: the returned count is the
order of the pad cloud's rotational symmetry. A chip resistor gives 2, a
square QFN with equal pads per side gives 4, a full ball grid gives 4, and
anything keyed or asymmetric gives 1.
Raises:
OrientationError: the first JITX pad sits on the centroid, so it
defines no angle.
"""
first = jitx[0]
if first.radius < 1e-9:
raise OrientationError(
"the first JITX pad sits on the landpattern centroid, so it "
"defines no angle"
)
# Distinct angles only. Two pads collinear with the centroid give the
# same rotation, and a grid has many such pairs, so without this a
# four-fold symmetric ball grid reports eight-fold and no rule can
# choose among duplicates of the same answer.
scored: list[tuple[float, float]] = []
seen: list[float] = []
for target in easyeda:
if target.radius < 1e-9:
continue
angle = (target.angle - first.angle) % (2 * math.pi)
if any(_same_angle(angle, other) for other in seen):
continue
seen.append(angle)
scored.append((angle, _rms(_rotate(jitx, angle), easyeda)))
if not scored:
raise OrientationError("every EasyEDA pad sits on the centroid")
scored.sort(key=lambda row: row[1])
floor = scored[0][1]
limit = max(floor * TIE, floor + 1e-6)
return [row for row in scored if row[1] <= limit]
def _same_angle(a: float, b: float) -> bool:
delta = abs(a - b) % (2 * math.pi)
return min(delta, 2 * math.pi - delta) < 1e-6
def _agreement(
jitx: Sequence[Point], easyeda: Sequence[Point], angle: float
) -> float | None:
"""Fraction of pads whose names agree once the JITX cloud is rotated.
Returns None when the two sides share no naming vocabulary at all, which
is the USB-C case: EasyEDA labels contacts `A1B12` and `A5` while the
landpattern calls them `p[1]`..`p[16]`, and no amount of agreement or
disagreement between those means anything.
Names are compared under the pairing the geometry induces, so this asks
"do the names corroborate this rotation" rather than "can the names be
made to correspond", which is the question that matters here.
"""
pairs = _pairing(_rotate(jitx, angle), easyeda)
named = [(a, b) for a, b in pairs if a.label is not None and b.label is not None]
if not named:
return None
# A vocabulary is shared only if both sides name the *same set* of pads.
# Mere overlap is not enough and is the trap this tool keeps walking
# into: a USB-C receptacle labels four shield posts "1".."4", which
# collide by spelling with a landpattern's p[1]..p[4] while meaning
# something entirely unrelated. An overlap test would read that as a
# vocabulary shared on four pads and then report 40% agreement, which
# looks like a contradiction rather than the absence of evidence it is.
ours = {a.label for a, _ in named}
theirs = {b.label for _, b in named}
if ours != theirs or len(named) != len(jitx):
return None
return sum(a.label == b.label for a, b in named) / len(named)
def _pin_one(
jitx: Sequence[Point],
easyeda: Sequence[Point],
scored: Sequence[tuple[float, float, float | None]],
) -> tuple[float, float, float | None] | None:
"""The tied rotation that lands the first JITX pad on pin 1.
The last resort, and it applies only when the catalogue footprint numbers
every pad numerically. A free-form scheme may well have a pad called "1"
that is not pin 1 at all: a USB-C receptacle numbers four shield posts
"1".."4" alongside contacts called "A5" and "A1B12", and matching the
component's first pad onto that "1" would seat the part against a
mounting post. Where the scheme is numeric throughout, "1" means pin 1.
Returns None when the rule does not apply, which leaves the part
ambiguous rather than failed: for a genuinely symmetric part any of the
tied rotations is correct.
Raises:
OrientationError: the rule applies but the rotation it asks for is
not one that fits the pad positions.
"""
if not all(p.label is not None and p.label.isdigit() for p in easyeda):
return None
ones = [p for p in easyeda if p.label == "1"]
if len(ones) != 1 or ones[0].radius < 1e-9:
return None
wanted = (ones[0].angle - jitx[0].angle) % (2 * math.pi)
for row in scored:
if _same_angle(row[0], wanted):
return row
# Deliberately not falling through to the next tied rotation. If pin 1
# does not land where the geometry allows, the premise that the
# component's first pad is the catalogue part's pin 1 is false, and every
# later pad rests on that same premise. Trying pin 2 would be guessing
# with the one piece of evidence already known to be wrong.
raise OrientationError(
"the catalogue footprint numbers its pads numerically, but the "
f"rotation putting the component's first pad on pin 1 "
f"({_degrees(wanted):g} deg) is not among the {len(scored)} that fit "
"the pad positions. The landpattern's first pad and the catalogue "
"part's pin 1 are not the same contact, so no rotation follows from "
"them; give the part an explicit LCSCPart(orientation=...)"
)
def _pairing(
points: Sequence[Point], targets: Sequence[Point]
) -> list[tuple[Point, Point]]:
"""Each point with its nearest unclaimed target, greedily."""
remaining = list(targets)
pairs: list[tuple[Point, Point]] = []
for point in points:
if not remaining:
break
best = min(range(len(remaining)), key=lambda i: _sq(point, remaining[i]))
pairs.append((point, remaining.pop(best)))
return pairs
def _rotate(points: Sequence[Point], angle: float) -> list[Point]:
cos, sin = math.cos(angle), math.sin(angle)
return [
Point(label=p.label, x=p.x * cos - p.y * sin, y=p.x * sin + p.y * cos)
for p in points
]
def _rms(points: Sequence[Point], targets: Sequence[Point]) -> float:
"""RMS distance from each point to its nearest unclaimed target.
Greedy rather than optimal assignment: these clouds either agree closely
or not at all, so the assignment is not where the answer lives, and an
optimal one would cost a dependency for no change in verdict.
"""
if not points or not targets:
return math.inf
remaining = list(targets)
total = 0.0
for point in points:
if not remaining:
# Unreachable via solve(), which rejects clouds of differing size.
# Kept so that a direct caller gets a bad score rather than a
# flatteringly good one from leaving pads unpaired.
total += max(t.radius for t in targets) ** 2
continue
best = min(range(len(remaining)), key=lambda i: _sq(point, remaining[i]))
total += _sq(point, remaining[best])
remaining.pop(best)
return math.sqrt(total / len(points))
def _sq(a: Point, b: Point) -> float:
return (a.x - b.x) ** 2 + (a.y - b.y) ** 2
def _mirror(points: Sequence[Point]) -> list[Point]:
return [Point(label=p.label, x=p.x, y=-p.y) for p in points]
def _centre(points: Iterable[Point]) -> list[Point]:
"""Shift a cloud onto its own centroid.
Rotation is solved about the centroid rather than about either origin,
since the two frames need not share an origin. `solve` rejects clouds of
differing size, so the two centroids are the same point of the same pad
set and this is an exact common frame, not an approximate one.
"""
collected = list(points)
if not collected:
return collected
cx = sum(p.x for p in collected) / len(collected)
cy = sum(p.y for p in collected) / len(collected)
return [Point(label=p.label, x=p.x - cx, y=p.y - cy) for p in collected]
def _normalize(number: str) -> str | None:
"""An EasyEDA pad number reduced to a comparable form.
EasyEDA pad numbers are free-form strings: a USB-C receptacle numbers its
contacts "A1B12", "A5" and so on, so this cannot assume integers.
"""
text = str(number).strip().upper()
return text or None
def _snap(degrees: float) -> float:
"""Round a measured angle to the nearest `SNAP` degrees.
Raises:
OrientationError: the angle is more than `SNAP_TOLERANCE` from a
multiple of `SNAP`.
"""
snapped = round(degrees / SNAP) * SNAP
if abs(degrees - snapped) > SNAP_TOLERANCE:
raise OrientationError(
f"the measured orientation of {degrees % 360.0:g} deg is more than "
f"{SNAP_TOLERANCE:g} deg from a multiple of {SNAP:g}; give the "
"part an explicit LCSCPart(orientation=...)"
)
return snapped % 360.0
def _degrees(radians: float) -> float:
return round(math.degrees(radians), 4) % 360.0
[docs]
def resolve(design: "RuntimeDesign", known: Iterable[str]) -> dict[str, float]:
"""Measure the orientation of every catalogue part that lacks one.
Walks the design's components, and for each that names an LCSC part
whose orientation is neither stated in the design nor already recorded in
`known`, fetches the catalogue footprint and measures the rotation.
A part that cannot be resolved is logged and omitted from the result
rather than recorded as zero, so that a later run retries it instead of
inheriting a guess.
Args:
design: the captured design to walk.
known: C-numbers whose orientation is already settled.
Returns:
Newly measured orientations, keyed by C-number. Only parts that were
missing and could be measured appear.
"""
from jitx.component import Component
from jitx.inspect import decompose
from ..part import LCSCPart
settled = set(known)
pending: dict[str, Any] = {}
for _, comp in design.query(Component):
if comp.soldered is False:
continue
for part in decompose(comp, LCSCPart):
if part.orientation is not None or part.partnumber in settled:
continue
pending.setdefault(part.partnumber, comp)
found: dict[str, float] = {}
for partnumber, comp in sorted(pending.items()):
try:
solution = orientation(partnumber, comp)
except OrientationError as exc:
logger.warning(
"Could not determine the orientation of %s: %s", partnumber, exc
)
continue
if solution.ambiguous:
logger.warning(
"%s is %d-fold symmetric and nothing could say which way "
"round it goes; leaving it unrecorded so it is measured "
"again rather than guessed once",
partnumber,
solution.symmetry,
)
continue
if solution.mirrored_better:
logger.warning(
"%s fits its catalogue footprint better mirrored, so the "
"landpattern and the catalogue part are probably not the "
"same footprint; leaving it unrecorded",
partnumber,
)
continue
found[partnumber] = solution.angle
jitx.log.notice(
logger,
"Measured %s at %g degrees (%s, residual %.3f mm)",
partnumber,
solution.angle,
solution.resolved_by,
solution.residual,
)
return found