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