141 lines
5.3 KiB
ReStructuredText
141 lines
5.3 KiB
ReStructuredText
---
|
|
title: "Gerbonara"
|
|
external_links:
|
|
- name: Sources
|
|
url: "https://git.jaseg.de/gerbonara.git"
|
|
- name: Issues
|
|
url: "https://gitlab.com/gerbolyze/gerbonara/issues"
|
|
- name: Docs
|
|
url: "https://gerbolyze.gitlab.io/gerbonara"
|
|
- name: PyPI
|
|
url: "https://pypi.org/project/gerbonara"
|
|
summary: >
|
|
Gerbonara is a user-friendly, powerful tool for reading, writing, modification and rendering of Gerber PCB artwork
|
|
from the command line or from Python code. Gerbonara supports the Gerber dialects of all industry-standard EDA
|
|
tools.
|
|
---
|
|
|
|
Gerbonara is a library to read, modify and write PCB manufacturing files such as Gerber, Excellon and IPC-356 through a
|
|
pythonic API. Gerbonara can open a folder of manufacturing files, and parse file names and metadata to figure out which
|
|
file contains what. Gerbonara is tested using an extensive library of real-world example files from CAD tools including
|
|
KiCAD, Altium, Eagle, Allegro, gEDA, Fritzing, Siemens/Mentor Graphics PADS, and Target3001!.
|
|
|
|
Gerbonara's API is built on two principles:
|
|
|
|
**Meaningful, object-oriented API**
|
|
Gerbonara abstracts away the details of the underlying file format such as tool indices, coordinate notation and
|
|
graphical state, and presents meaningful "graphical objects" such as a `primitives.Line`,
|
|
`primitives.Arc`, or `Region` through its API. These objects can be easily created,
|
|
manipulated or deleted from code without breaking anything else. You can even copy graphical objects between files,
|
|
and Gerbonara will automatically convert coordinate format, units etc. for you. `GerberFile` and
|
|
`ExcellonFile` use the same types of `graphic objects <object-api>`, so objects can be directly
|
|
copied between file types without conversion.
|
|
|
|
**Unit-safety**
|
|
Gerbonara embeds physical `LengthUnit` information in all objects. The high-level API such as
|
|
`LayerStack.merge` or `GerberFile.offset` accepts arguments with an explicitly given unit and
|
|
automatically converts them as needed. Objects can be copied between `GerberFile` instances and unit
|
|
conversion will be handled transparently in the background.
|
|
|
|
Gerbonara was started as an extensive refactoring of the pcb-tools_ and pcb-tools-extension_ packages. Both of these
|
|
have statement-based APIs, that is, they parse input files into one python object for every line in the file. This means
|
|
that when saving files they can recreate the input file almost byte by byte, but manipulating a file by changing
|
|
statements without breaking things is *hard*.
|
|
|
|
Gerbonara powers gerbolyze_, a tool for converting SVG_ vector graphics files into Gerber, and embedding SVG_ into
|
|
existing Gerber files exported from a normal PCB tool for artistic purposes.
|
|
|
|
Features
|
|
========
|
|
|
|
* File I/O
|
|
* Gerber, Excellon (drill file), IPC-356 (netlist) read and write
|
|
* supports file-level operations: offset, rotate, merge for all file types
|
|
* Modification API (`GraphicObject`)
|
|
* Rendering API (`GraphicPrimitive`)
|
|
* SVG export
|
|
* Full aperture macro support, including transformations (offset, rotation)
|
|
|
|
Quick Start
|
|
===========
|
|
|
|
First, install gerbonara from PyPI using pip:
|
|
|
|
.. code-block:: shell
|
|
|
|
pip install --user gerbonara
|
|
|
|
Then, you are ready to read and write gerber files:
|
|
|
|
.. code-block:: python
|
|
|
|
from gerbonara import LayerStack
|
|
|
|
stack = LayerStack.from_directory('output/gerber')
|
|
w, h = stack.outline.size('mm')
|
|
print(f'Board size is {w:.1f} mm x {h:.1f} mm')
|
|
|
|
Command-Line Interface
|
|
======================
|
|
|
|
Gerbonara comes with a `built-in command-line interface<cli-doc>` that has functions for analyzing, rendering,
|
|
modifying, and merging Gerber files. To access it, use either the ``gerbonara`` command that is part of the python
|
|
package, or run ``python -m gerbonara`` For a list of functions or help on their usage, you can use:
|
|
|
|
.. code:: console
|
|
|
|
$ python -m gerbonara --help
|
|
[...]
|
|
$ python -m gerbonara render --help
|
|
|
|
Development
|
|
===========
|
|
|
|
Gerbonara is developed on Gitlab under the gerbolyze org:
|
|
|
|
https://gitlab.com/gerbolyze/gerbonara/
|
|
|
|
A mirror of the repository can be found at:
|
|
|
|
https://git.jaseg.de/gerbonara
|
|
|
|
Our issue tracker is also on Gitlab:
|
|
|
|
https://gitlab.com/gerbolyze/gerbonara/-/issues
|
|
|
|
The documentation can be found at gitlab:
|
|
|
|
https://gerbolyze.gitlab.io/gerbonara/
|
|
|
|
With Gerbonara, we aim to support as many different format variants as possible. If you have a file that Gerbonara can't
|
|
open, please file an issue on our issue tracker. Even if Gerbonara can open all your files, for regression testing we
|
|
are very interested in example files generated by any CAD or CAM tool that is not already on the list of supported
|
|
tools.
|
|
|
|
Supported CAD Tools
|
|
===================
|
|
|
|
Compatibility with the output of these CAD tools is tested as part of our test suite using example files generated by
|
|
these tools. Note that not all of these tools come with default Gerber file naming rules, so YMMV if your Gerbers use
|
|
some non-standard naming convention.
|
|
|
|
* Allegro
|
|
* Altium
|
|
* Diptrace
|
|
* Eagle
|
|
* EasyEDA
|
|
* Fritzing
|
|
* gEDA
|
|
* KiCAD
|
|
* pcb-rnd
|
|
* Siemens / Mentor Graphics Xpedition
|
|
* Siemens PADS
|
|
* Target 3001!
|
|
* Upverter
|
|
* Zuken CR-8000
|
|
|
|
.. _pcb-tools: https://github.com/opiopan/pcb-tools-extension
|
|
.. _pcb-tools-extension: https://github.com/curtacircuitos/pcb-tools/issues
|
|
.. _gerbolyze: https://github.com/jaseg/gerbolyze
|
|
.. _SVG: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
|
|
|