CAD Libraries

Gerbtrace can sync and parse external CAD libraries to build its built-in package database. This page covers the ingestion workflow, parser pipelines, and quality controls.

Overview

The CAD library pipeline:

1. Syncs curated external libraries into .local/libraries/
2. Parses footprint data into TPSys-compatible package definitions
3. Outputs JSON files under public/packages/libraries/ (SMD) and public/packages/tht-libraries/ (THT)
4. Generates manifests and reports for validation

Library ingestion

Syncing libraries

pnpm run libraries:sync

This downloads curated CAD libraries from the source registry into .local/libraries/. The source list is defined in scripts/cad-library-sources.json.

Optional flags:

• --include-large – include very large repositories
• --include-disabled – include sources marked disabled
• --dry-run – print planned actions without downloading

Source registry

Each source record in scripts/cad-library-sources.json includes:

• Repository URL
• License and redistribution policy
• Tool classification (KiCad, Eagle, LibrePCB)
• Toggle flags (enabled, large)
• Display name for the Package Manager UI

Current sources:

• Gerbtrace (Newmatik) – core package definitions
• KiCad – KiCad official footprint libraries
• DigiKey KiCad – DigiKey's KiCad library

Output structure

.local/libraries/
  <licenseBucket>/
    <owner>/
      <repo>/
  _index/
    sources-lock.json      # Sync timestamp, commit hashes, skip reasons

SMD parser pipeline

pnpm run libraries:parse

Script: scripts/parse-cad-libraries-to-tpsys.mjs

Adapters

Mapping policy

• Enforce runtime package types already supported by PackageDefinition
• Use PT_GENERIC fallback when geometry cannot be mapped confidently
• Never introduce custom package type identifiers
• Skip mechanical footprints and non-translatable components
• Record skip reasons and collisions in report files
• When exposed-pad variants (*EP*) are present, preserve outer lead geometry

Naming policy

Naming follows KLC-inspired conventions:

• <PKG>-<PINCOUNT>[-<SPECIAL>]_<FIELD>_<FIELD>...
• Family normalization: SO-* / SOP-* becomes SOIC-*
• Compact options: THERMAL-VIAS becomes THERMALVIAS

See Package Naming for the full specification.

Filtering

• Skip MOUNTING-HOLE footprints
• Drop -THERMAL-VIAS variants when the base package exists

Conflict resolution

• Canonical key: normalized package name (uppercase + separator normalization)
• Deduplicate globally across emitted libraries
• Seed global keys with Newmatik built-ins (including aliases)
• On same-name/different-geometry conflicts, keep first deterministic match and record conflict in report

THT parser pipeline

pnpm run libraries:parse:tht

Script: scripts/parse-cad-libraries-to-tht.mjs

KiCad THT adapter

Parses .kicad_mod through-hole pads and graphics:

• Pads – position, size, shape, drill diameter
• Body/detail graphics – fp_line, fp_rect, fp_circle on F.Fab/F.SilkS
• Output shapes – rect, roundedRect, circle, line

Mapping policy

• Convert through-hole pads into visual pin primitives preserving shape class
• Render drill as an inner dark circle for realism
• Preserve footprint body/detail from Fab/Silk primitives
• Add explicit polarity marker near pin 1

Output structure

SMD packages

public/packages/libraries/
  _tree.json               # Library tree manifest
  _reports/
    <library-id>.json      # Parse report (skipped, conflicts)
  <library-id>/
    library.json           # Attribution, license, provenance
    packages/*.json        # Package definition files

THT packages

public/packages/tht-libraries/
  _tree.json
  _reports/
    <library-id>.json
  <library-id>/
    library.json
    packages/*.json

Quality gates

# Regenerate SMD manifest
pnpm run packages:manifest

# Validate SMD library
pnpm run packages:check

# Regenerate THT manifest
pnpm run packages:tht:manifest

The check script validates:

• Manifest/tree consistency
• Per-library unique keys
• Global name/alias collision safety

Full workflow

# 1. Sync external libraries
pnpm run libraries:sync

# 2. Parse SMD packages
pnpm run libraries:parse
pnpm run packages:manifest
pnpm run packages:check

# 3. Parse THT packages
pnpm run libraries:parse:tht
pnpm run packages:tht:manifest

License hygiene

Using third-party library data in PCB designs is not the same as redistributing library collections. Before publishing derived libraries, verify each upstream license and keep attribution/share-alike obligations where required.

Each library's library.json captures the license, redistribution policy, and upstream attribution for traceability.