Metadata-Version: 2.1
Name: gerbertools
Version: 0.1.0
Summary: Tools for inspecting and DRC'ing PCBs their Gerber files
Home-page: https://github.com/jvanstraten/gerbertools
Author: Jeroen van Straten
License: UNKNOWN
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: msvc-runtime ; platform_system == "Windows"

# GerberTools

Yet another tool for doing stuff with Gerber files. "Stuff" being:

 - rendering to SVGs;
 - rendering to 3D models (Wavefront OBJ format); and
 - (very) basic electrical DRC.

## Why? [insert tool here] can already do this.

For as far as I could find, no (open source) tool could do these things from
just gerber files (they use their own EDA file format), don't do it detailed
enough for my liking, can't be scripted, and/or don't have a way to export the
data. It's all kind of a mess. For example...

 - Other tools exist to render Gerber files to SVGs. But they use
   (comparatively) complex SVG operations to make things work, thus relying on
   the SVG rendering engine to do most of the work. If you're just viewing the
   file that's fine; if you're reading them from a script it's not. The SVGs
   generated by GerberTools only use polygons, making them much easier to read.

 - Most EDA tools nowadays have a 3D viewer built into them. But if they have
   an exporter at all, the export is limited to the board shape and holes.
   That's fine when you're doing 3D CAD, but it's nowhere near good enough when
   you're trying to make somewhat photorealistic renders, like this:

   ![Example render](assets/example.png?raw=true "Example render")

   The input file format (i.e. the native format of the EDA tool) can also be
   an issue, for example [when you're crazy enough to procedurally generate a
   PCB](https://github.com/jvanstraten/gated-clock). So is scriptability.

 - DRC has the same "issues" as above: when you only have Gerber files and a
   netlist, good luck getting any EDA tool to help you.

Ultimately, I built this because I myself needed it. Maybe it'll help someone
else as well, maybe not.

## How?

The core is written in C++, but wrapped in a (scarcely documented) Python
module. This module also includes a basic command-line interface. You can get
it the usual way with pip:

    pip install gerbertools

Once you have it, you can use the command-line interface using

    gerbertools --help

or equivalently, if the above won't work due to path shenanigans,

    python -m gerbertools --help

From within Python, you can do something like

    import gerbertools
    help(gerbertools)
    print(gerbertools.get_version())
    gerbertools.read('some_pcb').write_svg('some_pcb.svg')

You can also run the tests by running the `test_boards.py` script in the
`tests` directory. This should give you some basic usage examples, and
generates some example output files in `tests/output`.

Wheels should be available for Windows, MacOS, and Linux using the Python
versions active at the time of writing. If you're reading this in N years and
there is no wheel for your version, or you have some other reason to build it
yourself, it should be fairly straightforward to do so. All dependencies are
contained within the repository, so you really just need Python and a C++
compiler. The easiest way to build it is with:

    NPROCS=10 pip install -v -e .

where the `NPROCS` environment variable specifies the maximum amounts of
parallel compilation processes to use.

You can also build and install using the usual CMake methods, but then you only
get the C++ library that the Python module is based on. So that's really only
useful when you want to use the library from C++.

## Copyright stuff

The polygon geometry processing is done using the
[Clipper](http://www.angusj.com/delphi/clipper.php) library, lazily included
as source files in this repository. It uses the Boost software license. The
same thing goes for [Earcut](https://github.com/mapbox/earcut.hpp/), which uses
the ICS license. The relevant license text is at the top of the copied files.

Stuff I add will be licensed under MIT, which I'm more familiar with. Either
way, it'll be permissively licensed.

The circuit board files in the test directory have different licenses. They are
not distributed with or linked to any build, and I have no affiliation with the
makers/owners of those boards.


