add kindred integration docs
This commit is contained in:
Zoe Forbes
385
KINDRED_INTEGRATION.md
Normal file
385
KINDRED_INTEGRATION.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user