ztools/PLAN.md

ZTools Development Plan

Current Status: v0.1.0 (70% complete)

What's Working

• Workbench registration with 10 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 (21+ Catppuccin-themed SVGs)
• Metadata storage system (ZTools_Type, ZTools_Params, ZTools_SourceRefs)
• Spreadsheet linking for parametric control

Recent 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 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/InitGui.py	Workbench registration	~200
ztools/ztools/resources/icons.py	SVG icon definitions	~400

---

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

---

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