CAM improvements for the Adaptive operation

[davidgilkaufman]

Proposal description

The goal of the Adaptive clearing operation is to allow users to generate tool paths with constant load on the tool. FreeCAD's implementation of Adaptive clearing works in some cases, but also has buggy behavior for small stepovers and for entrance selection, and missing rest machining features, cumulatively inhibiting usability. I will solve these problems.

Deliverables

I propose 3 separate sub-projects:

1. Improve algorithm to enable successful generation at small stepovers

When you generate an adaptive toolpath with a "small" stepover (almost always at 1% stepover, less often as stepover increases, rare by 6% in my experience), generation often fails part way through computation, and no toolpath is produced. This is a poor user experience. Users are forced to repeatedly retry this compute-intensive generation process at increasing stepover, and then when generation succeeds, recalculate and program new feeds and speeds to match the heavier-than-desired tool load. I propose improving the adaptive toolpath generation algorithm so adaptive tool paths generate reliably at small stepovers.

Deliverables:

• a model that cannot generate adaptive toolpaths at small stepover
• a code change to enable successful generation of the toolpath

2. Improved automatic diameter selection for entry helix

Adaptive operations have a parameter HelixMaxDiameter that controls the size of the helix used to enter the adaptive toolpath. The default value (0mm) triggers a simple automatic selection of the size of this helix, always pricking 0.75 * tool diameter. However, if this automatic helix does not fit at the desired start location, tool path generation will fail with the message "Start point not found!", even though it could have worked with a smaller helix entrance. Users who do not know the full details of this process often do not understand what changes they could make to manually specify a valid entrance helix, and are entirely unable to use the adaptive operation for their model. I propose adding a new parameter to constrain the minimum acceptable helix size, and improving the automatic helix algorithm to always successfully generate an entrance helix if it is possible to do so at an acceptable diameter.

Deliverables:

• a model that fails to generate an adaptive toolpath due poor selection of helix diameter
• a code change to enable successful generation of the toolpath

Open user issues for this bug :
FreeCAD/FreeCAD#13455
FreeCAD/FreeCAD#15975

3. Add "rest machining" support for adaptive toolpaths

Adaptive toolpaths currently assume that the full region they need to clear is uncut stock before the operation starts. However, it is possible that prior operations have cleared some of that region (e.g. another adaptive operation using a larger tool). If so, the adaptive operation can produce a (much) more efficient toolpath if it understands what space is already cleared. I have already implemented this "rest machining" feature for other operations, but I did not implement it for adaptive because the adaptive operation is built on a different software stack than our "area operations" and has a more complicated interaction with its cleared space. I propose implementing this feature for adaptive toolpaths.

Deliverables:

• a "Use rest machining" checkbox in the adaptive UI panel
• a code change to avoid re-cutting regions that are already cut
• a code change to allow adaptive paths to plunge in cleared space to begin cutting in a region, instead of entering with a helix or from the edge of the stock

Timeline

I hope to complete each of these sub-projects in a few weeks each, spaced out over the duration of the quarter. My work schedule outside of FreeCAD is flexible and will allow for this.

Risks and mitigation

1. Support toolpath generation for small stepover: I have looked into this situation before and I think I understand why toolpath genration fails. It's not a simple fix, but I think I know what I'm getting into.

2. Fix automatic helix diameter selection: not risky; the scope and process for this change are straight forward.

3. Implement rest machining for adaptive: integrating with adaptive may be an involved task, but I think it is not very risky. I have already implemented the trickiest/riskiest features (identification of the regions already cut) of rest machining for other operations.

Compensation

I request a total of 4250 USD: 2000 USD for the small stepover project, 500 USD for automatic helix diameter selection, and 1750 USD for implementing rest machining, delivered upon the completion of each project.

About you

My name is David Kaufman, davidgilkaufman on the forums and github. I received a grant for CAM work last quarter. In that grant, I planned to complete all subtasks within the quarter, and right now (1 month remaining) I have working PRs under review for all proposed features.

This grant is more C++-heavy work, well within my area of expertise. I wrote FreeCAD's "rest machining" feature for other operations from scratch, and have spent time reading through the Adaptive algorithm, so I have good familiarity with the code I will be working with. I have prior experience bridging the C++/python boundary in FreeCAD, and I am comfortable with the CAM workbench code as a whole. Outside of FreeCAD I am a software developer, with C++ and computer geometry experience relevant to the work proposed in this grant.

[Reqrefusion]

As always, it's a great propasal text. I follow your planned and privileged work and it is absolutely dazzling. I would also like to point out that I am a big fan of FPA's support for CAM-related stuff. However, I have some reservations here, especially if a roadmap is being prepared for CAM right now and I wonder if it is included in this roadmap proposed here. I see that some of your work in the previous grant proposal is on hold for this reason. Another point is, of course, that we are working on the new version. There is probably a possibility that this will prolong or postpone things. I'm curious to see what @JohnOCFII, @tarman3, @Dimitris75 and @jffmichi who commented on your last grant proposal would have to say about it. And, of course, what does @sliptonic think about it. In addition, @Connor9220, @J-Dunn, @dbtayl and @knipknap who have developed on CAM may have something to say.

[sliptonic]

The proposed changes to the adaptive algorithm sound great. I would suggest considering some changes to the proposal which might make delivering it easier and also set us up better going forward. These changes are oriented at avoiding investment in an adaptive operation which should probably be deprecated in favor of an adaptive strategy for Pocket.

1. Rather than modifying the existing adaptive operation, I suggest implementing an adaptive 'generator' with the proposed changes. The generator would be an abstract pure function to calculate the adaptive tool path for an arbitrary polygon.
   It would handle the small step-over problems and the REST functionality as described but would not touch the existing operation.

2. The new generator could be implemented into the Pocket operation as a new 'strategy' alongside zigzag and offset. The goal would be to ultimately deprecate the adaptive operation entirely when the pocket version is stable.

3. Remove the need for a helical entry in the adaptive generator and rely instead on the helical generator. The helical generator could be used in conjunction with the adaptive generator to achieve the same thing but each would be independent and independently testable. This would require close coordination with developers, especially @tarman3

I'm open to further discussing the specifics and helping to coordinate work so both the helical generator and the adaptive improvements happen successfully.

[Dimitris75]

The minimum helix diameter is roughly the tool diameter + 30%. That can go up to 40% for very small end-mills and down to 15% for end-mills larger than 25-30mm (indexable). Chip evacuation is the limiting factor.

Setting good default values here is not an easy task but, letting users know what failed is important.

So, yes, that default 75% failure has to be solved.

We also mixing percentage and millimeters once again. Default value 75% of tool dia and max Helix dia in mm.

I do like all recommendations above but, I don't see Adaptive feed rate anywhere!

[davidgilkaufman]

@sliptonic are you available for a video call tomorrow morning? I think it will make this discussion easier.

I would suggest considering some changes to the proposal which might make delivering it easier and also set us up better going forward. These changes are oriented at avoiding investment in an adaptive operation which should probably be deprecated in favor of an adaptive strategy for Pocket.

I'm aware that you're hoping to migrate Adaptive's functionality into the pocket command, as an alternative fill strategy. I have more detailed comments about your specific suggestions, but on the whole, I do not think these suggestions will make delivery of my proposed features easier, and I think my proposed features will neither particularly help nor inhibit the migration process.

I somewhat intentionally chose not to attempt any migration within this grant because I have a gut feeling that the scope of that project is larger than it seems. Supporting features that currently exist in adaptive and not in Pocket may be tricky/involved/bug-prone; without actually investigating the details, I'm worried about the adaptive feature for entering from the side of the stock and the adaptive profile clearing mode. Additionally, I have had no chance to look at @dbtayl's recent work on model awareness for the adaptive operation (very similar to Pocket3D??) and I think there may be a lot of interactions or redundancy between that work and migration to an area operation. Hopefully none of this will be a bad sticking point, but I wasn't prepared to propose that project in this grant without a more certain sense of the scope of that change.

1. I suggest implementing an adaptive 'generator'

I know you've been talking about this, but I'm not sure quite what you want. My general sense for what's meant by "generator" here is "C++ CAM functionality exposed to and managed by python, potentially reusable in multiple operations". I don't know if there's more that you want than that, but at least that much I think we already have implemented for adaptive. See src/Mod/CAM/Path/Op/Adaptive.py's use of area.Adaptive2d() -- as I understand it, this is the generator you're looking for. Is there anything else you want out of this generator?

I suggest implementing an adaptive 'generator' with the proposed changes ... but would not touch the existing operation.

Supposing area.Adaptive2d() is the generator you want, I am definitely planning to make these changes inside the generator. If you want more out of the generator than currently exists, it probably doesn't matter much if that change happens before or after these features I'm proposing.

Hopefully this is besides the point now, but for what it's worth I do not like the idea of making changes in a copy while leaving the original operation alone. I think the result would be two copies of all adaptive-related files in our code base, and that it will be messy and confusing to work with. I'd consider doing something like that if we were making major breaking changes that require a strategy for backwards compatibility, but in this situation I don't think there is a good reason for it.

3. Remove the need for a helical entry in the adaptive generator and rely instead on the helical generator

I proposed a (small) sub-project of the grant entirely about helix entry, but for what it's worth I do not expect it to touch the helix generation code at all. The change is entirely about understanding on the inside of the generator how much space is available in which to helix down, and connecting inputs and outputs for that process through to the controlling python code. There may not even be a merge conflict with a PR to switch to a helix generator; I think the code changes I've proposed are surprisingly unrelated to that process.

[sliptonic]

Yes, I'm available. I have one errand to run early but free after that. Let's plan for 9:30 central time

[davidgilkaufman]

https://meet.jit.si/FreeCADCAMDevelopers

[chennes]

Thank you for applying for an FPA developer grant. Your grant was submitted in the window for Q3 2025, and is now under committee review. After the committee makes its recommendation to the FPA, a voting window will open, with decisions expected on 1 October 2025. Committee members and the FreeCAD community at large are invited to continue discussing this grant application with you here on this GitHub issue.

[davidgilkaufman]

I wonder if it is included in this roadmap proposed here. I see that some of your work in the previous grant proposal is on hold for this reason

Yes, unfortunately creation of the CAM roadmap has delayed my work for the last grant. However, all of that work is currently part of the roadmap, and 2 of the 4 PRs just merged today (3rd likely to follow; 4th needs a little iteration). I have an open pull request to add an epic on Adaptive improvements to the CAM roadmap. Based on the discussion at today's video chat I will make a few changes to it, but I expect it to merge during the CAM developers meeting on Friday, and it will include the work proposed in this grant.

I would suggest considering some changes to the proposal which might make delivering it easier and also set us up better going forward. These changes are oriented at avoiding investment in an adaptive operation which should probably be deprecated in favor of an adaptive strategy for Pocket.

Following up on this, to put some conclusions from our video chat into text, the CAM roadmap epic for Adaptive improvements will include migrating the adaptive operation to be used as a fill strategy for pocket (and also profile?), but the work for this grant will not include those tasks. These two efforts are not expected to conflict with each other. The improvements I propose in this grant can happen before, after, or during the migration, and they are needed regardless of whether Adaptive is used as its own operation or as a fill strategy in Pocket.

[davidgilkaufman]

I have an open pull request to add an epic on Adaptive improvements to the CAM roadmap.

Merged; the work proposed in this grant is on the CAM roadmap

[dbtayl]

I'm all for improvements to Adaptive. Rest machining sounds good to me- though if we're moving operations to a common architecture, presumably that also becomes common functionality with other operations?

The small stepover handling and helix modifications are "meh" from my perspective. Not high priority for me, but whoever does the work gets to choose, so have at it.

I would vote that table stakes for any new adaptive implementation include:

• Maintain ability to follow the model and not blindly project a selected region in Z to the specified depth
• Fix the instability issues the current algorithm has with clearing areas from the outside-in- strange/jittery toolpaths at the end, not quite clearing all the stock, etc.
• Be designed so as to not exclude multithreaded processing (or actually include it)

Making adaptive a strategy for pocket/profile makes me a little nervous, but I fundamentally don't have a problem with it if it works well and doesn't lose functionality or inherit problems with the current implementations- notably the open-curve handling headaches of profile.

[davidgilkaufman]

though if we're moving operations to a common architecture, presumably that also becomes common functionality with other operations?

No. I didn't implement rest machining for Adaptive when I implemented it for other operations because Adaptive works differently. While other operations merely input a new area (uncleared space, plus potentially-necessary space near it), Adaptive has a more intricate relationship with its cleared area and requires more involved support. This applies both in Adaptive's current form and also in a future where it is a fill strategy.

• Maintain ability to follow the model and not blindly project a selected region in Z to the specified depth

Isn't this already done? I have not gotten around to reading your PR in detail, but my understanding is that you have implemented and merged this change. Although fwiw I think this should have been an optional fork in Adaptive's functionality, in the same way that we support both Pocket2D and Pocket3D.

• Fix the instability issues the current algorithm has with clearing areas from the outside-in- strange/jittery toolpaths at the end, not quite clearing all the stock, etc.

I agree that these things are very important and I'd like to see them fixed too, but I'm not prepared yet to claim I know how to fix them and will do so within the quarter. Fundamentally, both this set of problems and the small stepover issue I propose fixing come from Adaptive's optimization algorithm missing better/entire paths that we would like it to find. I believe I can improve it in a way that will fix the issue with small stepover, and I'm actually hopeful that my changes will have broader impact on these other problems you mention. To that end, I plan to do at least some exploratory work beyond fixing the small stepover issue and see what else can be fixed. But I'm a lot more confident about fixing the small stepover problem than these other issues, so I haven't proposed them for this grant.

• Be designed so as to not exclude multithreaded processing (or actually include it)

I see this as a "nice to have", but for what it's worth, I think we excluded it from the Adaptive epic we just approved for the CAM roadmap. We explicitly excluded rewriting adaptive to generate G2/G3 commands instead of G1 -- the epic (i.e. CAM changes we decided are a priority) is about improvements and fixes to adaptive, and not rewriting/redesigning the algorithm wholesale. But if someone is prepared to iterate on the current adaptive algorithm to make it multithreaded and faster, I'd love to see that change and that's definitely in scope on the CAM roadmap.

[dbtayl]

Somehow in my head I conflated the "make generator" conversation with "make an entirely new Adaptive algorithm", so my comments were in that context. Apologies.

Maintain ability to follow the model and not blindly project a selected region in Z to the specified depth

Isn't this already done? I have not gotten around to reading your PR in detail, but my understanding is that you have implemented and merged this change. Although fwiw I think this should have been an optional fork in Adaptive's functionality, in the same way that we support both Pocket2D and Pocket3D.

Yes it's done. I disagree with the remainder of the above, but I won't clutter your issue with that discussion. We can find another forum if you or anybody wants to discuss.

Be designed so as to not exclude multithreaded processing (or actually include it)

I see this as a "nice to have", but for what it's worth, I think we excluded it from the Adaptive epic we just approved for the CAM roadmap. We explicitly excluded rewriting adaptive to generate G2/G3 commands instead of G1

Making it run in parallel for a single region is a completely different thing I in no way meant to suggest, as nice as it would be. I typed faster than my brain and communicated poorly, since just about any algorithm that isn't sharing data/dependencies can be run in parallel, so doing different regions in parallel (as I was thinking) isn't likely to be affected at all by whatever you do. So... feel free to disregard those comments.

Side note that at least a trivial first-pass at G2/G3 would involve little algorithmic modification AFAICT- "just" need to look at the delta in "heading" between consecutive steps, and merge into an arc for every sequential step with the same delta. When I briefly looked at it, it looked to be mostly a data structure problem (communicating separate G1/2/3 steps as output instead of just G1 points). Just FYI, not suggesting you expand your scope.

You may run into scope creep re: plunging, though. Right now it clips the edge of the stock on initial outside plunges and doesn't plunge into holes in the middle of the stock. Might be relevant to rest machining if that combo results in a bunch of helical entries to empty space?

Always glad to see somebody digging into improving the guts of Adaptive!

[davidgilkaufman]

You may run into scope creep re: plunging, though. Right now it clips the edge of the stock on initial outside plunges and doesn't plunge into holes in the middle of the stock. Might be relevant to rest machining if that combo results in a bunch of helical entries to empty space?

I don't have a full grasp on what I'm getting into here, but I do expect most of my work implementing rest machining to be resolving these things. I probably wouldn't call it "scope creep", but certainly this is responsible for most of my uncertainty about how big a task rest machining for adaptive is.

Side note that at least a trivial first-pass at G2/G3 would involve little algorithmic modification AFAICT- "just" need to look at the delta in "heading" between consecutive steps, and merge into an arc for every sequential step with the same delta.

I've been assuming that producing G2/G3 effectively would require doing so natively (algorithmic redesign), or require very effective resolution of existing noise/wobble/jitter issues. But maybe it doesn't! It would be interesting to see how well current adaptive output could be compressed by converting to arcs. It would require some careful checking to limit the area cut by arcs and not lines, or lines and not arcs, on each conversion. And to ensure that the arcs don't cut anywhere they're not allowed (i.e. error stepping over a boundary). But maybe it would be good.