soldermaskdocs

KiCad and 3D models

Every version gets a KiCad board and schematic you can open and change. Its parts are drawn from the vendor's own 3D models.

Gerbers carry copper, not intent. The KiCad files are how a person carries on from where the pipeline stopped.

The KiCad board

kicad.py writes <board>.kicad_pcb in KiCad 7's format, which KiCad 7, 8, 9 and 10 all read.

The file carriesDetails
LayersThe layer table, with In1.Cu and In2.Cu on a four-layer board
NetsThe net table, and the net on every pad
FootprintsOne per part, with its LCSC code, manufacturer and purpose as properties
OutlinesFab, silkscreen and courtyard drawings, and the board edge
HolesEach non-plated hole. A hole of no part, such as a mounting hole, is a soldermask:NPTH footprint left out of the BOM and CPL.
CopperEvery track, arc and via, once routed
PoursThe ground zones, and power zones where a power pour was asked for. A pad the fill reaches by one spoke is joined to it solid.
Rule areasEach area KiCad's DRC must keep copper out of (below)

The IDs in the file are deterministic, so two runs of one board can be diffed.

The rules are in the project file. A .kicad_pro beside the board carries the clearance, track, via, hole and copper-to-edge rules it was routed at. So KiCad's DRC judges the board by its own rules.

A track floor you set (constraints.rules.min_track_mm) becomes the net class's track width. The DRC's hard minimum stays at the fab's 0.127 mm, so KiCad does not fail a narrower track. See Track widths.

The pour arrives unfilled

Zones are written without their fill. kicad-cli fills them before every DRC. A command-line build with KiCad also saves the fill into the board in --out. In KiCad, press B to fill a saved version's zones.

Other parts of the file:

  • A part on the back is written on the B.* layers, mirrored the way KiCad stores a flipped footprint. Its reference reads from the back.
  • A pad the vendor draws as a polygon is a KiCad custom pad, anchored at a point inside it.
  • A board imported from a KiCad file keeps its own outline, holes, copper and mask artwork.

The frame is checked. The pipeline uses millimetres with y up, and KiCad uses y down. kicad.verify() reads back the file it just wrote, applies KiCad's rotation to every pad, and compares each pad centre with the placement to 0.1 µm.

A second reader

When the optional kiutils library is installed, it also parses the file. Without it the check still passes, and its line ends kiutils not installed -- not independently parsed.

Four copper layers

A four-layer board (--layers 4, or constraints.board.layers) adds two inner layers:

LayerCarries
F.CuSignals, with ground poured round them
In1.CuA solid sheet of ground
In2.CuSignals, with ground poured round them
B.CuSignals, with ground poured round them

SOLDERMASK_PLANES=gnd+power makes In2.Cu a solid sheet of the power rail with the most pins. Every via runs through all four layers.

Rule areas

A rule area holds KiCad's DRC, and a person's later edit, to what the router kept clear.

Rule areaKeeps out
An antenna keepoutTracks, vias and pour, on every copper layer
A connector's bodyTracks and vias on the side it is mounted on. Only the part's own ground may pour there.
An area the design asks to keep clear (constraints.keepouts)Tracks, vias, pads and pour, on every copper layer
A mounting holeEverything but the hole, round it, on every copper layer
A rule area of an imported boardTracks or vias, as the file's own area forbids them

The KiCad schematic

kicad_sch.py writes <board>.kicad_sch beside the board, in KiCad 7's format. It draws the same sheet the workbench shows, from the layout sheet.py makes, so KiCad opens the drawing you saw.

The sheet carriesDetails
SymbolsKiCad's library symbol for each part, embedded in the file
FieldsReference, Value and Footprint, with the LCSC code, manufacturer and purpose hidden
PowerA power symbol named for each supply net
SignalsWires and junctions where the sheet drew them, and local labels elsewhere
Unused pinsA no_connect on each pin with no net
Power flagsA PWR_FLAG on each supply net that no power-output pin drives

Then it is read back. kicad_sch.connectivity() traces the sheet the way KiCad does and compares it with the board, net for net. A mismatch is a gap on the version. With kicad-cli installed, a command-line build also exports KiCad's own netlist from the file, compares it net for net, and runs KiCad's ERC.

What the file does not carry:

  • A hierarchy. It is one sheet.
  • Footprint libraries. The footprints are named, not shipped.
  • A drawing for a part the symbol library lacks. That part draws as a box with its pin names.

A pad with no pin

A SOT-223 regulator's tab is a pad the library's three-pin symbol has no pin for. The check reports it, for example U1 pad 4 (+3V3) has no pin in its drawing and is not on the sheet. It is true of the board, not a drawing fault.

Vendor 3D models

EasyEDA publishes a 3D model for every part LCSC sells, keyed by the LCSC code the parts stage chose. models3d.py fetches it, cleans it up and places it:

  1. It reads the model's ID and offset from the vendor footprint.
  2. It fetches the model, an OBJ with its materials written inline.
  3. It welds and quantises the mesh.
  4. It centres the model on the footprint, with the part's bottom on the board.
  5. It turns the model to match the footprint (below).
  6. It caches the result in .cache/models3d.

A model the vendor does not have is cached as missing, so a build does not ask again. A fetch that timed out is not cached, so the next build tries again. A model over 40,000 triangles is left out of the 3D view, which draws the part from its package outline. KiCad still gets the model.

One mesh feeds the 3D view and KiCad:

FileUsed by
meshes.jsonThe 3D view, in the app and in the standalone export. One mesh per LCSC code.
models/<lcsc>.wrlKiCad, as VRML built from the same mesh
models/<lcsc>.stepKiCad, on a command-line build without --project, where the vendor has a STEP

The footprints in the .kicad_pcb point at ${KIPRJMOD}/models/. That path works when a person opens the board and when kicad-cli renders it.

Orientation is measured. A vendor model is often drawn turned from the pipeline's footprint. The model's feet, its lowest quarter-millimetre, are turned four ways and scored on how much lands on the pads. The best turn is baked into the model.

  • If two turns score the same, the vendor's own pads break the tie.
  • A body that opens one way, like a connector's mouth, must open the way the footprint does. It decides between a turn and its half turn when the two score the same.
  • If no turn lands the feet on the pads, the footprint alone sets the turn. A note says to check the 3D view.
  • If under 40% of the feet land at the best turn, they are likely a shell or a standoff. A body that opens one way then sets the turn, and a note says so.
  • If the feet fit one way and the body opens another, the feet win. A note says to check the datasheet.
  • If the vendor's pads share no names with the footprint, a note says the orientation could not be checked.
  • If the vendor's pads sit more than 0.35 mm off even at their best angle, the note says check it against the datasheet.

A model that stands more than 0.5 mm outside the space its footprint keeps gets a note. Check what sits next to that part before ordering.

A model on the back is turned half a turn more, so it sits on its own pads.

What this is not

Vendor and community geometry, not verified CAD. Good enough to see that a connector faces the wrong way. Not good enough to check a mechanical fit.

With KiCad installed

kicadcli.py looks for kicad-cli on the path, in Homebrew, and in /Applications/KiCad/KiCad.app. It uses one only after running it.

Every routed build needs KiCad's DRC. The build runs it on the copper, in the app and on the command line. The verdict counts its copper errors.

StepRuns onWhat it gives
DRCEvery routed buildKiCad's design rule check of the copper. The command line prints drc n errors, m warnings.
RenderThe command line<board>-3d.png, a raytraced picture of the board
GLBThe command line<board>.glb, a 3D export. The command line's inspector.html shows it in place of the meshes.
SchematicThe command lineKiCad's netlist of the .kicad_sch, compared net for net, and KiCad's ERC
Gerber cross-checkThe command lineKiCad's own Gerber plot, compared layer by layer with the pipeline's to 0.012 mm

Without KiCad, a routed board is not judged

The verdict needs KiCad's DRC of the copper. Without kicad-cli, a routed board comes back NOT JUDGED, never passed. The gaps say no DRC judged its copper. Ground is routed as tracks, since only kicad-cli can fill a pour.

KiCad is 1.3 GB and cannot be installed with pip. A command-line build without it says so: kicad-cli not installed -- no DRC, render or GLB (brew install --cask kicad).

--no-render skips the render and the GLB. The DRC still runs.

On this page