# Datum Creator System

The ZTools Datum Creator (`ZTools_DatumCreator`) creates parametric datum planes, axes, and points. It auto-detects the datum type from selected geometry and provides a unified task panel with 16 creation modes.

**Source files:**

- `mods/ztools/ztools/ztools/commands/datum_commands.py` -- UI, selection handling, mode detection
- `mods/ztools/ztools/ztools/datums/core.py` -- geometry computation and FreeCAD object creation

## Geometry Classification

The `SelectionItem` class wraps a selected geometry element and classifies it into one of seven types:

| Type | Detection | Icon |
|------|-----------|------|
| face | Planar `Part.Face` or object with "Plane" in TypeId | ▢ |
| plane | Datum plane objects or planar faces | ▣ |
| cylinder | `Part.Face` with `Surface.Cylinder` | ◎ |
| edge | `Part.Edge` with `Part.Line` curve | ― |
| circle | `Part.Edge` with `Part.Circle` or `Part.ArcOfCircle` | ○ |
| vertex | `Part.Vertex` | • |
| unknown | Unclassified geometry | ? |

Classification flow:

1. Extract shape from object using the sub-element name (Face#, Edge#, Vertex#)
2. Check shape type (Face, Edge, Vertex)
3. For faces: check `surface.isPlanar()` or `isinstance(surface, Part.Cylinder)`
4. For edges: check curve type (Line, Circle, ArcOfCircle)
5. Fall back to `unknown`

## Creation Modes

### Planes (7 modes)

| Mode | Required Selection | Parameters | Description |
|------|--------------------|------------|-------------|
| `offset_face` | 1 face | distance (mm) | Plane parallel to face at offset |
| `offset_plane` | 1 plane | distance (mm) | Plane parallel to datum plane at offset |
| `midplane` | 2 faces | -- | Plane halfway between two parallel faces |
| `3_points` | 3 vertices | -- | Plane through three non-collinear points |
| `normal_edge` | 1 edge | position (0--1) | Plane perpendicular to edge at parameter |
| `angled` | 1 face + 1 edge | angle (deg) | Plane at angle to face, rotating about edge |
| `tangent_cyl` | 1 cylinder | angle (deg) | Plane tangent to cylinder at angular position |

### Axes (4 modes)

| Mode | Required Selection | Parameters | Description |
|------|--------------------|------------|-------------|
| `axis_2pt` | 2 vertices | -- | Axis through two points |
| `axis_edge` | 1 edge | -- | Axis along linear edge |
| `axis_cyl` | 1 cylinder | -- | Axis along cylinder centerline |
| `axis_intersect` | 2 planes | -- | Axis at intersection of two planes |

### Points (5 modes)

| Mode | Required Selection | Parameters | Description |
|------|--------------------|------------|-------------|
| `point_vertex` | 1 vertex | -- | Point at vertex location |
| `point_xyz` | (none) | x, y, z (mm) | Point at explicit coordinates |
| `point_edge` | 1 edge | position (0--1) | Point at parameter location on edge |
| `point_face` | 1 face | -- | Point at center of mass of face |
| `point_circle` | 1 circle | -- | Point at center of circular edge |

## Auto-Detection Algorithm

The `_match_score()` method scores how well the current selection matches each mode's required types.

**Scoring:**

1. If the selection has fewer items than required, score is **0** (no match).
2. For each required type, find a matching selected type using fuzzy matching:
   - `face` requirement matches `face` or `cylinder`
   - `edge` requirement matches `edge` or `circle`
   - All other types require exact match
3. Score calculation:
   - **Exact cardinality** (selection count == required count): score = `100 + matched_count`
   - **Over-selected** (more items than required): score = `matched_count`
   - **No match**: score = `0`

The mode with the highest score wins. On each selection change, `update_mode_from_selection()` re-evaluates all 16 modes and activates the best match.

The detected mode is displayed with a category color:

- Planes: Mauve (#cba6f7)
- Axes: Teal (#94e2d5)
- Points: Yellow (#f9e2af)

## Task Panel UI

```
+-------------------------------------+
|      ZTools Datum Creator           |
+-------------------------------------+
| Selection                           |
|  [icon] Element Name       [Remove] |
|  [Add Selected] [Remove] [Clear]    |
+-------------------------------------+
| Datum Type                          |
|  DETECTED MODE (colored)            |
|  Override: [dropdown]               |
+-------------------------------------+
| Parameters (dynamic per mode)       |
|  Offset: [spinner] mm              |
|  Angle: [spinner] deg              |
|  Position: [spinner] 0-1           |
|  X/Y/Z: [spinner] mm              |
+-------------------------------------+
| Options                            |
|  [ ] Link to Spreadsheet           |
|  [x] Add to Active Body            |
|  [ ] Custom Name: [text]           |
+-------------------------------------+
|         [OK]     [Cancel]           |
+-------------------------------------+
```

### Selection table

Three columns: type icon (28px), element name (stretch), remove button (28px). Duplicates are rejected. A FreeCAD `SelectionObserver` keeps the "Add Selected" button state synchronized with the active 3D selection.

### Mode override

The dropdown lists all 16 modes prefixed by category (`[P]` plane, `[A]` axis, `[Pt]` point). Selecting a mode disables auto-detection until "(Auto-detect)" is re-selected.

### Parameters section

Rebuilt dynamically when the mode changes. Only the parameter widgets relevant to the active mode are shown. Modes with no parameters hide the section entirely.

### Options

- **Link to Spreadsheet**: creates a spreadsheet alias and expression-links the datum parameter (offset, angle, coordinates) for parametric control.
- **Add to Active Body**: when checked, creates a `PartDesign::Plane/Line/Point` inside the active body. When unchecked, creates a document-level `Part::Plane/Line/Vertex`.
- **Custom Name**: overrides the auto-generated name (format: `ZPlane_Offset_001`).

## Dispatch to core.py

`DatumCreatorTaskPanel.accept()` calls `create_datum()`, which:

1. Reads the current mode, body, name, and parameters from the UI
2. Extracts `SelectionItem` objects by type
3. Dispatches to the corresponding `core.*` function:

| Mode | Core function |
|------|---------------|
| `offset_face` | `core.plane_offset_from_face(face, distance, ...)` |
| `offset_plane` | `core.plane_offset_from_plane(plane, distance, ...)` |
| `midplane` | `core.plane_midplane(face1, face2, ...)` |
| `3_points` | `core.plane_from_3_points(p1, p2, p3, ...)` |
| `normal_edge` | `core.plane_normal_to_edge(edge, parameter, ...)` |
| `angled` | `core.plane_angled(face, edge, angle, ...)` |
| `tangent_cyl` | `core.plane_tangent_to_cylinder(face, angle, ...)` |
| `axis_2pt` | `core.axis_from_2_points(p1, p2, ...)` |
| `axis_edge` | `core.axis_from_edge(edge, ...)` |
| `axis_cyl` | `core.axis_cylinder_center(face, ...)` |
| `axis_intersect` | `core.axis_intersection_planes(plane1, plane2, ...)` |
| `point_vertex` | `core.point_at_vertex(vertex, ...)` |
| `point_xyz` | `core.point_at_coordinates(x, y, z, ...)` |
| `point_edge` | `core.point_on_edge(edge, parameter, ...)` |
| `point_face` | `core.point_center_of_face(face, ...)` |
| `point_circle` | `core.point_center_of_circle(edge, ...)` |

## Core Implementation

Each `core.*` function:

1. Creates the FreeCAD object (`PartDesign::Plane` in a body, `Part::Plane` at document level)
2. Computes the placement from the source geometry
3. Configures attachment (MapMode, AttachmentSupport, offset) for parametric updates
4. Stores ZTools metadata in custom properties:
   - `ZTools_Type` -- creation method identifier (e.g. `"offset_from_face"`)
   - `ZTools_Params` -- parameters as JSON (e.g. `{"distance": 10}`)
   - `ZTools_SourceRefs` -- source geometry references as JSON
5. Applies Catppuccin Mocha styling (mauve at 70% transparency for planes)
6. Optionally links parameters to a spreadsheet alias

Auto-naming uses the format `ZPlane_Offset_001`, incrementing the index for each new datum of the same type.