NAME

Data::Gerber

SYNOPSIS

my $gerb = Data::Gerber->new();

$gerb->format( 'zero' => 'L', 'coordinates' => 'A', 
               'format' => { 'integer'  => 2, 'decimal' => 4 } );
        
$gerb->mode('IN');

$gerb->aperture( 'code' => 'D11', 'type' => 'C', 'modifiers' => '0.0100' );

my $aper = $gerb->aperture( 'code' => 'D11' );

$gerb->function( 'aperture' => 'D11' );
$gerb->function( 'func' => 'G01', 'coord' => 'X010000Y010000', 'op' => 'D01' )
$gerb->function( 'func' => 'M02' );

DESCRIPTION

This Module is currently in "alpha" state and may contain numerous bugs or have partial implementations of the spec. Do not use in production systems.

Data::Gerber provides the capabilities to represent a series of RS-274X (commonly referred to as Gerber data) instructions in an object-oriented way, with methods and sub-classes for performing common activities such as:

Parsing Data from Files via Gerber::Parser

Writing Data to Files via Gerber::Writer

Determining Boundaries of Drawn Data

Basic Translations and Conversions of Data

METHODS

new

Constructor, creates a new instance of the class.

my $gerb = Gerber->new();

error

Returns the last set error, or undef if no error has been set

ignoreInvalid( FLAG )

Set or read the IgnoreInvalid flag.

When the IgnoreInvalid flag is set to any true value, any invalid or deprecated G-Codes or parameters will be ignored. When this flag is set to any false value an error will be generated.

The default flag value is 0, or false.

This method sets the flag if a flag argument is provided, or just reads the flag if the flag argument is not provided. This method always returns the current flag value, after any set operation.

ignoreBlank( FLAG )

Set or read the IgnoreBlank flag.

When the IgnoreBlank flag is set to any true value any drawing by a completely closed aperture (commonly used for comments, borders, etc.), after setting the flag, will be ignored when calculating the bounding box and size of the drawing area.

The default flag value is 0, or false.

This method sets the flag if a flag argument is provided, or just reads the flag if the flag argument is not provided. This method always returns the current flag value, after any set operation.

aperture( OPTS )

Add or Get a custom aperture, defined by OPTS.

Getting an Aperture that Has Been Defined

To get an aperture that has already been defined, provide only the 'code' key in OPTS, specifying the D-Code to retrieve, e.g.:

my $apt = $gerb->aperture( 'code' => 'D11' );

If the specified D-Code is found, a hashref will be returned with the following format:

{

  'code'      => D-code for aperture,
  'type'      => Aperture type (built-in or macro name)
  'modifiers' => String containing list of modifiers (if set)
  'diameter'  => diameter in format units (circle type only)
  
}

If the specified D-Code is not found, an empty hash ref will be returned.

If an invalid D-Code is specified, undef will be returned and the error will be set.

Creating an Aperture Definition

To create an aperture definition, you must provide at a minimum the following keys:

code    => the D-code to use for this aperture
type    => the type of aperture (C, R, O, P or aperture macro name)

Additionally, you may optionally supply a 'modifiers' key which provides any required modifiers.

Returns true (1) on success, or undef and sets the error on error.

For example:

if( ! $gerb->aperture( 'code' => 'D11', 'type' => 'C', 'modifiers' => 0.0100 ) ) {
        die $gerb->error();
}

apertures

Get All Defined Apertures

Returns a hashref with the following structure:

{
    aperture_code1 => {
        'type'       => Aperture type code or macro name
        'modifiers' => string containing list of modifiers,
        'diameter'   => diameter of circle in 'format' units (circle type only)
    },
    aperture_code2 => { ... },
    aperture_code3 => { ... },
    ...
}

mode( MODE )

Set or get the mode (units) for commands. The default mode is inches (IN).

If MODE is not specified, returns the current mode for the document without making any changes.

MODE can be one of:

IN (inches) or MM (millimeters)

Returns the specified mode if successful, or undef and sets the error if an error occurs.

# set mode
        if( ! $gerb->mode('MM') ) {
die $gerb->error();
        }
        
# get mode
        my $mode = $gerb->mode();
        
        

macro( MACRO_NAME, MACRO_DEF )

Set or get an aperture macro definition.

To get an existing macro definition, simply provide the name of the macro as MACRO_NAME. In this form, an arrayref will be returned specifying each line of the macro definition or undef if no such definition is found.

To set, or overwrite an existing macro, also provide an arrayref as MACRO_DEF with one element per line in the definition.

To set an aperture macro, provide the full macro definition string.

e.g.:

$gerb->macro('FOO', [ "0,1,2,3,4", "5,6,7,8" ] );

    # returns [  "0,1,2,3,4", "5,6,7,8" ]
my $macro = $gerb->macro('FOO');

macros

Get all set macros

Returns a hashref with following structure:

{
    macroName1 => [ def ],
    macroName2 => [ def ],
    ...
}

format( OPTS )

Set or retrieve the Format Specification for this object.

It is highly recommended to set the Format Specification first, before attempting to add commands, as the format has an impact on how certain area operations are performed

Retrieve Format Specification

To retrieve the format specification for this Gerber object, call the format method with no arguments, which will return the following hash reference:

{
        'zero'          => zero truncating setting
        'coordinates'   => coordinate mode
        'format'        => {
                'integer'       => # of integer places
                'decimal'       => # of decimal places
        }
}

 
 

Set Format Specification

To set the format specification, pass a set of hash keys and values as the argument to the method.

The following hash keys are supported:

zero

The zero omission setting, must be one of either L or T. (Representative of 'leading' and 'trailing' zero omission.) Any word that begins with L or T will function, which can be useful to write more readable code. The following are all equivalent:

'zero' => 'L'
'zero' => 'Lead'
'zero' => 'Leading'

coordinates

Which coordinate system to use, must be one of either A or I. (Representative of 'absolute' or 'incremental' coordinates.) Any word that begins with either A or I will function, which can be useful to write more readable code. The following at all equivalent:

'coordinates' => 'A'
'coordinates' => 'Abs'
'coordinates' => 'Absolute'
 

DO NOT USE INCREMENTAL COORDINATES

The use of incremental coordinates is strongly discouraged in the spec, and this module does not fully support them. Many features will not work properly with incremental coordinates. Simply put: do not use incremental coordinates.

Incremental coordinates are not to be confused with modality of coordinates. Full coordinate modality, as compliant with the spec, is supported.

format

The format of distances and values used in commands. As the specification requires that both X and Y format be the same, this module does not provide the ability to distinguish between the two.

The format of this entry is a hash reference, with the 'integer' and 'decimal' keys specifying the precision of integers and decimals in all numbers.

For example:

'format' => {
        'integer' => 5,
        'decimal' => 6
}

Note that 7 is the maximum format value.

Setting the format returns true (1) if successful, or returns undef and sets the error message in case of failure.

Example of setting the format specification:

if( ! $gerb->format( 'zero' => 'L', 'coordinates' => 'A', 'format' =>
    { 'integer' => 5, 'decimal' => 5 } ) ) {
    
    die $gerb->error();
}

You may specify any combination of specification values per call.

function( OPTS )

Add a function to the document.

Standard functions supported:

Aperture Select

G-Codes

Moves

Repeatable Parameter Calls

OPTS is a hash that provides one or more of the following keys, which define the function:

aperture Select the aperture to use for following functions

func

Function Code (i.e. G-Codes)

coord

Coordinate Data

op

Operation Code (i.e. D-Code)

param

Special parameter which can be repeated multiple times (e.g. LP, SR)

comment

A comment (used only with G04/G4, if you specify a comment for a non-G04 command, it may be useful in certain file writers that would automatically generate a new comment for you)

You can specify any combination which represents a valid function in Gerber notation, e.g.: func, coord, and op; coord and op, func; aperture; param

Note that if you specify an aperture or param key, all other keys are ignored.

The following are all valid function calls (presuming that you have already defined the apertures indicated, etc.):

$gerb->function( 'func' => 'G01', 'coord' => 'X001000Y001000', 'op' => 'D01' );
$gerb->function( 'func' => 'G01' );
$gerb->function( 'aperture' => 'D13' );
$gerb->function( 'coord' => 'Y-300', 'op' => 'D03' );
$gerb->function( 'func' => 'G04', 'comment' => 'My Comment' );

This method returns true (1) upon success, and undef and sets the error message on error.

Notes on Sequence

This library handles gerber data in a streaming fashion - that is, function sequences must be issued in the same order they would be issued in a file, as previous functions impact the interpretation of current functions.

All of your aperture, macro, and format specification activities should be done before creating functions.

functions( OPTS )

Count number of functions, or retrieve one or more functions.

When called with no arguments, this method returns all functions that have been added the document.

OPTS is a hash with any of the following keys:

count

Count number of functions in the document

num

Retrieve one function, the numth in the document (zero-indexed)

Examples:

my  $fCount = $gerb->functions( 'count' => 1 );
my $3rdFunc = $gerb->functions( 'num' => 2 );
my   @funcs = $gerb->functions();

This method returns undef, and sets the error message if an error occurs.

boundingBox

Returns the coordinates of a box which exactly holds the entire contents.

The result is an array with four elements, representing the Left-most X, Bottom-most Y, Right-most X, and Top-Most Y.

When considered as tuples of X, Y and corners, the first tuple would represent the bottom-left corner, and the second the top-right.

e.g.:

my ($lx, $by, $rx, $ty) = $gerb->boundingBox();

        # ex: 0, 0, 53.7, 123.0056

All values are floats, in the units specified by the format spec.

width

Returns the width of the bounding box, in native units as a decimal.

my $width = $gerb->width();

height

Returns the height of the bounding box, in native units as a decimal.

my $height = $gerb->height();

convert( NEW_OBJECT )

Translate the current gerber object instructions into a new type of gerber object, based on format, units, etc. NEW_OBJECT should be an initialized Data::Gerber object, with the format/unit/etc parameters specified.

After completion, NEW_OBJECT will represent the same functions and parameters as the current Gerber object, translated to the new set of formats.

Standard functions supported:

Aperture Select

G-Codes

Moves

Repeatable Parameter Calls

Warning: No Support for Aperture Macros!

AUTHOR

C. A. Church, D. Calderon, M. Smith MacroFab, Inc.

SEE ALSO

The Gerber File Format Specification