Documentation for GCodeMapper

Lederhilger Martin

August 26, 2013


GCodeMapper is a program which maps a g-code program’s movements from one surface to another.

1 Introduction

This program was created, because I have only a three axis CAM software package but a milling machine with an additional rotatory axis – as shown in figure 1. I use the machine controller software LinuxCNC You can have a look at for further information on how to set up the kinematics for such a kind of machine in LinuxCNC.


Figure 1: Machine with three cartesian and one rotatory axes

For a lot of problems it is sufficient to map the program cutting on the surface of a planar stock – as generated by a three axis CAM software – around a cylindrical stock. This is exactly what this program does – see figure 2.


Figure 2: Mapping of a straight line from a plane onto a cylinder. Gray lines represent the tool.

The mapping relation of coordinates [         ]
 Xp, Yp,ZpT in the planar program to coordinates [           ]
 Xc,Yc,Zc,AcT in the resulting cylindrical program is

        α = Yp
       r = Zp + rc
⌊Xc ⌋         ⌊  Xp   ⌋
|Yc |   [ro]  |sin(α)r|
|⌈Zc |⌉ =  0  + |⌈cos(α)r|⌉
 Ac             − α 180


where ro denotes the origin of the cylinder and rc the cylinders’s radius. The cylinders axis is parallel to the X-axis. Ac is the rotation of the tool’s tip around an axis which is parallel to the X-axis and goes through the point [Xc, Yc,Zc]T.

Straight motions (G0 and G1) in the planar program with a constant Z-coordinate are mapped to a helix (G2 or G3) in the cylindrical program. Straight motions in the planar program with a constant Y -coordinate are mapped to a straight motion (G1) in the cylindrical program. Straight motions violating these constraints and arcs (G2 and G3) are approximated by short line segments (G1). Note that a rapid movement (G0) is never mapped to a G0, that’s why you have to pass a feed rate for mapped G0 movements. All other motions are not implemented, so only G0, G1, G2 and G3 movements are supported.

2 Installation

Only a source package is provided at That means you have to compile this C++ program by yourself. This program has the following prerequisites:

To configure the program, create a build directory, change to it, and run

 cmake <path to source directory>


 cmake DCMAKE_INSTALL_PREFIX=<path to install directory> <path to source directory>

and then run

 make install

to compile and install the program.

3 Usage

Please note that I have used this program several times on my own machine, but it could still contain some bugs. So please take a look on the transformed program before running it on your machine!

The program has a command line interface. When running

 gcodemapper help

you get a general help, and when running

 gcodemapper help mapper CylinderGCodeMapper

you get the help for the command line parameters of the CylinderGCodeMapper – no other mapper type1 is implemented at the moment. Most of the parameters have reasonable defaults2 , only mapper, cylinder-diameter, rapid-feed-rate and input and output files are required. A hypen is also accepted as the input and output file parameter. This means that the file is read from standard input or written to standard output. You can also specify parameters which are always the same in “gcodemapper.conf”. It is searched in the current working directory. In the following listing you can see an example.

Listing 1: gcodemapper.conf

3.1 Example

This section shows how to apply this program on an example g-code program which was generated by CAMBam. The example is shown in figure 3 and in listing 2.


Figure 3: Example visible in CAMBam

Listing 2: example_planar.ngc
( example 8/22/2013 7:00:33 PM ) 
( T3 : 3.0 ) 
(STOCK/BLOCK,100.0,157.08,10.0,0.0,0.0,10.0 ) 
G21 G90 G91.1 G64 G40 
( Engrave1 ) 
G0 Z50.0 
( T3 : 3.0 ) 
( TOOL/MILL,3.0,0.0,0.0,0 ) 
O<wzw> call [3] 
G0 Z50.0 
M3 S100 
(begin mapping) 
G0 X23.0 Y4.0 
G0 Z5.0 
G1 F30.0 Z-1.0 
G2 F120.0 X13.0 Y14.0 I-0.487548322 J9.512451678 
G1 Y39.0 
G1 X27.0 Y55.0 
G1 X70.0 
G1 Y134.0 Z-11.0 
(end mapping) 
G0 Z50.0 

When the command

 gcodemapper mapper CylinderGCodeMapper cylinderdiameter 50 example_planar.ngc example_cylindrical.ngc

is executed, then everything between the begin and end mapping comment is mapped around the cylinder. The mapped output is shown in figure 4 and in listing 3.


Figure 4: Example visible in Axis

Listing 3: example_cylindrical.ngc
( example 8/22/2013 7:00:33 PM ) 
( T3 : 3.0 ) 
(STOCK/BLOCK,100.0,157.08,10.0,0.0,0.0,10.0 ) 
G21 G90 G91.1 G64 G40 
( Engrave1 ) 
G0 Z50.0 
( T3 : 3.0 ) 
( TOOL/MILL,3.0,0.0,0.0,0 ) 
O<wzw> call [3] 
G0 Z50.0 
M3 S100 
G90 G90.1 G19 
G0 Z50 
G0 Y0 
G2 F900 X23 Y7.96591 Z49.3614 A-9.16733 J0 K0 P1 
G1 F900 X23 Y4.77955 Z29.6168 A-9.16733 
G1 F30.0 X23 Y3.82364 Z23.6935 A-9.16733 
G1 F120.0 X21.9381 Y3.82823 Z23.6927 A-9.17843 
G1  X20.8833 Y3.94478 Z23.6736 A-9.46039 
G1  X19.8488 Y4.17155 Z23.6347 A-10.0097 
G1  X18.8473 Y4.50518 Z23.5734 A-10.8195 
G1  X17.8915 Y4.94061 Z23.486 A-11.8798 
G1  X16.993 Y5.47116 Z23.3681 A-13.1773 
G1  X16.1632 Y6.08856 Z23.2149 A-14.696 
G1  X15.4123 Y6.78299 Z23.0215 A-16.4169 
G1  X14.7497 Y7.54326 Z22.7837 A-18.3187 
G1  X14.1835 Y8.357 Z22.498 A-20.3778 
G1  X13.7209 Y9.21088 Z22.1621 A-22.5684 
G1  X13.3675 Y10.091 Z21.7755 A-24.8635 
G1  X13.1279 Y10.9832 Z21.3394 A-27.2345 
G1  X13.0048 Y11.8735 Z20.8571 A-29.6519 
G1  X13 Y12.7485 Z20.3341 A-32.0856 
G2  X13 Y23.9986 Z0.259107 A-89.3814 J0 K0 P1 
G2  X27 Y19.4039 Z-14.124 A-126.051 J0 K0 P1 
G1  X70 Y19.4039 Z-14.124 A-126.051 
G1  X70 Y18.7243 Z-14.8102 A-128.343 
G1  X70 Y18.021 Z-15.4646 A-130.634 
G1  X70 Y17.2955 Z-16.0867 A-132.926 
G1  X70 Y16.5492 Z-16.6756 A-135.218 
G1  X70 Y15.7836 Z-17.2307 A-137.51 
G1  X70 Y15.0002 Z-17.7515 A-139.802 
G1  X70 Y14.2006 Z-18.2372 A-142.094 
G1  X70 Y13.3862 Z-18.6876 A-144.385 
G1  X70 Y12.5587 Z-19.1022 A-146.677 
G1  X70 Y11.7195 Z-19.4807 A-148.969 
G1  X70 Y10.8702 Z-19.8227 A-151.261 
G1  X70 Y10.0125 Z-20.1282 A-153.553 
G1  X70 Y9.14775 Z-20.397 A-155.845 
G1  X70 Y8.27763 Z-20.6291 A-158.136 
G1  X70 Y7.40366 Z-20.8243 A-160.428 
G1  X70 Y6.52739 Z-20.9828 A-162.72 
G1  X70 Y5.65034 Z-21.1048 A-165.012 
G1  X70 Y4.77403 Z-21.1904 A-167.304 
G1  X70 Y3.89997 Z-21.2399 A-169.596 
G1  X70 Y3.02961 Z-21.2535 A-171.887 
G1  X70 Y2.16444 Z-21.2317 A-174.179 
G1  X70 Y1.30587 Z-21.175 A-176.471 
G1  X70 Y0.455324 Z-21.0837 A-178.763 
G1  X70 Y-0.385833 Z-20.9585 A-181.055 
G1  X70 Y-1.21625 Z-20.7999 A-183.346 
G1  X70 Y-2.03462 Z-20.6087 A-185.638 
G1  X70 Y-2.83965 Z-20.3855 A-187.93 
G1  X70 Y-3.63012 Z-20.131 A-190.222 
G1  X70 Y-4.40481 Z-19.8462 A-192.514 
G1  X70 Y-5.16258 Z-19.5318 A-194.806 
G1  X70 Y-5.9023 Z-19.1887 A-197.097 
G1  X70 Y-6.62289 Z-18.8179 A-199.389 
G1  X70 Y-7.32335 Z-18.4204 A-201.681 
G1  X70 Y-8.00268 Z-17.9972 A-203.973 
G1  X70 Y-8.65996 Z-17.5492 A-206.265 
G1  X70 Y-9.2943 Z-17.0777 A-208.557 
G1  X70 Y-9.90489 Z-16.5837 A-210.848 
G1  X70 Y-10.4909 Z-16.0683 A-213.14 
G1  X70 Y-11.0517 Z-15.5328 A-215.432 
G1  X70 Y-11.5866 Z-14.9783 A-217.724 
G1  X70 Y-12.0949 Z-14.4061 A-220.016 
G1  X70 Y-12.5761 Z-13.8173 A-222.308 
G1  X70 Y-13.0297 Z-13.2132 A-224.599 
G1  X70 Y-13.4553 Z-12.595 A-226.891 
G1  X70 Y-13.8524 Z-11.9642 A-229.183 
G1  X70 Y-14.2207 Z-11.3218 A-231.475 
G1  X70 Y-14.56 Z-10.6692 A-233.767 
G1  X70 Y-14.87 Z-10.0078 A-236.059 
G1  X70 Y-15.1505 Z-9.33873 A-238.35 
G1  X70 Y-15.4015 Z-8.66334 A-240.642 
G1  X70 Y-15.6229 Z-7.98292 A-242.934 
G1  X70 Y-15.8147 Z-7.29874 A-245.226 
G1  X70 Y-15.977 Z-6.61208 A-247.518 
G1  X70 Y-16.1098 Z-5.92419 A-249.81 
G1  X70 Y-16.2134 Z-5.23633 A-252.101 
G1  X70 Y-16.2879 Z-4.54972 A-254.393 
G1  X70 Y-16.3336 Z-3.86559 A-256.685 
G1  X70 Y-16.3509 Z-3.18513 A-258.977 
G1  X70 Y-16.3401 Z-2.5095 A-261.269 
G1  X70 Y-16.3016 Z-1.83987 A-263.561 
G1  X70 Y-16.2358 Z-1.17735 A-265.852 
G1  X70 Y-16.1434 Z-0.523052 A-268.144 
G1  X70 Y-16.0249 Z0.121968 A-270.436 
G1  X70 Y-15.8807 Z0.756669 A-272.728 
G1  X70 Y-15.7117 Z1.38005 A-275.02 
G1  X70 Y-15.5184 Z1.99113 A-277.312 
G1  X70 Y-15.3015 Z2.58899 A-279.603 
G1  X70 Y-15.0619 Z3.17273 A-281.895 
G1  X70 Y-14.8002 Z3.74148 A-284.187 
G1  X70 Y-14.5174 Z4.29443 A-286.479 
G1  X70 Y-14.2142 Z4.8308 A-288.771 
G1  X70 Y-13.8915 Z5.34986 A-291.063 
G1  X70 Y-13.5503 Z5.85092 A-293.354 
G1  X70 Y-13.1913 Z6.33332 A-295.646 
G1  X70 Y-12.8157 Z6.79646 A-297.938 
G1  X70 Y-12.4243 Z7.23978 A-300.23 
G1  X70 Y-12.0181 Z7.66278 A-302.522 
G1  X70 Y-11.5981 Z8.06497 A-304.814 
G1  X70 Y-11.1654 Z8.44596 A-307.105 
G1 F900 X70 Y-39.8764 Z30.1641 A-307.105 
G3 F900 X70 Y0 Z50 A-0 J0 K0 P1 
G90 G91.1 G17 
G0 Z50.0 

4 License

GCodeMapper - maps movements of a g-code program from one surface to another, eg. plane to cylinder. 
Copyright (C) 2013 Martin Lederhilger <> 
This program is free software: you can redistribute it and/or modify 
it under the terms of the GNU General Public License as published by 
the Free Software Foundation, either version 3 of the License, or 
(at your option) any later version. 
This program is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of 
GNU General Public License for more details. 
You should have received a copy of the GNU General Public License 
along with this program.  If not, see <>.

5 History

You can find the history of the program in table 1.

VersionDate Remarks

1.0 2013-08-23Initial release
1.1 2013-08-24Added tool’s orientation in figure 2
2013-08-26Added version information to required libraries in chapter 2

Table 1: Changelog