create/reference/ztools/PLAN.md

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:

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