389 lines
13 KiB
Markdown
389 lines
13 KiB
Markdown
# 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
|