Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@tracespace/parser

tracespace10.7kMIT5.0.0-next.0TypeScript support: included

Gerber and NC drill file parser

gerber, excellon, pcb, circuit, hardware, electronics

readme

tracespace

ci badge code coverage badge license badge chat badge

PCB visualization tools for Node.js and the browser

tracespace is an open-source collection of tools to make looking at circuit boards on the internet easier.

v5 checklist

This is the branch for tracespace v5, which is still very much in development.

  • <input checked="" disabled="" type="checkbox"> Written in TypeScript
  • @tracespace/parser package to generate unist abstract syntax trees
    • <input checked="" disabled="" type="checkbox"> Parses Gerber files
    • <input checked="" disabled="" type="checkbox"> Parses drill files
    • <input checked="" disabled="" type="checkbox"> Syncronous by default but streaming compatible
    • <input checked="" disabled="" type="checkbox"> Fully covered by tests
    • <input checked="" disabled="" type="checkbox"> In-code documentation
  • @tracespace/plotter package to take a board's collection of Gerber ASTs and generate image description trees
    • <input disabled="" type="checkbox"> Can plot any Gerber file
    • <input disabled="" type="checkbox"> Can plot any drill file
    • <input disabled="" type="checkbox"> Infers coordinate format settings using the full context of all layers
    • <input disabled="" type="checkbox"> Infers board outline
    • <input disabled="" type="checkbox"> Fully covered by tests
    • <input disabled="" type="checkbox"> In-code documentation
  • @tracespace/renderer package to output hast ASTs of the SVG translation of the image trees
    • <input disabled="" type="checkbox"> Renders individual layer views
    • <input disabled="" type="checkbox"> Renders board views
    • <input disabled="" type="checkbox"> Covered by tests
    • <input disabled="" type="checkbox"> In-code documentation
  • <input disabled="" type="checkbox"> tracespace CLI powered by new libraries
  • <input disabled="" type="checkbox"> tracespace view powered by new libraries
  • <input disabled="" type="checkbox"> documentation website

issues

The v5 release will attempt to fix / address the following open issues:

  • <input disabled="" type="checkbox"> Handle disagreements between filename type vs parsed type (#49)
  • <input disabled="" type="checkbox"> Reduce number of <use> tags in SVG output (#80)
  • <input disabled="" type="checkbox"> Arc plotting should be more lenient (#82)
  • <input disabled="" type="checkbox"> Operation with non-existent tool should no-op with a warning (#83)
  • <input checked="" disabled="" type="checkbox"> Fails to detect units if format spec combined with units spec (#234)
  • <input disabled="" type="checkbox"> clipPath for outline breaks in Firefox if outline has clear layers (#302)
  • <input checked="" disabled="" type="checkbox"> gerberParser.parseSync clobbers filetype option (#306)
  • <input checked="" disabled="" type="checkbox"> Gerber file starting with newline incorrectly identified as drill file (#307)
  • <input disabled="" type="checkbox"> Generate consistent document size for all layers. (#324)

examples

Renders of the Arduino Uno produced by tracespace:

arduino uno top arduino uno bottom

Arduino Uno design files used under the terms of the Creative Commons Attribution Share-Alike license.

<summary>Individual layers</summary>

top copper

drill hits

outline

top silkscreen

bottom copper

top soldermask

bottom soldermask

tracespace in the wild

  • tracespace.io/view - A Gerber viewer powered by the tracespace libraries
  • kitspace.org - An electronics project sharing site with links to easily buy the required parts
  • OpenHardware.io - A social site around open source hardware. Enables authors to sell and manufacture their boards.

apps and libraries

package description
@tracespace/view Probably the best Gerber viewer on the internet https://tracespace.io/view
@tracespace/cli Render PCBs as SVGs from the comfort of your own terminal cli npm badge cli deps badge
@tracespace/parser Gerber and drill file parser parser npm badge parser deps badge parser size badge
@tracespace/xml-id XML ID generation and sanitation utilities xml-id npm badge xml-id deps badge xml-id size badge
whats-that-gerber Identify Gerber and drill files by filename wtg npm badge wtg deps badge wtg size badge

contributing

We could use your help maintaining and growing the tracespace ecosystem! Issues and pull requests are greatly appreciated.

development setup

The tracespace tools live here in this monorepo. We use yarn and lerna to manage this setup.

Node v10 or later is required for development, but v12 is recommended.

# clone repository and install dependencies
git clone git@github.com:tracespace/tracespace.git
cd tracespace
yarn install

This repository adheres to the Conventional Changelog commit specification for automatic changelog generation. We recommend installing commitizen to ensure your commit messages are properly formatted:

yarn global add commitizen

# later, when you're ready to commit
git add some/files/*
git cz

All development scripts below should be run from the root of the repository. Lerna handles delegating scripts downwards to the individual projects as necessary.

tests

# run unit tests tests with coverage
yarn test

# run unit tests in watch mode (no coverage)
yarn test:watch

development servers

pcb-stackup, pcb-stackup-core, gerber-to-svg, and @tracespace/view have development servers. The first three serve a set of reference renders for manual visual inspection, and the @tracespace/view development server builds and serves the web-app locally.

# run all dev servers
yarn start

# run server for a specific project
yarn start --scope @tracespace/view

production assets

There are two production asset types that you can build:

  • Full web-app bundles
    • @tracespace/view
  • Standalone library bundles
    • @tracespace/cli
    • @tracespace/xml-id
    • whats-that-gerber

To build them:

# build production ESM bundles, UMD bundles, app bundles, and type definitions
yarn build

# build:all
# runs yarn build and also builds example files and documentation
yarn build:all

# build all bundles and serve them for testing/validation
yarn serve

# as with the dev server, these commands may be scoped by name
yarn serve --scope @tracespace/view

linting and formatting

# format the code for styling
yarn format

# lint the code for potential errors
yarn lint

# typecheck any typescript code
yarn types

publishing

Packages are published to npm by the CI server. To publish a release, you must have write access to the repository. There is a bump script in the package.json that will:

  • Run all tests
  • Write new version to package.json in updated packages
  • Generate / update the changelogs
  • Commit, tag, and push to git

First, checkout and pull down the latest commits on main:

git checkout main
get pull origin main

Then, bump the version:

# by default, bump to the next version as determined by conventional commits
yarn bump

# you may specify a bump level or exact version
# prerelease bumps will be prefixed with "next", e.g. 4.0.0 -> 4.0.1-next.0
# https://github.com/lerna/lerna/tree/master/commands/version#readme
yarn bump ${major|minor|patch|premajor|preminor|prepatch|prerelease}
yarn bump v42.0.0

# to do a "dry run", you can stop before commit and tag
yarn bump --no-git-tag-version

After you bump, push the commit and tag:

git push origin main --follow-tags

The release will be published to the latest npm tag for bare versions (e.g. 4.0.0) and to next for pre-release versions (e.g. 4.0.0-next.0).

changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

5.0.0-next.0 (2020-06-28)

Features

  • parser: add @tracespace/parser package (#338) (6f974dd)