orientation module#
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.
- CACHE_DIR = PosixPath('/home/runner/.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.
- class Point(label, x, y)[source]#
Bases:
objectOne pad, reduced to what the solver needs.
- Parameters:
- class Solution(angle, residual, symmetry, resolved_by, name_agreement, names_disagree, pads, mirrored_better=False, notes=())[source]#
Bases:
objectThe orientation correction for one part, with its provenance.
- Parameters:
angle (
float) – 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 (
float) – RMS pad mismatch in millimetres after applying the angle.symmetry (
int) – 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 (
str|None) – 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 (
float|None) – fraction of pads whose names agree under the chosen angle, or None when the two sides share no naming vocabulary.names_disagree (
bool) – the names contradict the geometry. The angle is still the geometric one; this is a flag to investigate, not a fallback.pads (
int) – pads on each side, which solve requires to be equal.mirrored_better (
bool) – the mirror of the EasyEDA cloud fits better than the cloud itself, which means the two are not the same footprint.notes (
tuple[str,...]) – anything a human should read before trusting the angle.
- fetch(lcsc, cache_dir=None, refresh=False)[source]#
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.
- easyeda_cloud(pads)[source]#
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.
- jitx_cloud(component)[source]#
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.
- Return type:
- Parameters:
component (Any)
- solve(jitx, easyeda)[source]#
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.
- Parameters:
- 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.
- Return type:
- orientation(lcsc, component, cache_dir=None, refresh=False)[source]#
The CPL orientation correction for a component ordered as an LCSC part.
- resolve(design, known)[source]#
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.