doc/dxfngc.xml (8e8b94d) - dxfngc · BlinkenArea

dxfngc.xml

<?xml version="1.0" encoding="utf-8"?>

<title>DXF to NGC Converter: dxfncg</title>

<title>Introduction</title>

<para>

The DXF to NGC converter <emphasis>dxfngc</emphasis> provides a
      means to convert 2D technical drawings in DXF file format to G-code
      in NGC format used by CNC mills or routers (e.g. LinuxCNC).

</para>

<para>

Usually, the 2D drawings in DXF format do not contain enough information
      for G-code creation, e.g. about which lines describe the border of a part
      and which lines describe holes.  The diameter of the cutting tool and the
      depth of the cut are other examples.  Therefore, dxfngc relies on a
      script file to control the G-code generation.  This script is the input
      to the tool.  It sets all required parameters, reads the drawing,
      controls generation of the G-code and finally writes the output file.

</para>

</sect1>

<title>A First Example</title>

<para>

To illustrate the usage of dxfngc, suppose a stencil for the
      <emphasis>BlinkenArea</emphasis> logo shall be cut with a CNC mill.  The
      basic shape of the stencil is a circle.  The logo is formed by two holes
      with a specific shape (see <xref linkend="logo_stencil"/>).

</para>

<figure xml:id="logo_stencil">
      <title>Logo Stencil</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="logo_stencil.svg" format="SVG" width="30%"/>
        </imageobject>
      </mediaobject>
      <caption>The logo stencil to be cut on the CNC mill.</caption>
    </figure>

<sect2>

<title>Creating the Drawing</title>

<para>

First, the 2D drawing is created with a CAD program in DXF format.  The
        circular border is drawn on layer <parameter>border</parameter> and the
        two holes are drawn on layer <parameter>holes</parameter> (see <xref
        linkend="logo_drawing"/>).

</para>

<figure xml:id="logo_drawing">
        <title>Logo Drawing</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="logo_drawing.svg" format="SVG" width="42%"/>
          </imageobject>
        </mediaobject>
        <caption>The CAD drawing of the logo stencil on 10mm grid.
                 Border and holes are on separate layers.</caption>
      </figure>

</sect2>

<sect2>

<title>Writing the Script</title>

<para>

The next step is to write the dxfngc script.  Such a script is shown in
        <xref linkend="logo_script"/>.  All lines starting with a hash
        character (<code>#</code>) are comments.  They will be ignored by
        dxfngc.  During processing of the script, dxfngc manages three three
        data objects in memory: the current settings, the current drawing and
        the list of G-code commands.  Initially, the settings are set to some
        reasonable defaults.  The drawing and the G-code are empty.

</para>

<para>

The first section of the example script fills the G-code list with
        some setup commands to configure the CNC mill.  This is done using
        the <code>cmd</code> command.  All the text folloing <code>cmd</code>
        is treated as a G-code command and is appended as a new command to
        the G-code list in memory.  Afterwards, the settings for processing the
        drawing to G-code are configured.  This includes the Z coordinates
        and the feed rates for moving and cutting as well as the diameter of
        the cutting tool.  Please see the <code>set_*</code> commands in
        <xref linkend="commands"/> for a description of all settings.

</para>

<para>

The <code>read_dxf</code> reads a CAD drawing in DXF format.  In this
        example, the logo drawing shown in <xref linkend="logo_drawing"/> is
        read.  This loads all layers of the DXF file to memory.  The layers can
        then be processed with the cutting commands (see <code>cut_*</code> in
        <xref linkend="commands"/>) to produce G-code.  The
        <code>cut_inside</code> command is used here to cut the holes.  It will
        calculate the path of the cutting tool to be half its diameter further
        to the inside of the holes.  This makes sure the hole has the desired
        size and shape after cutting - or more precise as close to it as
        possible with the selected cutting tool.  The <code>cut_outside</code>
        command is used for cutting the border of the stencil.  It basically
        works the same way, but moves the path of the cutting tool further to
        the outside.

</para>

<para>

After all G-code for cutting has been created, the G-code commands
        for finishing (e.g. turning off the CNC-mill) are appended using
        <code>cmd</code> like for the setup.  Finally, the G-code accumulated
        in memory is written to an output file useg <code>write_ngc</code>.

</para>

<figure xml:id="logo_script">
        <title>Logo Script</title>
        <programlisting><![CDATA[# add setup G-code commands
cmd G21
cmd G90
cmd G64 P0.01
cmd G17
cmd G40
cmd G49

# configure settings
set_precision 0.01
set_tool_diameter 3
set_move_z 5
set_base_z 0
set_cut_z -3.2
set_cut_z_step 1.1
set_feed_drill 100
set_feed_mill 200
set_layer_mode path_by_path

# read drawing
read_dxf logo.dxf

# generate G-code for actual cutting
cut_inside holes
cut_outside border

# add finishing G-code commands
cmd M2

# write G-code to output file
write_ngc logo.ngc]]></programlisting>
      </figure>

</sect2>

<sect2>

<title>Running the Script</title>

<para>

Once drawing and script are ready, the script can be run using the
        <code>dxfngc</code> tool.  (It is assumed here it has already been
        compiled. See <xref linkend="compiling"/> for compiling instructions.)
        As the script contains the filenames of input and output files, it is
        sufficient to provide the filename of the script file to dxfngc:

</para>

<para>

If everything goes well, this will produce a G-code file.  Otherwise an
        error message will be printed that informs about what went wrong.
        (There might also be some output like <code>dimeModel::largestHandle:
        65535</code>, which is coming from inside the DXF library used
        internally.  This output can be ignored.)
        <xref linkend="logo_g-code"/> shows the produced G-code rendered by
        LinuxCNC.

</para>

<figure xml:id="logo_g-code">
        <title>G-code for Logo Stencil</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="logo_g-code.png" format="PNG" width="100%"/>
          </imageobject>
        </mediaobject>
        <caption>G-code for the logo stencil, rendered by LinuxCNC.</caption>
      </figure>
    </sect2>

</sect1>

<title>Commands</title>

<para>

This section lists all commands available for use in the dxfngc scripts.
      For each command, it is described what it does and how it can be used.

</para>

<sect2>

<para>

The <code>cmd &lt;G-code&gt;</code> command append an arbitrary G-code
        command to the list of G-code commands in memory.  It is mainly used
        to generate initialization G-code at the beginning and cleanup G-code
        at the end of a script.

</para>

</sect2>

<sect2>

<para>

The <code>cut &lt;layer&gt;</code> command generates G-code to cut
        exactly at the lines of the specified layer from the loaded drawing
        using the current settings.  It does not compensate for the diameter
        of the cutting tool.  However, this command is able to process
        arbitrary drawings, especially drawings that contain curves that are
        not closed and/or do not form valid polygons.

</para>

</sect2>

<sect2>

<title>cut_inside</title>

<para>

The <code>cut_inside &lt;layer&gt;</code> command generates G-code to
        cut along the insides of the polygons contained in the specified layer
        using the current settings.  It tries to compensate for the for the
        diameter of the cutting tool as much as geometrically possible.

</para>

</sect2>

<sect2>

<title>cut_outside</title>

<para>

The <code>cut_outside &lt;layer&gt;</code> command generates G-code to
        cut along the outsides of the polygons contained in the specified layer
        using the current settings.  It tries to compensate for the for the
        diameter of the cutting tool as much as geometrically possible.

</para>

</sect2>

<sect2>

<title>cut_pcket</title>

<para>

The <code>cut_pocket &lt;layer&gt;</code> command generates G-code to
        cut away the inside of the polygons contained in the specified layer
        using the current settings.  It tries to compensate for the for the
        diameter of the cutting tool as much as geometrically possible.  The
        difference to the <code>cut_inside</code> command is that it does not
        only cut along the insides of the polygon outline.  Instead it will
        cover the entire area of the polygon.  This is useful if not cutting
        all the way (in Z direction) through the material, so the inner part
        will not fall out of the workpiece.  However, this comes at the cost of
        a long cutting path.

</para>

</sect2>

<sect2>

<para>

The command <code>read_dxf &lt;filename&gt;</code> discards the current
        drawing in memory and reads a 2D DXF drawing from the specified file.
        The filename may be an absolute path or a relative one.  If it is
        relative, it is interpreted relative to the directory of the script
        file being processed.  Whitespace and non-ASCII characters are not
        supported in the filename.  Most basic DXF primitives are supported.
        Unsupported DXF primitives (e.g. like text) are silently ignored.

</para>

</sect2>

<sect2>

<para>

The command <code>set_base_z &lt;z&gt;</code> sets the Z coordinate
        (in mm) at which cutting starts.  It is ususually set to the Z
        coordinate of the workpiece surface.  All floating point values are
        valid, the default is 0.

</para>

</sect2>

<sect2>

<para>

The command <code>set_cut_z &lt;z&gt;</code> sets the Z coordinate
        (in mm) to cut to.  For example, it is set to the Z coordinate of the
        workpiece bottom in order to cut through the entire workpiece.
        All floating point values are valid, the default is 0.

</para>

</sect2>

<sect2>

<para>

The command <code>set_cut_z &lt;z-step&gt;</code> sets the step size
        in Z direction (in mm) for cutting.  If the difference between base Z
        and cut Z coordinates are larger than the Z step size, the cut is done
        in multiple steps.  Each step cuts at as deep as the Z step size.
        Only positive floating point values are valid values for this setting.
        The default is 0.1.

</para>

</sect2>

<sect2>

<title>set_dwell_time</title>

<para>

The command <code>set_dwell_time &lt;time&gt;</code> sets the dwell
        time (in seconds).  The CNC machine will stop moving for this time
        before plunging downwards into the workpiece.  If the dwell time is
        set to zeor, no dwell command is put into the G-code.  A positive
        values causes generation of dwell commands with this time.  Negative
        values are not allowed.  The default is no dwelling.

</para>

</sect2>

<sect2>

<title>set_feed_drill</title>

<para>

The command <code>set_feed_drill &lt;feed&gt;</code> sets the feed rate
        (in mm per minute) for drilling into the material in Z direction.
        Only positive values are allowed for this setting, the default is 10.

</para>

</sect2>

<sect2>

<para>

The command <code>set_feed_mill &lt;feed&gt;</code> sets the feed rate
        (in mm per minute) for milling through the material in X/Y direction.
        Only positive values are allowed for this setting, the default is 10.

</para>

</sect2>

<sect2>

<title>set_layer_mode</title>

<para>

If a layer contains multiple polygons or paths and cutting happens in
        multiple steps in Z direction there are two possibilities to do the
        cutting, which are selected via the <code>set_layer_mode
        &lt;mode&gt;</code> command.  The <code>level_by_level</code> mode
        (which is the default) will process each polygon or path at the current
        cutting depth before moving the the next depth (i.e. the next Z step).
        The <code>path_by_path</code> mode will cut each polygon or path step
        by step until the cut Z coordinate is reached and then move to the next
        polygon or path.

</para>

</sect2>

<sect2>

<para>

The command <code>set_move_z &lt;z&gt;</code> sets the Z coordinate
        (in mm) at which movement between cuts is done.  It should be set high
        emough to not hit any obstacles during movements.  Setting it to a
        value too high will result in a lot of unneeded up/dowm movement
        between cuts.  All floating point values are valid, the default is 10.

</para>

</sect2>

<sect2>

<title>set_offset_x</title>

<para>

The command <code>set_offset_x &lt;x&gt;</code> sets an offset in X
        direction (in mm). All floating point values are valid, the default is
        0, i.e. no offset.

</para>

<para>

The coordinates from the drawing are rotated around the origin and the
        offsets in X and Y direction are added afterwards.  The resulting
        coordinate is then used for G-code generation.  This allows to adapt
        the coordinate system between the drawing and the CNC mill.  The offset
        can also be used to cut a workpiece drawn once at multiple positions.

</para>

</sect2>

<sect2>

<title>set_offset_y</title>

<para>

The command <code>set_offset_y &lt;y&gt;</code> sets an offset in X
        direction (in mm). All floating point values are valid, the default is
        0, i.e. no offset.

</para>

<para>

The coordinates from the drawing are rotated around the origin and
        the offsets in X and Y direction are added afterwards.  The resulting
        coordinate is then used for G-code generation.  This allows to adapt
        the coordinate system between the drawing and the CNC mill.  The offset
        can also be used to cut a workpiece drawn once at multiple positions.

</para>

</sect2>

<sect2>

<title>set_precision</title>

<para>

The command <code>set_precision &lt;precision&gt;</code> sets the
        precision to do all calculations with (in mm).  If the distance
        between two coordinates is less then the precision setting, they are
        considered equal for G-code generation.  Only positive floating point
        values smaller than 1 are valid, the default is 0.001.

</para>

</sect2>

<sect2>

<title>set_rotation_z</title>

<para>

The command <code>set_rotation_z &lt;angle&gt;</code> sets the rotation
        angle around the Z axis (in degrees, counter-clockwise). All floating
        point values are valid, the default is 0, i.e. no rotation.

</para>

<para>

The coordinates from the drawing are rotated around the origin and
        the offsets in X and Y direction are added afterwards.  The resulting
        coordinate is then used for G-code generation.  This allows to adapt
        the coordinate system between the drawing and the CNC mill.

</para>

</sect2>

<sect2>

<title>set_tool_diameter</title>

<para>

The command <code>set_tool_diameter &lt;diameter&gt;</code> sets the
        diameter of the cutting tool (in mm).  It is used in some of the
        <code>cut_*</code> commands.  Only non-negative floating
        point values are valid, the default is 1.

</para>

<para>

The dxfngc tool assumes a flat end mill is used.  If a cutting tool
        with another shape is used in the CNC mill, please note that the
        diameter compensation code assumes a fixed diameter of the tool over
        its whole length.  However, if this is kept in mind, it is also
        possible to use cutting tools with other shapes.

</para>

</sect2>

<sect2>

<title>write_ngc</title>

<para>

The command <code>write_ngc &lt;filename&gt;</code> writes the current
        list of G-code commands kept in memory to the specified file.  The
        filename may be an absolute path or a relative one.  If it is relative,
        it is interpreted relative to the directory of the script file being
        processed.  Whitespace and non-ASCII characters are not supported in
        the filename.  This command is usually used at the end of the script to
        output the generated G-code.

</para>

</sect2>

</sect1>

<title>Compiling</title>

<para>

To compile dxfngc, a C++ compiler and the following libraries have to be
      installed, including their development files:

</para>

<programlisting><![CDATA[libCGAL_Core (>= 3.6)
libCGAL (>= 3.6)
libdime (>= 2003-09-21)]]></programlisting>

<para>

To compile dxfngc, simply call <code>make</code> from the top-level
      directory.

</para>

<sect2>

<title>Compiling Documentation</title>

<para>

To compile the dxfngc documentation, <code>docbook (>= 5.0)</code>
        must be installed.

</para>

<para>

To compile the documentation, simply call <code>make</code> from the
        <code>doc</code> directory.

</para>

</sect2>

</sect1>

</article>

dxfngc

add compiling hints