create/docs/src/guide/ztools.md

ztools

ztools is a pure-Python FreeCAD workbench that consolidates part design, assembly, and sketcher tools into a single unified interface. It is the default workbench when Kindred Create launches.

• Submodule path: mods/ztools/
• Source: git.kindred-systems.com/forbes/ztools
• Stats: 6,400+ lines of code, 24+ command classes, 33 custom icons, 17 toolbars

Commands

Datum Creator (ZTools_DatumCreator)

Creates datum geometry (planes, axes, points) with 16 creation modes. The task panel auto-detects the geometry type from your selection and offers appropriate modes. Supports custom naming, spreadsheet linking, and body- or document-level creation.

Datum Manager (ZTools_DatumManager)

Manages existing datums. (Stub — planned for Phase 1, Q1 2026.)

Enhanced Pocket (ZTools_EnhancedPocket)

Extends FreeCAD's Pocket feature with Flip Side to Cut — a SOLIDWORKS-style feature that removes material outside the sketch profile rather than inside. Uses a Boolean Common operation internally. Supports all standard pocket types: Dimension, Through All, To First, Up To Face, Two Dimensions. Taper angle is supported for standard pockets (disabled for flipped).

Rotated Linear Pattern (ZTools_RotatedLinearPattern)

Creates a linear pattern with incremental rotation per instance. Configure direction, spacing, number of occurrences, and cumulative or per-instance rotation. Source components are automatically hidden.

Assembly Linear Pattern (ZTools_AssemblyLinearPattern)

Creates linear patterns of assembly components. Supports multi-component selection, direction vectors, total length or spacing modes, and creation as Links (recommended) or copies. Auto-detects the parent assembly.

Assembly Polar Pattern (ZTools_AssemblyPolarPattern)

Creates polar (circular) patterns of assembly components. Supports custom or preset axes (X/Y/Z), full circle or custom angle, center point definition, and creation as Links or copies.

Spreadsheet Formatting (9 commands)

Command	Action
ZTools_SpreadsheetStyleBold	Toggle bold
ZTools_SpreadsheetStyleItalic	Toggle italic
ZTools_SpreadsheetStyleUnderline	Toggle underline
ZTools_SpreadsheetAlignLeft	Left align
ZTools_SpreadsheetAlignCenter	Center align
ZTools_SpreadsheetAlignRight	Right align
ZTools_SpreadsheetBgColor	Background color picker
ZTools_SpreadsheetTextColor	Text color picker
ZTools_SpreadsheetQuickAlias	Auto-create aliases from row/column labels

Datum creation modes

Planes (7 modes)

Mode	Description	Input
Offset from Face	Offsets a planar face along its normal	Face + distance (mm)
Offset from Plane	Offsets an existing datum plane	Datum plane + distance (mm)
Midplane	Plane halfway between two parallel faces	Two parallel faces
3 Points	Plane through three non-collinear points	Three vertices
Normal to Edge	Plane perpendicular to an edge at a parameter location	Edge + parameter (0.0–1.0)
Angled	Rotates a plane about an edge by a specified angle	Face + edge + angle (degrees)
Tangent to Cylinder	Plane tangent to a cylindrical face at an angular position	Cylindrical face + angle (degrees)

Axes (4 modes)

Mode	Description	Input
2 Points	Axis through two points	Two vertices
From Edge	Axis along a linear edge	Linear edge
Cylinder Center	Axis along the centerline of a cylinder	Cylindrical face
Plane Intersection	Axis at the intersection of two planes	Two non-parallel planes

Points (5 modes)

Mode	Description	Input
At Vertex	Point at a vertex location	Vertex
XYZ Coordinates	Point at explicit coordinates	x, y, z (mm)
On Edge	Point at a location along an edge	Edge + parameter (0.0–1.0)
Face Center	Point at the center of mass of a face	Face
Circle Center	Point at the center of a circular or arc edge	Circular edge

PartDesign injection

ztools registers a _ZToolsPartDesignManipulator that hooks into the PartDesign workbench at startup. This injects the following commands into PartDesign's toolbars and menus:

PartDesign toolbar	Injected command
Part Design Helper Features	ZTools_DatumCreator, ZTools_DatumManager
Part Design Modeling Features	ZTools_EnhancedPocket
Part Design Transformation Features	ZTools_RotatedLinearPattern

The manipulator is registered in InitGui.py when the Create bootstrap module loads addon workbenches.

Directory structure

mods/ztools/
├── ztools/ztools/
│   ├── InitGui.py              # Workbench registration + manipulator
│   ├── Init.py                 # Console initialization
│   ├── commands/
│   │   ├── datum_commands.py       # DatumCreator + DatumManager
│   │   ├── datum_viewprovider.py   # ViewProvider + edit panel
│   │   ├── pocket_commands.py      # EnhancedPocket + FlippedPocket
│   │   ├── pattern_commands.py     # RotatedLinearPattern
│   │   ├── assembly_pattern_commands.py  # Linear + Polar assembly patterns
│   │   └── spreadsheet_commands.py      # 9 formatting commands
│   ├── datums/
│   │   └── core.py             # 16 datum creation functions
│   └── resources/              # Icons and theme
└── CatppuccinMocha/            # Theme preference pack

Internal properties

ztools stores metadata on feature objects using these properties (preserved for backward compatibility):

Property	Purpose
ZTools_Type	Feature type identifier
ZTools_Params	JSON creation parameters
ZTools_SourceRefs	JSON source geometry references

Known gaps

• Datum Manager is a stub — full implementation planned for Q1 2026
• Datum parameter changes don't recalculate from source geometry yet
• Enhanced Pocket taper angle is disabled for flipped pockets

Further reading

• mods/ztools/KINDRED_INTEGRATION.md — integration architecture and migration options
• mods/ztools/ROADMAP.md — phased development plan (Q1–Q4 2026)