Gerbolyze high-fidelity SVG/PNG/JPG to PCB converter

.. note::

The command-line usage and SVG template format of gerbolyze changed between v2.0 and v3.0. You can find details on
the new format below under command_line_usage_

Gerbolyze renders SVG vector and PNG/JPG raster images into existing gerber PCB manufacturing files. Vector data from SVG files is rendered losslessly without an intermediate rasterization/revectorization step. Still, gerbolyze supports (almost) the full SVG 1.1 spec including complex, self-intersecting paths with holes, patterns, dashes and transformations.

Raster images can either be vectorized through contour tracing (like gerbolyze v1.0 did) or they can be embedded using high-resolution grayscale emulation while (mostly) guaranteeing trace/space design rules.

Try gerbolyze online at https://dyna.kokoroyukuma.de/gerboweb

.. figure:: pics/pcbway_sample_02_small.jpg :width: 800px

Drawing by トーコ Toko <https://twitter.com/fluffy2038/status/1317231121269104640>__ converted using Gerbolyze and printed at PCBWay.

Tooling for PCB art is quite limited in both open source and closed source ecosystems. Something as simple as putting a pretty picture on a PCB can be an extremely tedious task. Depending on the PCB tool used, various arcane incantations may be necessary and even modestly complex images will slow down most PCB tools to a crawl.

Gerbolyze solves this problem in a toolchain-agnostic way by directly vectorizing SVG vector and PNG or JPG bitmap files onto existing gerber layers. Gerbolyze processes any spec-compliant SVG and "gerbolyzes" SVG vector data into a Gerber spec-compliant form. Gerbolyze has been tested against both the leading open-source KiCAD toolchain and the industry-standard Altium Designer. Gerbolyze is written with performance in mind and will happily vectorize tens of thousands of primitives, generating tens of megabytes of gerber code without crapping itself. With gerbolyze you can finally be confident that your PCB fab's toolchain will fall over before yours does if you overdo it with the high-poly anime silkscreen.

Gerbolyze is based on gerbonara_.

.. image:: pics/process-overview.png :width: 800px

.. contents::

Tl;dr: Produce high-quality artistic PCBs in three easy steps!

Gerbolyze works in three steps.

1. Generate a scale-accurate template of the finished PCB from your CAD tool's gerber output:

   .. code::

   $ gerbolyze template --top template_top.svg [--bottom template_bottom.svg] my_gerber_dir
   

2. Load the resulting template image Inkscape_ or another SVG editing program. Put your artwork on the appropriate SVG layer. Dark colors become filled gerber primitives, bright colors become unfilled primitives. You can directly put raster images (PNG/JPG) into this SVG as well, just position and scale them like everything else. SVG clips work for images, too. Masks are not supported.

3. Vectorize the edited SVG template image drectly into the PCB's gerber files:

   .. code::

    $ gerbolyze paste template_top_edited.svg my_gerber_dir output_gerber_dir
   

Quick Start Installation (Any Platform)

.. code-block:: shell

python -m pip install --user gerbolyze resvg-wasi

If you already have resvg installed, you can omit the resvg-wasi package.

To uninstall, run

.. code-block:: shell

python -m pip uninstall gerbolyze gerbonara resvg-wasi svg-flatten-wasi

To update, run

.. code-block:: shell

python -m pip install --user --upgrade --upgrade-strategy eager gerbolyze

Speeding up gerbolyze using natively-built binaries

This will install gerbolyze's binary dependency resvg and gerbolyze's svg-flatten utility as pre-built cross-platform WASM binaries. When you first run gerbolyze, it will take some time (~30s) to link these binaries for your system. The output is cached, so any future run is going to be fast.

WASM is slower than natively-built binaries. To speed up gerbolyze, you can natively build its two binary dependencies:

1. Install resvg natively using rust's cargo package manager: cargo install resvg
2. Install gerbolyze's svg-flatten utility natively. You can get pre-built binaries from gerbolyze's gitlab CI jobs at this link <https://gitlab.com/gerbolyze/gerbolyze/-/pipelines?scope=tags&page=1>__ by clicking the three dots on the right next to the version you want. These pre-built binaries should work on any x86_64 linux since they are statically linked. You can also build svg-flatten yourself by running make inside the svg-flatten folder from a gerbolyze checkout.

Gerbolyze will pick up these binaries when installed in your $PATH. resvg is also picked up when it is installed by cargo in your home's ~/.cargo, even if it's not in your $PATH. You can override the resvg, usvg or svg-flatten binary that gerbolyze uses by giving it the absoulute path to a binary in the $RESVG, $USVG and $SVG_FLATTEN environment variables.

Build from source (any distro)

.. code-block:: shell

    git clone --recurse-submodules https://git.jaseg.de/gerbolyze.git
    cd gerbolyze

    python3 -m venv
    source venv/bin/activate
    python3 setup.py install

Features
--------

Input on the left, output on the right.

.. image:: pics/test_svg_readme_composited.png
  :width: 800px

* Almost full SVG 1.1 static spec coverage (!)

  * Paths with beziers, self-intersections and holes
  * Strokes, even with dashes and markers
  * Pattern fills and strokes
  * Transformations and nested groups
  * Proper text rendering with support for complex text layout (e.g. Arabic)
  * <image> elements via either built-in vectorizer or built-in halftone processor
  * (some) CSS

* Writes Gerber, SVG or KiCAD S-Expression (``.kicad_mod``) formats
* Can export from top/bottom SVGs to a whole gerber layer stack at once with filename autodetection
* Can export SVGs to ``.kicad_mod`` files like svg2mod (but with full SVG support)
* Beziers flattening with configurable tolerance using actual math!
* Polygon intersection removal
* Polygon hole removal (!)
* Optionally vector-compositing of output: convert black/white/transparent image to black/transparent image
* Renders SVG templates from input gerbers for accurate and easy scaling and positioning of artwork
* layer masking with offset (e.g. all silk within 1mm of soldermask)
* Can read gerbers from zip files
* Limited SVG support for board outline layers (no fill/region support)
* Dashed lines supported on board outline layers

Gerbolyze is the end-to-end "paste this svg into these gerbers" command that handles all layers on both board sides at
once.  The heavy-duty computer geometry logic of gerbolyze is handled by the svg-flatten utility (``svg-flatten``
directory).  svg-flatten reads an SVG file and renders it into a variety of output formats. svg-flatten can be used like
a variant of the popular svg2mod that supports all of SVG and handles arbitrary input ``<path>`` elements.

Algorithm Overview
------------------

This is the algorithm gerbolyze uses to process a stack of gerbers.

* Map input files to semantic layers by their filenames
* For each layer:

  * load input gerber
  * Pass mask layers through ``gerbv`` for conversion to SVG
  * Pass mask layers SVG through ``svg-flatten --dilate``
  * Pass input SVG through ``svg-flatten --only-groups [layer]`` 
  * Overlay input gerber, mask and input svg
  * Write result to output gerber

This is the algorithm svg-flatten uses to process an SVG.

* pass input SVG through usvg_
* iterate depth-first through resulting SVG.

  * for groups: apply transforms and clip and recurse
  * for images: Vectorize using selected vectorizer
  * for paths:

    * flatten path using Cairo
    * remove self-intersections using Clipper
    * if stroke is set: process dash, then offset using Clipper
    * apply pattern fills
    * clip to clip-path
    * remove holes using Clipper

* for KiCAD S-Expression export: vector-composite results using CavalierContours: subtract each clear output primitive
  from all previous dark output primitives

Web interface
-------------

You can try gerbolyze online at https://dyna.kokoroyukuma.de/gerboweb

The web interface does not expose all of gerbolyze's bells and whistles, but it allows you to simply paste a single SVG
file on a board to try out gerbolyze. Upload your design on the web interface, then download the template for either the
top or bottom side, and put your artwork on the appropriate layer of that template using Inkscape_. Finally, upload the
modified template and let gerbolyze process your design.

Command-line usage
------------------
.. _command_line_usage:

Generate SVG template from Gerber files:

.. code-block:: shell

    gerbolyze template [options] [--top|--bottom] input_dir_or.zip output.svg

Render design from an SVG made with the template above into a set of gerber files:

.. code-block:: shell

    gerbolyze paste [options] artwork.svg input_dir_or.zip output_dir_or.zip

Use svg-flatten to convert an SVG file into Gerber or flattened SVG:

.. code-block:: shell

    svg-flatten [options] --format [gerber|svg] [input_file.svg] [output_file]

Use svg-flatten to convert an SVG file into the given layer of a KiCAD S-Expression (``.kicad_mod``) file:

.. code-block:: shell

    svg-flatten [options] --format kicad --sexp-layer F.SilkS --sexp-mod-name My_Module [input_file.svg] [output_file]

Use svg-flatten to convert an SVG file into a ``.kicad_mod`` with SVG layers fed into separate KiCAD layers based on
their IDs like the popular ``svg2mod`` is doing:

Note:
    Right now, the input SVG's layers must have *ids* that match up KiCAD's s-exp layer names. Note that when you name
    a layer in Inkscape