Guides

Package Library

Browse, search, and manage SMD and THT component packages for Pick and Place visualization.

Package Library

Gerbtrace includes a built-in library of component packages used to render footprints on the board canvas. The library supports both SMD (surface mount) and THT (through-hole) packages, with the ability to add custom team packages.

How packages are used

When PnP data is imported, Gerbtrace matches the CAD package name from each component against the library. Matched components render with accurate body outlines, pad geometry, and pin-1 markers. Unmatched components display a generic placeholder.

Built-in packages

Built-in packages are organized into libraries under public/packages/libraries/. Each library has:

  • A library.json with attribution, license, and provenance metadata
  • Individual package JSON files defining the geometry

Current built-in libraries include:

  • Gerbtrace (Newmatik) — core package definitions
  • KiCad — packages derived from the KiCad footprint libraries
  • DigiKey KiCad — packages from DigiKey's KiCad library

The runtime loads the library tree on demand, so only the packages you use are fetched.

Newmatik ERP library

Teams connected to the Newmatik ERP also get the Newmatik (ERP) library: every Approved and Deprecated Package Outline of the ERP, read when you open a project or the package manager and refreshed every 10 minutes. It is read-only; a Deprecated outline shows its replacement.

When a part matches several libraries, Gerbtrace uses, in this order: your local custom packages, team packages, the ERP library, the built-in libraries. An ERP outline with the same name as a built-in package also takes over that package's aliases, so R0603 draws the ERP's 0603. In a variant, a part whose ERP item links a Package Outline draws with that outline.

Gerbtrace hands an outline on with its TPSys package type (for example PT_TWO_POLE for a chip). When the parametric type would put pin 1 somewhere else than the ERP record, the outline is drawn from its lead groups (PT_GENERIC); its TPSys type still decides the PnP rotation convention, the polarity default, the SMT class and the pitch counts.

Package types

All packages use TPSys (Mycronic) package type classifications:

TypeDescriptionTypical packages
PT_TWO_POLETwo-terminal passivesChip resistors, capacitors, diodes
PT_THREE_POLEThree-terminal devicesSOT-23 family
PT_TWO_SYMDual-inline symmetricSOIC, SSOP, TSSOP, DFN
PT_FOUR_SYMQuad-flat symmetricQFP, QFN, LQFP
PT_TWO_PLUS_TWOAsymmetric quadDifferent lead counts per side pair
PT_FOUR_ON_TWOFour leads on two sidesDO-214AA and similar
PT_BGABall Grid ArrayBGA packages
PT_OUTLINEOutline onlyNo lead geometry
PT_GENERICGeneric with lead groupsNon-standard layouts

See Package Definitions for the complete technical reference.

Searching and matching

The package library supports search by name and alias. When you type a package name in the PnP panel, the search matches against:

  • Canonical package names (e.g., SOIC-8)
  • Aliases (e.g., SO-8, SO8, SOP-8 all resolve to SOIC-8)

The lookup normalizes input by stripping separators and converting to uppercase, so common variations are handled automatically.

Team packages (SMD)

Teams can create custom SMD packages that are shared across all team members:

  • Create a new package from the package manager
  • Edit package geometry and properties
  • Duplicate a built-in package as a starting point
  • Delete team packages that are no longer needed
  • Export packages as JSON or .pck (TPSys format)

BGA ball maps

A PT_BGA package is a grid of balls with an optional centred hole. For any other depopulated grid (empty rings, missing corners, single balls), name the missing balls under Missing balls in the package editor, as the datasheet's ball map names them: row letters from the top (A, B … skipping I, O, Q, S, X and Z, then AA, AB …), column numbers from the left. A range covers the rectangle between two balls: E5-E14 is part of row E, F5-N5 part of column 5, G8-G11 a block. You can also click balls on the ball map below the field to remove or restore them; the map shows how many balls are left.

Example: the Infineon XMC7100 in PG-LFBGA-272 is an 18 × 18 grid at 0.8 mm with Ø0.45 mm balls and the missing balls E5-E14, P5-P14, F5-N5, F14-N14, G8-G11, M8-M11, H7-L7, H12-L12, which leaves 272 balls. The .pck export writes one BGAB line per run of balls in a row (46 lines for this package) and imports back to the same ball map.

Team packages are stored in Supabase and available to all team members. Package names must be unique and cannot shadow built-in package names.

THT packages

THT (through-hole) packages use a separate visual system based on primitive shapes:

  • Rectangles — for IC bodies, connectors
  • Circles — for pins, mounting holes
  • Rounded rectangles — for rounded pads
  • Lines — for outlines and details

THT packages include:

  • Pin positions and shapes
  • Body graphics (from fabrication and silkscreen layers)
  • Drill hole indicators
  • Polarity markers near pin 1

Team THT packages

Like SMD packages, teams can create and share custom THT packages. The THT package editor provides a visual canvas where you can:

  • Add and position shape primitives
  • Customize colors for body, pins, and strokes
  • Preview the package in real time

Package preview

The package manager includes a preview pane that renders each package with its full geometry, showing body outline, pads/balls, and pin-1 highlighting. This helps verify that a package definition is correct before assigning it to components.

CAD package mapping

When PnP data uses non-standard package names, you can create a mapping from the CAD package name to a library package. These mappings persist with the project, so subsequent imports of the same file use the established mapping automatically. A package assigned to a DNP component, to a component whose CAD package is empty or a placeholder such as #N/A, or to one component with Only … (see SMD), is stored on that component only and creates no mapping.