Bed height mapping: probe a grid, bend Z to match the surface

[mandy-apperkeeper]

The idea

Probe the work surface on a grid, store a height map, and offset Z on
every move so the focal point follows a surface that is not flat.

Why

I run a large laser (8ft x 8ft bed) cutting fabric. Over that span the
bed waves by several millimetres — far more than the lens depth of focus.
A single Z height cannot stay in focus across the sheet.

Today the workaround is to export from Rayforge, then run the file through
bCNC's AutoLevel to inject Z, then send that to the controller. It works,
but it means a second program in the loop and the Rayforge preview no
longer matches what runs.

Most of this already exists

Reading through, the hard parts look done:

• Driver.run_probe_cycle(axis, max_travel, feed_rate) -> Pos | None,
  implemented for GRBL serial and network, returning the trigger point.
• probe_cycle: G38.2 {axis_letter}{max_travel} F{feed_rate} in the GRBL,
  Marlin, Smoothieware, LinuxCNC and Mach4 dialects, and in 29 of the 34
  shipped device dialects.
• z_cmd already in the travel_move, linear_move and arc templates.
• core/capability.py already notes # Future: PROBE, DWELL.

What is missing is the middle: loop the probe over a grid, keep the map,
and add the interpolated Z.

Suggested split

The probing and the map look like a clean addon — rayforge_init to reach
the machine driver, register_actions for a "Scan Bed" command and a map
view.

The Z offset itself cannot be done from an addon, as far as I can tell,
because both OpsTransformer.to_spec() and ops.to_gcode() cross into
raygeo. A height-map transformer spec in raygeo seems to be the one piece
that has to happen upstream.

Two things Rayforge could do better than bCNC

1. Probe offset. bCNC keys its map to machine coordinates with no field
   for where the probe sits relative to the tool, so a side-mounted probe
   shifts the whole map. Rayforge knows the head layout.
2. Arcs. bCNC reads finished G-code, so it has to flatten every arc
   into segments to subdivide them. Rayforge still has the geometry.

Happy to test on real hardware — FluidNC over wifi, 8 ft^2 bed, working
probe (I'm using the actual laser case itself, since the focal distance is measured from it).

[knipknap]

Hey Ben,

Thank you for the idea! I know such bed maps exist in software like Klipper/Moonraker, which is however a controller feature. I guess it would be possible to apply such Z corrections before sending G-code to the controller, but it would have some drawbacks. For example, imagine a single large arc being drawn. Normally, this is a single G-code command sent to the machine. If Rayforge were to adjust the Z height while travelling along the arc, it would have to split it into many small segments / commands.

It is technically possible, but it does (drastically) increase the G-code size and decreases precision. So in general, a superior solution is having the controller interpolate - which is what firmware like Klipper does. But given that Grbl does not support this, an application-side workaround may be acceptable, and a post processor could be created that applies such bed mesh based height corrections.

Your question about whether this could be done by an addon: Yes, it could. It would be a post processor that uses the Ops api to apply corrections. However, I would strongly recommend implementing this in Rust/raygeo instead, as this would be vastly faster and way more memory efficient - the main reason why all other post processors were already moved to Rust.

[mandy-apperkeeper]

Thanks -- that's a fair objection, and segment count is the real cost.

Two things shrink it a lot:

Subdivide against the mesh, not a fixed length. bCNC splits at grid-cell boundaries. On my bed a 100 mm grid turns a 1 m arc into ~10 segments. It can go further: the correction only needs to be finer than the lens depth of focus (~±0.6 mm here), so the split can follow the map's local slope -- emit the arc untouched where the mesh is flat, subdivide only where the surface actually moves. On a bolted frame that's a small fraction of the path.

On the Python-vs-Rust point, I measured it. I installed raygeo==1.59.0 and timed a bilinear 25x25 mesh correction over a 2400 mm bed using Ops.to_numpy_arrays() / Ops.from_numpy_arrays():

Commands	Time
50,001	35-44 ms

One numpy broadcast over the endpoints array, no Python loop over commands, command count unchanged.

I think this post processor may be unusual: the others do real per-command geometry, whereas this one adds a column to an array that is already contiguous. So the Rust argument might be weaker here than it is elsewhere.

Ops.transform_moving() with its Python callbacks also looks like a clean fit, including on_aux_point for arc control points.

One thing I couldn't find a route to from an addon: OpsTransformer.to_spec() requires one of the typed specs in raygeo.ops.transform, and I don't see a generic one, so an addon can't occupy the transformer slot itself -- which I think means no live preview of the warp. Is a register_actions command plus an Ops pass before export the intended shape for something like this, or have I missed a hook?

Chord error is a non-issue at my scale -- over 100 mm of a large-radius arc it's well under the laser kerf in fabric. And sewing-pattern input is mostly lines and already-flattened splines, so few true arcs survive to the toolpath anyway.

Happy to test on real hardware: FluidNC over wifi, 2.4 m bed, working probe, and a surface that genuinely needs the correction.

[knipknap]

Raygeo:

Rayforge:

Note that the Rayforge change is NOT merged. Since I cannot test this - my machine has no Z axis - the Rayforge PR needs testing by someone who has a machine with a Z axis + probing support before this can make it into a release.

[mandy-apperkeeper]

Ill have my machine up and running soon, just have to run the motor cabling and the endstops, then ill have x,y,z for you to test whatever you need.