@tracespace/parser
Version:
Gerber and NC drill file parser
470 lines (469 loc) • 14.8 kB
TypeScript
import { Position } from 'unist';
import * as Types from './types';
/**
* {@linkcode Root} node type
*
* @category Node
*/
export declare const ROOT = "root";
/**
* {@linkcode Comment} node type
*
* @category Node
*/
export declare const COMMENT = "comment";
/**
* {@linkcode Done} node type
*
* @category Node
*/
export declare const DONE = "done";
/**
* {@linkcode Units} node type
*
* @category Node
*/
export declare const UNITS = "units";
/**
* {@linkcode CoordinateFormat} node type
*
* @category Node
*/
export declare const COORDINATE_FORMAT = "coordinateFormat";
/**
* {@linkcode ToolDefinition} node type
*
* @category Node
*/
export declare const TOOL_DEFINITION = "toolDefinition";
/**
* {@linkcode ToolMacro} node type
*
* @category Node
*/
export declare const TOOL_MACRO = "toolMacro";
/**
* {@linkcode ToolChange} node type
*
* @category Node
*/
export declare const TOOL_CHANGE = "toolChange";
/**
* {@linkcode LoadPolarity} node type
*
* @category Node
*/
export declare const LOAD_POLARITY = "loadPolarity";
/**
* {@linkcode StepRepeat} node type
*
* @category Node
*/
export declare const STEP_REPEAT = "stepRepeat";
/**
* {@linkcode Graphic} node type
*
* @category Node
*/
export declare const GRAPHIC = "graphic";
/**
* {@linkcode InterpolateMode} node type
*
* @category Node
*/
export declare const INTERPOLATE_MODE = "interpolateMode";
/**
* {@linkcode RegionMode} node type
*
* @category Node
*/
export declare const REGION_MODE = "regionMode";
/**
* {@linkcode QuadrantMode} node type
*
* @category Node
*/
export declare const QUADRANT_MODE = "quadrantMode";
/**
* {@linkcode Unimplemented} node type
*
* @category Node
*/
export declare const UNIMPLEMENTED = "unimplemented";
/**
* {@linkcode MacroComment} node type
*
* @category Macro
*/
export declare const MACRO_COMMENT = "macroComment";
/**
* {@linkcode MacroVariable} node type
*
* @category Macro
*/
export declare const MACRO_VARIABLE = "macroVariable";
/**
* {@linkcode MacroPrimitive} node type
*
* @category Macro
*/
export declare const MACRO_PRIMITIVE = "macroPrimitive";
interface BaseNode {
type: string;
/** Location in the source file the node was parsed from */
position?: Position;
}
interface BaseParent extends BaseNode {
children: Array<BaseNode>;
}
/**
* Syntax tree node
*
* @category Node
*/
export declare type Node = Root | ChildNode;
/**
* Child of the tree's {@linkcode Root} node
*
* @category Node
*/
export declare type ChildNode = Comment | Done | Units | CoordinateFormat | ToolDefinition | ToolMacro | ToolChange | InterpolateMode | RegionMode | QuadrantMode | LoadPolarity | StepRepeat | Graphic | Unimplemented;
/**
* Child of a {@linkcode ToolMacro} node
*
* @category Macro
*/
export declare type MacroBlock = MacroComment | MacroVariable | MacroPrimitive;
/**
* Root node of the syntax tree, identifying the filetype and whether or not
* the entire file seems to have been read. Filetype, if known, will be
* either {@linkcode GERBER | gerber} or {@linkcode DRILL | drill}.
*
* If `filetype` is `null` or `done` is `false`, this may be a sign that
*
* 1. the parser has not finished parsing the file or
* 2. the file is invalid and/or not a Gerber or drill file.
*
* @category Node
*/
export interface Root extends BaseParent {
/** Node type */
type: typeof ROOT;
/** The parsed file's type (Gerber or NC drill), if known */
filetype: Types.Filetype | null;
/** Whether the parser has encountered a "done" command in the file */
done: boolean;
/** Parse results */
children: ChildNode[];
}
/**
* Node representing a comment in the file. Usually, comment nodes can be
* ignored, but in NC drill files, they may contain important format
* specifications that are not able to be expressed in the file itself.
*
* @category Node
*/
export interface Comment extends BaseNode {
/** Node type */
type: typeof COMMENT;
/** Contents of the comment as a string */
comment: string;
}
/**
* Node representing a done command. This represents an `M02` or `M00` command
* in a Gerber file or an `M00` or `M30` in an NC drill file. Its presence in a
* tree means the full source file was parsed.
*
* @category Node
*/
export interface Done extends BaseNode {
/** Node type */
type: typeof DONE;
}
/**
* A `Units` node specifies the units used for the file. Units may be
* {@linkcode IN | in} or {@linkcode MM | mm}.
*
* @category Node
*/
export interface Units extends BaseNode {
/** Node type */
type: typeof UNITS;
/** Inches or millimeters */
units: Types.UnitsType;
}
/**
* A `CoordinateFormat` node specifies the format of coordinate value strings.
*
* In Gerber and drill files, coordinates are (almost always) specified as
* strings of digits without decimal points. `format` is a tuple where the
* first element is the number of integer places in the string and the second
* is the number of decimal places. Leading or trailing zeros may also be
* omitted from the coordinate strings.
*
* For example, with `format` set to `[2, 4]`, some (intermediate) coordinate
* strings could be:
*
* - `0.012` > `000120`
* - `3.45` > `034500`
* - `67` > `670000`
*
* With those same numbers, either {@linkcode LEADING | leading} or
* {@linkcode TRAILING | trailing} zeros may be omitted depending on the
* `zeroSuppression` setting:
*
* - `0.012` > `000120` > leading omitted: `120`, trailing omitted: `00012`
* - `3.45` > `024500` > leading omitted: `24500`, trailing omitted: `0245`
* - `67` > `670000` > leading omitted: `670000`, trailing omitted: `67`
*
* Some important things to keep in mind when processing coordinate strings
* according to the `CoordinateFormat` node:
*
* - `format`, `zeroSuppression`, and/or `mode` could be left unspecified
* - In this case, `format` and `zeroSuppression` should be assumed or
* inferred, if possible
* - It's very safe to assume `mode` is always {@linkcode ABSOLUTE | absolute};
* {@linkcode INCREMENTAL | incremental} mode is deprecated and very rare
* - Just because `zeroSuppression` is set doesn't mean zeros are dropped
* - It's common to see Gerber writers keep all zeros to ensure there is no
* ambiguity, but `zeroSuppression` still needs to be set to _something_
* - A Gerber or NC drill file may choose to include decimal points! This is
* not necessarily "in spec", but it is unambiguous and easy to parse
*
* @category Node
*/
export interface CoordinateFormat extends BaseNode {
/** Node type */
type: typeof COORDINATE_FORMAT;
/** Integer/decimal format setting, if known */
format: Types.Format | null;
/** Zero suppression setting, if known */
zeroSuppression: Types.ZeroSuppression | null;
/** Absolute or incremental coordinate system, if known */
mode: Types.Mode | null;
}
/**
* A `ToolDefinition` node defines a "tool" that may be used to either create a
* shape ("pad" or "drill hit") or a stroke ("trace" or "route") in a later
* graphic command.
*
* A tool shape may be one of:
*
* - {@linkcode Circle} - A circle defined by a diameter
* - {@linkcode Rectangle} - A rectangle defined by sizes in the x and y axis
* - {@linkcode Obround} - A "pill" rectangle, with a border-radius equal to half of its shorter side
* - {@linkcode Polygon} - A regular polygon defined by its diameter, number of vertices, and rotation
* - {@linkcode MacroShape} - A shape defined by a previous {@linkcode ToolMacro}
*
* A tool may have a hole in its center; the `hole`, if not `null`, may be a:
*
* - {@linkcode Circle}
* - {@linkcode Rectangle} (deprecated by the Gerber specification)
*
* Only `Circle` or `Rectangle` tools without a `hole` may create strokes.
* `MacroShape` tools may not have a `hole` defined.
*
* @category Node
*/
export interface ToolDefinition extends BaseNode {
/** Node type */
type: typeof TOOL_DEFINITION;
/** Unique tool identifier */
code: string;
/** Tool shape */
shape: Types.ToolShape;
/** Hole shape, if applicable */
hole: Types.HoleShape | null;
}
/**
* A `ToolMacro` node describes a complex shape in a Gerber file that can use a
* variety of "primitives", simple arithmetic, and differing polarities to lay
* out an image that will later be repeated.
*
* See the {@link https://www.ucamco.com/gerber | Gerber file specification}
* for an in-depth description of how macros function.
*
* @category Node
*/
export interface ToolMacro extends BaseNode {
/** Node type */
type: typeof TOOL_MACRO;
/** Unique macro identifier */
name: string;
/** Macro definition blocks */
children: MacroBlock[];
}
/**
* A `MacroComment` represents a comment in a macro and can be safely ignored
*
* @category Macro
*/
export interface MacroComment extends BaseNode {
/** Node type */
type: typeof MACRO_COMMENT;
/** Comment string */
comment: string;
}
/**
* A `MacroVariable` node assigns a value to the `name` variable in a macro,
* where that value may be a number or an arithmetic expression.
*
* @category Macro
*/
export interface MacroVariable extends BaseNode {
/** Node type */
type: typeof MACRO_VARIABLE;
/** Variable name */
name: string;
/** Concrete value or expression to assign to variable */
value: Types.MacroValue;
}
/**
* A `MacroPrimitive` node describes a shape to add to the overall macro shape.
*
* @category Macro
*/
export interface MacroPrimitive extends BaseNode {
/** Node type */
type: typeof MACRO_PRIMITIVE;
/** Primitive shape type */
code: Types.MacroPrimitiveCode | string;
/** Shape modifier values or expressions */
modifiers: Types.MacroValue[];
}
/**
* A `ToolChange` node sets the current active "tool". At a given point in the
* file, the active tool determines the image that graphical operations produce.
*
* @category Node
*/
export interface ToolChange extends BaseNode {
/** Node type */
type: typeof TOOL_CHANGE;
/** Tool identifier */
code: string;
}
/**
* A `LoadPolarity` node sets the current polarity to {@linkcode DARK | dark}
* or {@linkcode CLEAR | clear}. Subsequent {@linkcode Graphic} operations
* add to the overall image if the polarity is "dark", or remove from the image
* if the polarity is "clear".
*
* @category Node
*/
export interface LoadPolarity extends BaseNode {
/** Node type */
type: typeof LOAD_POLARITY;
/** Polarity */
polarity: Types.Polarity;
}
/**
* A `StepRepeat` node starts or ends a step repeat block.
*
* See the {@link https://www.ucamco.com/gerber | Gerber file specification}
* for an in-depth description of step repeat blocks.
*
* @category Node
*/
export interface StepRepeat extends BaseNode {
/** Node type */
type: typeof STEP_REPEAT;
/** Step repeat parameters */
stepRepeat: Types.StepRepeatParameters;
}
/**
* A `Graphic` node that represents an image being draw to the active layer.
* The type of image "drawn" is dependent on the value of `graphic`:
*
* - {@linkcode SHAPE | shape} - the shape of the current tool is added to the
* image at `coordinates`
* - {@linkcode MOVE | move} - the plotter is "moved" to `coordinates` **without
* drawing anything to the image**
* - {@linkcode SEGMENT | segment} - the tool is "stroked" from the plotter's
* current location to `coordinates`
* - The path the tool takes is determined by the current {@linkcode IterpolateMode}
* - The segment may be a standalone path, or it may be a part of a region
* fill set by a {@linkcode RegionMode}
* - Only {@linkcode Circle} or {@linkcode Rectangle} tools may create
* standalone paths
* - {@linkcode SLOT | slot} - a drill-file-specific graphic that creates a
* slot from `(coordinates.x1, coordinates.y1)` to `(coordinates.x2, coordinates.y2)`
* - `null` - The graphic type was not explicitly specified in the source file
* - This is deprecated syntax in Gerber files, but if present the last
* used graphic type should be repeated
* - In a drill file, this means `shape` if in `drill` mode (default),
* `move` if in `move` mode, or `segment` if in a routing mode
*
* @category Node
*/
export interface Graphic extends BaseNode {
/** Node type */
type: typeof GRAPHIC;
/** Graphical operation */
graphic: Types.GraphicType;
/** Coordinates where the graphic will be applied */
coordinates: Types.Coordinates;
}
/**
* An `InterpolateMode` node is a command to define how subsequent `segment`
* (or `null`, if you're processing a drill file) graphic nodes are rendered.
* The `mode` may be one of:
*
* - {@linkcode LINE | line} - Draw a straight line segment
* - {@linkcode CW_ARC | cwArc} - Draw a clockwise arc segment
* - {@linkcode CCW_ARC | ccwArc} - Draw a counterclockwise arc segment
* - {@linkcode MOVE | move } - (Drill file only) Move the current coordinate without drawing
* - {@linkcode DRILL | drill} - (Drill file only) Draw a shape with the current tool
*
* @category Node
*/
export interface InterpolateMode extends BaseNode {
type: typeof INTERPOLATE_MODE;
mode: Types.InterpolateModeType;
}
/**
* A `RegionMode` node is a command to treat subsequent graphics as part of a
* region definition. Regions are typically used to describe things like
* copper fills, and only occur in Gerber files. In region mode:
*
* - `segment` graphics define the edges of the region
* - `move` graphics end the current region and start a new one
* - Other grahpics are disallowed
*
* @category Node
*/
export interface RegionMode extends BaseNode {
type: typeof REGION_MODE;
region: boolean;
}
/**
* A `QuadrantMode` node determines how subsequent arc segments are drawn.
*
* See the {@link https://www.ucamco.com/gerber | Gerber file specification}
* for an in-depth description of arc plotting.
*
* @category Node
*/
export interface QuadrantMode extends BaseNode {
type: typeof QUADRANT_MODE;
quadrant: Types.QuadrantModeType;
}
/**
* An `Unimplemented` node is a chunk that the parser recognizes as part of a
* Gerber file, but that it doesn't know how to process. These Nodes may be
* implemented in a future minor release of the parser and should be used with
* caution.
*
* Most unimplemented nodes will either be deprecated commands or valid
* commands in the {@link https://www.ucamco.com/gerber | Gerber specification}
* that we don't yet support.
*
* @category Node
*/
export interface Unimplemented extends BaseNode {
/** Node type */
type: typeof UNIMPLEMENTED;
/** String value of chunk */
value: string;
}
export {};