Source code for jitxlib.jlcpcb.export.orientation

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