kindred/create
1
1
Fork 0
Code Issues 53 Pull Requests Actions Packages Projects 9 Releases 2 Wiki Activity
Files
main
create/reference/ztools/PLAN.md
forbes c8b0706a1d
All checks were successful
Build and Test / build (pull_request) Successful in 32m17s
Details
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

421 lines
14 KiB
Markdown
Raw Permalink Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink