GerbMerge -- A Gerber-file merging program

---

What's New

In release 1.9.4

• Metric support fixed and tested with Diptrace
• Support for Cygwin environment
• Fixed Windows installation
• Some Gerber parsing fixes

In release 1.9

• Added metric support
• Added default timeout for random tile placement
• Added DipTrace support
• Use boardoutline files (when present) to build cutlines in silkscreen layers instead of the default calculated algorithm. This change permits non-rectangular board outlines.

In release 1.8:

• Released under more recent GPL v3 license
• Summary statistics prints out smallest drill tool diameter
• Added FiducialPoints, FiducialCopperDiameter, and FiducialMaskDiameter configuration options
• Added option to write fiducials to final panel
• Scoring lines now go all the way across a panel

In release 1.7:

• Added a new command-line option --search-timeout to time-limit the automatic placement process.
• Added preliminary support for a GUI controller interface.

Introduction

GerbMerge is a program for combining (panelizing) the CAM data from multiple printed circuit board designs into a single set of CAM files. The purpose of doing so is to submit a single job to a board manufacturer, thereby saving on manufacturing costs.

GerbMerge currently works with:

• CAM data generated by the Eagle and DipTrace circuit board design programs, with "best effort" support for Orcad, Protel, and PCB
• Artwork in Gerber RS274-X format
• Drill files in Excellon format

Here is one sample and another sample of the program's output. These samples demonstrate panelizing multiple, different jobs, and also demonstrate board rotation.

Requirements

GerbMerge is written in pure Python. It depends upon the following packages for operation:

• Python version 2.4 or later
• SimpleParse version 2.1.0 or later

All of the above packages come with easy installation programs for both Windows, Mac OS X, and Linux.

Automatic Installation with PIP

This repository can generate a tarball for installation with PIP. In the repository, run:

$ python setup.py sdist
$ pip install dist/gerbmerge-1.9.4.tar.gz

PIP will automatically resolve the dependencies. -1.9.4 will change with the current tool version.

To easily run the installed package without looking up your python path, use python's "run module as script" feature:

$ python -m gerbmerge <args>

Installation

Windows / Cygwin

Install Cygwin with python, python-setuptools, and gcc packages (gcc is needed for simpleparse). Launch Cygwin shell and install pip, then simpleparse:

easy_install-x.y pip
pip install simpleparse

(x.y is the current Python version)

Download and unpack gerbmerge sources, navigate to its folder in Cygwin shell and run:

python setup.py sdist
pip install dist/gerbmerge-1.9.4.tar.gz

Now you can use it by running gerbmerge in Cygwin shell.

To uninstall gerbmerge, launch Cygwin shell and run:

pip uninstall gerbmerge

Windows (native)

Download and install Python-2.7, pip will be installed too. Assuming Python installation folder is C:\Python27, open command propmt and run:

cd c:\python27\
scripts\pip.exe install simpleparse

Download and unpack gerbmerge sources, navigate to its folder and run:

c:\python27\python.exe setup.py sdist
c:\python27\scripts\pip.exe istall dist\gerbmerge-1.9.4.zip

Now you can use it by running c:\python27\gerbmerge.bat in command prompt.

To uninstall gerbmerge, launch command prompt and run:

c:\python27\scripts\pip.exe uninstall gerbmerge

Unix / Mac OS X

Install python, gcc (required to build simpleparse), and pip (recommended)

Launch shell and install simpleparse:

sudo pip install simpleparse

Download and unpack gerbmerge sources, navigate to its folder and run:

python setup.py sdist
sudo pip istall dist/gerbmerge-1.9.4.tar.gz

Now you can use it by running gerbmerge.

To uninstall gerbmerge, open shell and run:

sudo pip uninstall gerbmerge

Running GerbMerge

Windows / Cygwin

Launch Cygwin shell and type

gerbmerge

Windows (native)

Open a DOS command prompt and laucnh gerberge.bat file:

c:\python27\gerbmerge.bat

Unix / Mac OS X

Open shell and type

gerbmerge

Operation

There are three ways to run GerbMerge:

1. By manually specifying the relative placement of jobs
2. By manually specifying the absolute placement of jobs
3. By letting GerbMerge automatically search for a placement that minimizes total panel area

Manual Relative Placement

For the manual relative placement approach, GerbMerge needs two input text files:

• The configuration file specifies global options and defines the jobs to be panelized

• The layout file specifies how the jobs are to be laid out.

The names of these files are the two required parameters to GerbMerge:

gerbmerge file.cfg file.def

The following links describe the contents of the configuration file and layout file.

Manual Absolute Placement

For the manual absolute placement approach, GerbMerge also needs the configuration file as well as another text file that specifies where each job is located on the panel and whether or not it is rotated:

gerbmerge --place-file=place.txt file.cfg

The place.txt file looks something like:

job1 0.100 0.100
cpu 0.756 0.100
cpu*rotated 1.35 1.50

This method of placement is not meant for normal use. It can be used to recreate a previous invocation of GerbMerge, since GerbMerge saves its results in a text file (whose name is set in the [MergeOutputFiles] section of the configuration file) after every run. Thus, you can experiment with different parameters, save a placement you like, do some more experimentation, then return to the saved placement if necessary.

Alternatively, this method of placement can be used with third-party back ends that implement intelligent auto-placement algorithms, using GerbMerge only for doing the actual panelization.

Automatic Placement

For the automatic placement approach, GerbMerge only needs the configuration file:

gerbmerge file.cfg

Command-line options can be used to modify the search algorithm. See the Automatic Placement page for more information.

Input File Requirements

GerbMerge requires the following input CAM files:

• Each job must have a Gerber file describing the board outline, which is assumed rectangular. In Eagle, a board outline is usually generated from the Dimension layer. This board outline is a width-0 line describing the physical extents of the board. If you're not using Eagle, you don't have to generate a width-0 rectangle, but GerbMerge does need to use some Gerber layer to determine the extents of the board. GerbMerge will take the maximum extents of all drawn objects in this layer as the extents of the board.

• Each job must have an Excellon drill file.

• Each job can have any number of optional Gerber files describing copper layers, silkscreen, solder masks, etc.

• All files must have the same offset and must be shown looking from the top of the board, i.e., not mirrored.

• Each job may have an optional tool list file indicating the tool names used in the Excellon file and the diameter of each tool. This file is not necessary if tool sizes are embedded in the Excellon file. A typical tool list file looks like:

            T01 0.025in
            T02 0.032in
            T03 0.045in
  

Verifying the Output

Before sending your job to be manufactured, it is imperative that you verify the correctness of the output. Remember that GerbMerge comes with NO WARRANTY. Manufacturing circuit boards costs real money and a single mistake can render an entire lot of boards unusable.

I recommend the following programs for viewing the final output data. Take the time to become very familiar with at least one of these tools and to use it before every job you send out for manufacture.

gerbv

For Linux, the best option (currently) for viewing Gerber and Excellon files is the gerbv program. Simply type in the names of all files generated by GerbMerge as parameters to gerbv:

gerbv merged.*.ger merged.*.xln

GC-Prevue

For Windows, GC-Prevue is a good program that I have used often. It is a free program. GraphiCode makes lots of other, more powerful Gerber manipulation and viewing programs but they are quite pricey ($495 and up).

ViewMate

Another free Windows program, ViewMate is similar to GC-Prevue. I have not used ViewMate much, but that is mostly due to familiarity with GC-Prevue. The two programs are comparable, although I'm sure that someone who is much more familiar with both could point out some differences.

Limitations

• This program has mainly been tested with output from Eagle CAD and Diptrace programs. Limited testing has been performed with Orcad, Protel, and PCB. Other CAD programs will NOT WORK with a very high probability, as the input parser is quite primitive.

  If you have the need/motivation to adapt GerbMerge to other CAD programs, have a look at the gerber2pdf program. It is written in Python and implements a much more complete RS274-X input file parser. Combining GerbMerge with gerber2pdf should be a fairly simple exercise. Also, feel free to send us samples of Gerber/Excellon output of your CAD tool and we'll see if we can add support for it.

• This program handles apertures that are rectangles, ovals, circles, macros without parameters or operators, and Eagle octagons (which are defined using a macro with a single parameter, hence currently handled as a special case).

• The panelizing capabilities of this program do not allow for arbitrary placement of jobs, although there is a fair amount of flexibility.

• All jobs are assumed to be rectangular in shape. Non-rectangular jobs can be handled but will lead to wasted space in the final panel.

• A maximum of 26 different drill sizes is supported for generating a fabrication drawing.

Program Options

--octagons=normal

--octagons=rotate

The --octagons option affects how the octagon aperture is defined in the output files. The parameter to this option must either be rotate or normal. Normally, octagons begin at an angle of 22.5 degrees, but some Gerber viewers have a problem with that (notably CircuitMaker from LPKF). These programs expect octagons to begin at 0.0 degrees.

The --octagons=normal option is the default (22.5 degrees) and need not be specified. A rotation of 0.0 degrees can be achieved by specifying --octagons=rotate.

--random-search

This option is the default when only a configuration file is specified (see the documentation on Automatic Placement for more information). It indicates that a randomized search of possible job tilings is to be performed. This option does not make sense when a layout file is specified.

--full-search

This option may be specified to indicate that all possible job tilings are to be searched (see the documentation on Automatic Placement for more information). This option does not make sense when a layout file is specified.

--rs-fsjobs=N

This option is used with randomized search to indicate how many jobs are to undergo full search for each tiling. See the documentation on Automatic Placement for more information.

--place-file=filename

This option performs a panel layout based upon absolute job positions in the given text file, rather than by random/full search or by a layout file. The placement file created by GerbMerge can be used as an input file to this option in order to recreate a previous layout.

--no-trim-gerber

This option prevents GerbMerge from trying to trim all Gerber data to lie within the extents of a given job's board outline. Normally, GerbMerge will try to do so to prevent one job's Gerber data (most notably, silkscreen lines for connectors that protrude from the board) from interfering with a neighboring job on the final panel. Specify this command-line option if you do not want this trimming to occur.

--no-trim-excellon

This option prevents GerbMerge from trying to trim all Excellon data to lie within the extents of a given job's board outline. Normally, GerbMerge will try to do so to prevent one job's drill holes from landing in the middle of a neighboring job on the final panel. Specify this command-line option if you do not want this trimming to occur.

--search-timeout=seconds

When random placements are used, this option can be used to automatically terminate the search process after the specified number of seconds. If the number of seconds is 0 or this option is not specified, then random placements are tried forever, until Ctrl-C is pressed to stop the process and keep the best placement so far.

-h, --help

The '-h' or '--help' option prints a brief summary of available options.

-v, --version

The '-v' or '--version' option prints the current program version and author contact information.

Examples

Example layout config files and gerber files (both original and merged) can be found in gerbmerge/examples folder

Copyright & License

Copyright © 2016 Unwired Devices LLC.

This repo is a fork of gerbmerge, version 1.9 from ProvideYourOwn.com, with additional patches by Ian Hartwig and Paulo Henrique Silva

Copyright © 2013 ProvideYourOwn.com. All Rights Reserved.

This repo is a fork of gerbmerge, version 1.8 from Rugged Circuits LLC:

Copyright © 2011 Rugged Circuits LLC. All Rights Reserved. mailto: support@ruggedcircuits.com

GerbMerge comes with ABSOLUTELY NO WARRANTY. This is free software licensed under the terms of the GNU General Public License Version 3. You are welcome to copy, modify and redistribute this software under certain conditions. For more details, see the LICENSE file or visit The Free Software Foundation.

To Do

1. Proper metric/inch support: parse files with arbitrary units, output files with units specified in the config
2. Accept outputs from more CAD programs
3. A graphical interface for interactive placement
4. Better reporting of parse errors in the layout and configuration files
5. Implement simple primitive for panelizing a single job in an array
6. More intelligent placement algorithms, possibly based on the fabric cutting problem.
7. Accept aperture macro parameters and operators

Credits

Thanks to Jace Browning for major contributions to this code. This help file is based on a template for the help file for mxTools by M.A. Lemburg. This software was created with VIM; thanks to the authors of this program and special thanks for the Python syntax support. Thanks to M.A. Lemburg for his mxBase package, Mike Fletcher for his SimpleParse package, and the authors of gerbv, a great Gerber file viewer for Linux/Mac OS X, and, of course, to the Python developers and support community.

Thanks to Joe Pighetti for making me start writing this program, and to the Grand Valley State University Firefighting Robot Team for making me finish it.

Thanks to Matt Kavalauskas for identifying Eagle's annulus and thermal macros and supporting the development of the aperture macro code.

Thanks to Bohdan Zograf for the Belorussian translation of this documentation.

---

Copyright © 2016 Unwired Devices LLC. All Rights Reserved.

Portions (version 1.9.3 & prior): Copyright © 2013 ProvideYourOwn.com. All Rights Reserved.

Portions (version 1.8 & prior): Copyright © 2003-2011, Copyright by Rugged Circuits LLC; All Rights Reserved. mailto: support@ruggedcircuits.com