Path Sanity

From FreeCAD Documentation
Jump to navigation Jump to search
Other languages:
English • ‎français • ‎italiano

This documentation is not finished. Please help and contribute documentation.

GuiCommand model explains how commands should be documented. Browse Category:UnfinishedDocu to see more incomplete pages like this one. See Category:Command Reference for all commands.

See WikiPages to learn about editing the wiki pages, and go to Help FreeCAD to learn about other ways in which you can contribute.

This is an unfinished experimental feature. Enable Experimental Features

Path Sanity.svg Path Sanity

Menu location
Default shortcut
Introduced in version
See also


Many Path users are hobbyists and DIYers. As such, they use their CNC machines to run gcode that they configured and generated themselves. That isn't the case for most professional/commercial users. In professional shops, different people are responsible for creating the gcode (CNC programmers) from those who run it on the machines (CNC operator).

Hobbyists usually run the gcode just a few minutes after post-processing it and probably only a once or twice. In a professional shop, proven gcode may be run many times for months or years after initially generated.

One issue that arises in a professional CNC shop is that there are many assumptions made by the programmer that are NOT communicated in the gcode itself. For example, the gcode can call for a tool "T3" but unless its commented, the gcode doesn't say what kind of tool "T3" refers to. It's just assumed that T3 in the CAM system is the same as T3 on the machine. There are many assumptions like this involving machine setup, tooling, material, part orientation, etc. Even if the gcode is perfect, if the operator doesn't set up the machine with the same assumptions, it can crash.

Commercial shops will often create a 'setup book' which documents all these assumptions and gives the operators what they need to configure the machine and produce a part.

Path Sanity is the tool in Path workbench to generate this kind of information. The output of the Path Sanity command is a stand-alone html file with embedded images.

Above: Example of a Path Sanity generated report

About the Report

As much as possible, the content is FreeCAD agnostic. The CNC Operator may never use FreeCAD so FreeCAD/Path specific terminology is confusing. The report has distinct sections and is formatted to make finding things easy and predictable.

Part Information

This section gives an overview of what is being made. Ideally the image should show the base objects. If there are multiple base objects, the image should show how they nest.

Run Summary

Gives a quick view of minimum and maximum heights and run times.

Rough Stock

Details the Stock object from the Job. This is an area where Path would benefit from some improvement. A rudimentary material property for the stock would be useful here and could also be used to help suggest feeds/speeds.

Tool Data

Has subsections for each tool number used in the job. It details what the programmer assumes the tool to be and which operations are using it. This section only works with the new toolbit system. This is another area where Path needs improvement. Specifically, Toolbits need additional attributes about the tool like manufacturer/url/part number.


Gives details about where and when the gcode was post-processed. It also shows whether the job contains optional/mandatory stops so the operator knows if it's safe to walk away from the machine during a run.



Fixtures and Work-holding

Shows the parts in the context of the stock envelope and also shows the Part origin.


Warnings and errors detected by Path Sanity. These may or may not be problems but they're noted for additional attention. For example if the same tool number is used for different toolbits, it will show as an error. If a tool controller has no feed/speed configured, it will appear as a warning. It will also detect and warn about unused tool controllers. Path would benefit here from the ability to add arbitrary notes or warnings.


  1. Selects a Path job in the Tree view
  2. Invoke the Path Sanity.svg Path Sanity button.
    • The relevant information is collected into a python dictionary and then formatted into asciidoc format.
    • The asciidoc file is written to disk in the same location as the file that will be post-processed.
    • An external process calls asciidoctor to read the asciidoc and generate the html.
    • This will auto-launch the system web browser to view the generated standalone HTML report.

Note an ASCIIDOC and Asciidoctor

Asciidoc is a lightweight markup format for authoring notes, articles, books ,etc. It is human-readable and easily translated into other formats.

Asciidoctor is a fast open-source text processor for converting asciidoc into HTML, PDF, or other formats. It's available for Linux, Windows, and MacOS. Asciidoctor is not installed with FreeCAD. If you use Path-Sanity without installing Asciidoctor, the asciidoc source file will be generated but the resulting HTML will not be produced. Asciidoctor website