OpenCarvePython

Image-to-G-code for CNC surface machining with an interactive 3D toolpath viewer

OpenCarvePython — main interface with a loaded image and toolpath preview

Project Overview

OpenCarvePython turns grayscale images — heightmaps or bas-relief artwork — into G-code for CNC surface carving. A PyQt5 desktop UI pairs configurable machining parameters with a real-time 3D visualization of the generated toolpath, a postprocessor that compacts the G-code output, and a runtime estimator that previews job duration before sending it to the machine.

Stack

PythonPyQt5OpenGLNumPy & PillowCNC / G-code

Interface Walkthrough

The desktop app puts image loading, parameter configuration, G-code generation, and 3D preview into a single window. Operators switch between the 2D heightmap view and the 3D toolpath viewer without losing context, and can hide rapid moves to inspect the actual cutting path more clearly.

Main view — parameters on the left, loaded image on the right, G-code panel and toolpath preview in the same window.
Main view — parameters on the left, loaded image on the right, G-code panel and toolpath preview in the same window.

Workflow

Load a grayscale image via the Load Image button — each pixel is read as a height value.
Configure the machining parameters: pixel size, maximum depth, safe Z, XY and Z feed rates, spindle RPM, step-down, and boundary margin.
Generate the G-code, inspect it in the 3D viewer, optionally run it through the postprocessor, and send the result to the CNC machine.

3D Viewer & Controls

Middle mouse button — orbit mode to rotate the scene around the workpiece.
Left + right mouse buttons together, or Shift + middle mouse button — pan mode for lateral view shifts.
Mouse wheel — adjusts camera distance and zoom level.
Navigation cube top-right — clicking a face snaps the view to a predefined orientation.
Rapid moves can be hidden so the actual cutting profile stands out clearly.

Machining Parameters

Pixel Size (mm) — sets the step between adjacent G-code paths and therefore the physical scale of the carved part.
Maximum Depth (mm) — the deepest cut; darker pixels approach this depth.
Safe Z (mm) — travel height for rapid moves between cutting segments to avoid collisions.
Feed Rate XY (mm/min) — horizontal traversal speed during cutting moves.
Feed Rate Z (mm/min) — plunge and retract speed for vertical moves.
Spindle Speed (RPM) — rotation speed of the cutting tool.
Step-Down (mm) — depth per pass; if the maximum depth isn't reached in one pass, the tool cuts down in increments of this value.
Boundary Margin (mm) — safety margin around the toolpath; the effective machining area is reduced by twice the margin.

Examples

Input images and rendered toolpaths from the repository: topographic heightmaps, Hochschule Kaiserslautern logos, and classic bas-relief samples.

Topographic heightmap — one of the sample inputs from the repository.
Topographic heightmap — one of the sample inputs from the repository.

Highlights

Converts grayscale images into precise G-code toolpaths for CNC machining.
Configurable machining parameters like depth, feed rates, spindle speed, step-down, and boundary margin.
Interactive 3D viewer for toolpath inspection and navigation before machining.
Built-in G-code postprocessing to merge compatible commands and reduce output size.
Estimated machining runtime based on generated G-code.