kopia lustrzana https://gitlab.com/gerbolyze/gerbonara
151 wiersze
5.4 KiB
ReStructuredText
151 wiersze
5.4 KiB
ReStructuredText
Welcome to gerbonara's documentation!
|
|
=====================================
|
|
|
|
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 :py:class:`~primitives.Line`,
|
|
:py:class:`~primitives.Arc`, or :py:class:`.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. :py:class:`.GerberFile` and
|
|
:py:class:`.ExcellonFile` use the same types of :doc:`graphic objects <object-api>`, so objects can be directly
|
|
copied between file types without conversion.
|
|
|
|
**Unit-safety**
|
|
Gerbonara embeds physical :py:class:`.LengthUnit` information in all objects. The high-level API such as
|
|
:py:meth:`.LayerStack.merge` or :py:meth:`.GerberFile.offset` accepts arguments with an explicitly given unit and
|
|
automatically converts them as needed. Objects can be copied between :py:class:`.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 (:py:class:`GraphicObject`)
|
|
* Rendering API (:py:class:`GraphicPrimitive`)
|
|
* SVG export
|
|
* Full aperture macro support, including transformations (offset, rotation)
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
:caption: Contents:
|
|
|
|
cli
|
|
api-concepts
|
|
examples
|
|
file-api
|
|
object-api
|
|
apertures
|
|
aperture-macros
|
|
graphic-primitive-api
|
|
utilities
|
|
|
|
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')
|
|
|
|
You can find some more elaborate examples in this doc's :ref:`Examples section<examples-doc>`.
|
|
|
|
Command-Line Interface
|
|
======================
|
|
|
|
Gerbonara comes with a :ref:`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
|
|
|
|
A copy of this documentation can also 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
|
|
|
|
Indices and tables
|
|
==================
|
|
|
|
* :ref:`genindex`
|
|
* :ref:`modindex`
|
|
* :ref:`search`
|
|
|
|
.. _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
|
|
|