gbtiler 2.0 manual, gerber tiling utility
 
 
 

 
Gbtiler 2.0 User Manual
August 2004 alpha release
http://gbtiler.sourceforge.net

Sections of this document:


 
 
 
Introduction

Gbtiler is a Perl program which can offset and merge the gerber and NC drill files typically generated by programs such as EagleCAD and Protel. By using gbtiler, common layers from multiple circuit boards may be merged and offset into one or more large files, each holding a layer of the combined board artwork.

Gbtiler 2.0 processes gerber Cartesian data and gerber arc statements, and NC drill file data. Both RS274X gerber and NC drill languages, however, offer a rich set of plotting and drilling directives. Gbtiler doesn't handle all or even most of the more complex, obscure gerber and drill statements. See the gerber and drill formats section of this manual for a brief overview and pointers on gerber and NC drill language descriptions. Since this project's inception in November 2002 there has been no expressed demand for gbtiler to process other types of gerber data statements and directives.

To report bugs and to request additional features, please e-mail the gbtiler development team. See the contact section for directions on contacting gbtiler developers.
 
 
 
^ How to use gbtiler 2.0

System requirements:

To run gbtiler you need a Unix command prompt and a Perl interpreter. Many standard Linux distributions come with Perl by default. In FreeBSD, Perl is an optional package you can add during an expert install. Similarly in Cygwin, a Unix-within-Windows program set, Perl can be added as an available package.

Gbtiler is a text-based, command line oriented tool. Users may download, install and run this program via an ssh or telnet session to a remote Unix-based host on which they have an account.
 
 
Setting up gbtiler:

Typical steps to obtain and set up gbtiler on a Unix or Linux system entail,  

 
After untarring the gbtiler 2.0 released package, users should see three directories named 'src', 'docs', and 'examples'. Note that in the docs directory there is a small text file which lists all the files and directories which are a part of gbtiler 2.0 alpha release.

The source directory contains the gbtiler Perl packages and an associated driving script. Package names end with the file extension '.pm'. The driving script, which you'll use to invoke and execute gbtiler, is named 'gbtiler'. The docs directory contains this manual for gbtiler 2.0, and a couple of jpeg images of tiled files. These images are of the tiled results that come from running gbtiler on source gerber and drill files provided in the 'examples' directory. The example gerber files and argument files are provided to give end users a chance to try gbtiler and obtain easily verifiable results. By comparing gbtiler output with the jpegs, users can generally see whether the script is working as expected or not. To test gbtiler 2.0 using the provided example files, you can invoke gbtiler while in its directory with the following line,  

   gbtiler --argfile ../examples/test-args--relay-and-icd.txt
 
Immediately after untarring, the gbtiler 2.0 src and examples directories should share a common parent directory. In this situation the above line should cause gbtiler to tile some provided example files. There is a second test arguments file in the examples directory as well. Both temporary files and final tiled files are written to a directory named 'workspace' along side the tiler itself and its packages. This directory is not part of the 2.0 release, but is created when gbtiler doesn't find it and has permission to do so.

When you view the results of gbtiler in a gerber viewer, colors may differ from those in the provided jpeg example pictures. What should be the same, however, is that the combined circuit boards appear in the same positions, without distortions or other obvious errors. Drilled holes should generally appear centered in via and pad features of the boards.
 
 
Typical use:

The general things a user must specify to gbtiler include,  

 
As of 2004-08-12 gbtiler puts temporary, intermediate files and final tiled output files in a directory named 'workspace' in the directory in which the scripts are stored. With the 2.0 alpha release there is not an option for users to specify a different output directory. This option will probably appear in the 2.1 beta release of gbtiler.

When users specify integer and decimal precision, this formatting applies to all tiled gerber output files of a given tiling job. To maintain gerber file integrity in the tiled output, gbtiler 2.0 may increase user requested precision if one or more source files have greater precision than specified by the user. Also, gbtiler 2.0 sets both X and Y precisions equal to the larger of the two, if they differ prior to final tiling. Though the gerber language allows one to request differing precisions for X and Y values, doing this generally leads to file data being misinterpreted by some factor of 10. It's best to format X and Y data with the same precision.


 
 
 
^ Example arguments files 

--path ../examples/
--leading_zeroes 0
--trailing_zeroes 0
--x_integer_digits 2
--x_decimal_digits 4
--y_integer_digits 2
--y_decimal_digits 4

--layer drill
   --drillfile relay-board-v1.xln
      --offset 0.0 0.0
      --offset 4.2 0.0
   --drillfile ICD-ver1.TXT
      --offset -1.00 2.50
      --offset 2.75 2.50
      --offset 6.50 2.50
   --outfile relay-and-icd.xln

--layer bottom
   --gerberfile relay-board-v1.gbl
      --offset 0.0 0.0
      --offset 4.2 0.0
   --gerberfile ICD-ver1.GBL
      --offset -1.00 2.50
      --offset 2.75 2.50
      --offset 6.50 2.50
   --outfile relay-and-icd.gbl

--layer top
   --gerberfile relay-board-v1.gtl
      --offset 0.0 0.0
      --offset 4.2 0.0
   --gerberfile ICD-ver1.GTL
      --offset -1.00 2.50
      --offset 2.75 2.50
      --offset 6.50 2.50
   --outfile relay-and-icd.gtl

 
 
Gbtiler does not require indentation in its argument files. In this example the indentation is present for human readability. Developer Ted encourages people to use white space and indentation whenever possible, to make code and documents more readable.

Though not present in this example, some drill files have a separate rackfile which lists the tool or drill names and their corresponding sizes. There is a --rackfile option which can be used to specify rack files associated with particular drill files.

When a single board is tiled multiple times, there are actually two ways a user can specify this type of tiling. In the example file just above each source file is followed by two or three --offset option and value argument pairs. As gbtiler parses the user's argument list, --offset tags and their coordinate value pairs are interpreted as "tile the most recently named file with this set of offset values, now tile that same file with this next set of offset values..." This type of format in the argument list allows a user to highlight or focus on the offset values, which may make sense if a single file is to be tiled many times. With this formatting, it's easy to watch offset values change in a step-wise, successive manner from one pair of values to the next.

Similarly, if a user prefers to name each file explicitly she could also construct an arguments file with lines like these, 

--layer top
   --gerberfile receiver.gtl --offset 2.00 3.50
   --gerberfile receiver.gtl --offset 4.00 3.50
   --gerberfile receiver.gtl --offset 6.00 3.50
   --outfile radio-combo.gtl

 
 
 
^ List of gbtiler options

OPTION DESCRIPTION
FILE AND PATH OPTIONS --argfile [filename] name of file of additional options. Multiple argument files may be specified on the command line which invokes gbtiler but --argfile tags in external arguments files are basically ignored. In typical use, only one external argument file should be needed anyway.
--gerberfile [filename] filename of Gerber source file to tile.
--drillfile [filename] filename of NC drill file to tile.
--rackfile [filename] filename of rack or tool file to accompany a given NC drill file.
--outfile [filename] output file name for tiled layer which may be either a tiling of RS274X Gerber files or a tiling of NC drill files, but not a mix of both.
--path [pathname] path to prepend to all source files up to next --path option. This option makes it easier to include files to tile that are located in different directories. When encountered, the script updates an variable as it builds the hash of circuit board layers to tile.
--created_by [CAD program name] option to identify program which created the current NC drill file,
GLOBAL OPTIONS --offset [n.n,n.n] offset to apply to input file data, where n.n represent a real value. Gerber data precision is limited to a 6.6 format, where this stands for a maximum supported six integer digits and six decimal digits. NC drill data have fixed formats of 2.3 or 3.3 depending on whether the data represent English or Metric units of measure.
--leading_zeroes [ 0 | 1 ] toggels leading zero formatting on and off. Not yet fully implemented in gbtiler 2.0. See notes following this table,
--trailing_zeroes [ 0 | 1 ] toggels trailing zero formatting on and off. Not yet fully implemented in gbtiler 2.0. See notes following this table,
--x_integer_digits [n] output file coordinate formatting, n is an integer value between 1 and 6 inclusive,
--x_decimal_digits [n] output file coordinate formatting, n is an integer value between 1 and 6 inclusive,
--y_integer_digits [n] output file coordinate formatting, n is an integer value between 1 and 6 inclusive,
--y_decimal_digits [n] output file coordinate formatting, n is an integer value between 1 and 6 inclusive,
--drill_substitution apc this currently limited option followed by the token 'apc' turns on a simple, Alberta Printed Circuit drill substitution routine. In the DrillRacks package see the routine named 'check_for_substitution' for details. See the future plans section for improved drill substitution slated for next gbtiler release.

 
Additional notes on gbtiler options:

leading and trailing zeroes

Please note that in the August 2004 alpha release of gbtiler, version 2.0, the options to toggle leading and trailing zeroes on and off are not yet fully implemented. Leading and trailing zeroes are added unconditionally to the tiled output files. The gbtiler specification describes that only leading or trailing zeroes should or need appear in a file, but the presence of both leading and trailing zeroes has not appeared to cause harm during this project's two years of development and use by the Portland State Aerospace Society, whose members have inspired and helped in its development.

Leading zero and trailing zero formatting have improved readability of the gerber data during development work. See the section on gerber and NC drill file formats for details. To the end user, and in general when things are working, leading and trailing zeroes are probably not important.

X and Y precision formatting

Four separate options are part of gbtiler 2.0, for setting X data integer and decimal precision and Y data integer and decimal precision. However, with the next release of gbtiler the X and Y integer precision will likely be simplified to a --integer_precision option. Same for the decimal precision. Though gerber formatting appears to allow for different X and Y precision settings, the precision needs to be the same for X and Y data in order to have gerber files render properly.

'Created by' option for drill files

In gbtiler 2.0 there is also a --created_by option, which the TilerArguments package searches for in its arguments list, but this option is not used elsewhere in the gbtiler 2.0 scripts. This option appears in the code for development reasons. Specifically it was added with the thought that it would be needed for correct processing of external rack files. During the August 2004 transition work from version 1.0 to 2.0, it turned out not to be needed to properly tile the test gerber files on hand. For the moment, however, this option's presence is not hurting anything and it may be used in the future, so it is part of the 2.0 alpha release.
 
 
 
^ Gerber and NC drill formats

RS274X gerber file structure and some codes

A search on Google or other internet search engines for "gerber file formats" typically leads to useful, descriptive documents, with some sifting required. There is a gerber specification document in pdf format, by the Barco-Gerber Corporation, but this document is copyrighted. For NC drill files, the drill format description on Excellon Company's web site offers detailed information about this machining language.

In his work with Protel, EagleCAD and gbtiler development, developer Ted has found that the typical gerber file representing a circuit board layer contains the following parts,  

 
A gerber header section specifies such things as units of measure, numeric formatting and precision, and light polarity of the data in the file. Often times, a shape that is more complicated than a simple circle or square pattern is described in a section of macro definitions. Macros must precede aperture definitions which include or refer to the macro definitions.

As an aside, all this talk about apertures goes back to the light plotting machines of twenty or thirty years ago, which contained wheels with various punched circular shapes and other patterns. A gerber file would direct a light plotting machine to select a particular aperture, move it's aperture wheel, and turn its light source on and off. By performing these actions in planned patterns, meaningful designs are printed or otherwise photo-generated onto light sensitive media. Some of the old machines are still in use, and many modern plotting machines use and understand the gerber plotting and NC drill languages.

In a typical gerber file the three, relatively small header, macro and aperture sections are followed by a larger section of gerber coordinate data. Sometimes there are also gerber arc data and other data types. Among the data, references to apertures (also called tool change directives) appear periodically.

Here is an example RS274X gerber header, 

G75*            . . . set arc mode to 360 degree interpolation
G70*            . . . set measurement unit to inches
%OFA0B0*%       . . . offset A or X axis by 0, offset B or Y axis by 0
%FSAX24Y24*%    . . . format statement, 2 integer digits and 4 decimal digits per datum
%IPPOS*%        . . . image polarity positive
%LPD*%          . . . layer polarity dark
 
 
Here is an example of a gerber macro definition followed by several aperture definitions,

%AMOC8                        . . . macro definition*
5,1,8,0,0,1.08239X$1,22.5*
*%
%ADD10R,0.0197X0.0591*%       . . . rectangular aperture
%ADD11R,0.0591X0.0197*%       . . . rectangular aperture
%ADD12C,0.0660*%              . . . circular aperture
%ADD13C,0.0400*%              . . . circular aperture
%ADD14C,0.0892*%              . . . circular aperture
 
 
Here is some sample gerber data. Note the tool change directive lines which start with a 'D', 

D24*
X013224Y019805D03*
X011885Y019805D03*
D25*
X010956Y019755D03*
X009854Y019755D03*
D26*
X010105Y029605D03*
   .
   .
   .
M02*
 
 
These represent many of the gerber statements and codes that gbtiler 2.0 is designed to parse and tile. However, many of the header lines simply pass through the tiler. Part of the error and file integrity checking that is slated for the beta release, gbtiler version 2.1, includes code to determine whether source files of a given job contain conflicting header lines, like opposing polarities or differing units of measurement. This potentially important sanity checking is not present in gbtiler 2.0.

All the circuit board gerber files developer Ted has seen end with the gerber code 'M02'.  
 
 
NC drill files

NC drill files have a similar but somewhat more simple structure, compared with gerber files. NC drill files typically contain the sections,  

 
Here are the first dozen or so lines from a typical NC drill file. The lines from the 'M48' code to the 'M72' code constitute the header and drill rack. Drill racks are lists of cutting tools or drills and their sizes. Lines following the lone percent character on its own line are the drill data. A drill file without an embedded drill rack section typically begins with the line containing only a percent character: 

M48
T01 0.028in
T02 0.035in
T03 0.042in
T04 0.052in
T05 0.125in
G90
M72
%
T01
X344Y171
X884Y851
X939Y916
X1704Y1296
X1914Y1526
   .
   .
   .
M30
 
 
NC drill files end with an 'M30' code.
 
 
 
^ Program strategy and implementation

This section will be completed most likely with the beta release of gbtiler 2.0. Current August 2004 version 2.0 release is an alpha version, largely untested. There are, however, many comments by the developers throughout the Perl packages that comprise gbtiler. These comments focus on implementation and intent of coding, as well as on gerber and NC drill format issues.

In brief, however, the major data structure used in gbtiler is a complex hash tree which the argument parsing package TilerArguments largely builds. This job hash tree at its top most level contains keys pointing to global formatting information, and layers of gerber and NC drill files to be tiled. Within gerber and drill file branches of the job hash, file specific data such as offsets, and gathered header, drill size and aperture data are stored.

The way this data structure is passed from the driving script 'gbtiler' to various package instantiations is a departure from some original goals to write an object oriented gbtiler. With experience gained and thoughts pondered over the past two years, developer Ted thinks now that an object oriented approach may not be best for the gbtiler. The program does not fit a server/client model. The packages of gbtiler need not worry about trusting each other in terms of sharing data.

Gbtiler's development team still holds among its goals writing a program that is quick to develop and debug. With the 2.0 release, and some improvements to the diagnostics package included with the gbtiler scripts, our team has realized much more of the "ease of development" goal than during previous release times.
 
 
 
^ gbtiler history

Gbtiler began in the late fall of 2002 as the Portland State Aerospace Society needed to build several custom prototype circuit boards. Members of the PSAS avionics team recognized that the format of their circuit board artwork files, RS274X gerber format, is a plain ASCII text format. Being text, this data could be manipulated via scripts to combine numerous small board artworks into a single, larger printed circuit board file. The PSAS group uses Alberta Printed Circuits in Canada for low-run, prototype board manufacturing. Our group agreed that if we could programmatically tile several boards and view them correctly in various gerber viewers, that we would send off the tiled job for actual production. Several uses later, the tiler appears to be working.

Initially two developers on took on the separate and distinct tasks of tiling gerber files and NC drill files. Gbtiler and drilltiler appear as the first two released, bundled file sets on the gbtiler downloadable files page at SourceForge. There were, however, two major shortfalls of this first circuit board tiling effort. The first shortfall was that the gbtiler 1.0 and the accompanying but separate drilltiler processed only one layer of board artwork at a time. A typical minimal board design has three layers:  a top layer, bottom layer, and drill layer. We expect users of gbtiler to have additional layers as well, such as solder mask and silk screening layers.

The second major shortfall of gbtiler 1.0, but not of the drill tiling scripts, is that the program took long times to complete larger tiling tasks. This problem has largely been solved, with tiling jobs that used to take minutes now taking only seconds. Before moving gbtiler from version 1.0 to 2.0, developer Ted Havelka believed that large memory allocations for arrays might be causing the scripts to take a long time to run. During the rework, however, it became apparent that unnecessarily numerous subroutine calls could also be the cause for the tiler to take so long on larger jobs. The tiler has been tested on Solaris Ultra 10 stations with 256 MB of memory, and on various Intel desktop and laptop systems, running Debian, Redhat Linux and Cygwin. Run times of larger tiling jobs varied only by a factor of three or four at the most across these various machines.

The Portland State Aerospace Society is preparing for another tiling job in late August of 2004. With gbtiler 2.0's ability to process multiple layers and both gerber and drill files in a single job, our tiling work should be much easier this time around. Developers on the gbtiler project are also looking forward to faster debugging cycles, as the program now tiles reasonably quickly and gives results in seconds rather than minutes.
 
 
 
^ future plans

Ideas for needed and new capabilities in gbtiler include,  

 
These are some of the major ideas for improving the gbtiler. For more detailed explanations and information about the status of these various improvements, see the gbtiler improvements section on the gbtiler homepage.

By no means is this list of improvements and new features complete. End users will likely contribute more good ideas as time passes. At the same time, at least one item on the list represents what is a complete and different project in its own right -- a gerber viewer. There are already several gerber viewers in popular use today. To view gerber files developer Ted has used GCPrevue, Lavenir's viewer, and Gerbv, the last of which is also a SourceForge hosted project. If and when gbtiler moves toward graphical support it will likely make sense to see whether an open source project such as Gerbv can be combined with gbtiler, and to see whether that makes sense user-wise and in terms of program implementation.
 
 
 
^ Contact gbtiler development team

The current developer and contact person for the gbtiler project is Ted Havelka. Ted can be reached via e-mail at ted@cs.pdx.edu. Developer Ted is happy to consider requests for new capabilities in gbtiler, and would like to hear reports of bugs in the latest version of the program.
 
 
 

Top of document