create/reference/ztools/ROADMAP.md

ZTools Roadmap

Version: 0.3.0
Last Updated: 2026-01-25
Target Platform: FreeCAD 1.0+
License: LGPL-3.0-or-later

---

Executive Summary

ZTools is an extended PartDesign workbench replacement for FreeCAD, focused on velocity-driven CAD workflows. It integrates enhanced datum creation, assembly patterning, spreadsheet formatting, and a unified dark theme (Catppuccin Mocha).

Current State: 80% complete for v1.0 release
Active Development Areas: Datum management, Enhanced Pocket completion, documentation

---

Table of Contents

1. Implemented Features
2. Known Gaps & Incomplete Features
3. FreeCAD Ecosystem Alignment
4. Development Roadmap
5. Technical Architecture
6. File Reference

---

Implemented Features

1. Workbench Integration (17 Toolbars)

ZTools consolidates multiple FreeCAD workbenches into a single unified interface:

Category	Toolbars	Commands
PartDesign	Structure, Datums, Additive, Subtractive, Transformations, Dress-Up, Boolean	35+ native commands
Sketcher	Sketcher	4 native commands
Assembly	Assembly, Assembly Joints, Assembly Management	21 native commands
Spreadsheet	Spreadsheet	6 native commands
ZTools Custom	ztools Datums, ztools Patterns, ztools Features, ztools Assembly, ztools Spreadsheet	14 custom commands

2. Datum Creation System (16 Functions)

Custom Attachment System - Replaces FreeCAD's unreliable vanilla attachment:

• Calculates placement directly from source geometry
• Stores source references in ZTools_SourceRefs (JSON)
• Uses MapMode='Deactivated' to prevent interference
• Stores creation parameters in ZTools_Params for recalculation

Datum Planes (7 modes)

Mode	Function	Parameters
Offset from Face	plane_offset_from_face()	distance (mm)
Offset from Plane	plane_offset_from_plane()	distance (mm)
Midplane	plane_midplane()	2 parallel faces
3 Points	plane_from_3_points()	3 vertices
Normal to Edge	plane_normal_to_edge()	parameter (0.0-1.0)
Angled	plane_angled()	angle (degrees)
Tangent to Cylinder	plane_tangent_to_cylinder()	angle (degrees)

Datum Axes (4 modes)

Mode	Function	Parameters
2 Points	axis_from_2_points()	2 vertices
From Edge	axis_from_edge()	linear edge
Cylinder Center	axis_cylinder_center()	cylindrical face
Plane Intersection	axis_intersection_planes()	2 planes

Datum Points (5 modes)

Mode	Function	Parameters
At Vertex	point_at_vertex()	vertex
XYZ Coordinates	point_at_coordinates()	x, y, z
On Edge	point_on_edge()	parameter (0.0-1.0)
Face Center	point_center_of_face()	face
Circle Center	point_center_of_circle()	circular edge

Datum Creator GUI:

• Auto-detection of 15+ creation modes based on selection
• Manual mode override
• Spreadsheet linking option
• Custom naming
• Real-time selection observer

3. Pattern Tools (3 Commands)

Command	Description	Status
ZTools_RotatedLinearPattern	Linear pattern with incremental rotation per instance	Complete
ZTools_AssemblyLinearPattern	Pattern assembly components linearly	Complete
ZTools_AssemblyPolarPattern	Pattern assembly components around axis	Complete

Assembly Pattern Features:

• Multi-component selection via table UI
• Creates as Links (recommended) or copies
• Direction/axis presets or custom vectors
• Spacing modes: Total Length or Fixed Spacing
• Angle modes: Full Circle or Custom Angle
• Auto-detects parent assembly container

4. Spreadsheet Formatting (9 Commands)

Command	Description	Status
ZTools_SpreadsheetStyleBold	Toggle bold	Complete
ZTools_SpreadsheetStyleItalic	Toggle italic	Complete
ZTools_SpreadsheetStyleUnderline	Toggle underline	Complete
ZTools_SpreadsheetAlignLeft	Left align	Complete
ZTools_SpreadsheetAlignCenter	Center align	Complete
ZTools_SpreadsheetAlignRight	Right align	Complete
ZTools_SpreadsheetBgColor	Background color picker	Complete
ZTools_SpreadsheetTextColor	Text color picker	Complete
ZTools_SpreadsheetQuickAlias	Auto-create alias from label	Complete

5. Enhanced Features

Command	Description	Status
ZTools_EnhancedPocket	Pocket with "Flip Side to Cut" (SOLIDWORKS-style)	90% Complete

Flip Side to Cut: Removes material OUTSIDE the sketch profile instead of inside, using Boolean Common operation.

6. Theme System (Catppuccin Mocha)

• Complete Qt StyleSheet (QSS) for entire FreeCAD interface
• 26-color palette consistently applied
• 50+ widget types styled
• FreeCAD-specific widgets: PropertyEditor, Python Console, Spreadsheet
• Spreadsheet colors auto-applied on workbench activation

7. Icon System (33 Icons)

All icons use Catppuccin Mocha palette:

• Workbench icon
• Datum icons (planes, axes, points - 13 total)
• Pattern icons (3 total)
• Pocket icons (2 total)
• Assembly pattern icons (2 total)
• Spreadsheet formatting icons (9 total)

---

Known Gaps & Incomplete Features

Critical (Must Fix)

Issue	Location	Description	Priority
Datum Manager stub	datum_commands.py:853	Placeholder only - needs full implementation	High
Datum edit recalculation	datum_viewprovider.py:351,355,359	Parameter changes don't recalculate placement from source geometry	High

Non-Critical (Should Fix)

Issue	Location	Description	Priority
Enhanced Pocket incomplete	pocket_commands.py	Taper angle disabled for flipped pockets	Medium
Pocket execution logic	pocket_commands.py	UI complete but execution needs verification	Medium

Future Enhancements (Nice to Have)

Feature	Description	Priority
Curve-driven pattern	Sweep instances along spline	Low
Fill pattern	Populate region with instances	Low
Variable spacing pattern	Non-uniform spacing	Low
Enhanced Pad	Multi-body support, draft angles	Low
Body operations	Split, combine, shell improvements	Low

---

FreeCAD Ecosystem Alignment

FreeCAD 1.0 (November 2024) - Current Target

Key Features ZTools Leverages:

• TNP Mitigation: Topological Naming Problem largely resolved
• Integrated Assembly Workbench: Ondsel's assembly system now core
• Material System Overhaul: New material handling
• UI/UX Improvements: Dark/light themes, selection filters

ZTools Alignment:

• Custom attachment system complements TNP fix
• Full integration with native Assembly workbench
• Catppuccin theme extends FreeCAD's theming

FreeCAD 1.1 (Expected Late 2025)

Planned Features:

• New Transform Manipulator
• UI Material Rendering Improvements
• Continued TNP refinement for Sketcher/PartDesign

ZTools Opportunities:

• Watch for new Assembly API standardization
• Monitor Sketcher improvements for datum integration

FreeCAD Strategic Priorities (from Roadmap)

FreeCAD Priority	ZTools Alignment
Model Stability	Custom attachment system prevents fragile models
Assembly Integration	Full native Assembly command exposure
Flatten Learning Curve	Unified toolbar consolidation
UI Modernization	Catppuccin Mocha theme
Streamlined Workflow	Quick formatting toolbars, auto-detection

Ondsel Contributions (Note: Ondsel shut down October 2025)

Ondsel's contributions now maintained by FreeCAD community:

• Assembly workbench (ZTools integrates)
• VarSets custom properties (potential future integration)
• Sketcher improvements

---

Development Roadmap

Phase 1: v0.3.x - Stability & Completion (Current)

Timeline: Q1 2026

Task	Status	Priority
Complete Datum Manager GUI	Not Started	High
Implement datum parameter recalculation	Not Started	High
Verify Enhanced Pocket execution	Partial	Medium
Add comprehensive test coverage	Not Started	Medium
Documentation completion	In Progress	Medium

Phase 2: v0.4.0 - Polish & UX

Timeline: Q2 2026

Task	Description
Keyboard shortcuts	Add hotkeys for common operations
Context menus	Right-click menus in 3D view
Undo/redo improvements	Better transaction naming
Error handling	User-friendly error messages
Preferences panel	ZTools configuration UI

Phase 3: v0.5.0 - Advanced Features

Timeline: Q3 2026

Task	Description
Curve-driven pattern	Pattern along splines
Enhanced Pad	Draft angles, lip/groove
Body operations	Split, combine, shell
Datum freeze/update	Control source geometry updates

Phase 4: v1.0.0 - Production Release

Timeline: Q4 2026

Task	Description
Full test suite	Automated testing
User documentation	Complete user guide
Video tutorials	Getting started series
FreeCAD Addon Manager	Official listing

---

Technical Architecture

Directory Structure

ztools/
├── Init.py                          # Startup (non-GUI)
├── InitGui.py                       # Workbench registration
└── ztools/
    ├── __init__.py
    ├── commands/                    # GUI commands
    │   ├── __init__.py
    │   ├── datum_commands.py        # Datum Creator/Manager
    │   ├── datum_viewprovider.py    # Custom ViewProvider
    │   ├── pattern_commands.py      # Rotated Linear Pattern
    │   ├── pocket_commands.py       # Enhanced Pocket
    │   ├── assembly_pattern_commands.py  # Assembly patterns
    │   └── spreadsheet_commands.py  # Spreadsheet formatting
    ├── datums/                      # Core datum library
    │   ├── __init__.py
    │   └── core.py                  # 16 datum functions
    └── resources/                   # Assets
        ├── __init__.py
        ├── icons.py                 # 33 SVG icons
        ├── theme.py                 # Catppuccin QSS
        └── icons/                   # Generated SVG files

Key Design Patterns

1. Command Pattern: All tools follow FreeCAD's GetResources(), Activated(), IsActive() pattern
2. Task Panel Pattern: Complex UIs use QWidget with selection observers
3. Feature Python Pattern: Custom features use Part::FeaturePython with ViewProvider
4. Metadata System: JSON properties for tracking ZTools objects

Metadata Properties

All ZTools objects have:

• ZTools_Type: Feature type identifier
• ZTools_Params: JSON creation parameters
• ZTools_SourceRefs: JSON source geometry references

---

File Reference

File	Purpose	Lines
InitGui.py	Workbench registration, toolbars, menus	~330
datums/core.py	16 datum creation functions	~1300
commands/datum_commands.py	Datum Creator/Manager GUI	~520
commands/datum_viewprovider.py	Custom ViewProvider, edit panel	~400
commands/pattern_commands.py	Rotated Linear Pattern	~206
commands/pocket_commands.py	Enhanced Pocket	~600
commands/assembly_pattern_commands.py	Assembly patterns	~580
commands/spreadsheet_commands.py	Spreadsheet formatting	~480
resources/icons.py	33 SVG icon definitions	~540
resources/theme.py	Catppuccin Mocha QSS	~1500

Total: ~6,400+ lines of code

---

Statistics Summary

Category	Count
Command Files	6
Command Classes	24+
Datum Creation Functions	16
Icons Defined	33
Toolbars Registered	17
Menu Hierarchies	7 major
Native Commands Exposed	66
Custom ZTools Commands	14
Theme Colors	26
Styled Widget Types	50+

---

Contributing

ZTools follows FreeCAD's contribution guidelines. Key areas needing help:

1. Testing: Manual testing on different platforms
2. Documentation: User guides and tutorials
3. Translations: Internationalization support
4. Bug Reports: Issue tracking and reproduction

---

License

LGPL-3.0-or-later

Compatible with FreeCAD's licensing model.

---

Changelog

v0.3.0 (2026-01-25)

• Added zSpreadsheet module with 9 formatting commands
• Added Spreadsheet workbench integration (6 native commands)
• Added 9 spreadsheet formatting icons

v0.2.0 (2026-01-25)

• Added Assembly workbench integration (21 native commands)
• Added Assembly Linear Pattern tool
• Added Assembly Polar Pattern tool
• Added assembly pattern icons

v0.1.0 (2026-01-24)

• Initial release
• Custom attachment system for datums
• 16 datum creation functions
• Datum Creator GUI with auto-detection
• Rotated Linear Pattern
• Enhanced Pocket (partial)
• Catppuccin Mocha theme
• 21 initial icons