chore: archive QuickNav and ZTools into reference folder (#345)

Copy QuickNav and ZTools source trees into reference/ for developer reference during the UI/UX rework. These are plain directories (not submodules) and are not included in the build. - reference/quicknav/ — QuickNav addon source - reference/ztools/ — ZTools addon source Part of the UI/UX rework preparation. See #346.
2026-02-27 12:54:40 -06:00
parent a623f280da
commit c8b0706a1d
68 changed files with 9273 additions and 0 deletions
--- a/reference/ztools/ROADMAP.md
+++ b/reference/ztools/ROADMAP.md
@@ -0,0 +1,388 @@
+# 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