No Secrets: Open-source CAM Application Bares All

Note: The following article appeared in Digital Machinist Volume 5 No. 3 Fall 2010. HeeksCAD has continued to mature since then. The current user interface may vary significantly from the images below.

No Secrets: Open-source CAM application bares all.

In the opening scene of the 1981 movie Raiders of the Lost Ark, explorers come upon an idol hidden in the jungle. Weaker men flee, but the hero, undaunted, continues on to discover a treasure.

The first words on the HeeksCAD website are a little like that: “HeeksCAD is not finished, yet. “ Those who make it past this warning, will face challenges but are ultimately rewarded with a prize: HeeksCAD and it’s CAM plug-in HeeksCNC are quite usable – and powerful- even in their unfinished condition.

Unless you’re a public relations agent for a big software company, you have to admit that open-source software has been making impressive gains in the last few years. The Firefox browser, OpenOffice productivity suite, MySQL database, and Linux operating system are all as well known as their commercial counterparts. Some, like the Apache web server, are even dominating their respective markets. The truth is, if you need a high quality software package of almost any type, there’s probably an open-source alternative worth trying.

There are lots of reasons for the success of open-source software. Low cost is the one most people think of first. Most applications can be obtained for free without surrendering so much as an email address. True open-source software, as opposed to freeware or shareware, is also free of nag screens, pop-ups, trial periods, and limited functionality.

Many applications run on multiple platforms making it easy to switch between a home and work machine. Release cycles for open-source projects tend to be much shorter so new features and bug fixes appear on a regular basis.

All this is great, but it’s the open nature of open-source software that should appeal to the readers of this magazine. This software is written and supported by do-it-yourselfers – people who value the freedom to pop open the hood and see what makes it tick. No secrets. No patents. No tricks.

The definition of open-source means you, the user, get more than just the compiled binary version of the software. You get the source code, too. That means if you’re a programmer, tinkerer, or just curious, you can look inside to see how things work. You can even change it if you want. If you have ever experienced the horror of having to deal with a software company going out of business and not supporting your favorite (or mission critical) application, you might find security in that.

It might be tempting to think that having the source code is just a benefit for programmers. Not true. It’s the spirit of openness, this willingness to disclose the inner workings, that makes software developed this way different from commercial applications and leads to some interesting features, as we’ll see.

Open-Source CAD/CAM at last.

While open-source options abound for many kinds of applications, until very recently, Computer Aided Design and Machining (CAD/CAM) have not been among them. We had a pretty good 2D CAD system with Qcad (http://www.qcad.org/), but 3D CAD was non-existent. As for CAM; a handful of niche utilities, orphaned projects, and a few scripts were all we had to choose from. Most of us eventually concluded that there was no alternative but to invest in a commercial package or learn to write g-code by hand. That situation appears to be changing at last.

Like other open-source applications, HeeksCAD and HeeksCNC, offer all the benefits mentioned before. Published under the very permissive BSD license, the code is free to download, use, sell, modify, or even use in your own commercial software product.

The author, Dan Heeks, regularly makes binary packages available for the Windows operating system on the project website (http://heekscad.org). There’s a large community of Linux users and plenty of documentation to get things going. A smaller community has been using the applications on Apple computers as well.

A Family of Applications

A big difference between commercial and open-source software is that where commercial software tends toward large monolithic solutions, open-source favors code reuse and leveraging existing solutions. The use of modules, plugin-ins, and third-party libraries is commonplace and allows developers to rapidly add new features. HeeksCAD is no exception.

HeeksCAD is the main application. The user interface (figure 1) provides all the tools and controls for importing files, manipulating geometry, and working with your project files. The central feature is a 3D window for viewing your design and navigating in 3D space. A set of dock-able panels provide access to the project tree, properties of the objects in the tree, and the application options.

 

The application makes a distinction between two dimensional geometry, called sketches, and three dimensional geometry – solids. Sketches are collections of points, lines, and arcs. Sketches can be turned into faces and faces can be extruded into the third dimension to create solids (figure2). Solids, as you would expect, can be further edited by filleting or chamfering the edges or by combining them with boolean operations to make more complex shapes.

In many ways the user interface is still rough around the edges and even difficult to use but it has surprising power under the hood. One interesting feature is a dynamic constraint auto-solver. HeeksCAD allows you to indicate that two elements have a relationship. For example, you can indicate that two lines are perpendicular. With such a constraint enabled, and the auto-solver turned on, the user interface will only allow movement of lines that preserve the constraint. (editor: see note about Constraint Images in the image index file) and will automatically adjust the position of one line when you move the other.  (See Figures 3 – 7)

There are many different kinds of constraints working already including:
Constraining lines to be parallel, perpendicular, collinear, or of equal length
Forcing two points to be coincident
Constraining a line to be a specific length or tangent to an ellipse.

The constraint solver is an area of heavy development and the engine is well suited for the addition of future constraint types.

Putting all these tools together, it’s possible to create sophisticated models using only the HeeksCAD application. But perhaps you have a design tool that you’re comfortable with or are starting with an existing drawing from another application. HeeksCAD has good support for importing and exporting a variety of file types including dxf, stl, gerber, iges, step, and svg. This lets HeeksCAD become part of your toolbox and play nice with other CAD applications like Qcad, mesh editors like Blender, or vector drawing programs like Inkscape.

CAM: Going Beyond Design

If that’s all there was to HeeksCAD, you might conclude that it’s an interesting project but probably not worth the learning curve yet. Your opinion might change when you’ve met HeeksCAD’s versatile little sister, HeeksCNC. This is a separate application project, also by Dan Heeks with it’s own website (see the reference section at the end of this article) The application works as a plug-in to extend the functionality of HeeksCAD and turn it from a design-only tool into a full fledged CAM system.

If you’re new to CNC machining, you should know that a CAM application lets the user define a set of operations to be performed by a CNC equipped machine. It takes, as input, a 2D or 3D design and generates, as output, instructions that can be processed by the machine controller.

After HeeksCNC has been installed and enabled, HeeksCAD will have a new ‘machining’ menu. It also has a tool bar and several windows that are disabled by default but can be turned on under the ‘window’ menu.

The first thing you’re likely to notice is that the Objects panel has several new entries in the tree (Figure 8). These are for defining tools, creating machining operations, and configuring their properties.

Before HeeksCNC can produce usable g-code it needs to know a bit more about your machine configuration. G-code varies somewhat between machine controllers so the first thing you should do is select a post-processor that matches your machine (CNCInterface.png). The Linux Enhanced Machine Controller (EMC), is supported along with a handful of others.. If you really want full control or just want to make a small change to how your g-code is produced, instructions for rolling your own post-processor are available on the project wiki.

The next thing a CAM application needs to know is something about the tools that the machine is equipped to use. Mills, drills, probes, and other tools all have individual properties that will affect the output. From the Objects panel, you can add or edit tool definitions that match tools you’ll actually be using. Right clicking on the Tools item also gives some options for importing and exporting the tool table for reuse in future projects.

For the examples given here, I’m using the EMC post processor and the the default 6.35mm end mill. If you have a different configuration, your output might appear different.

HeeksCNC provides a large collection of operations for doing things like milling, drilling, counter-boring, chamfering, V-bit carving, cutting pockets (Figure 9) and 3D surfacing (Figure 10). It also has operations for things like probing and edge locating. Many of these operations are provided natively by HeeksCNC but some rely on other open-source libraries. Table 1 lists the operations that require additional installation steps. If you aren’t planning to use these operations, you don’t need to install the library.

Profiling and Pocketing are the bread and butter of 2D machining. It’s hard to imagine doing anything useful without those two operations so you’ll almost certainly want to install their helper libraries.

Table 1: Some HeeksCNC operations make use of other libraries

Profile	Used to cut out 2D shapes. Also useful for engraving. The Kurve code comes with HeeksCNC but requires a separate compilation step.	Kurve
Pocket	Used to progressively remove material to create voids or ‘pockets’ in the stock material	Libarea
Adaptive Roughing	Adaptive clearing is an algorithm for efficiently roughing complex 3D shapes. Originally written by Julian Todd and Martin Dunschen (http://www.freesteel.co.uk) it is licensed to CAM vendors for inclusion in their applications.  Libactp is based on an early version implementation released under the GPL.	libactp
Zigzag	An open-source library for doing 3D surface machining. Written by Anders Wallin. http://code.google.com/p/opencamlib/	opencamlib

 

A simple example:

The work flow for making something with HeeksCNC works like this:

A part is designed in HeeksCAD or another application and imported to HeeksCAD. In this example (Figure 11), We’ve designed a simple mounting plate with a center hole and eight mounting holes. Machining the part will require four distinct operations: Two operations to drill the mounting holes -they’re different sizes, an inner profile of the large center hole, and an outer profile of the whole part.

We usually choose to have a sketch for each operation so that we can do all the internal work first and cut the part away from the stock last. If all the lines and points are in the same sketch, you will probably want to use the tools in HeeksCAD to organize the elements by splitting and combining sketches. Expand each sketch in the Objects tree, select the elements you’re interested in. Right-click to open the context menu and then click ‘Make to sketch’ . Two or more sketches can be combined in a similar way.

Newly combined sketches or sketches imported from another CAD application may need to be reordered before the operations work correctly. This puts the elements into a sequential order to make machining possible. If the ‘order’ property of the sketch reads ‘bad’ just click ‘reorder’ (Figure 12). If it says anything else, it’s ready to go.

 

With the geometry cleaned up and organized it’s time to add operations. Select each sketch and add the appropriate operation. In figure 13, We’ve added the drilling operations and the outer profile. Operations will be executed in the order they appear in the Objects tree. If you add them in the wrong order, operations can be resequenced by dragging them up and down in the Objects tree.

Let’s skip the large center hole for now and come back to it. First, let’s talk about one of the realities of machining parts. If the stock was roughly cut to the size of the final part, the profile operation might be sufficient as it is to finish the part. But what if we’re cutting the part out of a larger piece of material? In that case, the part would need to be securely clamped so it won’t break, twist, or fly out as the profile separates it from the stock. This is difficult to do because the clamps themselves will interfere with the profiling operation.

An alternative is to leave a little bit of material behind in a couple places to hold the part. This remaining material can be cut by hand afterward. Many CAM packages have this feature and in HeeksCNC it’s called a “holding tag”. We’ve added two tags to the profile operation and you can see the effect on the tool path in (holdingtags.png)

When everything looks good, hit the G0 button or click ‘post-process’ in the machining menu to generate the g-code. If you have the ‘Output’ window visible, you’ll see the g-code displayed there. The 3D window will display a back-trace of your g-code so you can examine it for problems. If you find anything wrong, you may need to edit your drawing, adjust the parameters of the operations and post-process again. A strange looking tool path is also a sign that your sketch needs to be re-ordered.

More Control means more power.

So what just happened? Somehow, the individual operations got processed to produce machine compatible g-code complete with feeds, speeds, and tool-change directives. Let’s take a closer look at HeeksCNC’s post-processing system.

The first thing HeeksCNC does when we post-process is to build a kind of master script called post.py. It’s like a recipe for how to build your g-code. This script is customized for your specific operations, machine configuration, and tool-table.

Next, it runs that script. Post.py, in turn, calls on each of the needed helpers, passes them the geometry and parameters they require and waits for them to hand back a fragment of g-code. Finally, it assembles all the g-code fragments and writes them to a file. HeeksCNC then reads the file back in and plots the tool-path in the 3D window.

Remember how open-source software makes the source code available to programmers, tinkerers, and the naturally curious? Well HeeksCNC takes this principle one step further. If you have the ‘Program’ window visible you’ll see some programming code appear in it when you post-process. This code, written in Python, is the intermediate step mentioned above – the recipe.

Python is a powerful language used in all kinds of applications. It’s easy to learn and very flexible. Python, like other scripting languages, isn’t compiled ahead of time. Instead, it’s interpreted at the time it is run and this makes it ideal for extending applications and gluing things together.

In a commercial application, this intermediate code would probably be hidden from the user or thrown away after it was run, but HeeksCNC makes it accessible. The user doesn’t necessarily need to see this code, or even care that it exists, but having it means we can do something interesting with it.

For example, we can copy that code, edit it, and paste it back in the window.
Commands can be added to the script which are as simple as “feed(x=1.25,y=.333)” or could combine simple feed moves with “if-then” type loops to produce very complex behavior.

After pasting in the edited code, we can click the ‘run python script’ menu item. This skips the first part of the post-processing routine and goes right into executing it – along with your modified code – to produce custom g-code. Now we have all the power of hand-coding but with a relatively simple scripting language like python.

Introducing Parametric CAM Programming with Python

Editing the intermediate python code is fine for an occasional tweak, but if you accidentally hit the ‘post-process’ button instead to the ‘run python script’ your hand crafted code will be overwritten. What’s needed is an easier way to introduce custom code into the post-processing routine.

That’s exactly what we have with the Script Operation (ScriptOp). ScriptOp gives users a way of adding new operations that are limited only by their imaginations. It’s added like any other operation, by selecting some geometry and adding it from the machining menu. It behaves like any other operation and can be sequenced, enabled, or disabled in the Objects tree. Its purpose is to hold a bit of Python code. During post-processing, the code will be executed. The script has access to the associated geometry of the sketches and the resulting g-code will be incorporated into the final output.

Returning to our example, lets cut the large center hole. Rather than add another profile operation that makes the end-mill plunge into the material, let’s create a helical entry that moves the cutter forward as it descends around the perimeter.

First select the sketch containing the center hole circle, and add a ScriptOp from the menu (Figure15).

Select the ScriptOp in the object tree and type the code from Listing 1 into the white space at the bottom of the properties window.

Listing 1:

def helical_ramp(x_cen,y_cen,z_depth,dia,pitch,z_clear):
    r=dia/2
    flush_nc()
    rapid(z=z_clear)
    rapid(x=x_cen,y=y_cen) 

    feed(x=(x_cen+r))
    z_level=z_clear 

    while (z_level > z_depth ): 

        arc_ccw(x=(x_cen-r),y=y_cen,z=(z_level - pitch*.5),i=-r,j=0)
        arc_ccw(x=(x_cen+r),y=y_cen,z=(z_level - pitch),i=r,j=0)
        z_level= z_level-pitch 

    arc_ccw(x=(x_cen-r),y=y_cen,z=(zdepth),i=-r,j=0)
    arc_ccw(x=(x_cen+r),y=y_cen,i=r,j=0)
    arc_ccw(x=(x_cen-r),y=y_cen,i=-r,j=0)
    arc_ccw(x=(x_cen+r),y=y_cen,i=r,j=0)
    arc_ccw(x=(x_cen),y=y_cen,i=-r*.5,j=0) 

    rapid(z=(z_clear)) 

tool_radius=3.175
p=3
zclr=10
zdepth=-12.8 

for sketch in graphics.sketches:
    spans = sketch.getTypeSpanPairs()
    for span in spans:
        span_type = span[0]
        span_element = span[1]
        if (span_type == ocl.ArcSpanType):
            arc = span_element
            d= abs(arc.p1.x-arc.c.x)*2-tool_radius
            center= (arc.c.x, arc.c.y)
            helical_ramp(arc.c.x, arc.c.y, zdepth, d, p, zclr)

Fully explaining everything that is happening in the ScriptOp is beyond the scope of this article but we’ll step through to get a sense of how it works. In Python, indentation is very important and you can tell a little about the overall structure just by studying it.

In the first section, we’ve defined a function called helical_ramp. It’s going to do the heavy lifting of moving our cutter in a descending spiral. It takes, as input, the location, depth, and diameter of the circle we’re going to cut. Since the cutter is going to move in a helix and not a flat circle, we also need to know the spacing between revolutions – the pitch. Of course we’ll be moving the cutter around and there could be clamps or other protrusions so we should tell the script a safe height (z_clear).

The rest of the function is a loop that performs a series of counter-clockwise arc movements around the center, descending as it goes. It finishes up by making a couple extra arc movements to make sure the tool has completed a full revolution at the desired depth and then retracting the cutter back to the safe height.

With this function, our script is now smart enough to cut a helical path of any size at any location that we want. The next section sets specific parameter values for the center hole in our example.
You can see that we’ve assigned the tool_radius to be half the diameter of the 6.35mm end mill, the pitch is 3, the safe height is 10mm. Our part is 12.5mm thick and we want to cut all the way through so we’ll go to a zdepth of 12.8mm.

We could also hard code the diameter and the X/Y location of the center of the circle. This wouldn’t be a problem with our example, since it has just one circle. The same thing would be difficult or impossible if the sketch contained many holes of different diameter. As it happens, hard-coding these values isn’t necessary. We already made the geometry of the circle available to the ScriptOp when we selected the sketch at the beginning. The only thing we need is some code to pull out the relevant values now. The last part of the script is a bit obscure but it’s sufficient to say that this is exactly what it’s doing. It’s scanning through the sketch and trying to find circles. Finding one, it extracts the center and diameter.

With those values in hand, and the ones we hard-coded earlier, it calls the helical_ramp function to do the work. Figure 16 shows the resulting tool path.

ScriptOp isn’t likely to be a feature that appeals to beginners but it’s easy to see how incredibly powerful this technique can be. We fully expect that the software will continue to mature in this area and in the future, it will be even easier to implement custom operations into your projects.

What’s Missing?

HeeksCAD and HeeksCNC have many features that aren’t described in this article. In fact, they probably have new features at the time of publication that didn’t exist when this article was written. So you might be curious about what’s missing. Fair enough. In an article about software without secrets, a discussion about shortcomings is fair game. As in most applications, improvements to the user experience, speed, and stability are always possible. What follows are some the bigger shortcomings in the application today.

In many operations, having the cutter enter the material in ways other than direct plunging is desired. Ramping down in a straight line or a helical pattern, like our example, is required for certain kinds of tools. Work is being done now to make this part of the standard operations.

HeeksCAD has started to gain favor as a design tool with many hobbyists in the Reprap – ‘Additive Machining’ – community. Sadly, HeeksCNC doesn’t have operations for 3D printing yet.

Operations for lathe turning have been started but are not yet usable. Milling operations for anything more complex than a 3 axis machine are also well in the future.

Many commercial packages offer features for cutter compensation. HeeksCNC doesn’t have this yet.

ScriptOp is very new so don’t expect much help from the application in writing or debugging your Python code.

Documentation. The project wiki is a good place to start, but thorough documentation is still needed. HeeksCAD is barely 2 years old and growing rapidly so documentation is a challenge. In the YouTube age, video tutorials are expected but only a handful exist for HeeksCAD. This is an area where non-programmers could contribute significantly.

Free But Not Cheap

One final note: HeeksCAD and HeeksCNC are collaborative projects. They rely on libraries or other applications to do part of the work. Sometimes progress is rapid in one area and lags in another. Sometimes documentation is weak, out of date, or missing altogether because developers would rather work on new features than write manuals. This can be frustrating if you’re used to the polish that comes with commercial solutions.

The community that has sprung up around HeeksCAD and HeeksCNC is like many in the open-source world. Developers work on the things that interest them and share what they build. Users accept that there will be bumps and snags and report bugs in ways that are helpful. Users that have encountered a problem and solved it, try to share their knowledge by editing the wiki or answering someone else’s question. In short, open-source software is free to obtain but requires an investment of time and effort. The pay-off, however, is power, control, and fun.

Resources

If you want to explore HeeksCAD and HeeksCNC, you’ll find an active, and growing community. Developers are regularly available on the IRC #CAM channel and there’s a user group at http://groups.google.com/group/heekscad-users Project website is http://heekscad.org

The HeeksCAD website includes links to all the related projects mentioned in this article and several not mentioned including HeeksArt and HeeksPython.

HeeksCAD/HeeksCNC aren’t the only applications in the open-source CAD/CAM world. Here’s a few more projects that are also worth a look:

FreeCAD – A general purpose 3D modeling tool. FreeCAD does not have a strong CAM component yet but is showing great promise as a feature based parametric CAD system.

Blender. A mesh-modeling tool originally intended for artists and animators. The ingenuity of the community is amazing and some have scripted extensions to handle CAM functions as well.

OpenSCAD – OpenSCAD isn’t a CAM application but has a programmer’s philosophy in mind for solid modeling. Objects can be created with a programming like syntax. This lets the modeler change aspects of the design simply by changing the underlying parameters.

About the Authors

Brad Collette has a degree in psychology and a quiet disregard for his own safety. He has no business using such powerful tools. Foolishly, he does it anyway and blogs about the results at https://sliptonic.com. Daniel Falck is a tooling designer and CAD jockey with a very crowded garage for a shop. His blog is at http://opensourcedesigntools.blogspot.com/ . Both are frequent contributors to the IRC #CAM channel.