feat: unified datum creation command replacing separate plane/line/point commands #241

New Issue

forbes · 2026-02-15T10:51:20Z

forbes commented

2026-02-15 10:51:20 +00:00

Summary

Replace the four separate PartDesign datum commands (PartDesign_Plane, PartDesign_Line, PartDesign_Point, PartDesign_CoordinateSystem) with a single unified datum creation command based on the ztools DatumCreator.

Motivation

The current PartDesign workflow requires users to know which datum type they need before selecting geometry. The ztools DatumCreator reverses this: select geometry first, and the tool auto-detects the best datum type from 16 modes (7 planes, 4 axes, 5 points). This is faster, more discoverable, and covers creation modes that the native commands cannot express at all (midplane, tangent to cylinder, axis at cylinder center, point at face center, etc.).

Current State

Native PartDesign (4 commands, C++):

PartDesign_Plane / PartDesign_Line / PartDesign_Point / PartDesign_CoordinateSystem
Grouped as PartDesign_CompDatums in toolbar
Uses vanilla AttachExtension with the standard attachment panel
No metadata, no auto-detection

ztools DatumCreator (1 command, Python):

ZTools_DatumCreator — unified task panel with selection table + auto-detection
16 creation modes across planes (7), axes (4), and points (5)
Stores metadata: ZTools_Type, ZTools_Params, ZTools_SourceRefs
Custom edit panel via ZToolsDatumViewProvider
Catppuccin Mocha styling, optional spreadsheet parameter linking
Currently injected into PartDesign toolbar via WorkbenchManipulator

Proposed Change

Integrate the unified datum creation command into the base FreeCAD PartDesign workbench, replacing the four separate commands with one:

Replace PartDesign_CompDatums toolbar group with the unified datum command
Replace the four menu entries under PartDesign > Datums with a single entry
Keep existing PartDesign::Plane/Line/Point objects — the unified command creates the same underlying objects, just with a better UI for choosing creation mode
Add auto-detection logic — score selection geometry against all 16 modes, present best match with manual override
Store creation metadata as custom properties for later editing
Custom ViewProvider with double-click to reopen the unified editor instead of the vanilla attachment panel

16 Datum Creation Modes

Planes (7)

Mode	Selection	Parameters
Offset from Face	1 face	distance (mm)
Offset from Plane	1 datum plane	distance (mm)
Midplane	2 faces	—
3 Points	3 vertices	—
Normal to Edge	1 edge	position (0–1)
Angled from Face	1 face + 1 edge	angle (°)
Tangent to Cylinder	1 cylindrical face	angle (°)

Axes (4)

Mode	Selection	Parameters
2 Points	2 vertices	—
From Edge	1 linear edge	—
Cylinder Center	1 cylindrical face	—
Plane Intersection	2 datum planes	—

Points (5)

Mode	Selection	Parameters
At Vertex	1 vertex	—
At XYZ	(none)	x, y, z (mm)
On Edge	1 edge	position (0–1)
Face Center	1 face	—
Circle Center	1 circular edge	—

Key Files

mods/ztools/ztools/ztools/commands/datum_commands.py — DatumCreator command + task panel
mods/ztools/ztools/ztools/datums/core.py — 16 creation functions + attachment logic
mods/ztools/ztools/ztools/commands/datum_viewprovider.py — custom ViewProvider + edit panel
src/Mod/PartDesign/Gui/Command.cpp — native datum commands (lines 2638–2720)
src/Mod/PartDesign/Gui/Workbench.cpp — native toolbar/menu registration

Notes

The DatumManager command (ZTools_DatumManager) is currently a placeholder stub — it is not part of this issue
CoordinateSystem creation is not yet covered by the unified command and can remain as a separate command for now
The unified command should remain a Python workbench (not ported to C++) for development velocity

## Summary Replace the four separate PartDesign datum commands (`PartDesign_Plane`, `PartDesign_Line`, `PartDesign_Point`, `PartDesign_CoordinateSystem`) with a single unified datum creation command based on the ztools DatumCreator. ## Motivation The current PartDesign workflow requires users to know which datum type they need before selecting geometry. The ztools DatumCreator reverses this: select geometry first, and the tool auto-detects the best datum type from 16 modes (7 planes, 4 axes, 5 points). This is faster, more discoverable, and covers creation modes that the native commands cannot express at all (midplane, tangent to cylinder, axis at cylinder center, point at face center, etc.). ## Current State **Native PartDesign (4 commands, C++):** - `PartDesign_Plane` / `PartDesign_Line` / `PartDesign_Point` / `PartDesign_CoordinateSystem` - Grouped as `PartDesign_CompDatums` in toolbar - Uses vanilla `AttachExtension` with the standard attachment panel - No metadata, no auto-detection **ztools DatumCreator (1 command, Python):** - `ZTools_DatumCreator` — unified task panel with selection table + auto-detection - 16 creation modes across planes (7), axes (4), and points (5) - Stores metadata: `ZTools_Type`, `ZTools_Params`, `ZTools_SourceRefs` - Custom edit panel via `ZToolsDatumViewProvider` - Catppuccin Mocha styling, optional spreadsheet parameter linking - Currently injected into PartDesign toolbar via `WorkbenchManipulator` ## Proposed Change Integrate the unified datum creation command into the base FreeCAD PartDesign workbench, replacing the four separate commands with one: 1. **Replace `PartDesign_CompDatums`** toolbar group with the unified datum command 2. **Replace the four menu entries** under PartDesign > Datums with a single entry 3. **Keep existing PartDesign::Plane/Line/Point objects** — the unified command creates the same underlying objects, just with a better UI for choosing creation mode 4. **Add auto-detection logic** — score selection geometry against all 16 modes, present best match with manual override 5. **Store creation metadata** as custom properties for later editing 6. **Custom ViewProvider** with double-click to reopen the unified editor instead of the vanilla attachment panel ## 16 Datum Creation Modes ### Planes (7) | Mode | Selection | Parameters | |------|-----------|------------| | Offset from Face | 1 face | distance (mm) | | Offset from Plane | 1 datum plane | distance (mm) | | Midplane | 2 faces | — | | 3 Points | 3 vertices | — | | Normal to Edge | 1 edge | position (0–1) | | Angled from Face | 1 face + 1 edge | angle (°) | | Tangent to Cylinder | 1 cylindrical face | angle (°) | ### Axes (4) | Mode | Selection | Parameters | |------|-----------|------------| | 2 Points | 2 vertices | — | | From Edge | 1 linear edge | — | | Cylinder Center | 1 cylindrical face | — | | Plane Intersection | 2 datum planes | — | ### Points (5) | Mode | Selection | Parameters | |------|-----------|------------| | At Vertex | 1 vertex | — | | At XYZ | (none) | x, y, z (mm) | | On Edge | 1 edge | position (0–1) | | Face Center | 1 face | — | | Circle Center | 1 circular edge | — | ## Key Files - `mods/ztools/ztools/ztools/commands/datum_commands.py` — DatumCreator command + task panel - `mods/ztools/ztools/ztools/datums/core.py` — 16 creation functions + attachment logic - `mods/ztools/ztools/ztools/commands/datum_viewprovider.py` — custom ViewProvider + edit panel - `src/Mod/PartDesign/Gui/Command.cpp` — native datum commands (lines 2638–2720) - `src/Mod/PartDesign/Gui/Workbench.cpp` — native toolbar/menu registration ## Notes - The DatumManager command (`ZTools_DatumManager`) is currently a placeholder stub — it is **not** part of this issue - CoordinateSystem creation is not yet covered by the unified command and can remain as a separate command for now - The unified command should remain a Python workbench (not ported to C++) for development velocity

forbes closed this issue

2026-02-23 18:29:04 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: kindred/create#241