Levelling

WARNING: This feature is in development. It is not ready for production. Test it with the spindle off and the tool away from the work.

Levelling measures the height of the workpiece at points that you choose, or at a grid of points. It then changes the Z values of a CNCJob G-code so that the cutting depth follows the surface. The tool does not move the machine. It writes probing G-code for the controller, and it uses the height map file that the controller writes.

Where to find it

• Menu: Options > Experimental. The tool is installed there without a keyboard shortcut.
• The tool opens in a new tab of the side panel. The tab shows the plugin name.
• The G-code Sender also has an autolevelling section. See GCode Sender.

Quick start

1. Create or select a CNCJob object that was made from a Geometry or Excellon object. An imported G-code file also works.
2. Open the Levelling tool from the Options > Experimental menu.
3. Select the CNCJob in Source Object.
4. Select the Controller: MACH3, MACH4 or LinuxCNC.
5. Set Probe Tip Dia, Probe Z travel, Probe Z depth and Probe Feedrate.
6. Keep Mode on Grid. Set Columns and Rows. Select a Method.
7. Click Add Probe Points. The probe points appear in the Probe Points Table.
8. Click Save Probing GCode. Load the file on the controller and run it.
9. The controller writes a height map file. Click Import Height Map and select that file.
10. The tool creates a new CNCJob named <name>_levelled. The source object does not change.

Screenshot placeholder: images/Levelling-1.png - the Levelling tool in the Plugin tab with the Source Object, the Controller and the Probe Points Table.

Screenshot placeholder: images/Levelling-2.png - the probe points on the canvas, with the grid and the Voronoi cells when Plot probing points is on.

Parameters

Title and object

Parameter	Description	Default
Beginner / Advanced button	Beginner hides many parameters. Advanced shows all parameters.	From global_app_level (Beginner)
Source Object	The CNCJob object to level. Only a CNCJob made from a Geometry or Excellon object, or an imported G-code file, can be used.	Active object, if it is a CNCJob
Controller	The controller for which the probing G-code is made. MACH3 and MACH4 use G31 with M40 and M41. LinuxCNC uses G38.2 with a PROBEOPEN file. The GRBL choice was removed. Use the G-code Sender for GRBL.	MACH3

Probe Points Table

Parameter	Description	Default
Show	Shows or hides the Probe Points Table.	Checked
Probe Points Table	Lists each probe point with a number, its X-Y coordinates and its height. The heights are read only.	Empty
Plot probing points	Draws the probe points on the canvas. For a Voronoi method, it also draws the Voronoi areas.	Unchecked
Avoid Excellon holes	When checked, a probe point is not placed over a drill hole of an Excellon object. In Grid mode, the point moves to the side.	Unchecked
Avoid Step	The distance, in mm, that a grid point moves each time it is blocked by a drill hole. Shown only when Avoid Excellon holes is checked. Must be above 0.	0.5

Parameters

Parameter	Description	Default
Probe Tip Dia	The diameter of the probe tip, in mm. Used to check the holes and to draw the probe point. Range 0 to 10.	0.3
Probe Z travel	The safe Z height for travel between probe points, in mm.	2.0
Probe Z depth	The lowest Z that the probe can reach while it probes. Negative value.	-1.0
Probe Feedrate	The feedrate of the probe move, in units per minute.	120

Mode and method

Parameter	Description	Default
Mode: Manual	You add probe points by clicking on the canvas.	-
Mode: Grid	The tool builds a grid of probe points over the bounds of the object.	Grid
Method: Voronoi	Each probe point covers the area that is nearest to it. The height of a move is the height of the nearest probe point.	Voronoi
Method: Bilinear	Interpolates the height inside each grid cell. Needs a grid. Not available in Manual mode.	-
Method: Bicubic	Makes a smooth surface through the grid points. Needs at least 4 rows and 4 columns. Not available in Manual mode.	-
Columns	The number of grid columns. Minimum 2 for Bilinear and Bicubic. Minimum 1 for Voronoi.	4
Rows	The number of grid rows. Minimum 2 for Bilinear and Bicubic. Minimum 1 for Voronoi.	4

Method and grid size are disabled in Manual mode. Manual mode always uses Voronoi.

Buttons

Button	Description
Add Probe Points	Creates the probe points in the current mode. It clears the earlier points and the earlier probing G-code.
Save Probing GCode	Saves the probing G-code to a file. The default file name is probing_gcode.
View/Edit the probing GCode (icon)	Opens the probing G-code in the Code Viewer. Click Update code in the viewer to keep your changes.
Import Height Map	Reads a height map file and creates the levelled CNCJob.
Reset Tool	Resets the parameters of the tool.

Advanced

Manual mode

• Left click on the canvas to add a probe point. The point must be inside the bounds of the object.
• A point on an Excellon drill hole is refused when Avoid Excellon holes is checked.
• Right click or press Escape to finish. The tool then builds the cells and the probing G-code.

Grid mode

• The points are placed at equal steps over the bounds of the object.
• The points are sorted in a snake order, so the probe does not cross the board between rows.
• When Avoid Excellon holes is checked and a point is over a hole, the point moves in steps of Avoid Step. It moves right, left, up and down, up to 10000 steps in each direction. A point that cannot leave the hole is not added.

Interpolation methods

• Voronoi uses the nearest probe point. It works with any set of points.
• Bilinear needs the points on a regular grid. If the points do not form a regular grid, the tool shows a warning and uses Voronoi instead.
• Bicubic needs at least 4 x 4 points with equal spacing. If the grid is too small or not regular, the tool shows a warning and uses Bilinear instead.

Importing a height map

• The file is a text file. Each row is X,Y,Z (comma separated, as MACH3 and MACH4 write) or X Y Z (space separated, as LinuxCNC writes). Extra columns are ignored. Lines that cannot be read are skipped.
• Each row is matched to the nearest probe point.
• If some rows do not match a probe point, the tool shows a warning and continues.
• If some probe points have no row, the import is refused with an error.
• If no probe points exist, the import creates them from the rows.
• The levelled CNCJob is created after a complete, valid map.

What the levelling changes

• Only the Z word of each cutting move is changed. The X and Y values stay the same.
• The levelled object is named <name>_levelled. The source CNCJob is not changed.
• The units of the CNCJob and of the height map must be the same. The tool stops with an error if they are not.
• A move outside the probed area uses the selected method. The tool counts these moves and shows a coverage warning.

Limits

• The probe points must lie inside the bounds of the object. The probing G-code uses the same units as the application.
• The probing G-code header states the name of the object, the units and the creation time.
• The tool does not perform the probing itself. The controller runs the probing G-code, and the controller writes the file.

Tcl

No Tcl command was found for this tool. See Tcl Command Reference.

See also

• GCode Sender - the same probing and autolevelling, with a live connection to GRBL and a job stream.
• E-Cut - the E-Cut USB motion board. It is not used by Levelling.
• CNCJob Object - the object that Levelling changes.
• Preprocessors - the G-code format for each controller.
• Preferences-CNCJob and Preferences-Plugins.
• Keyboard Shortcuts and FAQ and Troubleshooting.