CAM ToolShape

Description

ToolShapes are a core part of the CAM Tools system. ToolShapes are the templates from which ToolBits are created. They represent the specific physical shape of a tool. A ToolShape does not completely describe the bit - for that some additional parameters are needed which will be added when an actual bit is parameterized from the template.

A Tool Shape is a FreeCAD document with a single PartDesign Body and a PropertyBag labeled Attributes, created with the Workbench PartDesign Part Design workbench. The label of the Body selects the shape type: it must equal the name (or an alias) of one of the shape types listed below, otherwise the shape is loaded as a Custom shape with a generic parameter set.

Creating new ToolShapes is an advanced topic. The most commonly needed ToolShapes already exist and are provided with the FreeCAD installation at:

  • On Linux it is usually /usr/lib64/FreeCAD/Mod/CAM/Tools/Shape

  • On Windows it is usually C:\Program Files\FreeCAD\Mod\CAM\Tools\Shape

  • On macOS it is usually /Applications/FreeCAD.app/Contents/Resources/Mod/CAM/Tools/Shape

They are:

  • ballend.fcstd

  • bullnose.fcstd

  • chamfer.fcstd

  • dovetail.fcstd introduced in 1.1

  • drill.fcstd

  • endmill.fcstd

  • probe.fcstd

  • radius.fcstd introduced in 1.1 (corner-rounding mill; added as fillet and renamed radius)

  • reamer.fcstd introduced in 1.1

  • slittingsaw.fcstd

  • tap.fcstd introduced in 1.1

  • taperedballnose.fcstd introduced in 26.3

  • thread-mill.fcstd

  • v-bit.fcstd

User-defined Tool Shapes are stored in the Tools/Shape folder of the CAM asset directory (see CAM Preferences → Assets). A user shape with the same file name as a shipped shape replaces it in the Toolbit Shape Selection dialog.

Next to each .fcstd file there is an .svg drawing of the same name. It is shown in the Toolbit Parameter Editor and the Tool Bit lists; the text elements of the drawing provide the abbreviations (for example D, L, H) displayed next to the parameters.

Parameters

The shape type determines the parameters a Tool Bit of that shape carries:

  • Endmill: CuttingEdgeHeight, Diameter, Flutes, Length, ShankDiameter.

  • Ballend: CuttingEdgeHeight, Diameter, Flutes, Length, ShankDiameter.

  • Bullnose: CuttingEdgeHeight, Diameter, Flutes, Length, ShankDiameter, CornerRadius (older files using FlatRadius are converted).

  • Chamfer: CuttingEdgeAngle, CuttingEdgeHeight, Diameter, Flutes, Length, ShankDiameter, TipDiameter.

  • V-Bit: CuttingEdgeAngle, CuttingEdgeHeight, Diameter, Flutes, Length, ShankDiameter, TipDiameter.

  • Drill: Diameter, Flutes, Length, TipAngle.

  • Dovetail: TipDiameter (crest height), CuttingEdgeAngle, CuttingEdgeHeight (dovetail height), Diameter (major diameter), Flutes, Length, NeckDiameter, NeckHeight, ShankDiameter.

  • Reamer: CuttingEdgeHeight, Diameter, Length, ShankDiameter.

  • Slitting Saw: BladeThickness, CapDiameter, CapHeight, Diameter, Flutes, Length, ShankDiameter.

  • Tap: CuttingEdgeLength, Diameter, Flutes, Length, ShankDiameter, TipAngle, Pitch.

  • Thread Mill: Crest, Diameter, Flutes, Length, NeckDiameter, NeckLength, ShankDiameter, cuttingAngle.

  • Probe: Diameter (ball diameter), Length, ShaftDiameter.

  • Tapered Ball Nose introduced in 26.3: CuttingEdgeHeight, Diameter, Flutes, Length, ShankDiameter, TaperAngle, TaperDiameter.

  • Radius Mill: CuttingEdgeHeight, Diameter, CuttingRadius, Flutes, Length, ShankDiameter, TipDiameter.

  • Custom (any other Body label): CuttingEdgeHeight, Diameter, Flutes, Length, ShankDiameter plus every property found in the Attributes PropertyBag.

Aliases and subtypes

Shape names are matched case-insensitively and through aliases (for example torus → Bullnose, fillet → Radius, v_bit → VBit, conicalballnose → TaperedBallNose). introduced in 26.3: a shape may define subtypes (Drill: jobber, stub, spot, center, brad_point). A subtype does not change the parameters; it is stored in the Tool Bit’s shape-type key, can be chosen as Toolbit Type in the Toolbit Parameter Editor and is used for filtering in the Library Manager.

Usage

  1. Create a new FreeCAD document.

  2. Open the Workbench PartDesign PartDesign Workbench.

  3. Create a Body and give the Body a label you want to show up in the bit selection. For the shape to be recognized as one of the types above, the label must equal that type’s name or an alias.

  4. Create a PartDesign NewSketch Sketch on the XZ-plane and draw half the profile of the bit.

  5. Constrain the bottom most center of the bit on the origin (0,0). This will be the center of the axis on which the G-code will rotate the bit.

    • Note: Do not add dimensional constraints at this time.

  6. Close the Sketch.

  7. PartDesign Revolution Revolve the Sketch around the vertical Sketch axis.

  8. Open the Workbench CAM CAM Workbench.

  9. Select the Body in the Tree View so that the PropertyBag created in the next step is nested in the Body.

  10. Select the CAM  Utils  PropertyBag option from the menu.

  11. A PropertyBag named Attributes is created. This PropertyBag will be used to control the dimensions in the Sketch. The PropertyBag must keep the label Attributes; put every dimension that drives the Sketch into the Shape property group. If the Body label matches a shipped shape type, use the parameter names of that type; other properties are copied to the Tool Bit as custom properties.

  12. Double-click the PropertyBag in the Tree View.

  13. The Property Bag task panel opens.

  14. Click the Add…​ button.

  15. The Create Property dialog opens.

  16. Create the properties Diameter and Length (both mandatory: operations and the LinuxCNC export read them) and the other dimensions of the shape. Property names are case-sensitive and may not contain spaces.

  17. Select Shape from the Group dropdown list.

  18. Select the appropriate Type.

  19. Optionally specify a ToolTip.

  20. Click the OK button.

  21. In the Property Bag task panel enter a value for the Diameter property.

  22. Similarly add all other required properties.

  23. Click the OK button in the Property Bag task panel when done.

  24. Double-click the Sketch in the Tree View.

  25. Add dimensional constraints and apply the properties from the created PropertyBag. For example to apply the Diameter property:

    1. Double-click a dimension.

    2. Click the Bound expression icon.

    3. Enter [Attributes].Diameter in the Formula editor.

    4. Click the OK button twice.

  26. Repeat this until the Sketch is fully constrained.

  27. Save the file as <name>.fcstd in the Tools/Shape folder of the CAM asset directory. Optionally add a <name>.svg drawing in the same folder; give each text element an id equal to the parameter name (for example id="Diameter") to have its text shown as abbreviation in the editor.

    • Note: create only one Body, and create it before any other object; the loader reads the label of the object whose internal name is Body.

Tool Thumbnail Images

If no .svg drawing exists next to the shape file, the thumbnail embedded in the .fcstd file is used as icon.

Important notes:

  • Before saving the document make sure you have Save Thumbnail selected, and Add program logo deselected in FreeCAD’s preferences (Edit  Preferences  General  Document).

  • Also make sure to switch to Front View and Fit content to screen.

  • Whatever you see when saving the document will end up being the visual representation of the template.

Scripting

from Path.Tool.shape import ToolBitShape

shape = ToolBitShape.from_file("/path/to/endmill.fcstd")
print(shape.name, shape.schema())
body = shape.make_body(App.ActiveDocument)