Package Definitions

All component package definitions in Gerbtrace follow the Mycronic/TPSys baseline. This document covers the package type system, JSON format, coordinate conventions, and orientation rules.

Package type discriminators

Every package JSON has a "type" field using the official TPSys technical name:

The label map is defined in app/utils/package-types.ts as PACKAGE_TYPE_LABELS.

Only TPSys package types are allowed. Custom types must not be introduced. If a package cannot be represented by the simplified parametric models, use PT_GENERIC with explicit lead-group data.

Coordinate system

All geometry is in millimeters, centered at the component origin:

        +Y (up)
         |
         |
  -------+-------> +X (right)
         |
         |

• +X right, -X left
• +Y up, -Y down
• Component center at (0, 0)

Orientation: What "0 degrees" means

All packages are defined in Mycronic/TPSys 0-degree orientation. The Pick and Place convention selector (Mycronic / IPC-7351 / IEC 61188-7) only changes how imported PnP rotations are interpreted and displayed. It does not modify the package definitions.

PT_TWO_POLE (Chip, two-terminal)

At Mycronic 0 degrees:

• Body is vertical (length along Y)
• Pad 1 is at the top (+Y)
• Pad 2 is at the bottom (-Y)

        +Y
         ^
         |   pad1 (1)
         |   +------+
         |   +------+
         |   +------+
         |   | BODY |
         |   +------+
         |   +------+
         |   +------+
         |   pad2 (2)
         +-----------> +X

Pad 1 (top) is rendered in red.

Molded diode families (DO-214/DO-213/DO-219/DO-221 and similar)

For molded diode packages with formed terminals, do not model them as PT_TWO_POLE unless the package is truly chip-style.

Use PT_GENERIC with explicit lead groups and the correct lead shape:

• Use J_LEAD for J-lead style molded packages.
• Keep terminal width (padWidth) based on lead/terminal band dimensions (b), not body width.
• Keep terminal length (padLength) based on lead length (L) / wrapped-foot geometry.
• Keep package orientation in Mycronic/TPSys baseline; pin 1 marker should remain upper-left in the rendered 0-degree baseline.

This avoids rendering diodes as full-height chip end caps when the real package has narrower formed terminals.

Multi-pin packages (3+ pins)

At Mycronic 0 degrees:

• Pin 1 / A1 is at the upper-left (-X, +Y)
• Pin numbering proceeds counter-clockwise around the package

This applies to PT_THREE_POLE, PT_TWO_SYM, PT_FOUR_SYM, and PT_BGA.

PnP convention selector

Different PnP sources use different rotation directions and 0-degree reference orientations. Gerbtrace converts imported rotations into a single renderer angle:

rotationCCW = direction * pnpRotation + offsetDeg

Rotation direction

Offsets

Offsets are package-type specific and are configured in app/utils/pnp-conventions.ts (PNP_CONVENTIONS[convention].offsetDegByType). This is the authoritative source for convention-specific rotation adjustments.

JSON format

Each JSON file defines one package:

{
  "name": "SOIC8",
  "type": "PT_TWO_SYM",
  "aliases": ["SO-8", "SOIC-8"],
  "body": { "length": 4.9, "width": 3.9 },
  "twoSymmetric": {
    "numberOfLeads": 8,
    "widthOverLeads": 6,
    "leadPitch": 1.27,
    "leadWidth": 0.4,
    "leadLength": 0.6
  }
}

Key rules:

• All dimensions are in millimeters
• name and aliases are used to match PnP package names
• The pin-1 marker is generated in code, not stored in JSON
• type must be one of the TPSys names listed above

Library tree layout

Built-in packages are organized under public/packages/libraries/:

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

Each library.json stores attribution and provenance: display name, source type, owner, license, redistribution policy, upstream repo URL, and notice text.

Adding packages

To add a new built-in package:

1. Create a new JSON file in public/packages/libraries/newmatik/packages/.
2. Regenerate manifests: pnpm run packages:manifest.
3. Validate: pnpm run packages:check.
4. Ensure the geometry corresponds to Mycronic/TPSys 0-degree orientation.
5. Add enough aliases to match common CAD/PnP package names (KiCad and Eagle often differ).

Related reference

• Package Naming — canonical naming rules for package libraries
• TPSys Format — deep reference for the TPSys pck.pck database format