Skip to content

Flat: contour-parallel offset passes, area by area, with arc entries (#38) - #359

Merged
10-X-eng merged 26 commits into
stevecad:mainfrom
Wookie1:flat-area-38
Nov 21, 2026
Merged

10-X-eng merged 26 commits into
stevecad:mainfrom
Wookie1:flat-area-38

Conversation

@Wookie1

@Wookie1 Wookie1 commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #38. The CAD floor-boundary input and optional final wall pass are tracked in #371.

Flat now finishes each level with contour-parallel offset passes instead of raster rows. Every pass keeps the exact per-facet proof the rows had, and no entry plunges into stock.

What changes

Passes

  • The region of tool centres on a level is the level's shadow grown by the cutter radius, minus everything standing above it grown by the radius plus its stated errors. Its inward offsets at 0, stepover_mm, 2·stepover_mm, ... are the passes, cut outside in, with climb milling (outer loops CW, hole loops CCW).
  • A core deeper than a radius, and corners where an offset pinches off, get half-step passes, so the disk covers every reachable flat point at stepovers up to the cutter diameter.
  • Offset loops are cut as arcs. Each arc is proven by its chords, each chord is held to the same proof with radius r + sagitta, and the arc is emitted as arc blocks only when every chord proves. A chord that can't be proven is halved down to 1/16 of the loop, and what still fails goes to dropped_length_mm.
  • An inner ring is cut only where floor is left that the earlier rings' swept disks did not reach. Each kept ring's sweep is subtracted from every depth's remaining area, so passes don't run over air or over floor that is already finished.
  • Areas are ordered so that each one is finished before the tool crosses to the next. A loop waits for every shallower loop within two radii of it, and the nearest available loop is cut next. This order is used only when it needs fewer entries than the plain order, or the same number with less travel.
  • Consecutive pieces join by a straight link at cut height and cutting feed when the link is at most two stepovers long, passes the same proof and lies inside the machine limits.

Entries (in this order; nothing is ever plunged into stock)

  1. An arc lead-in: a vertical plunge through air, then a quarter circle of the tool radius, tangent to the pass. It is flat at cutting feed when the plunge point is a radius beside the face or over finished floor, and a helix at the declared ramp angle otherwise.
  2. A plunge at the pass start where no stock stands above it.
  3. An arc ramp, used where the stock left over the pass is shallow: a plunge through air, an arc of the tool radius that turns to the declared RampEntry angle above the stock, a straight leg at that angle, and an arc of the tool radius onto the pass. The stock is never met steeper than the declared angle, and the whole descent starts at most four tool radii back. Where the cells beside a wall are too tall to ramp along the pass, the arc ramp comes down beside the pass start on its open side, followed by a level arc lead-in. A closed loop with no room at its start is entered the same way at the middle of a straight side, and the loop starts and ends there.
  4. The existing zigzag ramp along the first loop, with its refusals unchanged.

Every plunge that ends on a finished face stops one radius high and turns to horizontal on a quarter circle, so it leaves no plunge mark. Each chain ends with a tangent quarter-circle lead-out where its end is clear.

API and report

  • New radial_stock_to_leave_mm (default 0): the radial stock left on the walls. Passes stay that much farther than the cutter radius from everything standing above a flat. This is a stock declaration, not a switch.
  • axis is still accepted so old jobs load, but it no longer orders anything and is unused.
  • New report fields: loops, rows (loops cut, counting the open pieces of a split loop), links_at_depth, arc_lead_ins, arc_lead_outs, rounded_plunges and arc_ramps (also counted in ramped_entries).
  • docs/operations.md: the Flat section describes the passes, the order, the entries and the report fields.

Existing tests changed

python/tests/test_flat.py: only the stock in the two ramp tests. Their blank had exactly the part's footprint, so every open side was air outside the stock. The new side and arc lead-ins enter there, and the tests stopped exercising a ramp. The stock now extends 10 mm beyond the part, so the chains still have to ramp:

  • roughed() takes a margin argument: the blank is (24 + 2m) × (16 + 2m), shifted by (−m, −m). The 3-degree ramp test uses roughed(margin=10).
  • test_a_ramp_that_does_not_fit_is_refused_not_plunged uses a StockSpec((-10, -10, 0), (34, 26, 8), 0.25) for both of its simulations.

The asserts and the expected refusal messages are unchanged.

New tests

python/tests/test_flat_offset.py checks the output against the part geometry and the stock, independently of the planner:

  • Coverage of every reachable flat point. The tool never reaches into the part above its tip and never cuts below the part.
  • No moves of kernel artefacts, and climb milling.
  • Few entries and links at depth. Passes don't run over finished floor, and each area is finished before the tool crosses to the next.
  • Open edges are entered from the side in air, and the first ring of each level follows its edge.
  • No vertical plunge onto a finished face: plunges turn to horizontal on a quarter circle, and entries over finished floor plunge rather than spiral.
  • Entries plunge in air and lead in and out on tangent arcs.
  • Arc ramps meet the stock at no more than the declared angle, and every move above the stock stays above the live stock's top.
  • Radial stock is left on every wall.

Measured

macOS arm64, release. Only the flat workload changes, and every other workload matches its expectations. bench/expectations/flat.json is updated with bench/expectations.py in a separate commit.

flat (flats) main this PR
Moves 222 197
Cycle s, exact stop / tangent 190.98 / 190.98 40.43 / 38.90
Posted blocks 245 224
Cut mm 964.8 329.1
Air cut mm 426.8 39.5
Link mm 0 7.8
Rapid mm 458.8 55.4
Plunges / retracts 105 / 39 3 / 3
Removed mm³ 36.02 37.57
Leftover mm³, certain / possible 0.950 / 104.63 0.000 / 103.08
Overcut mm³, certain / possible 0.000 / 24.40 0.000 / 48.00

Possible overcut. The upper bound rises from 24.40 to 48.00 mm³ because the last ring now runs tangent to the boss wall, so the cells on both sides of the wall face count as possible overcut. Main stops its rows about 0.005 mm short of the wall and leaves a 0.1 mm rim there (the 0.95 mm³ certain leftover, now 0). It is a cell-resolution bound with no definite cells. All 256 cells lie on the boss wall's cell band, and the bound halves with the cell size: 24.00 mm³ at 0.125 mm, 12.00 at 0.0625 mm (main: 11.81, 5.86). A separate check sampled every feed move every 0.01 mm against the exact box geometry. No cut move enters the part, and the closest approach is 0.0011 mm off the boss wall (main: 0.0051 mm).

Limits and costs

  • Arc entries and lead-outs add short moves through air, about 9–13% of feed length on a 3x-scale stepped part and an island part (1/4" tool, 0.1 mm radial stock).
  • The stock grid gives the cells next to a wall the wall-top height. A ramp along a pass that starts beside a wall would start from the wall top, which is why the arc ramp comes down beside the pass instead. A finer stock grid would make this unnecessary.
  • The 48 × 32 mm stepped part with a 2 mm cutter and zero radial allowance is a regression fixture. Two adjacent straight chords in a mixed line/arc boundary can be strictly ordered in Y even when the arc backend reports an overlap. Their Y intervals meet only at the common endpoint. The planner now keeps the unswept remainder for subsequent rings. A separate six-vertex boundary test rejects a genuine backtrack.

Checks run

  • macOS arm64, at this branch's head, rebased on main ac7d965. cargo test lib + tests: 1171 passed. Doc tests: 1 passed. Python unittest: 1080 OK, 19 skipped. cargo fmt --check and ruff (check and format) are clean. clippy shows only the 2 src/surface/spline_bounds.rs lints from the local toolchain, which this branch doesn't touch and which main also shows. Both examples export with --accept-unchecked-machine, and without it each refuses in a fresh directory and writes no NC file.
  • Linux x86_64: the flat tests only (test_flat.py, test_flat_offset.py), before the rebase onto ac7d965, passing.
  • Windows: through CI.

The passes run outside in, so the stock still to cut lies inward of each
ring: outer loops now run clockwise and holes counter-clockwise, putting
that stock on the right of travel (climb with a clockwise spindle). Before,
the outer-loop-CCW orientation of pocket walls made most flat cutting
conventional (stepped part: 40 mm climb against 199 mm conventional).

refit_arcs also refits runs that mix straight chords with micro-arcs on one
circle (the island part's 258 sub-0.01 mm cuts at Z5), and straight stubs
under ARC_MOVE_SAGITTA are absorbed into a straight neighbour (the corner
grid-snap stubs). Island 899 -> 644 motions, stepped 451 -> 449.
@Wookie1 Wookie1 self-assigned this Nov 20, 2026
@10-X-eng

Copy link
Copy Markdown
Contributor

The doubled stepped part (48 × 32 mm, 4 mm tool, 1.5 mm stepover, zero radial allowance) reproduced the reported refusal. A six-vertex mixed boundary independently reproduced the false overlap. The geometry regression accepts monotone adjacent straight edges and still rejects a true backtrack.

A second stepped fixture exposed a debug assertion in the arc library when it subtracted overlapping sweeps individually. Flat now subtracts all capsules of a retained ring together through the existing bounded integer kernel. It keeps narrow unswept floor available to later passes. The independent checks follow the actual arc/helix and measure coverage against finite arcs.

All 17 flat-offset tests passed locally on Linux with debug assertions. The release benchmark on the revised code matched every committed flat expectation: 197 moves, 3 plunges, 38.895 s tangent cycle and zero certain overcut.

@10-X-eng
10-X-eng enabled auto-merge November 21, 2026 14:37
@10-X-eng
10-X-eng added this pull request to the merge queue Nov 21, 2026
Merged via the queue into stevecad:main with commit 4cf6317 Nov 21, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Optimize Flat-area finishing

2 participants