From e6f1de4ef8421f483ea69838908e2d9b772d6438 Mon Sep 17 00:00:00 2001 From: Zoe Forbes Date: Mon, 26 Jan 2026 23:06:14 -0600 Subject: [PATCH] add kindred integration docs --- KINDRED_INTEGRATION.md | 385 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 385 insertions(+) create mode 100644 KINDRED_INTEGRATION.md diff --git a/KINDRED_INTEGRATION.md b/KINDRED_INTEGRATION.md new file mode 100644 index 0000000..0d19282 --- /dev/null +++ b/KINDRED_INTEGRATION.md @@ -0,0 +1,385 @@ +# 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.