dxfngc

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

2) 

3) <article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">

4) 
5)   <title>DXF to NGC Converter: dxfncg</title>
6) 

7)   <sect1 xml:id="introduction">

8) 
9)     <title>Introduction</title>
10) 
11)     <para>
12) 

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

16) 
17)     </para>
18) 
19)     <para>
20) 
21)       Usually, the 2D drawings in DXF format do not contain enough information
22)       for G-code creation, e.g. about which lines describe the border of a part

23)       and which lines describe holes.  The diameter of the cutting tool and the
24)       depth of the cut are other examples.  Therefore, dxfngc relies on a
25)       script file to control the G-code generation.  This script is the input
26)       to the tool.  It sets all required parameters, reads the drawing,
27)       controls generation of the G-code and finally writes the output file.

28) 
29)     </para>
30) 
31)   </sect1>
32) 

33)   <sect1 xml:id="first_example">

34) 

35)     <title>A First Example</title>

36) 
37)     <para>
38) 

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

43) 
44)     </para>
45) 

46)     <figure xml:id="logo_stencil">
47)       <title>Logo Stencil</title>
48)       <mediaobject>
49)         <imageobject>
50)           <imagedata fileref="logo_stencil.svg" format="SVG" width="30%"/>
51)         </imageobject>
52)       </mediaobject>
53)       <caption>The logo stencil to be cut on the CNC mill.</caption>
54)     </figure>
55) 

56)     <sect2>
57) 
58)       <title>Creating the Drawing</title>
59) 
60)       <para>
61) 
62)         First, the 2D drawing is created with a CAD program in DXF format.  The
63)         circular border is drawn on layer <parameter>border</parameter> and the
64)         two holes are drawn on layer <parameter>holes</parameter> (see <xref
65)         linkend="logo_drawing"/>).
66) 
67)       </para>
68) 
69)       <figure xml:id="logo_drawing">
70)         <title>Logo Drawing</title>
71)         <mediaobject>
72)           <imageobject>
73)             <imagedata fileref="logo_drawing.svg" format="SVG" width="42%"/>
74)           </imageobject>
75)         </mediaobject>
76)         <caption>The CAD drawing of the logo stencil on 10mm grid.
77)                  Border and holes are on separate layers.</caption>
78)       </figure>

79) 

80)     </sect2>

81) 

82)     <sect2>

83) 

84)       <title>Writing the Script</title>
85) 
86)       <para>
87) 
88)         The next step is to write the dxfngc script.  Such a script is shown in
89)         <xref linkend="logo_script"/>.  All lines starting with a hash
90)         character (<code>#</code>) are comments.  They will be ignored by
91)         dxfngc.  During processing of the script, dxfngc manages three three
92)         data objects in memory: the current settings, the current drawing and
93)         the list of G-code commands.  Initially, the settings are set to some
94)         reasonable defaults.  The drawing and the G-code are empty.
95) 
96)       </para>
97) 
98)       <para>
99) 
100)         The first section of the example script fills the G-code list with
101)         some setup commands to configure the CNC mill.  This is done using
102)         the <code>cmd</code> command.  All the text folloing <code>cmd</code>
103)         is treated as a G-code command and is appended as a new command to
104)         the G-code list in memory.  Afterwards, the settings for processing the
105)         drawing to G-code are configured.  This includes the Z coordinates
106)         and the feed rates for moving and cutting as well as the diameter of

107)         the cutting tool.  Please see the <code>set_*</code> commands in
108)         <xref linkend="commands"/> for a description of all settings.

109) 

110)       </para>
111) 
112)       <para>
113) 
114)         The <code>read_dxf</code> reads a CAD drawing in DXF format.  In this
115)         example, the logo drawing shown in <xref linkend="logo_drawing"/> is
116)         read.  This loads all layers of the DXF file to memory.  The layers can

117)         then be processed with the cutting commands (see <code>cut_*</code> in
118)         <xref linkend="commands"/>) to produce G-code.  The
119)         <code>cut_inside</code> command is used here to cut the holes.  It will
120)         calculate the path of the cutting tool to be half its diameter further
121)         to the inside of the holes.  This makes sure the hole has the desired
122)         size and shape after cutting - or more precise as close to it as
123)         possible with the selected cutting tool.  The <code>cut_outside</code>
124)         command is used for cutting the border of the stencil.  It basically
125)         works the same way, but moves the path of the cutting tool further to
126)         the outside.

127) 
128)       </para>
129) 
130)       <para>
131) 
132)         After all G-code for cutting has been created, the G-code commands
133)         for finishing (e.g. turning off the CNC-mill) are appended using
134)         <code>cmd</code> like for the setup.  Finally, the G-code accumulated
135)         in memory is written to an output file useg <code>write_ngc</code>.
136) 
137)       </para>
138) 
139)       <figure xml:id="logo_script">
140)         <title>Logo Script</title>
141)         <programlisting><![CDATA[# add setup G-code commands
142) cmd G21
143) cmd G90
144) cmd G64 P0.01
145) cmd G17
146) cmd G40
147) cmd G49
148) 
149) # configure settings
150) set_precision 0.01
151) set_tool_diameter 3
152) set_move_z 5
153) set_base_z 0
154) set_cut_z -3.2
155) set_cut_z_step 1.1
156) set_feed_drill 100
157) set_feed_mill 200
158) set_layer_mode path_by_path
159) 
160) # read drawing
161) read_dxf logo.dxf
162) 
163) # generate G-code for actual cutting
164) cut_inside holes
165) cut_outside border
166) 
167) # add finishing G-code commands
168) cmd M2
169) 
170) # write G-code to output file
171) write_ngc logo.ngc]]></programlisting>
172)       </figure>
173) 
174)     </sect2>
175) 
176)     <sect2>
177) 
178)       <title>Running the Script</title>
179) 
180)       <para>
181) 
182)         Once drawing and script are ready, the script can be run using the
183)         <code>dxfngc</code> tool.  (It is assumed here it has already been

184)         compiled. See <xref linkend="compiling"/> for compiling instructions.)
185)         As the script contains the filenames of input and output files, it is
186)         sufficient to provide the filename of the script file to dxfngc:

187) 
188)       </para>
189) 
190)       <programlisting><![CDATA[./dxfngc logo.txt]]></programlisting>
191) 
192)       <para>
193) 
194)         If everything goes well, this will produce a G-code file.  Otherwise an
195)         error message will be printed that informs about what went wrong.
196)         (There might also be some output like <code>dimeModel::largestHandle:
197)         65535</code>, which is coming from inside the DXF library used
198)         internally.  This output can be ignored.)
199)         <xref linkend="logo_g-code"/> shows the produced G-code rendered by
200)         LinuxCNC.
201) 
202)       </para>
203) 
204)       <figure xml:id="logo_g-code">
205)         <title>G-code for Logo Stencil</title>
206)         <mediaobject>
207)           <imageobject>
208)             <imagedata fileref="logo_g-code.png" format="PNG" width="100%"/>
209)           </imageobject>
210)         </mediaobject>
211)         <caption>G-code for the logo stencil, rendered by LinuxCNC.</caption>
212)       </figure>
213)     </sect2>

214) 

215)   </sect1>
216) 

217)   <sect1 xml:id="commands">
218) 
219)     <title>Commands</title>
220) 

221)     <para>
222) 
223)       This section lists all commands available for use in the dxfngc scripts.
224)       For each command, it is described what it does and how it can be used.
225) 
226)     </para>
227) 

228)     <sect2>
229) 
230)       <title>clear_ngc</title>
231) 
232)       <para>
233) 
234)         The command <code>clear_ngc</code> cleares the current list of G-code
235)         commands kept in memory.  This command is usually used after writing
236)         the G-code to a file, before generating another G-code sequence from
237)         the same script.
238) 
239)       </para>
240) 
241)     </sect2>
242) 

243)     <sect2>
244) 
245)       <title>cmd</title>
246) 
247)       <para>
248) 
249)         The <code>cmd &lt;G-code&gt;</code> command append an arbitrary G-code
250)         command to the list of G-code commands in memory.  It is mainly used
251)         to generate initialization G-code at the beginning and cleanup G-code
252)         at the end of a script.
253) 
254)       </para>
255) 
256)     </sect2>
257) 
258)     <sect2>
259) 
260)       <title>cut</title>
261) 
262)       <para>
263) 
264)         The <code>cut &lt;layer&gt;</code> command generates G-code to cut
265)         exactly at the lines of the specified layer from the loaded drawing
266)         using the current settings.  It does not compensate for the diameter
267)         of the cutting tool.  However, this command is able to process
268)         arbitrary drawings, especially drawings that contain curves that are
269)         not closed and/or do not form valid polygons.
270) 
271)       </para>
272) 
273)     </sect2>
274) 
275)     <sect2>
276) 
277)       <title>cut_inside</title>
278) 
279)       <para>
280) 
281)         The <code>cut_inside &lt;layer&gt;</code> command generates G-code to
282)         cut along the insides of the polygons contained in the specified layer
283)         using the current settings.  It tries to compensate for the for the
284)         diameter of the cutting tool as much as geometrically possible.
285) 
286)       </para>
287) 
288)     </sect2>
289) 
290)     <sect2>
291) 
292)       <title>cut_outside</title>
293) 
294)       <para>
295) 
296)         The <code>cut_outside &lt;layer&gt;</code> command generates G-code to
297)         cut along the outsides of the polygons contained in the specified layer
298)         using the current settings.  It tries to compensate for the for the
299)         diameter of the cutting tool as much as geometrically possible.
300) 
301)       </para>
302) 
303)     </sect2>
304) 
305)     <sect2>
306) 
307)       <title>cut_pcket</title>
308) 
309)       <para>
310) 
311)         The <code>cut_pocket &lt;layer&gt;</code> command generates G-code to
312)         cut away the inside of the polygons contained in the specified layer
313)         using the current settings.  It tries to compensate for the for the
314)         diameter of the cutting tool as much as geometrically possible.  The
315)         difference to the <code>cut_inside</code> command is that it does not
316)         only cut along the insides of the polygon outline.  Instead it will
317)         cover the entire area of the polygon.  This is useful if not cutting
318)         all the way (in Z direction) through the material, so the inner part
319)         will not fall out of the workpiece.  However, this comes at the cost of
320)         a long cutting path.
321) 
322)       </para>
323) 
324)     </sect2>
325) 
326)     <sect2>
327) 
328)       <title>read_dxf</title>
329) 
330)       <para>
331) 
332)         The command <code>read_dxf &lt;filename&gt;</code> discards the current
333)         drawing in memory and reads a 2D DXF drawing from the specified file.
334)         The filename may be an absolute path or a relative one.  If it is
335)         relative, it is interpreted relative to the directory of the script
336)         file being processed.  Whitespace and non-ASCII characters are not
337)         supported in the filename.  Most basic DXF primitives are supported.
338)         Unsupported DXF primitives (e.g. like text) are silently ignored.
339) 
340)       </para>
341) 
342)     </sect2>
343) 
344)     <sect2>
345) 
346)       <title>set_base_z</title>
347) 
348)       <para>
349) 
350)         The command <code>set_base_z &lt;z&gt;</code> sets the Z coordinate
351)         (in mm) at which cutting starts.  It is ususually set to the Z
352)         coordinate of the workpiece surface.  All floating point values are
353)         valid, the default is 0.
354) 
355)       </para>
356) 
357)     </sect2>
358) 
359)     <sect2>
360) 
361)       <title>set_cut_z</title>
362) 
363)       <para>
364) 
365)         The command <code>set_cut_z &lt;z&gt;</code> sets the Z coordinate
366)         (in mm) to cut to.  For example, it is set to the Z coordinate of the
367)         workpiece bottom in order to cut through the entire workpiece.
368)         All floating point values are valid, the default is 0.
369) 
370)       </para>
371) 
372)     </sect2>
373) 
374)     <sect2>
375) 
376)       <title>set_cut_z_step</title>
377) 
378)       <para>
379) 
380)         The command <code>set_cut_z &lt;z-step&gt;</code> sets the step size
381)         in Z direction (in mm) for cutting.  If the difference between base Z
382)         and cut Z coordinates are larger than the Z step size, the cut is done
383)         in multiple steps.  Each step cuts at as deep as the Z step size.
384)         Only positive floating point values are valid values for this setting.
385)         The default is 0.1.
386) 
387)       </para>
388) 
389)     </sect2>
390) 
391)     <sect2>
392) 
393)       <title>set_dwell_time</title>
394) 
395)       <para>
396) 
397)         The command <code>set_dwell_time &lt;time&gt;</code> sets the dwell
398)         time (in seconds).  The CNC machine will stop moving for this time
399)         before plunging downwards into the workpiece.  If the dwell time is
400)         set to zeor, no dwell command is put into the G-code.  A positive
401)         values causes generation of dwell commands with this time.  Negative
402)         values are not allowed.  The default is no dwelling.
403) 
404)       </para>
405) 
406)     </sect2>
407) 
408)     <sect2>
409) 
410)       <title>set_feed_drill</title>
411) 
412)       <para>
413) 
414)         The command <code>set_feed_drill &lt;feed&gt;</code> sets the feed rate
415)         (in mm per minute) for drilling into the material in Z direction.
416)         Only positive values are allowed for this setting, the default is 10.
417) 
418)       </para>
419) 
420)     </sect2>
421) 
422)     <sect2>
423) 
424)       <title>set_feed_mill</title>
425) 
426)       <para>
427) 
428)         The command <code>set_feed_mill &lt;feed&gt;</code> sets the feed rate
429)         (in mm per minute) for milling through the material in X/Y direction.
430)         Only positive values are allowed for this setting, the default is 10.
431) 
432)       </para>
433) 
434)     </sect2>
435) 
436)     <sect2>
437) 
438)       <title>set_layer_mode</title>
439) 
440)       <para>
441) 
442)         If a layer contains multiple polygons or paths and cutting happens in
443)         multiple steps in Z direction there are two possibilities to do the
444)         cutting, which are selected via the <code>set_layer_mode
445)         &lt;mode&gt;</code> command.  The <code>level_by_level</code> mode
446)         (which is the default) will process each polygon or path at the current
447)         cutting depth before moving the the next depth (i.e. the next Z step).
448)         The <code>path_by_path</code> mode will cut each polygon or path step
449)         by step until the cut Z coordinate is reached and then move to the next
450)         polygon or path.
451) 
452)       </para>
453) 
454)     </sect2>
455) 
456)     <sect2>
457) 
458)       <title>set_move_z</title>
459) 
460)       <para>
461) 
462)         The command <code>set_move_z &lt;z&gt;</code> sets the Z coordinate
463)         (in mm) at which movement between cuts is done.  It should be set high
464)         emough to not hit any obstacles during movements.  Setting it to a
465)         value too high will result in a lot of unneeded up/dowm movement
466)         between cuts.  All floating point values are valid, the default is 10.
467) 
468)       </para>
469) 
470)     </sect2>
471) 
472)     <sect2>
473) 
474)       <title>set_offset_x</title>
475) 
476)       <para>
477) 
478)         The command <code>set_offset_x &lt;x&gt;</code> sets an offset in X
479)         direction (in mm). All floating point values are valid, the default is
480)         0, i.e. no offset.
481) 
482)       </para>
483) 
484)       <para>
485) 

486)         The coordinates from the drawing are scaled using different factors
487)         for X and Y directions, rotated around the origin and the offsets in
488)         X and Y direction are added afterwards.  The resulting coordinate is
489)         then used for G-code generation.  This allows to adapt the coordinate
490)         system between the drawing and the CNC mill.  The offset can also be
491)         used to cut a workpiece drawn once at multiple positions.

492) 
493)       </para>
494) 
495)     </sect2>
496) 
497)     <sect2>
498) 
499)       <title>set_offset_y</title>
500) 
501)       <para>
502) 
503)         The command <code>set_offset_y &lt;y&gt;</code> sets an offset in X
504)         direction (in mm). All floating point values are valid, the default is
505)         0, i.e. no offset.
506) 
507)       </para>
508) 
509)       <para>
510) 

511)         The coordinates from the drawing are scaled using different factors
512)         for X and Y directions, rotated around the origin and the offsets in
513)         X and Y direction are added afterwards.  The resulting coordinate is
514)         then used for G-code generation.  This allows to adapt the coordinate
515)         system between the drawing and the CNC mill.  The offset can also be
516)         used to cut a workpiece drawn once at multiple positions.

517) 
518)       </para>
519) 
520)     </sect2>
521) 
522)     <sect2>
523) 
524)       <title>set_precision</title>
525) 
526)       <para>
527) 
528)         The command <code>set_precision &lt;precision&gt;</code> sets the
529)         precision to do all calculations with (in mm).  If the distance
530)         between two coordinates is less then the precision setting, they are
531)         considered equal for G-code generation.  Only positive floating point
532)         values smaller than 1 are valid, the default is 0.001.
533) 
534)       </para>
535) 
536)     </sect2>
537) 
538)     <sect2>
539) 
540)       <title>set_rotation_z</title>
541) 
542)       <para>
543) 
544)         The command <code>set_rotation_z &lt;angle&gt;</code> sets the rotation
545)         angle around the Z axis (in degrees, counter-clockwise). All floating
546)         point values are valid, the default is 0, i.e. no rotation.
547) 
548)       </para>
549) 
550)       <para>
551) 

552)         The coordinates from the drawing are scaled using different factors
553)         for X and Y directions, rotated around the origin and the offsets in
554)         X and Y direction are added afterwards.  The resulting coordinate is
555)         then used for G-code generation.  This allows to adapt the coordinate
556)         system between the drawing and the CNC mill.
557) 
558)       </para>
559) 
560)     </sect2>
561) 
562)     <sect2>
563) 
564)       <title>set_scale_x</title>
565) 
566)       <para>
567) 
568)         The command <code>set_scale_x &lt;x&gt;</code> sets a scaling factor
569)         for the X direction.  All floating point values are valid, the default
570)         is 1, i.e. no scaling.
571) 
572)       </para>
573) 
574)       <para>
575) 
576)         The coordinates from the drawing are scaled using different factors
577)         for X and Y directions, rotated around the origin and the offsets in
578)         X and Y direction are added afterwards.  The resulting coordinate is
579)         then used for G-code generation.  This allows to adapt the coordinate
580)         system between the drawing and the CNC mill.  The scaling can also be
581)         used to mirror a drawing by setting it to -1.
582) 
583)       </para>
584) 
585)     </sect2>
586) 
587)     <sect2>
588) 
589)       <title>set_scale_y</title>
590) 
591)       <para>
592) 
593)         The command <code>set_scale_y &lt;x&gt;</code> sets a scaling factor
594)         for  the Y direction.  All floating point values are valid, the default
595)         is 1, i.e. no scaling.
596) 
597)       </para>
598) 
599)       <para>
600) 
601)         The coordinates from the drawing are scaled using different factors
602)         for X and Y directions, rotated around the origin and the offsets in
603)         X and Y direction are added afterwards.  The resulting coordinate is
604)         then used for G-code generation.  This allows to adapt the coordinate
605)         system between the drawing and the CNC mill.  The scaling can also be
606)         used to mirror a drawing by setting it to -1.

607) 
608)       </para>
609) 
610)     </sect2>
611) 
612)     <sect2>
613) 
614)       <title>set_tool_diameter</title>
615) 
616)       <para>
617) 
618)         The command <code>set_tool_diameter &lt;diameter&gt;</code> sets the
619)         diameter of the cutting tool (in mm).  It is used in some of the
620)         <code>cut_*</code> commands.  Only non-negative floating
621)         point values are valid, the default is 1.
622) 
623)       </para>
624) 
625)       <para>
626) 
627)         The dxfngc tool assumes a flat end mill is used.  If a cutting tool
628)         with another shape is used in the CNC mill, please note that the
629)         diameter compensation code assumes a fixed diameter of the tool over
630)         its whole length.  However, if this is kept in mind, it is also
631)         possible to use cutting tools with other shapes.
632) 
633)       </para>
634) 
635)     </sect2>
636) 
637)     <sect2>
638) 
639)       <title>write_ngc</title>
640) 
641)       <para>
642) 
643)         The command <code>write_ngc &lt;filename&gt;</code> writes the current
644)         list of G-code commands kept in memory to the specified file.  The
645)         filename may be an absolute path or a relative one.  If it is relative,
646)         it is interpreted relative to the directory of the script file being
647)         processed.  Whitespace and non-ASCII characters are not supported in
648)         the filename.  This command is usually used at the end of the script to
649)         output the generated G-code.
650) 
651)       </para>
652) 
653)     </sect2>
654) 
655)   </sect1>
656) 

657)   <sect1 xml:id="compiling">
658) 
659)     <title>Compiling</title>
660) 
661)     <para>
662) 
663)       To compile dxfngc, a C++ compiler and the following libraries have to be
664)       installed, including their development files:
665) 
666)     </para>
667) 
668)     <programlisting><![CDATA[libCGAL_Core (>= 3.6)
669) libCGAL (>= 3.6)
670) libdime (>= 2003-09-21)]]></programlisting>
671) 
672)     <para>
673) 
674)       To compile dxfngc, simply call <code>make</code> from the top-level
675)       directory.
676) 
677)     </para>
678) 
679)     <sect2>
680) 
681)       <title>Compiling Documentation</title>
682) 
683)       <para>
684) 
685)         To compile the dxfngc documentation, <code>docbook (>= 5.0)</code>
686)         must be installed.
687) 
688)       </para>
689) 
690)       <para>
691) 
692)         To compile the documentation, simply call <code>make</code> from the
693)         <code>doc</code> directory.
694) 
695)       </para>
696) 
697)     </sect2>
698) 
699)   </sect1>
700)