# Line vs Theoretical Report

The Line vs Theoretical report computes the **signed deviation (DR)** of every measured point from its configured theoretical polyline, for every selected line definition and every section in the chainage range.

Unlike the {doc}`../analytics/index` pipeline — which compares a whole cross-section against a chosen reference — the Line vs Theoretical report runs once per measured line definition and uses the **line's own theoretical reference** (the polyline name stored on the line definition as `DeviationLine`). This is the same reference the Section View uses when it draws DR labels, so the DR numbers in the report match what the user sees interactively.

## Dialog

Open **Reports → Line vs Theoretical...** from the main menu.

| Control | Effect |
|---------|--------|
| **From / To** | Chainage filter. Pre-filled with the alignment's start and end chainage when the dialog opens; edit to narrow the band. |
| **Line Definitions** | Tick the measured lines to include. Lines without a configured `DeviationLine` still appear in the summary but with `HasTheoretical = False` and DR columns left blank. |
| **Mode — Summary** | Produces only the per-(section × line) aggregate table. |
| **Mode — Full Detail** | Adds per-point rows with measured / nearest-on-theoretical / DR. |
| **Include overlay plot** | PDF only. When ticked, each section with Full Detail gets an extra mini-plot with the measured line in blue and the theoretical line in grey, to visualise the DR geometrically. Default on. |
| **Format — PDF / XLSX** | |

Default selection: all lines ticked, Mode = *Full Detail*, Format = *PDF*, Overlay = on.

## DR sign convention

For every measured point the closest point on the configured theoretical polyline is located. The signed DR is then:

```
DR > 0  — measured point is **farther** from the tunnel axis origin (0, 0) than the nearest theoretical point → over-excavation.
DR < 0  — measured point is **closer** to the axis origin than the nearest theoretical point → under-excavation.
```

This matches the Section View's DR labels exactly, so the report and the on-screen annotations are always in agreement.

## Theoretical-polyline resolution

For each section and each measured line, the report looks up the theoretical polyline by name:

1. Read `LineDefinition.DeviationLine` (set in **Section Details / Line Definitions**).
2. If the section has a line with that name, use its points directly.
3. Otherwise, if the tunnel has a template at that station, fetch the template and retrieve the line whose name matches `DeviationLine` (falling back to the template-line library).
4. If neither step resolves a polyline, the section is listed in the summary as `HasTheoretical = False` and DR is not computed for it.

This two-step resolution means an alignment without a full template library can still produce a DR report as long as each section carries the theoretical polyline inline.

## Summary table

Always emitted. One row per (section × line) combination:

| Column | Content |
|--------|---------|
| **Chainage** | Station, km+m. |
| **Line** | Measured line definition name. |
| **Theoretical** | Name of the theoretical polyline (same as `DeviationLine`). Blank when not configured. |
| **Points** | Number of measured points on that line in that section. |
| **Max Over (mm)** | Largest positive DR. |
| **Max Under (mm)** | Largest absolute-value negative DR. Stored as a negative number in the XLSX. |
| **Mean DR (mm)** | Arithmetic mean of DRs. |
| **RMS (mm)** | Root-mean-square of DRs. |

When Mode = *Summary*, this is the only table produced.

## Per-point detail (Full mode)

One row per measured point, grouped by section then by line:

| Column | Content |
|--------|---------|
| **Chainage** | |
| **Line** | |
| **#** | Zero-based point index. |
| **Meas X, Y** | Measured point, section-local coordinates. |
| **Theo X, Y** | Nearest point on the theoretical polyline, section-local. |
| **DR (mm)** | Signed deviation. |
| **Over / Under** | Short text — `Over` if positive, `Under` if negative, `-` if zero. |

Rows with `DR > 0` are tinted green in the PDF; `DR < 0` rows tinted red. In XLSX a conditional-format icon set highlights the same split.

## Overlay plot (PDF only)

When **Include overlay plot** is ticked, each section with detail data gets a single-page overlay: the theoretical polyline is drawn in grey, the measured polyline in blue, and every measured-to-theoretical match is connected with a thin red/green tick in the DR direction. The plot is framed in a square picture box and scaled to the common bounding rectangle of both polylines.

The overlay is useful as a quick visual check that the theoretical polyline resolution picked the intended reference.

## PDF layout

A4 portrait, 180 mm usable width after margins.

- **Page 1+** — Summary table. Paginates with a repeated header.
- **Subsequent pages** — Full-detail rows, with optional overlay plots interleaved per section when enabled.
- Footer on every page with page number and project/tunnel.

## XLSX layout

Two sheets:

- **Summary** — one row per (section × line).
- **Detail** — one row per measured point (only when Full Detail is selected).

```{note}
If a line definition has no `DeviationLine` configured, the Summary row still appears but with DR columns blank and **Theoretical** empty. This makes the gap visible to reviewers — they see the line exists but was never matched to a reference.
```

```{tip}
If you want the full analytics pipeline (grade, compliance, Cpk, sector map) on a specific line pair, use the {doc}`../analytics/modes` *Measured vs Measured* mode instead. Line vs Theoretical is the quick per-line listing; Analytics is the full quality assessment.
```