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

589)   <sect1 xml:id="compiling">
590) 
591)     <title>Compiling</title>
592) 
593)     <para>
594) 
595)       To compile dxfngc, a C++ compiler and the following libraries have to be
596)       installed, including their development files:
597) 
598)     </para>
599) 
600)     <programlisting><![CDATA[libCGAL_Core (>= 3.6)
601) libCGAL (>= 3.6)
602) libdime (>= 2003-09-21)]]></programlisting>
603) 
604)     <para>
605) 
606)       To compile dxfngc, simply call <code>make</code> from the top-level
607)       directory.
608) 
609)     </para>
610) 
611)     <sect2>
612) 
613)       <title>Compiling Documentation</title>
614) 
615)       <para>
616) 
617)         To compile the dxfngc documentation, <code>docbook (>= 5.0)</code>
618)         must be installed.
619) 
620)       </para>
621) 
622)       <para>
623) 
624)         To compile the documentation, simply call <code>make</code> from the
625)         <code>doc</code> directory.
626) 
627)       </para>
628) 
629)     </sect2>
630) 
631)   </sect1>
632)