Path Workbench

Introduction
The Path workbench is used to produce machine instructions for CNC machines from a FreeCAD 3D model. These produce real-world 3D objects on CNC machines such as mills, lathes, lasercutters, or similar. Typically, these instructions are some kind of G-Code dialect.



The FreeCAD Path Workbench workflow creates these machine instructions as follows:
 * A 3D model is the base object, typically created using one or more of the Part Design, Part or Draft Workbenches.
 * A Job is created in Path Workbench. This contains all the information required to generate the necessary G-Code to process the Job on a CNC mill: there is Stock material, the mill has a certain set of tools and it follows certain commands controlling speed and movements (usually G-Code).
 * Tools are selected as required by the Job Operations.
 * Milling paths are created using e.g. Contour and Pocket Operations. These Path objects use an internal agnostic FreeCAD G-Code dialect which is independent of the CNC machine.
 * Because each CNC Controller speaks a specific G-Code dialect, a Dialect-correct Postprocessor translates from the internal agnostic FreeCAD G-Code. Several Postprocessors are included allowing direct use or as a templates for modification. Postprocessors contain configuration flags and are designed to be tuned by adding G-Codes and M-Codes to provided definitions for:
 * Machine initialization
 * Job finalization
 * Tool-Changes
 * Cooling on /off
 * Etc...

Links for the impatient
Depending on your interest in the Path workbench there are different topics for further reading:


 * If you are a new new user trying to get familiar with Path, you might be interested in a fast walk-through tutorial.
 * If you have a special machine which cannot use one of the available postprocessors you may want to write your own postprocessor
 * As an experienced user you may want to write a macro for the Path Workbench
 * Power users may want to streamline processes.
 * New Developers might want to understand core concepts.

General concepts
The Path Workbench generates G-Code defining the paths required to mill the Project represented by the 3D model on the target mill—in [the Path Job Operations FreeCAD G-Code dialect], which is later translated to the appropriate dialect for the target CNC controller by selecting the appropriate Postprocessor. The G-Code is generated from directives and Operations contained in a Path Job. The Job Workflow lists these in the order they will be executed. The list is populated by adding Path Operations, Path Dressups, Path Partial Commands, and Path Modifications—from the Path Menu, or GUI buttons.

A summary of the contents of the Path Job includes:
 * 1) A list of Tool-Controller definitions, specifying the geometry, Feeds, and Speeds for the Path Operations Tools.
 * 2) A Workflow sequential list of Path Operations.
 * 3) A Base Body—a clone used for offset.
 * 4) A Stock, representing the raw material that will be milled to Path Workbench.
 * 5) A SetupSheet, containing inputs used by the Path Operations, including static values and formulas.
 * 6) Configuration parameters specifying the output G-Code job's destination path, file name, and extension, and the Postprocessor—used to generate the appropriate dialect for the target CNC Controller, and customize Units, Tool Changes, Parking, etc...

The Path Workbench provides a Tool Manager (Library, Tool-Table), and G-Code Inspection, and Simulation tools. It links the Postprocessor, and allows importing and exporting Job Templates.

The Path Workbench has external dependencies including:
 * 1) The FreeCAD 3D model units are defined in the Edit-> Preference...->General->Units tab's Units settings.  The Postprocessor configuration defines the final G-Code units.
 * 2) The Macro file path, and Geometric tolerances, are defined in the Edit->Preferences...->Path->Job Preferences  tab.
 * 3) Colors are defined in the Edit->Preferences...->Path->Path colors tab.
 * 4) Holding tag parameters are defined in the Edit->Preferences...->Path->Dressups tab.
 * 5) That the Base 3D model quality supports the Path WB requirements—passes Check Geometry.

FreeCAD Path Workbench internal G-Code dialect represents Feed rates in Units/Second—what the G-Code Inspection tool will show. The Postprocessor is configured to generate the appropriate Feed rates—either in Units/Second or Units/Minute for the target mill.

Scripting
The Path workbench offers a broad python scripting API. With it, you can create and modify paths from python scripts, or extend the available functionality of the workbench.

How many axes can Path Workbench handle?
At the moment Path Workbench can handle up to 3 axis milling.

Why does it seem that in some instances, Path workbench provides more than one way to specify an Operation?
Path workbench provides existing tools to meet many milling operations, more are in progress, and because FreeCAD is open source, there is nothing impeding any user from creating their own functionality.

As with 3D modeling, there are often multiple methods available that might be advantageous to use for different Job operations. In some cases, combinations of Operations are used to provide complete milling of the Stock.

One common example is that a Contour cut could be generated from Edges or Faces. In some cases there will be an advantage to one geometric input over another.

Why does Dressing up an Operation change change the position in the Job Workflow shown in the Operations list?
All additions to the Job--including modifications, and Operation copies--are appended at the end of the Job Workflow. If that disrupts the correct Job sequence, it must be reordered in the Job editor->Workflow tab.

What is the difference between Clearance Height and Safe Height?
More detailed information is available in depths and heights.

Each Operation has a local definition for Clearance and Safe Heights. The user will benefit from ensuring that Jobs containing local "valleys", separated by local "peaks" have Clearance and Safe Heights defined that do not Rapid transit through the "peaks". The CAM simulation can be invaluable in detecting these and other errors.



What is the typical use of the SetupSheet?
The SetupSheet is a dedicated spreadsheet contained within a Job, modified in the Property view, accessible only from Path workbench. It provides a mechanism for more expert users to configure aspects of their Job by using Values and Expressions contained within the SetupSheet.

Current inputs for Depths, Heights, and Tool Controllers include:
 * 1) Final Depth Expression -- OpFinalDepth
 * 2) Start Depth Expression -- OpStartDepth
 * 3) Step Down Expression -- Defaults to OpToolDiameter. This expression is used for each Operation to calculate its default Step down value based on the diameter of the Tool defined in the associated Tool controller.
 * 4) Clearance Height Expression -- StartDepth+SetupSheet.ClearanceHeightOffset
 * 5) Clearance Height Offset Value -- Contains value used in Expressions
 * 6) Safe Height Expression -- StartDepth+SetupSheet.SafeHeightOffset
 * 7) Safe Height Offset Value -- Contains value used in Expressions
 * 8) Horizontal Rapid Value -- Provides the default value used to initially populate the Horizontal Rapid Feed rate for all Tool controllers.
 * 9) Vertical Rapid Value -- Provides the default value used to initially populate the Vertical Rapid Feed rate for all Tool controllers.

This provides flexibility. For example, default expressions are provided, but can be overwritten by the user. The modification can even reduce the default equation to a Value if that suits the user.

What is the typical use of the Job Templates?
Job templates provide a mechanism for saving commonly used Job definitions from an existing Job, then importing them when creating future similar Jobs to save setup time.

Available definition data that can be exported/imported includes:
 * 1) Postprocessor
 * 2) Extent and Placement of the Stock
 * 3) Operation Depths, Heights, and Tool Controller data contained in the SetupSheet
 * 4) Tool Controllers

Exporting a template can be done at any time, from within the Path workbench Job, using the Path->Export Template menu, or by right clicking the Job in the Combo View.

The Edit->Preferences...->Path->Job Preferences tab, Defaults->Template is used to set the default template defining a Job at creation.

How many Base objects does Path workbench support?
Support exists only for a single Base object. To create paths for multiple solids in a single Job you can make a Compound out of them and use that as the base object for the Job.

Why does an Operation not produce usable output?
A variety of reasons exist that may cause an individual Operation to generate no output.

One common reason is that the Tool geometry defined in the Tool controller selected for the Operation is too large to fit within the geometry selected on the 3D model for the Operation.

Be aware that this will typically exhibit as a Rapids movement to where the Operation beginning, completed by a Rapid Z movement to the geometry selected to define the Operation, and then a return to Rapid transit height.

Another common misunderstanding is that a Contour Operation is not outputting paths, when the Contour editor Operation->Cut Side is "Inside", the default, and toggling the 3D Model viability allows them to be seen.

Can Path Workbench perform 3D surface milling?
Yes, Path provides for 3D surface milling Operations. It requires installation in the Macro file path of OpenCamLibrary--a 3rd party Open Source module.

OpenCamLibrary is not integrated into FreeCAD to ensure no licensing violations occur.

What do I do if the default Operation strategies don't meet my needs?
For Pocket Operations, the Start Point defaults to XYZ = 000, and is always on, but it too can be configured in the Property view window. Pocket and Facing Operations provide explicit Climb versus Conventional Cut Mode specification in the Operation tab.

For Contour style Operations, the Operation tab has a "Direction" input that may be configured as CW, or CCW, which defines the cut direction. For reference: Cut Side = Inside, Cut Direction = CCW, Climb Cut
 * 1) Cut Side = Outside, Cut Direction = CCW, Climb Cut
 * 2) Cut Side = Outside, Cut Direction = CW, Conventional Cut
 * 3) Cut Side = Inside, Cut Direction = CW, Conventional Cut

Start Points can be enabled--and configured in the Property view window.

In FaceMill Operations Material Allowance can be specified, allowing overcutting for positive values, and undercutting for negative values.

In Contour and Pocket Operations, the Extra Offset serves the same purpose.

These inputs are valuable, allowing functionality including:
 * 1) Defining Roughing Passes, in conjunction with the Depths input fields.
 * 2) Specifying overcut for Facing operations
 * 3) Features smaller than the Tool diameter, that must be faced, can benefit from specifying an Outside Contour cut with a negative Extra Offset value.

Judicious care should be exercised when specifying Material Allowances and Offsets, at the risk of undesired cuts into the Stock.

What do I do if an Operation generates more Vertical movements than my Job can tolerate?
Operations such as 3D_Pocket, Pocket_Shape, and FaceMill, but not Contour Operations have a configuration option to keep the tool down, in the Data tab of the Property View.

How can I leave tabs to clamp my milled work?
Path workbench provides a Tag dressup for just this purpose.

What is a Postprocessor?
The Postprocessor uses the [Path Job Operations FreeCAD G-Code dialect], in conjunction with the Postprocessor configuration definitions, to generate Dialect-Correct G-Code for a target machine. To simply illustrate the purpose of the Postprocessor, consider a small machine shop with two separate CNC mills using different CNC controllers, or with any combination of:


 * 1) CNC mill
 * 2) CNC lathe
 * 3) 3D Printer
 * 4) DragKnife Cutter
 * 5) Laser Cutter
 * 6) Engraver
 * 7) Plasma Torch Cutter
 * 8) Etc...

A single 3D Model could be used as the Base for Jobs targeting any combination of CNC machines--requiring anywhere from one Postprocessor to one per machine, depending on how many machines share a common Postprocessor.

Can I modify an existing, or make my own Postprocessor?
Postprocessors are Python scripts, and are saved in the Macro file path.

The provided Postprocessors are written with comments indicating areas containing Flags, Configuration Variables, and Sections of G-Codes and M-Codes that are to be used by the Postprocessor to configure the output.

Typical Configuration True/False Flags include:
 * 1) OUTPUT_COMMENTS (True = Allow, False = Suppress)
 * 2) OUTPUT_HEADER (True = Allow, False = Suppress)
 * 3) OUTPUT_LINE_NUMBERS (True = Allow, False = Suppress)
 * 4) SHOW_EDITOR (True = Allow, False = Suppress)
 * 5) MODAL (True = Allow, False = Suppress)

Typical Configuration Variables include:
 * 1) LINENR (Line Number Offset)
 * 2) UNITS (G20 or G21)
 * 3) MACHINE_NAME (Name of Target CNC Mill)
 * 4) PRECISION (Number of digits after the decimal place in final output file)

Typical Configuration Sections include:
 * 1) PREAMBLE (Code configuration inserted at beginning of the Job)
 * 2) POSTAMBLE (Code configuration appended to the Job, providing for parking the machine, etc...)
 * 3) TOOL_CHANGE (Code inserted with each tool change in the Job)

I only want to use one Postprocessor--can I make it the default, or hide other options?
The Edit->Preferences...->Path->Job Preferences tab, Defaults->Path is used to set the default Postprocessor selected on Job creation.

How I can set metric/imperial units for my path object?
The 3D model units are defined in the Edit->Preferences...>General->Units tab's User System drop menu.

The Units setting configuring how the the target mill interprets the Job G-Code is set in the output Postprocessor, which inserts a G20, or a G21 G-Code command to indicate inches or millimeters, respectively.

The Postprocessor also is configured for Units/Second, or Units/Minute. If set for Units/Minute, the Path workbench internal G-Code dialect Feed rate is multiplied by 60.

Mismatches between the 3D model and Postprocessor settings are likely culprits for factor of 60 errors in Feed rate, and factors of 25.4 in distance.

How I can simulate my milling strategies?
A volumetric simulator is provided to view the result of cutting the tool geometries included in the Job Operations against the Stock.

If the path lines obscure the simulation result, their visibility should be toggled off before simulation.

What is the significance of the path line colors?
Path line colors are defined in the Edit->Preference...->Path->Path colors tab. Default colors include:
 * 1) Green for normal paths.
 * 2) Red for rapid paths.
 * 3) Yellow for Probed paths.

How do I Enable/Disable visibility of path lines?
Path workbench allows control of the display of path lines by toggling the visibility of the Job by selecting it in the Combo View. The visibility of individual or groups of Operations are then toggled from the Combo View.

How do I check that my G-Code sequence is correct?
By default, the Postprocessor output is displayed in a window before saving. This--along with the Path CAM simulator provide a means to examine the Job before processing it on a CNC machine. The G-Code inspection tool allows you to inspect the internal Path G-Code for each Operation, providing a means to trace whether the output of the Postprocessor reflects what is defined in the Operation.

The Operations list in the Combo View panel displays the sequence that the operations will be processed in the Job. If the Operations are correct, but not in the desired sequence, that can be adjusted by double clicking the Operations list and dragging the Operations to their proper location, or by double clicking the Job editor and selecting the Workflow tab, then using the Up/Down arrows on selected Operations to sort them.

Why am I not getting correct G-Code output from my Postprocessor for Operations inserted using the Partial Command->Custom command?
Because the Custom G-Code command does not link to a Tool Controller, indicating the Tool index to the Postprocessor, Tool changes will not be correct, until the User hand codes the Tool control information at the beginning of the Custom G-Code. By example, for a 4mm diameter tool, given Index number 6, with Spindle speed equal to 10000, this would appear like:

(T6: 4mm Endmill)

M6 T6

M3 S10000

Feed rates will be incorrect if the Postprocessor shifts the output G-Code from Units/second to Units/minute, unless the Custom G-Code Feed rates are written in Units/second.

To match the FreeCAD G-Code dialect, typical output is: G0 XYZ

G1 F XYZ

Why do changes to Placement values in the Property View not seem to work correctly in Path workbench?
"The Path feature also holds a Placement property. Changing the value of that placement will change the position of the Feature in the 3D view, although the Path information itself won't be modified. The transformation is purely visual. This allows you, for example, to create a Path around a face that has a particular orientation on your model, that is not the same orientation as your cutting material will have on the CNC machine.

However, Path Compounds can make use of the Placement of their children (see below)."

[Path scripting]

Why does Path workbench on my computer seem to miss functionality that I see in other users forum posts?
By default, Experimental functionality is hidden in Path workbench. To enable it to use and test requires the user edit their

'Tools'->'Edit Parameters...' to create a new Boolean parameter BaseApp.Preferences.Mod.Path.EnableExperimentalFeatures, set to True.



Why do Youtube videos posted by Path workbench developers appear out of synch with the Path workbench?
Path workbench shifted dramatically from FreeCAD v0.16 to v0.17, and any videos posted prior to January 1st, 2018, are very likely to contain information that is no longer in synch with v0.17 of FreeCAD Path workbench.