jaseg/gerbonara
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gerbonara/docs/api-concepts.rst
jaseg 7473e471dc Add some documentation
2022-02-01 22:08:54 +01:00

3.7 KiB
Raw Blame History

Gerbonara API concepts

High-level overview

Gerbonara's API is split into three larger sub-areas:

File API

This is where the main user interface classes live: .LayerStack (for opening a directory/zip full of files, and automatically matching file roles based on filenames), .GerberFile (for opening an individual RS-274X file), .ExcellonFile (for Excellon drill files) and .Netlist (for IPC-356 netlist files).

Graphic Object API

This is where the nuts and bolts inside a .GerberFile or .ExcellonFile such as ~.graphic_objects.Line, ~.graphic_objects.Arc, .Region and .Flash live. Everything in here has explicit unit support. A part of the Graphic object API is the Aperture API<apertures>.

Graphic Primitive API

This is a rendering abstraction layer. Graphic objects can be converted into graphic primitives for rendering. Graphic primitives are unit-less. Units are converted during .GraphicObject to .GraphicPrimitive rendering.

The hierarchy works like: A .LayerStack contains either a .GerberFile, an .ExcellonFile or a .Netlist for each layer. Each of these file objects contains a number of .GraphicObject instances such as ~.graphic_objects.Line or .Flash. These objects can easily be changed or deleted, and new ones can be created programmatically. For rendering, each of these objects as well as file objects can be rendered into .GraphicPrimitive instances using .GraphicObject.to_primitives.

Apertures

Gerber apertures are represented by subclasses of .Aperture such as .CircleAperture. An instance of an aperture class is stored inside the ~.graphic_objects.Line.aperture field of a .GraphicObject. .GraphicObject subclasses that have an aperture are ~.graphic_objects.Line, ~.graphic_objects.Arc and .Flash. You can create and duplicate .Aperture objects as needed. They are automatically de-duplicated when a Gerber file is written.

Gerbonara has full aperture macro support. Each aperture macro is represented by an .parse.ApertureMacro instance. Like apertures, .parse.ApertureMacro instances are de-duplicated when writing a file. An aperture macro-based aperture definition is represented by the .ApertureMacroInstance subclass of .Aperture. An aperture macro instance basically binds an aperture macro to a given set of macro parameters. Note that even if a macro does not accept any parameters you still cannot directly stick it into the aperture field of a graphic object, and instead need to wrap it inside an .ApertureMacroInstance first.

Excellon vs. Gerber

Excellon files use the same graphic object classes as Gerber files. Inside an Excellon file, only ~.graphic_objects.Line, ~.graphic_objects.Arc and .Flash are allowed. Lines and arcs map to milled Excellon slots. Excellon drills are mapped to .Flash instances.

Excellon drills are internally handled using a special .ExcellonTool aperture class. When you put a .GraphicObject from an Excellon file into a Gerber file, these become circular apertures. You can also take objects from an Excellon file and put them into a Gerber file if they have a simple .CircleAperture. Copying objects with other apertures into an Excellon file will raise an error when saving.