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/PLAN.md
+++ b/reference/ztools/PLAN.md
@@ -0,0 +1,420 @@
+# ZTools Development Plan
+
+## Current Status: v0.3.0 (80% complete)
+
+### What's Working
+- Workbench registration with 17 toolbars and menus
+- All 15 datum creation functions with custom ZTools attachment system
+- Datum Creator GUI (task panel with Planes/Axes/Points tabs)
+- OK button creates datum, Cancel dismisses without creating
+- Rotated Linear Pattern feature (complete)
+- Icon system (32+ Catppuccin-themed SVGs)
+- Metadata storage system (ZTools_Type, ZTools_Params, ZTools_SourceRefs)
+- Spreadsheet linking for parametric control
+- FreeCAD 1.0+ Assembly workbench integration (all stock commands)
+- Assembly Linear Pattern tool (complete)
+- Assembly Polar Pattern tool (complete)
+- FreeCAD Spreadsheet workbench integration (all stock commands)
+- zSpreadsheet formatting toolbar (9 commands)
+
+### Recent Changes (2026-01-25)
+- Added zSpreadsheet module with formatting toolbar
+- Native Spreadsheet commands exposed (CreateSheet, Import, Export, SetAlias, MergeCells, SplitCell)
+- Created 9 formatting commands: Bold, Italic, Underline, Align Left/Center/Right, Background Color, Text Color, Quick Alias
+- Added 9 spreadsheet icons (Catppuccin Mocha theme)
+- Spreadsheet text color now defaults to white for dark theme compatibility
+
+### Previous Changes (2026-01-25)
+- Added FreeCAD 1.0+ Assembly workbench integration
+- All native Assembly commands exposed in ztools workbench (21 commands)
+- Created Assembly Linear Pattern tool with task panel UI
+- Created Assembly Polar Pattern tool with task panel UI
+- Added assembly pattern icons (Catppuccin Mocha theme)
+
+### Previous Changes (2026-01-24)
+- Replaced FreeCAD's vanilla attachment system with custom ZTools attachment
+- All datums now use `MapMode='Deactivated'` with calculated placements
+- Source references stored in `ZTools_SourceRefs` property for future update capability
+- Fixed all 3 point functions (`point_on_edge`, `point_center_of_face`, `point_center_of_circle`) to accept source parameters
+- Removed redundant "Create Datum" button - OK now creates the datum
+- Task panel properly cleans up selection observer on close
+
+---
+
+## ZTools Attachment System
+
+FreeCAD's vanilla attachment system has reliability issues. ZTools uses a custom approach:
+
+1. **Calculate placement directly** from source geometry at creation time
+2. **Store source references** in `ZTools_SourceRefs` property (JSON)
+3. **Use `MapMode='Deactivated'`** to prevent FreeCAD attachment interference
+4. **Store creation parameters** in `ZTools_Params` for potential recalculation
+
+This gives full control over datum positioning while maintaining the ability to update datums when source geometry changes (future feature).
+
+### Metadata Properties
+
+All ZTools datums have these custom properties:
+- `ZTools_Type`: Creation method identifier (e.g., "offset_from_face", "midplane")
+- `ZTools_Params`: JSON-encoded creation parameters
+- `ZTools_SourceRefs`: JSON-encoded list of source geometry references
+
+---
+
+## Phase 0: Complete (Assembly Integration)
+
+### FreeCAD 1.0+ Assembly Workbench Commands
+
+ZTools exposes all native FreeCAD Assembly workbench commands in 3 toolbars:
+
+**Assembly Structure:**
+- `Assembly_CreateAssembly` - Create new assembly container
+- `Assembly_InsertLink` - Insert component as link
+- `Assembly_InsertNewPart` - Create and insert new part
+
+**Assembly Joints (13 types):**
+- `Assembly_CreateJointFixed` - Lock parts together (0 DOF)
+- `Assembly_CreateJointRevolute` - Rotation around axis
+- `Assembly_CreateJointCylindrical` - Rotation + translation along axis
+- `Assembly_CreateJointSlider` - Translation along axis
+- `Assembly_CreateJointBall` - Spherical rotation
+- `Assembly_CreateJointDistance` - Maintain distance
+- `Assembly_CreateJointParallel` - Keep parallel
+- `Assembly_CreateJointPerpendicular` - Keep perpendicular
+- `Assembly_CreateJointAngle` - Maintain angle
+- `Assembly_CreateJointRackPinion` - Rack and pinion motion
+- `Assembly_CreateJointScrew` - Helical motion
+- `Assembly_CreateJointGears` - Gear ratio constraint
+- `Assembly_CreateJointBelt` - Belt/pulley constraint
+
+**Assembly Management:**
+- `Assembly_ToggleGrounded` - Lock part in place
+- `Assembly_SolveAssembly` - Run constraint solver
+- `Assembly_CreateView` - Create exploded view
+- `Assembly_CreateBom` - Generate bill of materials
+- `Assembly_ExportASMT` - Export assembly file
+
+### ZTools Assembly Pattern Tools
+
+**Assembly Linear Pattern** (`ZTools_AssemblyLinearPattern`)
+
+Creates copies of assembly components along a linear direction.
+
+Features:
+- Multi-component selection via table UI
+- Direction vector (X, Y, Z)
+- Occurrence count (2-100)
+- Spacing modes: Total Length or Fixed Spacing
+- Creates as Links (recommended) or copies
+- Option to hide original components
+- Auto-detects parent assembly
+
+UI Layout:
+```
+----------------------------------+
+| Components                       |
+| +------------------------------+ |
+| | Component_1         [X]     | |
+| | Component_2         [X]     | |
+| +------------------------------+ |
+| Select components in 3D view     |
+----------------------------------+
+| Pattern Parameters               |
+| Direction: X[1] Y[0] Z[0]        |
+| Occurrences: [3]                 |
+| Mode: [Total Length v]           |
+| Total Length: [100 mm]           |
+----------------------------------+
+| Options                          |
+| [x] Create as Links              |
+| [ ] Hide original components     |
+----------------------------------+
+```
+
+**Assembly Polar Pattern** (`ZTools_AssemblyPolarPattern`)
+
+Creates copies of assembly components around a rotation axis.
+
+Features:
+- Multi-component selection via table UI
+- Axis presets (X, Y, Z) or custom axis vector
+- Center point specification
+- Occurrence count (2-100)
+- Angle modes: Full Circle (360) or Custom Angle
+- Creates as Links (recommended) or copies
+- Option to hide original components
+
+UI Layout:
+```
+----------------------------------+
+| Components                       |
+| +------------------------------+ |
+| | Component_1         [X]     | |
+| +------------------------------+ |
+----------------------------------+
+| Rotation Axis                    |
+| Axis: [Z Axis v]                 |
+| Direction: X[0] Y[0] Z[1]        |
+| Center: X[0] Y[0] Z[0]           |
+----------------------------------+
+| Pattern Parameters               |
+| Occurrences: [6]                 |
+| Mode: [Full Circle v]            |
+| Total Angle: [360 deg]           |
+----------------------------------+
+| Options                          |
+| [x] Create as Links              |
+| [ ] Hide original components     |
+----------------------------------+
+```
+
+---
+
+## Phase 0.5: Complete (zSpreadsheet)
+
+### FreeCAD Spreadsheet Workbench Commands
+
+ZTools exposes native Spreadsheet commands in the "Spreadsheet" toolbar:
+
+- `Spreadsheet_CreateSheet` - Create new spreadsheet
+- `Spreadsheet_Import` - Import CSV file
+- `Spreadsheet_Export` - Export to CSV
+- `Spreadsheet_SetAlias` - Set cell alias
+- `Spreadsheet_MergeCells` - Merge selected cells
+- `Spreadsheet_SplitCell` - Split merged cell
+
+### ZTools Spreadsheet Formatting Tools
+
+Quick formatting toolbar for cell styling without dialogs:
+
+**Style Commands:**
+- `ZTools_SpreadsheetStyleBold` - Toggle bold (B icon)
+- `ZTools_SpreadsheetStyleItalic` - Toggle italic (I icon)
+- `ZTools_SpreadsheetStyleUnderline` - Toggle underline (U icon)
+
+**Alignment Commands:**
+- `ZTools_SpreadsheetAlignLeft` - Align text left
+- `ZTools_SpreadsheetAlignCenter` - Align text center
+- `ZTools_SpreadsheetAlignRight` - Align text right
+
+**Color Commands:**
+- `ZTools_SpreadsheetBgColor` - Set cell background color (color picker)
+- `ZTools_SpreadsheetTextColor` - Set cell text color (color picker)
+
+**Utility Commands:**
+- `ZTools_SpreadsheetQuickAlias` - Create alias from adjacent label cell
+
+### Implementation Details
+
+**Cell Selection Helper:**
+The `get_selected_cells()` function:
+1. Gets active MDI subwindow
+2. Finds QTableView widget
+3. Gets selected indexes from selection model
+4. Converts to A1 notation (handles AA, AB, etc.)
+
+**Style Toggle Pattern:**
+```python
+current = sheet.getStyle(cell) or ""
+styles = set(s.strip() for s in current.split("|") if s.strip())
+if "bold" in styles:
+    styles.discard("bold")
+else:
+    styles.add("bold")
+sheet.setStyle(cell, "|".join(sorted(styles)))
+```
+
+**Color Picker Integration:**
+Uses Qt's `QColorDialog.getColor()` with Catppuccin defaults for dark theme.
+
+---
+
+## Phase 1: Complete (Datum Tools)
+
+All datum creation functions now work:
+
+### Planes (6 modes)
+- Offset from Face
+- Midplane (2 Faces)
+- 3 Points
+- Normal to Edge
+- Angled from Face
+- Tangent to Cylinder
+
+### Axes (4 modes)
+- 2 Points
+- From Edge
+- Cylinder Center
+- Plane Intersection
+
+### Points (5 modes)
+- At Vertex
+- XYZ Coordinates
+- On Edge (with parameter)
+- Face Center
+- Circle Center
+
+---
+
+## Phase 2: Complete Enhanced Pocket
+
+### 2.1 Wire Up Pocket Execution (pocket_commands.py)
+
+The EnhancedPocketTaskPanel has complete UI but no execute logic.
+
+Required implementation:
+1. Get selected sketch from user
+2. Create PartDesign::Pocket with selected type
+3. Apply "Flip Side to Cut" by:
+   - Reversing the pocket direction, OR
+   - Using a boolean cut approach with inverted profile
+4. Handle all pocket types: Dimension, Through All, To First, Up To Face, Two Dimensions
+
+### 2.2 Register Pocket Command
+
+Add to InitGui.py toolbar if not already present.
+
+---
+
+## Phase 3: Datum Manager
+
+### 3.1 Implement DatumManagerTaskPanel
+
+Replace the stub in datum_commands.py with functional panel:
+
+Features:
+- List all datum objects (planes, axes, points) in document
+- Filter by type (ZTools-created vs native)
+- Toggle visibility (eye icon per item)
+- Rename datums inline
+- Delete selected datums
+- Jump to datum in model tree
+
+UI Layout:
+```
+----------------------------------+
+| Filter: [All v] [ZTools only ☐]  |
+----------------------------------+
+| ☑ ZPlane_Offset_001    [👁] [🗑] |
+| ☑ ZPlane_Mid_001       [👁] [🗑] |
+| ☐ ZAxis_Cyl_001        [👁] [🗑] |
+----------------------------------+
+| [Rename] [Show All] [Hide All]   |
+----------------------------------+
+```
+
+---
+
+## Phase 4: Additional Features (Future)
+
+### 4.1 Module 2 Completion: Enhanced Pad
+- Multi-body support
+- Draft angles on pad
+- Lip/groove profiles
+
+### 4.2 Module 3: Body Operations
+- Split body at plane
+- Combine bodies
+- Shell improvements
+
+### 4.3 Module 4: Pattern Tools
+- Curve-driven pattern (sweep instances along spline)
+- Fill pattern (populate region with instances)
+- Pattern with variable spacing
+
+### 4.4 Datum Update Feature
+- Use stored `ZTools_SourceRefs` to recalculate datum positions
+- Handle topology changes gracefully
+- Option to "freeze" datums (disconnect from sources)
+
+---
+
+## File Reference
+
+| File | Purpose | Lines |
+|------|---------|-------|
+| `ztools/ztools/datums/core.py` | Datum creation functions | ~750 |
+| `ztools/ztools/commands/datum_commands.py` | Datum Creator/Manager GUI | ~520 |
+| `ztools/ztools/commands/pocket_commands.py` | Enhanced Pocket GUI | ~600 |
+| `ztools/ztools/commands/pattern_commands.py` | Rotated Linear Pattern | ~206 |
+| `ztools/ztools/commands/assembly_pattern_commands.py` | Assembly Linear/Polar Patterns | ~580 |
+| `ztools/ztools/commands/spreadsheet_commands.py` | Spreadsheet formatting tools | ~480 |
+| `ztools/InitGui.py` | Workbench registration | ~330 |
+| `ztools/ztools/resources/icons.py` | SVG icon definitions | ~540 |
+
+---
+
+## Testing Checklist
+
+### Phase 1 Tests (Datum Tools)
+- [ ] Create plane offset from face
+- [ ] Create midplane between 2 faces
+- [ ] Create plane from 3 points
+- [ ] Create plane normal to edge at various parameters
+- [ ] Create angled plane from face about edge
+- [ ] Create plane tangent to cylinder
+- [ ] Create axis from 2 points
+- [ ] Create axis from edge
+- [ ] Create axis at cylinder center
+- [ ] Create axis at plane intersection
+- [ ] Create point at vertex
+- [ ] Create point at XYZ coordinates
+- [ ] Create point on edge at parameter 0.0, 0.5, 1.0
+- [ ] Create point at face center (planar and cylindrical)
+- [ ] Create point at circle center (full circle and arc)
+- [ ] Verify ZTools_Type, ZTools_Params, ZTools_SourceRefs properties exist
+- [ ] Verify no "deactivated attachment mode" warnings in console
+
+### Phase 2 Tests (Enhanced Pocket)
+- [ ] Create pocket with Dimension type
+- [ ] Create pocket with Through All
+- [ ] Create pocket with Flip Side to Cut enabled
+- [ ] Verify pocket respects taper angle
+
+### Phase 3 Tests (Datum Manager)
+- [ ] Datum Manager lists all datums
+- [ ] Visibility toggle works
+- [ ] Rename persists after recompute
+- [ ] Delete removes datum cleanly
+
+### Assembly Integration Tests
+- [ ] Assembly workbench commands appear in toolbars
+- [ ] Assembly_CreateAssembly works from ztools
+- [ ] Assembly_InsertLink works from ztools
+- [ ] All joint commands accessible
+- [ ] Assembly_SolveAssembly works
+
+### Assembly Pattern Tests
+- [ ] Linear pattern with 3 occurrences along X axis
+- [ ] Linear pattern with Total Length mode
+- [ ] Linear pattern with Spacing mode
+- [ ] Linear pattern creates links (not copies)
+- [ ] Polar pattern with 6 occurrences (full circle)
+- [ ] Polar pattern with custom angle (90 degrees, 4 occurrences)
+- [ ] Polar pattern around Z axis
+- [ ] Polar pattern with custom center point
+- [ ] Multiple components can be patterned simultaneously
+- [ ] Pattern instances added to parent assembly
+
+### zSpreadsheet Tests
+- [ ] Spreadsheet toolbar appears with stock commands
+- [ ] ztools Spreadsheet toolbar appears with formatting commands
+- [ ] Create new spreadsheet via toolbar
+- [ ] Select cells and toggle Bold style
+- [ ] Select cells and toggle Italic style
+- [ ] Select cells and toggle Underline style
+- [ ] Align cells left/center/right
+- [ ] Set background color via color picker
+- [ ] Set text color via color picker (verify white default for dark theme)
+- [ ] Quick Alias creates alias from left-adjacent cell content
+- [ ] Undo/redo works for all formatting operations
+- [ ] Commands are disabled when no cells selected
+
+---
+
+## Notes
+
+- FreeCAD 1.0+ required (TNP mitigation assumed)
+- ZTools uses custom attachment system (not FreeCAD's vanilla attachment)
+- Catppuccin Mocha theme is bundled as preference pack
+- LGPL-3.0-or-later license