create/reference/ztools/ztools

ztools - Extended PartDesign for FreeCAD

Velocity-focused CAD tools extending FreeCAD 1.0+ PartDesign workbench.

Installation

Manual Installation

1. Copy the ztools folder to your FreeCAD Mod directory:

   • Linux: ~/.local/share/FreeCAD/Mod/ztools/
   • Windows: %APPDATA%\FreeCAD\Mod\ztools\
   • macOS: ~/Library/Application Support/FreeCAD/Mod/ztools/

2. Restart FreeCAD

3. Select ztools from the workbench dropdown

Directory Structure

ztools/
├── InitGui.py              # Workbench registration
├── ztools/
│   ├── __init__.py
│   ├── datums/
│   │   ├── __init__.py
│   │   └── core.py         # Datum creation functions
│   └── commands/
│       ├── __init__.py
│       └── datum_commands.py  # GUI commands
├── setup.cfg
└── README.md

Module 1: Datum Tools

Datum Creator (GUI)

Unified task panel for creating:

Planes

• Offset from Face
• Midplane (2 parallel faces)
• 3 Points
• Normal to Edge (at parameter)
• Angled from Face (about edge)
• Tangent to Cylinder

Axes

• 2 Points
• From Edge
• Cylinder Center
• Plane Intersection

Points

• At Vertex
• XYZ Coordinates
• On Edge (at parameter)
• Face Center
• Circle Center

Options

• Link to Spreadsheet: Creates aliases in Spreadsheet for parametric control
• Add to Active Body: Creates PartDesign datums vs Part geometry
• Custom Name: Override auto-naming (e.g., ZPlane_Offset_001)

Python API

from ztools.datums import (
    plane_offset_from_face,
    plane_midplane,
    axis_cylinder_center,
    point_at_coordinates,
)

doc = App.ActiveDocument
body = doc.getObject('Body')

# Offset plane from selected face
face = body.Shape.Faces[0]
plane = plane_offset_from_face(face, 15.0, body=body, link_spreadsheet=True)

# Midplane between two faces
mid = plane_midplane(face1, face2, name="MidPlane_Custom")

# Axis at cylinder center
cyl_face = body.Shape.Faces[2]
axis = axis_cylinder_center(cyl_face, body=body)

# Point at coordinates with spreadsheet link
pt = point_at_coordinates(50, 25, 0, link_spreadsheet=True)

Metadata

All ztools datums store creation metadata in custom properties:

• ZTools_Type: Creation method (e.g., "offset_from_face")
• ZTools_Params: JSON-encoded parameters

Access via:

plane = doc.getObject('ZPlane_Offset_001')
print(plane.ZTools_Type)      # "offset_from_face"
print(plane.ZTools_Params)    # {"distance": 15.0, ...}

Roadmap

• Module 2: Enhanced Pad/Pocket (multi-body, draft angles, lip/groove)
• Module 3: Body operations (split, combine, shell improvements)
• Module 4: Pattern tools (curve-driven, fill patterns)
• Datum Manager: Panel to list/toggle/rename all datums

License

LGPL-2.1 (same as FreeCAD)

Contributing

Kindred Systems LLC - Kansas City