API documentation for gerber-parser. An understanding of the Gerber file format specification and the Excellon NC drill format (as poorly defined as it is) will help with understanding the parser API.
var gerberParser = require('gerber-parser')
var parser = gerberParser(OPTIONS)
var gerberStream = getReadableStreamSomehow()
gerberStream.pipe(parser)
.on('warning', function(warning) {
// handle warning
})
.once('error', function(error) {
// handle error
})var gerberParser = require('gerber-parser')
var parser = gerberParser(OPTIONS)The parser is stateful, so be sure to use one parser per file. The parser has both a streaming and a synchronous interface.
The object returned by gerberParser is a Node Transform Stream. When you write a Gerber or Drill file contents into the stream, it will emit command objects to be consumed by an image generator (or plotter).
var parser = gerberParser()
var gerberStream = getReadableStreamSomehow()
gerberStream.pipe(parser)The transform may also be performed synchronously on a string. This will block, but will most likely run faster.
var parser = gerberParser()
var gerberFile = fs.readFileSync('path/to/file.gbr')
var arrayOfCommands = parser.parseSync(gerberFile)The gerberParser function takes an options object and returns a transform stream. The options object can be used to override or certain details that would normally be parsed from the Gerber file or may be missing from the file entirely (which can happen a lot, especially with drill files).
var options = {
places: [3, 5],
zero: 'L',
filetype: 'gerber'
}
var parser = gerberParser(options)The available options are:
| key | value | description |
|---|---|---|
| places | [int, int] | Coordinate places before / after the decimal |
| zero | 'L' or 'T' | Leading or trailing zero suppression |
| filetype | 'gerber' or 'drill' | Type of file |
A gerber parser has certain public properties. Any properties not listed here as public could be changed at any time.
The format object parser.format can be used once parsing has finished to determine any formatting decisions the parser made. Specifically, coordinate places format, zero suppression format, and filetype.
parser.on('end', function() {
console.log(parser.format)
})
// could print:
// {
// places: [2, 4],
// zero: 'L',
// filetype: 'gerber'
// }parser.line indicates the current line of the gerber file that the parser is processing at any given moment. After parsing is done, it will indicate one less than the number of lines the file contained (parser.line starts at 0).
Because the gerber parser is a Node stream, it is also an event emitter. In addition to the standard stream events, it will also emit certain other events.
A warning event is emitted if the parser encounters a recoverable problem while parsing the file. Typically, these warning are caused by elements that are deprecated in the current Gerber specification or missing information that will be replaced with assumptions by the parser.
// warning object
{message: WARNING_MESSAGE, line: LINE_NO_IN_GERBER}The parser will emit warnings when:
- It encounters a block it does not recognize (usually caused by deprecated and harmless commands)
- Missing coordinate format (will assume
[2, 4]) - Trailing zero suppression is used in a Gerber file (it has been deprecated by the Gerber spec)
- No zero suppression was specified (will assume leading suppression for Gerber and trailing suppression for drill)
- Deprecated or unrecognized macro primitives are used
Xis used instead ofxfor multiplication in a macro
An error event will be emitted with an Error object if the parser encounters an unrecoverable problem (in addition to the Node Transorm stream errors). Because of the way EventEmitters work, unless the error event has a listener attached, an emitted error will throw.
The only custom error event that the parser will throw is if it is unable to determine the filetype (Gerber or drill) of the input stream.
Given a gerber or drill file stream, the parser will emit a stream of plotter command objects. Objects are of the format:
{
type: COMMAND_TYPE,
line: GERBER_LINE_NO,
params...
}Objects that indicate the end of a Gerber file. This corresponds to the Gerber "end" command, not the end of the text stream. If the end of the text stream happens without receiving this command, the file has likely been accidentally truncated.
{
type: 'done',
line: GERBER_LINE_NO
}Commands used to set the state of the plotter.
{
type: 'set',
line: GERBER_LINE_NO,
prop: PROPERTY,
value: VAL
}| property | value | description |
|---|---|---|
mode |
i, cw, or ccw |
linear, CW-arc, or CCW-arc draw mode |
arc |
s or m |
single or multi-quadrant arc mode |
region |
true or false |
region mode on or off |
units |
mm or in |
units |
backupUnits |
mm or in |
backup units (used if units missing) |
epsilon |
[Number] |
threshold for comparing two coordinates |
nota |
A or I |
absolute or incremental coord notation |
backupNota |
A or I |
backup notation (used if missing) |
tool |
[Integer string] |
currently used tool code |
Commands used to move the plotter location and create image objects
{
type: 'op',
line: GERBER_LINE_NO,
op: OP_TYPE,
coord: COORDINATE
}where COORDINATE is a coordinate object and OP_TYPE is the type of operation:
| operation | description |
|---|---|
int |
interpolate (draw) to COORDINATE based on current tool and mode |
move |
move to COORDINATE without affecting the image |
flash |
add image of current tool to the layer image at COORDINATE |
last |
do whatever the last operation was (deprectated) |
A coordinate object is an object with the keys:
| key | description |
|---|---|
x |
x coordinate |
y |
y coordiate |
i |
(Optional) x-offset of arc center |
j |
(Optional) y-offset of arc center |
a |
(Optional) arc radius (mutually exclusive with i and j) |
Commands used to create new polarity or step-repeat image levels.
{
type: 'level',
line: GERBER_LINE_NO,
level: LEVEL_TYPE,
value: VAL
}| level type | val | description |
|---|---|---|
polarity |
C or D |
Clear or Dark image polarity |
stepRep |
{x: _, y: _, i: _, j: _} |
Steps in x and y at offsets i and j |
Commands used to create new tools.
{
type: 'tool',
line: GERBER_LINE_NO,
code: TOOL_CODE,
tool: TOOL_OBJECT
}where TOOL_CODE is the unique tool identifier in string format and TOOL_OBJECT is of the format:
{
shape: SHAPE,
params: SHAPE_PARAMS_ARRAY,
hole: HOLE_PARAMS_ARRAY
}There are five types of shapes available
| shape | parameters |
|---|---|
circle |
[DIA] |
rect |
[WIDTH, HEIGHT] |
obround |
[WIDTH, HEIGHT] |
poly |
[DIA, N_POINTS, ROTATION_IN_DEG] |
MACRO_NAME |
[$1, $2, ..., $N] |
Standard tools (i.e. not macros) may have a hole in the middle. The hole, if it exists, may be a circle or a rectangle (though rectangle holes are deprecated by the latest Gerber file specification).
| hole type | hole array |
|---|---|
| No hole | [] |
| Circle hole | [DIA] |
| Rectangle hole | [WIDTH, HEIGHT] |
Commands used to create new tool macros.
{
type: 'macro',
line: GERBER_LINE_NO,
name: MACRO_NAME,
blocks: MACRO_BLOCKS_ARRAY
}Where MACRO_NAME is the name of the macro being defined and MACRO_BLOCKS_ARRAY is an array of macro block objects.
A tool macro is composed of blocks. A macro block object has a type key that indicates the type of block.
A variable set block contains a function that takes the current set of macro modifiers (variables) and returns a new, modified set to use.
{type: 'variable', set: (mods) => mods}A primitive adjusts the macro image. All primitive objects have an exposure key exp that will be 0 if the primitive erases the existing image or 1 if it adds to the existing image. They also have a rotation in degrees key rot that will rotate the primitive around the macro image's origin.
All values in a primitive object will either be a Number or a function that takes the current modifier map and returns a number (mods) => Number
A comment primitive does nothing:
{type: 'commment'}A circle primitive adds a circle to the macro image:
{type: 'circle', exp, dia, cx, cy, rot}A vector primitive adds a stroke with width and endpoints (x1, y1) and (x2, y2):
{type: 'vect', exp, width, x1, y1, x2, y2, rot}A rectangle primitive adds a rectangle with width and height centered at (cx, cy):
{type: 'rect', exp, width, height, cx, cy, rot}A lower-left rectangle primitive adds a rectangle with width and height with its lower left point at at (x, y):
{type: 'rectLL', exp, width, height, x, y, rot}An outline primitive adds an outline polygon described by a points array of format [x1, y1, x2, y2, ..., xN, yN]:
{type: 'outline', exp, points, rot}An polygon primitive adds a regular polygon with circumcircle diameter dia, number of vertices vertices, and a center at (cx, cy):
{type: 'poly', exp, vertices, cx, cy, dia, rot}A moiré primitive adds a moiré (target) with center at (cx, cy), outer diameter dia, ring thickness ringThx, ring gap ringGap, maximum number of rings maxRings, crosshair line thickness crossThx, and crosshair line length crossLen:
{type: 'moire', exp, cx, cy, dia, ringThx, ringGap, maxRings, crossThx, crossLen, rot}A thermal primitive adds a thermal with center at (cx, cy), outer diameter outerDia, inner diameter innerDia, and ring gap gap:
{type: 'thermal', exp, cx, cy, outerDia, innerDia, gap, rot}