# Template Editor

The Template Editor is the primary dialog for creating, viewing, and modifying templates. Open it from the ribbon via **Template > Assign**, or from the menu via **Template > Edit Templates**.

## Dialog layout

The Template Editor is divided into several areas:

- **Toolbar** (top) -- buttons for New, Delete, Duplicate, Import DXF, Export, Import, Export DXF, Test Transform, Apply, and Close.
- **Tree panel** (left) -- hierarchical view of all templates and their template lines.
- **Properties panel** (left, below tree) -- name, description, and display options for the selected template or line.
- **Points grid** (left, below properties) -- coordinate editor for the selected template line's vertices, with Add, Delete, Insert, and Reverse buttons.
- **Preview area** (center) -- visual display of the current template with zoom/pan navigation.
- **Station Definitions grid** (bottom) -- chainage-to-template assignments. See {doc}`station-definitions`.
- **Station strip** (below grid) -- a longitudinal color bar showing template zones along the alignment, with template names and transition zone markers.
- **Status bar** (bottom) -- shows the cursor position in world coordinates.

## Tree panel

The tree shows all templates in the current tunnel alignment. Each template node expands to reveal its template lines. Selecting a template node shows all of its lines overlaid in the preview. Selecting a specific line node shows only that line, with vertex dots highlighted.

Template lines are color-coded according to their Template Line Definition color, making it easy to distinguish between different design layers.

## Properties

When a template is selected in the tree, the properties panel shows:

- **Name** -- the template identifier, used in station definitions and reports.
- **Description** -- free-text field for notes (e.g., "Standard section - good rock").

When a specific template line is selected:

- **Closed** -- whether the polyline is drawn as a closed shape (last point connects back to first).
- **Show Direction** -- toggles direction arrows on the preview, showing point order and winding direction (CW/CCW label).

```{tip}
Use "Show Direction" to verify the winding order of your template lines. Consistent winding direction matters for correct area and overbreak/underbreak calculations.
```

## Points grid

The points grid is enabled when a template line is selected in the tree. It displays one row per vertex with the following columns:

| Column | Description |
|--------|-------------|
| **#** | Point index (zero-based) |
| **X** | Horizontal offset from the section axis (positive = right, negative = left) |
| **Y** | Elevation value |
| **Bulge** | Arc bulge factor (0 = straight segment to next point) |

### Adding points

Click the **Add** button below the grid to append a new point. The new point is added at (0, 0) with zero bulge and can then be edited in the grid cells.

### Inserting points

Select a row in the grid and click **Insert Point** to add a new point after the selected row. The new point is inserted at (0, 0) with zero bulge. All point indices are renumbered automatically.

### Deleting points

Select a row in the grid and click **Delete** to remove that vertex.

### Reversing point order

Click **Reverse** to reverse the order of all points in the current template line. This also negates all bulge values to maintain the correct arc direction. Use this when the winding direction (CW/CCW) needs to be flipped — enable "Show Direction" to verify the result.

### Applying changes

After editing point coordinates or bulge values in the grid, click **Apply** in the toolbar to commit the changes to the template. The preview updates immediately to reflect the new geometry.

```{important}
Bulge values are applied after all points have been added to the internal polyline. When entering bulge values, make sure the endpoint of the arc segment already exists in the grid before setting a non-zero bulge.
```

## Preview area

The preview renders the template geometry on a dark background with a coordinate grid and center marker (red crosshair at the origin). Navigation:

- **Drag** (any mouse button) -- pan the view.
- **Mouse wheel** -- zoom in/out, centered on the cursor position.
- The preview auto-zooms to fit the template extents when a new template or line is selected.

When all lines are shown (template node selected), each line is drawn in its definition color. When a single line is selected, it is drawn with highlighted vertex dots showing the control points.

## Creating a new template

1. Click **New** in the toolbar.
2. Enter a unique name in the input dialog and confirm.
3. The new template is created with template lines matching all existing Template Line Definitions (auto-synchronized), but the lines have no geometry yet.
4. Select each template line in the tree and add points via the points grid, or use {doc}`dxf-import` to import geometry from a DXF file.

## Duplicating a template

Select an existing template in the tree and click **Duplic.** to create a copy. You will be prompted for a new name. The duplicate includes all template line geometry (points and bulge values), making it useful when a new zone needs a profile similar to an existing one with minor modifications.

## Deleting a template

Select a template in the tree and click **Delete**. A confirmation dialog appears before the template is removed. Deleting a template does not affect cross-sections that already reference it, but those sections will no longer have a valid template for future deviation analysis.

## Exporting templates

### Export to XML (.tcx)

Click **Export** in the toolbar to save all templates, template line definitions, and station definitions to a `.tcx` file (TunnelCAD Template XML). This portable file can be imported into any other tunnel alignment.

### Export to DXF

Select a template in the tree and click **Export DXF** to save it as a DXF file. Each template line is written as a LWPOLYLINE on its own layer, using the Template Line Definition layer name and color. Lines with no geometry are skipped.

## Importing templates

Click **Import** in the toolbar to load templates from a `.tcx` file. The import wizard shows:

- **Template Line Definitions** -- checkbox list of definitions in the file. New definitions (not in the current alignment) are marked "(new)".
- **Templates** -- checkbox list with line count and point count for each template. Templates that already exist are marked "[exists]".
- **Import Station Definitions** -- optional checkbox to also import chainage ranges (unchecked by default since chainages are alignment-specific).

When importing a template whose name already exists, you are prompted to **Skip**, **Overwrite**, or **Rename** (imported as "Name (imported)"). The "Apply to all" checkbox applies your choice to all remaining conflicts.

## Transformation preview

The **Test Transform** button in the toolbar activates the transformation preview, which lets you visualize how the interpolation engine blends two templates before applying it to sections.

### Activating the preview

1. In the Station Definitions grid, select a row that has a **Transform To** template and a **Transform Length** greater than 0.
2. Click **Test Transform** in the toolbar.
3. The preview switches to transformation mode and a control panel appears below the preview area.

The button is disabled when the selected station definition has no transformation configured.

### Preview controls

| Control | Description |
|---------|-------------|
| **Slider** | Drag from 0% (pure source template) to 100% (pure destination template) to see the interpolated profile at any point in the transition zone. |
| **Chainage** | Type a chainage value and press Enter to jump to that station within the transition zone. The slider updates to match, and vice versa. |
| **Type dropdown** | Switch between **Linear** and **Cubic** easing to compare the transition behavior. |
| **Check** | Opens a diagnostic report showing which lines will be interpolated and which are skipped, with the reason (point count mismatch, empty geometry, etc.). |
| **Close** | Exits the transformation preview and returns to normal template editing. |

### Visual display

In transformation preview mode, the preview area shows three layers:

- **Source template** -- drawn as dim gray lines (ghost).
- **Destination template** -- drawn as dim purple lines (ghost).
- **Interpolated template** -- drawn in full color using the Template Line Definition colors, representing the blended profile at the current slider position.

As you drag the slider, the interpolated lines smoothly morph between the source and destination shapes.

### Check report

The **Check** button opens a grid dialog showing the compatibility analysis for every template line:

| Column | Description |
|--------|-------------|
| **Line Name** | Name of the template line |
| **Source Pts** | Number of points in the source template |
| **Dest Pts** | Number of points in the destination template |
| **Status** | OK (will interpolate), or SKIP with the specific reason |

Possible skip reasons:

- **both empty** -- neither template has geometry for this line.
- **source empty** / **destination empty** -- geometry exists in only one template.
- **point count mismatch** -- the line has a different number of points in each template. Edit the templates to match the point counts.
- **not found in source** / **not found in destination** -- the line definition exists in one template but not the other.

```{tip}
Always run the Check report before relying on a transformation. It quickly reveals which lines need editing to enable full interpolation.
```