# 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](#implemented-features)
2. [Known Gaps & Incomplete Features](#known-gaps--incomplete-features)
3. [FreeCAD Ecosystem Alignment](#freecad-ecosystem-alignment)
4. [Development Roadmap](#development-roadmap)
5. [Technical Architecture](#technical-architecture)
6. [File Reference](#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