create/reference/ztools/KINDRED_INTEGRATION.md

Kindred Create Integration Guide

This document outlines the requirements, options, and steps for integrating the ztools workbench into Kindred Create as a native workbench.

---

Table of Contents

1. Current Architecture Overview
2. Integration Options
3. Files Requiring Modification
4. Branding Changes
5. FreeCAD API Dependencies
6. Recommended Integration Path
7. Testing Checklist

---

Current Architecture Overview

Directory Structure

ztools-0065/
├── package.xml                    # FreeCAD addon metadata
├── CatppuccinMocha/               # Preference pack (theme)
└── ztools/                        # Main addon directory
    ├── Init.py                    # Pre-GUI initialization
    ├── InitGui.py                 # Workbench class definition
    └── ztools/                    # Python package
        ├── __init__.py
        ├── commands/              # GUI commands
        │   ├── __init__.py
        │   ├── datum_commands.py
        │   ├── datum_viewprovider.py
        │   ├── pattern_commands.py
        │   ├── pocket_commands.py
        │   ├── assembly_pattern_commands.py
        │   └── spreadsheet_commands.py
        ├── datums/                # Datum creation logic
        │   ├── __init__.py
        │   └── core.py
        └── resources/             # Icons and theming
            ├── __init__.py
            ├── icons.py
            └── theme.py

Module Statistics

Component	Files	Commands	Description
Datum Tools	3	2	15 attachment modes, DatumCreator + DatumManager
Pattern Tools	1	1	Rotated linear pattern
Pocket Tools	1	1	Enhanced pocket with face selection
Assembly Tools	1	2	Linear and polar assembly patterns
Spreadsheet Tools	1	9	Formatting and quick alias
Resources	2	-	33 SVG icons, theme colors

External Dependencies

• Python Standard Library Only - No pip dependencies
• FreeCAD Modules: FreeCAD, FreeCADGui, Part, PartDesign, Sketcher, Assembly (1.0+), Spreadsheet
• Qt/PySide: QtCore, QtGui, QtWidgets (via FreeCAD's bundled PySide)

---

Integration Options

Option A: Addon-Style Integration (Minimal Changes)

Effort: Low
Compatibility: Maintains upstream FreeCAD compatibility

Bundle ztools as a pre-installed addon in Kindred Create's addon directory.

Pros:

• Minimal code changes
• Can still be distributed as standalone addon
• Easy to update independently

Cons:

• Not truly "native" - still appears as addon
• Users could accidentally uninstall

Changes Required:

• Update package.xml metadata with Kindred Create branding
• Optionally rename workbench display name

Option B: Native Workbench Integration (Moderate Changes)

Effort: Medium
Compatibility: Kindred Create specific

Move ztools into FreeCAD's Mod/ directory as a first-party workbench.

Pros:

• Appears alongside PartDesign, Assembly, etc.
• Cannot be uninstalled via Addon Manager
• Full integration with Kindred Create identity

Cons:

• Requires maintaining fork-specific code
• Branding changes throughout codebase

Changes Required:

• Rename all ZTools_* commands to KindredCreate_* or similar
• Update workbench class name and identifiers
• Modify directory structure to match FreeCAD conventions
• Update all user-facing strings

Option C: Full Workbench Replacement (Major Changes)

Effort: High
Compatibility: Kindred Create only

Replace existing PartDesign/Assembly workbenches with unified Kindred workbench.

Pros:

• Unified user experience
• Complete control over workflow

Cons:

• Significant development effort
• Diverges heavily from upstream FreeCAD
• Harder to merge upstream improvements

---

Files Requiring Modification

Critical Files

File	Changes Needed
package.xml	Package name, description, workbench name, classname
ztools/InitGui.py	Class name, MenuText, ToolTip, Icon, console messages
ztools/Init.py	Console messages
ztools/ztools/commands/__init__.py	No changes (internal imports)

Command Registration (All Command Files)

Each command file registers commands with Gui.addCommand("ZTools_*", ...). These need renaming:

File	Commands to Rename
datum_commands.py	ZTools_DatumCreator, ZTools_DatumManager
pattern_commands.py	ZTools_RotatedLinearPattern
pocket_commands.py	ZTools_EnhancedPocket
assembly_pattern_commands.py	ZTools_AssemblyLinearPattern, ZTools_AssemblyPolarPattern
spreadsheet_commands.py	ZTools_SpreadsheetStyleBold, ZTools_SpreadsheetStyleItalic, ZTools_SpreadsheetStyleUnderline, ZTools_SpreadsheetAlignLeft, ZTools_SpreadsheetAlignCenter, ZTools_SpreadsheetAlignRight, ZTools_SpreadsheetBgColor, ZTools_SpreadsheetTextColor, ZTools_SpreadsheetQuickAlias

Internal References

Custom properties use ZTools_ prefix for disambiguation:

File	Properties
datums/core.py	ZTools_SourceRefs, ZTools_Params, ZTools_DatumMode
datum_viewprovider.py	Same properties accessed

Note: These property names are stored in FreeCAD documents. Renaming them would break backward compatibility with existing documents. Consider keeping these internal or implementing migration.

---

Branding Changes

User-Visible Strings

Location	Current	Suggested
InitGui.py MenuText	"ztools"	"Kindred Design" or similar
InitGui.py ToolTip	"Extended PartDesign replacement..."	Kindred-specific description
InitGui.py console messages	"ztools workbench..."	"Kindred Design workbench..."
Init.py console messages	"ztools addon loaded"	"Kindred Design loaded"
Toolbar names	"ztools Datums", etc.	"Kindred Datums", etc.
Menu names	"ztools"	"Kindred"

Command Prefixes

Current: ZTools_*
Suggested: KindredCreate_*, Kindred_*, or KC_*

Class Names

Current	Suggested
ZToolsWorkbench	KindredDesignWorkbench
ZToolsDatumObject	KindredDatumObject
ZToolsDatumViewProvider	KindredDatumViewProvider

---

FreeCAD API Dependencies

Core APIs Used

# Application
import FreeCAD as App
import FreeCADGui as Gui

# Part/PartDesign
import Part
import PartDesign

# Workbench patterns
Gui.Workbench              # Base class
Gui.addCommand()           # Command registration
Gui.Control.showDialog()   # Task panels
Gui.Selection              # Selection observer

# Document operations
App.ActiveDocument
doc.openTransaction()
doc.commitTransaction()
doc.abortTransaction()
doc.recompute()

# Feature Python
Part.makeCompound()
doc.addObject("Part::FeaturePython", name)
doc.addObject("PartDesign::Plane", name)
doc.addObject("PartDesign::Line", name)
doc.addObject("PartDesign::Point", name)
doc.addObject("App::Link", name)

Assembly Workbench APIs (FreeCAD 1.0+)

# Assembly operations
asm.TypeId == "Assembly::AssemblyObject"
App.Link objects for component instances

Spreadsheet APIs

sheet.set(cell, value)
sheet.getContents(cell)
sheet.setStyle(cell, style)
sheet.setAlignment(cell, alignment)
sheet.setBackground(cell, (r, g, b))
sheet.setForeground(cell, (r, g, b))
sheet.setAlias(cell, alias)

Qt/PySide APIs

from PySide import QtCore, QtGui, QtWidgets

# Dialogs
QtWidgets.QColorDialog.getColor()

# Task panels
QtWidgets.QWidget subclasses

# Selection from table views
QTableView.selectionModel()
QItemSelectionModel.selectedIndexes()

Preference System

App.ParamGet("User parameter:BaseApp/Preferences/Mod/Spreadsheet")
params.SetUnsigned(key, value)
params.GetUnsigned(key)

---

Recommended Integration Path

Phase 1: Branding Update (Option B)

1. Fork the repository for Kindred Create
2. Rename package and workbench:
   • package.xml: Update name, description
   • InitGui.py: Update class name, MenuText, ToolTip
   • Init.py: Update log messages
3. Rename command prefixes:
   • Global find/replace: ZTools_ → Kindred_
   • Update all Gui.addCommand() calls
   • Update all toolbar/menu references in InitGui.py
4. Update toolbar/menu labels:
   • "ztools Datums" → "Kindred Datums"
   • etc.
5. Keep internal property names (ZTools_SourceRefs, etc.) for document compatibility

Phase 2: Directory Restructure

1. Move to FreeCAD's Mod directory:

   freecad-source/src/Mod/KindredDesign/
   ├── Init.py
   ├── InitGui.py
   └── KindredDesign/
       ├── commands/
       ├── datums/
       └── resources/
   

2. Update CMakeLists.txt in FreeCAD source to include new module
3. Add to default workbench list if desired

Phase 3: Theme Integration

1. Move CatppuccinMocha to Kindred Create's default themes
2. Optionally set as default theme for new installations
3. Update apply_spreadsheet_colors() to use Kindred theme colors

---

Testing Checklist

Functional Tests

• Workbench activates without errors
• All toolbars appear with correct icons
• All menus appear with correct structure
• Datum Creator: All 15 modes work
• Datum Manager: Opens (stub functionality)
• Rotated Linear Pattern: Creates patterns correctly
• Enhanced Pocket: Face selection works
• Assembly Linear Pattern: Creates component arrays
• Assembly Polar Pattern: Creates circular arrays
• Spreadsheet Bold/Italic/Underline: Toggle correctly
• Spreadsheet Alignment: Left/Center/Right work
• Spreadsheet Colors: Dialogs open, colors apply
• Spreadsheet Quick Alias: Creates aliases from labels
• Undo/Redo works for all operations

Integration Tests

• Existing FreeCAD documents open correctly
• New documents created with Kindred tools save/load properly
• PartDesign features work alongside Kindred datums
• Assembly joints work with Kindred patterns
• Spreadsheet aliases work in PartDesign expressions

Theme Tests

• Catppuccin Mocha preference pack loads
• Spreadsheet text colors are correct (light on dark)
• Icons render with correct theme colors
• QSS styling applies to all custom widgets

---

Migration Notes

Document Compatibility

Documents created with ztools will contain:

• Objects with ZTools_* custom properties
• References to ZTools_* in expressions (unlikely but possible)

Recommendation: Keep internal property names unchanged, or implement a document migration script that updates property names on load.

User Preference Migration

If users have existing FreeCAD installations:

• Spreadsheet color preferences are stored per-user
• Consider running apply_spreadsheet_colors() on first Kindred Create launch

---

Summary

The ztools workbench is well-structured for integration into Kindred Create. The recommended path is Option B (Native Workbench Integration) which provides:

• Native appearance alongside other FreeCAD workbenches
• Kindred Create branding throughout
• Maintained document compatibility
• Reasonable development effort

Key points:

• No external dependencies - clean integration
• Standard FreeCAD APIs - future-compatible
• Modular structure - easy to extend
• 33 custom icons - complete visual identity ready for recoloring

Estimated effort for full integration: 2-4 hours for branding changes, additional time for build system integration depending on Kindred Create's structure.