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 !!!TODO!!! for instruction for compiling.)  As the script
185)         contains the filenames of input and output files, it is sufficient to
186)         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)     <sect2>
222) 
223)       <title>cmd</title>
224) 
225)       <para>
226) 
227)         The <code>cmd &lt;G-code&gt;</code> command append an arbitrary G-code
228)         command to the list of G-code commands in memory.  It is mainly used
229)         to generate initialization G-code at the beginning and cleanup G-code
230)         at the end of a script.
231) 
232)       </para>
233) 
234)     </sect2>
235) 
236)     <sect2>
237) 
238)       <title>cut</title>
239) 
240)       <para>
241) 
242)         The <code>cut &lt;layer&gt;</code> command generates G-code to cut
243)         exactly at the lines of the specified layer from the loaded drawing
244)         using the current settings.  It does not compensate for the diameter
245)         of the cutting tool.  However, this command is able to process
246)         arbitrary drawings, especially drawings that contain curves that are
247)         not closed and/or do not form valid polygons.
248) 
249)       </para>
250) 
251)     </sect2>
252) 
253)     <sect2>
254) 
255)       <title>cut_inside</title>
256) 
257)       <para>
258) 
259)         The <code>cut_inside &lt;layer&gt;</code> command generates G-code to
260)         cut along the insides of the polygons contained in the specified layer
261)         using the current settings.  It tries to compensate for the for the
262)         diameter of the cutting tool as much as geometrically possible.
263) 
264)       </para>
265) 
266)     </sect2>
267) 
268)     <sect2>
269) 
270)       <title>cut_outside</title>
271) 
272)       <para>
273) 
274)         The <code>cut_outside &lt;layer&gt;</code> command generates G-code to
275)         cut along the outsides of the polygons contained in the specified layer
276)         using the current settings.  It tries to compensate for the for the
277)         diameter of the cutting tool as much as geometrically possible.
278) 
279)       </para>
280) 
281)     </sect2>
282) 
283)     <sect2>
284) 
285)       <title>cut_pcket</title>
286) 
287)       <para>
288) 
289)         The <code>cut_pocket &lt;layer&gt;</code> command generates G-code to
290)         cut away the inside of the polygons contained in the specified layer
291)         using the current settings.  It tries to compensate for the for the
292)         diameter of the cutting tool as much as geometrically possible.  The
293)         difference to the <code>cut_inside</code> command is that it does not
294)         only cut along the insides of the polygon outline.  Instead it will
295)         cover the entire area of the polygon.  This is useful if not cutting
296)         all the way (in Z direction) through the material, so the inner part
297)         will not fall out of the workpiece.  However, this comes at the cost of
298)         a long cutting path.
299) 
300)       </para>
301) 
302)     </sect2>
303) 
304)     <sect2>
305) 
306)       <title>read_dxf</title>
307) 
308)       <para>
309) 
310)         The command <code>read_dxf &lt;filename&gt;</code> discards the current
311)         drawing in memory and reads a 2D DXF drawing from the specified file.
312)         The filename may be an absolute path or a relative one.  If it is
313)         relative, it is interpreted relative to the directory of the script
314)         file being processed.  Whitespace and non-ASCII characters are not
315)         supported in the filename.  Most basic DXF primitives are supported.
316)         Unsupported DXF primitives (e.g. like text) are silently ignored.
317) 
318)       </para>
319) 
320)     </sect2>
321) 
322)     <sect2>
323) 
324)       <title>set_base_z</title>
325) 
326)       <para>
327) 
328)         The command <code>set_base_z &lt;z&gt;</code> sets the Z coordinate
329)         (in mm) at which cutting starts.  It is ususually set to the Z
330)         coordinate of the workpiece surface.  All floating point values are
331)         valid, the default is 0.
332) 
333)       </para>
334) 
335)     </sect2>
336) 
337)     <sect2>
338) 
339)       <title>set_cut_z</title>
340) 
341)       <para>
342) 
343)         The command <code>set_cut_z &lt;z&gt;</code> sets the Z coordinate
344)         (in mm) to cut to.  For example, it is set to the Z coordinate of the
345)         workpiece bottom in order to cut through the entire workpiece.
346)         All floating point values are valid, the default is 0.
347) 
348)       </para>
349) 
350)     </sect2>
351) 
352)     <sect2>
353) 
354)       <title>set_cut_z_step</title>
355) 
356)       <para>
357) 
358)         The command <code>set_cut_z &lt;z-step&gt;</code> sets the step size
359)         in Z direction (in mm) for cutting.  If the difference between base Z
360)         and cut Z coordinates are larger than the Z step size, the cut is done
361)         in multiple steps.  Each step cuts at as deep as the Z step size.
362)         Only positive floating point values are valid values for this setting.
363)         The default is 0.1.
364) 
365)       </para>
366) 
367)     </sect2>
368) 
369)     <sect2>
370) 
371)       <title>set_dwell_time</title>
372) 
373)       <para>
374) 
375)         The command <code>set_dwell_time &lt;time&gt;</code> sets the dwell
376)         time (in seconds).  The CNC machine will stop moving for this time
377)         before plunging downwards into the workpiece.  If the dwell time is
378)         set to zeor, no dwell command is put into the G-code.  A positive
379)         values causes generation of dwell commands with this time.  Negative
380)         values are not allowed.  The default is no dwelling.
381) 
382)       </para>
383) 
384)     </sect2>
385) 
386)     <sect2>
387) 
388)       <title>set_feed_drill</title>
389) 
390)       <para>
391) 
392)         The command <code>set_feed_drill &lt;feed&gt;</code> sets the feed rate
393)         (in mm per minute) for drilling into the material in Z direction.
394)         Only positive values are allowed for this setting, the default is 10.
395) 
396)       </para>
397) 
398)     </sect2>
399) 
400)     <sect2>
401) 
402)       <title>set_feed_mill</title>
403) 
404)       <para>
405) 
406)         The command <code>set_feed_mill &lt;feed&gt;</code> sets the feed rate
407)         (in mm per minute) for milling through the material in X/Y direction.
408)         Only positive values are allowed for this setting, the default is 10.
409) 
410)       </para>
411) 
412)     </sect2>
413) 
414)     <sect2>
415) 
416)       <title>set_layer_mode</title>
417) 
418)       <para>
419) 
420)         If a layer contains multiple polygons or paths and cutting happens in
421)         multiple steps in Z direction there are two possibilities to do the
422)         cutting, which are selected via the <code>set_layer_mode
423)         &lt;mode&gt;</code> command.  The <code>level_by_level</code> mode
424)         (which is the default) will process each polygon or path at the current
425)         cutting depth before moving the the next depth (i.e. the next Z step).
426)         The <code>path_by_path</code> mode will cut each polygon or path step
427)         by step until the cut Z coordinate is reached and then move to the next
428)         polygon or path.
429) 
430)       </para>
431) 
432)     </sect2>
433) 
434)     <sect2>
435) 
436)       <title>set_move_z</title>
437) 
438)       <para>
439) 
440)         The command <code>set_move_z &lt;z&gt;</code> sets the Z coordinate
441)         (in mm) at which movement between cuts is done.  It should be set high
442)         emough to not hit any obstacles during movements.  Setting it to a
443)         value too high will result in a lot of unneeded up/dowm movement
444)         between cuts.  All floating point values are valid, the default is 10.
445) 
446)       </para>
447) 
448)     </sect2>
449) 
450)     <sect2>
451) 
452)       <title>set_offset_x</title>
453) 
454)       <para>
455) 
456)         The command <code>set_offset_x &lt;x&gt;</code> sets an offset in X
457)         direction (in mm). All floating point values are valid, the default is
458)         0, i.e. no offset.
459) 
460)       </para>
461) 
462)       <para>
463) 
464)         The coordinates from the drawing are rotated around the origin and the
465)         offsets in X and Y direction are added afterwards.  The resulting
466)         coordinate is then used for G-code generation.  This allows to adapt
467)         the coordinate system between the drawing and the CNC mill.  The offset
468)         can also be used to cut a workpiece drawn once at multiple positions.
469) 
470)       </para>
471) 
472)     </sect2>
473) 
474)     <sect2>
475) 
476)       <title>set_offset_y</title>
477) 
478)       <para>
479) 
480)         The command <code>set_offset_y &lt;y&gt;</code> sets an offset in X
481)         direction (in mm). All floating point values are valid, the default is
482)         0, i.e. no offset.
483) 
484)       </para>
485) 
486)       <para>
487) 
488)         The coordinates from the drawing are rotated around the origin and
489)         the offsets in X and Y direction are added afterwards.  The resulting
490)         coordinate is then used for G-code generation.  This allows to adapt
491)         the coordinate system between the drawing and the CNC mill.  The offset
492)         can also be used to cut a workpiece drawn once at multiple positions.
493) 
494)       </para>
495) 
496)     </sect2>
497) 
498)     <sect2>
499) 
500)       <title>set_precision</title>
501) 
502)       <para>
503) 
504)         The command <code>set_precision &lt;precision&gt;</code> sets the
505)         precision to do all calculations with (in mm).  If the distance
506)         between two coordinates is less then the precision setting, they are
507)         considered equal for G-code generation.  Only positive floating point
508)         values smaller than 1 are valid, the default is 0.001.
509) 
510)       </para>
511) 
512)     </sect2>
513) 
514)     <sect2>
515) 
516)       <title>set_rotation_z</title>
517) 
518)       <para>
519) 
520)         The command <code>set_rotation_z &lt;angle&gt;</code> sets the rotation
521)         angle around the Z axis (in degrees, counter-clockwise). All floating
522)         point values are valid, the default is 0, i.e. no rotation.
523) 
524)       </para>
525) 
526)       <para>
527) 
528)         The coordinates from the drawing are rotated around the origin and
529)         the offsets in X and Y direction are added afterwards.  The resulting
530)         coordinate is then used for G-code generation.  This allows to adapt
531)         the coordinate system between the drawing and the CNC mill.
532) 
533)       </para>
534) 
535)     </sect2>
536) 
537)     <sect2>
538) 
539)       <title>set_tool_diameter</title>
540) 
541)       <para>
542) 
543)         The command <code>set_tool_diameter &lt;diameter&gt;</code> sets the
544)         diameter of the cutting tool (in mm).  It is used in some of the
545)         <code>cut_*</code> commands.  Only non-negative floating
546)         point values are valid, the default is 1.
547) 
548)       </para>
549) 
550)       <para>
551) 
552)         The dxfngc tool assumes a flat end mill is used.  If a cutting tool
553)         with another shape is used in the CNC mill, please note that the
554)         diameter compensation code assumes a fixed diameter of the tool over
555)         its whole length.  However, if this is kept in mind, it is also
556)         possible to use cutting tools with other shapes.
557) 
558)       </para>
559) 
560)     </sect2>
561) 
562)     <sect2>
563) 
564)       <title>write_ngc</title>
565) 
566)       <para>
567) 
568)         The command <code>write_ngc &lt;filename&gt;</code> writes the current
569)         list of G-code commands kept in memory to the specified file.  The
570)         filename may be an absolute path or a relative one.  If it is relative,
571)         it is interpreted relative to the directory of the script file being
572)         processed.  Whitespace and non-ASCII characters are not supported in
573)         the filename.  This command is usually used at the end of the script to
574)         output the generated G-code.
575) 
576)       </para>
577) 
578)     </sect2>
579) 
580)   </sect1>
581)