Development

[giannissc]

Hello there,

I have recently started using cq_cam and I am quite enjoying and I would love to help it develop further.
I have already fixed a bug that I found locally but documentation is lacking so I am not sure if the way I do it is the best. If you are willing to walk me through the code I am happy to update the documentation and fix any bugs that I find

Best wishes,
John

[voneiden]

Hi John, thanks for the comment! The intent is there but for the time being this one stays on my backlog. You might also be interested in fluent-experiments branch which has a CQ like experimental fluent API and various experiments leveraging OpenCascade algorithms. I worked on this during last summer (northern hemisphere..), unfortunately I ran out of vacation before I could finish anything. I did use fluent-experiments to do some machining though, also last summer, so it's proven to work with some caveats.

If you have small fixes, you're welcome to open PR's and I can take a look. Just keep in mind that sooner or later I do intend to do some heavy handed refactoring/rewriting to get this project stabilized, so you might not want to put too much effort here yet.

I do have hopes that I'll manage to do that during the upcoming summer season.

Also, btw I'll convert this to a discussion.

[giannissc]

Great to hear! I will keep an eye on it!

[giannissc]

Hi I was wondering how the mini-rampage is going? 😛 I wanted to start working with adding the spindle setting and the feed setting at operation level. I have the hardware to test both!

[voneiden]

Yep, family size increased here by one since my last message, so I've had to turn my attention to mini-me instead of mini-rampage. Anyway no worries, maybe the best course would be now to just merge my changes so that some kind of sane incremental (and collaborative) development can resume.

I still want to write some kind of architecture overview, but for the time being this is the short version of the game plan:

Fluent API -> Direct API -> Toolpath generation -> Routing -> (Post processing) -> gcode/visualization

• The toolpath generation phase is responsible for creating the toolpaths that MUST be milled
• The routing phase is responsible for handling the transitions between the generated toolpaths
  • This current implementation supports only very simple horizontal plunges between contours
  • this is where stuff like ramping (vertical and horizontal) and deciding orientation (climb/conventional) can be implemented

Some things will be broken, like stepdown (at least for 2.5D pocketing) and zigzag milling.

[voneiden]

OK, merged, feel free to proceed.

For any new features tests are very much appreciated. In general I'd love to have a fairly high test coverage since bugs can cause all sorts of real life damage.

[giannissc]

Congats on the new family member!

[giannissc]

I will start going through the codebase and I will write some documentation along the way. I will try to tackle #19, and #20 and then take it from there!

[giannissc]

Documentation thread:

[giannissc]

A quick comparison with FreeCAD Path Workspace:

Tool Shape -> Tool Bit -> Tool Controller -> Tool Library -> Job

The Setup Sheet is similar to cq-cam's Job. It set the basic properties of a job that are consistent across all of the operations.

Setup Sheet (FreeCAD)	Job (cq-cam)
Rapid Feed` (Horizontal/Vertical)	plunge_feed
Clearance Height	rapid_height
Safe Height	op_safe_height
Coolant Mode	N/A

Some other properties that are not part of FreeCAD's Setup Sheet but are part of the Job structure are:

• Post-processor: grbl, linuxcnc, mach3, mach4, marlin, etc.
• Work coordinate systems: G53, G54, G55, G56, G57, G58, G59, G59.1, G59.2, G59.3, G59.4, G59.5

The Tool Bit is used to define permanent properties of the various tools:

Tool Bit (FreeCAD)	Job (cq-cam)
Cutting Edge Height	N/A
Cutting Diameter	tool_diameter
Length	N/A
Shank Diameter	N/A
Material	N/A
Chip Load	N/A
Flutes	N/A

The Tool Controller represents Job-specific tool properties

Tool Bit (FreeCAD)	Job (cq-cam)
Spindle Direction	N/A
Spindle Speed	N/A
Feed Rate (Horizontal/Vertical)	feed
Tool Number	N/A

The Tool Shape is linked to a Tool Bit and represents the shape of the tool. It can be very useful when your tool is not flat. Examples include V end mill for engraving or ball end mills.

The Tool Library is a collection of Tool Bit that is imported into a job to generate the Tool Controllers

[giannissc]

I think that we could follow a similar model. We can merge the Tool Bit and Tool Controller into a single class (Tool class) that will hold the most important properties:

• Spindle Direction
• Spindle Speed - This is important for machine that support modifications to the spindle operation
• Feed Rate (Horizontal/Vertical) - These need to be separate
• Tool Diameter
• Cutting Edge Height - These can be important to make sure that the paths that are generated won't damage the material/tool/machine. If an operation need to exceed the edge height then it should result in an error.
• Tool Shape - These can be important for more advanced paths and can be skipped for now
• Tool Number - This is required by gcode to perform tool changes

I can test both the spindle properties and the tool number property as I have access to a machine that supports them.

The new Tool class object can be bundled in a list and be passed into Job in place of tool_diameter and feed. The Job class can be thus simplified and hold properties that are only job specific. The new proposed Job class properties are going to be:

• Name
• Units (mm/inch)
• Positioning (absolute/relative)
• Work Coordinates (G54-G59.1)
• Tools
• Rapid Feed (float)
• Rapid Height (float)
• Safe Height(float
• Coolant Mode (on/off)
• gcode precision
• post-processor

Operation can then request for specific tools from the Tool list instead of selecting based on each property individually.

[giannissc]

How does this seem? @voneiden

[voneiden]

Seems good overall. plunge_feed should correspond to vertical cut feedrate (Setup Sheet table).

Simplicity and maintainability are things I'd request to keep in mind when adding new stuff. We're a niche of a niche with limited resources to keep it together. It's also easier to lure in new contributors if the codebase is not too complicated.

Regarding post-processors, FreeCAD's implementation is a wee bit spaghetti with lots of duplicate code ( https://github.com/FreeCAD/FreeCAD/tree/master/src/Mod/Path/Path/Post/scripts ).

For example LinuxCNC and MACH3 are very similar

• https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Path/Path/Post/scripts/linuxcnc_post.py
• https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Path/Path/Post/scripts/mach3_mach4_post.py

State of FreeCADs Path codebase was actually one reason that motivated me to try out the idea of cq-cam in the first place. 😅

[giannissc]

I am not implying to adopt FreeCAD structure but in the case of machine setting they are dependent on the tools being used and the capabilities of the machine. In my case case I have access to both a powerful machine (Tormach) and a less powerful (Modella). The tormach allows for toolchanges, coolants and spindle setting and the modella does not. So I will try to think of the appropriate structure to satisfy both requirements. As for my plan I will modify the gcode generation first (as per my comments below) and then move on to this

[giannissc]

Proposed gcode format:

(Exported by cq-cam)
(Post Processor: foo)
(Name)
(Output Time)

(begin preamble)
....
(finish preamble)

(begin tool change: x mm Square Endmill)
...
(finish tool change: x mm Square Endmill)

(begin operation: operation_name)
...
(finish operation: operation_name)

(begin postamble)
...
(finish postamble)

[giannissc]

Does the proposed structure seem reasonable here? @voneiden
I will also use these notes to start the documentation. Gcode 101 will be the motivation for the Job class.
The next documentation chapter will cover the basics of machining and the corresponding operations (profile, pocket, drill) with simple 2.5D shapes.

[voneiden]

Yes, it seems reasonable. Do you intend expand the existing documentation or go with something new? The foundations for the existing one is pretty much copied from cadquery

[giannissc]

I haven't decided yet. I will have a proper look tomorrow. I was thinking initially to have an informal markdown documentation as I explore the codebase and understand more the space. From that then it can evolve into a documentation for user and another one for developers along with the corresponding code documentation!

[voneiden]

By the way, feel free to create issues to organize your work.

[giannissc]

Since I have only done python programming in jupyter notebook I have no idea how to do software engineering.

How do you build the project?
How do you build the documentation?
How do you run the test?
Is there anything else I need to now?

Also sorry if I am taking a time from your little one. I promise to keep future communications to a minimum.

I am traveling home today so I will be busy making changes to the project. Here is a rough roadmap of things I want to add:

1. Extend commons.py with additional classes for a complete gcode description.
2. Supplement the output of to_gcode with gcode comment to make it easier to debug the output and catch errors.
3. Change the interface of job with the additional capabilities added to commons.py. I will refrain from removing parameters but I will add new ones for (coolant, spindle, positioning, etc.)
4. Create a new class ToolConfig that will contain properties relevant to tool changes. This will allow to save ToolConfigs in a separate file for reusability. This class will be an input to each of the operations. The properties of the ToolConfig class are going to be examined one-by-one and individually change properties of Job class. If any of the properties of ToolConfig is None that means that the global property is not affected.
5. Create new folder post-processors and implement post-processors for LinuxCNC (which is the one I am using). I also want to target that one your machine supports. I will also try to implement post processors for Mach, grbl, Marlin, and uccnc

[voneiden]

No worries. Probably plenty of pitfalls ahead as you expand from jupyter, but live and learn.

How do you build the project?

Nothing to build. For local development I personally install the library straight from the git repo as editable like this: https://github.com/voneiden/cq-cam#install-locally-editable-development-version

Currently there are no PYPI packages. I'll automate that at some point with github actions once this thing is stable enough for regular use.

How do you build the documentation?

It uses sphinx-build command. Looks like sphinx is missing from requirements, but you'll probably have it installed if you have cadquery installed. https://github.com/voneiden/cq-cam/blob/unstable/build-docs.sh

How do you run the test?

In cq-cam folder run (preferably with conda or virtualenv active to avoid polluting system python)

pip install -r requirements-dev.txt
pytest

Is there anything else I need to now?

I suppose we'll figure those out on the way. Some general things/thoughts:

• Remember to run black . and isort .. PR's will fail if black and isort checks don't pass.
• Descriptive commit titles
• Descriptive commit messages where needed. Both the title and message can be very helpful in a few years when someone is doing refactoring or something and wondering why it was coded the way it is. I slacked a bit on these myself recently, but I'll try to do better.
• Commits should have a clear scope, ie if possible avoid situations where a single commit does multiple unrelated changes.

1. ok
2. ok
3. ok
4. ok, can consider also a shorter class name Tool, fits the theme of having Job, Operation etc.
5. ok, modules need to use underscores instead of hyphens (post_processors). Anyway here I suggest spending some time exploring how this should be handled, I feel like there are multiple ways to approach this. Some thoughts:

• They might fit also in a single file depending on complexity.
• Some post processing options can be generic so custom post processors might want to extend a generic base class. This also would help keep the structure consistent.
• Do we apply post processing before to_gcode, in to_gcode or after to_gcode?

[giannissc]

The remaining of my plan is to:

• Remove reference to Tuple[] or List[] and replace with tuple[] and list[]
• Make the to_gcode() method for MotionCommand take no argument (same as ConfigCommand
• Add documentation to routers.py (I don't think that I will be making any other changes for now)
• Create a new Tool class and introduce it to each operation to support tool changes
• Modify the Job Class to use both MotionCommands and ConfigCommands in its to_gcode() and remove any other text
• Introduce post_processors (design undecided for now. I will reveal more once the rest are resolved)

[giannissc]

My plan for post-processor. cq-cam Commands will simply capture the intend and all the relevant gcode data (e.g. T, X, Y, Z, F, S, etc.) Then the post-processor will read the Command list and decide what gcode to output.

Example 1 - ToolChange: Some machines don't support tool changes using the M6 command in this case you can just use M0 command
Example 2 - Home Position: If some machine doesn't support G30 post processor will switch to G28. If it supports neither then it can be simulated using G0
Example 3 - Canned Cycles: For machines that don't support G81...G84 drilling can be simulated using G1
Example 4 - Spindle: If a machine doesn't provide spindle control simply don't include it into the StartSequence command
Example 5 - Coolant: If a machine doesn't provide spindle control simply don't include it into the StartSequence and StopSequence commands

[voneiden]

Seems good to me. On Home Position I'd like to note that wild west machines with no limit switches, like mine, do exist - these can't do homing and at least with grbl there is no guarantee that the G28 is a physically accessible position by the machine. A rogue G28 will likely lead to a gnarly crash (been there done that multiple times).

So I need to be able to opt out from homing. In fact, I'd prefer if it was opt-in.

[giannissc]

Is this the case with all grbl machines or just the state of your current setup? In this case this could part of the setup for post-processors. You could provide an alternative home position using X,Y,Z or disable it altogether. Will this be sufficient?

[voneiden]

My setup. grbl does support limit switches, I just don't have any. It's not completely unusual in the DIY scene.

AFAIK with grbl the machine coordinates (used by G28) can only be set by running the homing cycle which I can't run. There's some persistence, so when powering up the machine I'll have some random machine coordinates.

[voneiden]

https://github.com/voneiden/cq-cam/blob/unstable/src/cq_cam/fluent.py#L144

post-review: overriding job values is sketchy and may lead to unexpected behaviour.

The feed/speed precedence could be: Job < Tool < Operation

That is: operation feed/speed would override tool default would override job defaults

edit: pardon the brevity, typing with one hand 😄

[giannissc]

I will have a proper think about it when its time for implementing the post-processors. We can also have a proper chat about it but until then we can start the discussion here. I agree with you that what I am doing here is not ideal and I am open to other options. The ideal API for me is one that mimics what is being done during machining and also reflected in the gcode, which is "keep using the current tool until told otherwise". I am not sure what do you mean by operation feed/speed. should those be added to each operation?

[voneiden]

Let me throw my original ideas in the bin for a while. How do you envision this API would look in practice? Something like this?

big_endmill = Tool(...)
fine_endmill = Tool(...)

job = (
    Job(...)
    .tool(big_endmill)
    .pocket(...)  # Done with big_endmill
    .pocket(...)  # Done with big_endmill
    .tool(fine_endmill)
    .pocket(...)  # Done with fine_endmill
    .tool(big_endmill)
    .profile(...)  # Done with big_endmill
)

I might be OK with this. This would allow to get rid of job/operation specific settings and rely only on what is set through tool method. This seems like a fairly unambiguous approach.

job = (
    Job(...)
    .pocket(...)  # ValueError, no tool defined
)

How about feed override? In the tool method or in the operation method?

big_endmill = Tool(feed=300, ...)

job = (
    Job(...)
    .tool(big_endmill, feed=500)  # Here?
    .pocket(feed=500, ...)  # or here? 
)