CAM Sanity

CAM Sanity CAM Sanity

Menu location

CAM  Sanity Check; also in the Tree View context menu of a Job

Workbenches

CAM

Default shortcut

P S

Introduced in version

0.19

See also

CAM QuickValidate, CAM Post

Description

Many CAM users are hobbyists and DIYers. As such, they use their CNC machines to run G-code that they configured and generated themselves. That isn’t the case for most professional and commercial users. In professional shops, different people are responsible for creating the G-code and for running it on the machine.

Hobbyists usually run the G-code shortly after post-processing it and probably only once or twice. In a professional shop, proven G-code may be run many times over a long period.

One issue in that workflow is that many assumptions made by the programmer are not communicated by the G-code itself. For example, the G-code may call for a tool T3, but the file does not necessarily explain what tool that is, how the stock is oriented, or what setup is expected. Similar assumptions can apply to machine setup, tooling, material, part orientation, coolant, and work-holding.

Even if the G-code itself is correct, differences between the programmed setup and the actual machine setup can still lead to mistakes. Commercial shops often solve this by preparing a setup report or setup book for the machine operator.

The CAM Sanity CAM Sanity command (tooltip: Checks the CAM job for common errors; toolbar: Project Setup → Sanity Check) is used to generate this kind of setup-oriented information. The output is a standalone HTML report with embedded images that can be opened in a web browser.

The figure shows the report of a Job that has one Profile Operation.

Setup Report for CAM Job: Job, with the Run Summary table and the Squawks section

Above: Example of a CAM Sanity generated report

About the Report

As much as possible, the content is FreeCAD-agnostic. The machine operator may never use FreeCAD, so FreeCAD- and CAM-specific terminology should be kept to a minimum. The report contains a table of contents and the sections Part Information, Run Summary, Rough Stock, Tool Data, Output (G-code), Fixtures and Squawks.

Part Information

Shows the CAD file name and last save date, the Customer (document Company field), the Job type, the Job’s sequence among the Jobs of the document, the Job description, an image of the Model(s) and the list of Models with their counts.

Run Summary

Lists the estimated total cycle time, the lowest and highest Z of the Job, and a table of every Operation with its Z range, cycle time and coolant mode. Inactive Operations are flagged with "(INACTIVE)"; Dressups are listed with their base Operation.

introduced in 26.3: The Z values of the Run Summary are in Job coordinates. For an Operation that links to a Work Plane, the report calculates the Z range from the Toolpath at its position in the Job. The Z range of the Job is the lowest Z and the highest Z of all its Operations. An Operation without a Toolpath has an empty Z range.

Rough Stock

Shows the Stock dimensions, the assigned stock material with its carbide and HSS surface speeds (if defined; see Assign Material on the Job’s Setup tab), and an image of the Stock.

Tool Data

One subsection per tool number with the Tool Bit description, shape, diameter, an image of the Tool Bit, horizontal feed, spindle speed and the Operations that use the Tool Controller. Manufacturer, URL, part number and inspection notes are reserved and currently empty.

Output (G-code)

Shows when the Job was last post-processed, the G-code file name, size and line count, whether the Job contains Stop operations (so the operator knows whether the machine run requires attention during execution), the Post-Processor and its arguments.

Fixtures

Lists the Work Offsets (Fixtures) and the output order, with an image showing the part datum relative to Stock and Model.

Squawks

This section lists warnings and errors detected by CAM Sanity. Each squawk has a type (Note, Tip, Caution, Warning) shown by an icon, a date, an operator and a note. Current checks: Job not yet post-processed; last G-code file missing; no stock material assigned; legacy tool; tool number used by several Tool Bits; Tool Controller without feed rate or spindle speed; unused Tool Controller; Job without Operations or Model. When a Machine is assigned, the machine-based Post-Processor can add its own checks. These items may or may not be actual problems, but they should be reviewed before post-processing or running the Job.

introduced in 26.3: A machine-based Post-Processor checks each commanded Spindle Speed of the Job against the speed limits of the Toolhead of the Machine. The check reads the Spindle Speed from the M3 and M4 commands in the Toolpaths of the Tool Controllers and the Operations. The check does not read the Spindle Speed property of the Tool Controller.

The Spindle Speed check gives these Squawks:

  • A Spindle Speed below the minimum speed of the Toolhead gives a WARNING Squawk: '<label>' commands spindle speed <speed> rpm, below the machine minimum of <minimum> rpm.

  • A Spindle Speed above the maximum speed of the Toolhead gives a WARNING Squawk: '<label>' commands spindle speed <speed> rpm, above the machine maximum of <maximum> rpm.

  • A Machine with more than one Toolhead gives a NOTE Squawk: Machine defines <count> toolheads; spindle speed was not checked against their limits.

The <label> in a WARNING Squawk is the label of the Tool Controller or the Operation that commands the Spindle Speed. The Spindle Speed check reports each combination of label and Spindle Speed one time.

The Spindle Speed check has these conditions:

  • The check applies only when the Machine has exactly one Toolhead and the type of that Toolhead is rotary.

  • A Toolhead limit of 0 is a limit that is not specified. The check does not compare the Spindle Speed with a limit that is not specified.

  • The check ignores a commanded Spindle Speed of 0.

introduced in 26.3: A machine-based Post-Processor checks the rotary axis moves between the Operations of the Job. The rotary axis check calculates the rotary axis positions of each active Operation from the Work Plane of the Operation. A Dressup uses the Work Plane of its base Operation.

The rotary axis check gives a WARNING Squawk when all these conditions are true:

  • The Machine has rotary axes.

  • The Pre-Rotary Move Post-Processor Property of the Machine is empty.

  • Two consecutive active Operations have different rotary axis positions.

The text of the rotary axis Squawk is: The rotary axes move between operations and the Pre-Rotary Move property of machine '<machine>' is empty. Put the moves that bring the tool clear of the part there, in machine coordinates (for example G53 G0 Z0).

The rotary axis check ignores an Operation on a Work Plane that the Machine cannot index to. The Post-Processor refuses that Operation when it writes the G-code.

introduced in 26.3: A machine-based Post-Processor checks the Fixture property of each Work Plane of the Job. A Fixture is a G54 to G59.9 selection, not the clamping of the Stock. The Fixture check ignores a Work Plane that names no Fixture.

The Fixture check gives these Squawks:

  • A Fixture value that is not an accepted Fixture word gives a WARNING Squawk: Work plane '<plane>' names '<fixture>' as its fixture, which is not a work coordinate system (G54-G59.9, or G54.1 Pn). The post will refuse it.

  • A Fixture that is also in the Fixtures list of the Job gives a WARNING Squawk when that list has more than one Fixture: Work plane '<plane>' selects <fixture>, which is also one of the fixtures the Job repeats its program for. Inside each repetition the plane’s selection wins.

The <plane> in a Fixture Squawk is the label of the Work Plane. The accepted Fixture words are G54 to G59, each with an optional decimal digit from 1 to 9 and an optional P number. The Fixture check accepts upper case and lower case letters.

A Post-Processor can replace, add or remove a check. Refer to Writing a Machine-Based Post-Processor.

Usage

  1. Select a CAM Job CAM Job in the Tree View.

  2. There are several ways to invoke the command:

    • Press the CAM Sanity Sanity Check button.

    • Select the CAM  Sanity Check option from the menu.

    • Select Sanity Check from the context menu of the Job.

    • Use the keyboard shortcut: P then S.

  3. In the Save Sanity Check Report dialog choose where to save the HTML file (defaults to the folder of the FreeCAD document).

  4. The report is written and opened in the system’s default web browser; the path is also printed in the Report view.

Quick Validate

introduced in 26.3

The related command CAM QuickValidate (shortcut P V, not in the menus; run it with Gui.runCommand('CAM_QuickValidate')) runs the same checks without images or HTML and prints the squawks to the Report view.

Post Process dialog integration

introduced in 26.3

When post-processing with a Machine, the Post Process dialog runs the same checks and shows them on its Warnings tab (the tab label shows the count and a "(!)" marker when warnings or cautions exist). The Overview tab has a Generate HTML sanity report checkbox (in the current development version this option is collected but does not yet write a report).

Notes

  • The report is generated directly as HTML by FreeCAD. A separate AsciiDoc or Asciidoctor installation is not required.

  • The generated HTML file is intended to be easy to review, archive, or share together with the Job output.

  • Report images are captured from the 3D view and embedded directly in the generated HTML file, so a report generated in FreeCADCmd (without the GUI) has no images.

  • The target folder must exist.

  • Where applicable, report values are formatted for display using the current unit formatting.

  • Tool diameter and feed values are formatted for display, and spindle speed is shown with an rpm suffix.

  • The report is a review aid. It does not replace visual Toolpath inspection, simulation, or machine-specific setup documentation.

Scripting

from Path.Main.Sanity import Sanity
checker = Sanity.CAMSanity(job, '/tmp/report.html')
open('/tmp/report.html', 'w').write(checker.get_output_report())
squawks, critical = Sanity.CAMSanity.validate_job(job)