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](#current-architecture-overview)
2. [Integration Options](#integration-options)
3. [Files Requiring Modification](#files-requiring-modification)
4. [Branding Changes](#branding-changes)
5. [FreeCAD API Dependencies](#freecad-api-dependencies)
6. [Recommended Integration Path](#recommended-integration-path)
7. [Testing Checklist](#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

```python
# 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+)

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

### Spreadsheet APIs

```python
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

```python
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

```python
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.