# Measurement Import and Export

TunnelCAD reads and writes per-section measurement data (line points) as ASCII text files, in addition to the LandXML round-trip described in {doc}`landxml`. These ASCII workflows are intended for exchanging survey data with total stations, scanners, and external analysis tools that produce simple delimited text.

## Concepts

A *measurement* in this context is a 3D point that belongs to a specific cross-section's line data. The import and export tools share the same column-mapping engine (the **format profile** system), which lets the same file shapes be read and written.

Three coordinate flavours are supported:

XYZ
: World-coordinate points. The alignment engine reduces each point to its nearest section via offset-aware projection. This is the format produced by most field instruments.

Station / Offset / Z
: Pre-projected points already expressed along the alignment. The station selects the section; the offset is signed (right-positive) and Z is the absolute elevation.

Station / Offset / dZ
: Same as above, but Z is the difference from the alignment axis at that station rather than an absolute elevation. This matches TunnelCAD's internal section-local convention.

```{note}
Section local coordinates inside TunnelCAD use **dZ from the offset-axis point**, not absolute Z. The Sta-Off-dZ flavour matches this internal representation; the other two are converted on the fly.
```

## Format profiles

A format profile names a column layout (delimiter + column roles such as `Name`, `X`, `Y`, `Z`, `Sta`, `Offset`, `DZ`, `Code`, `Ignore`). 13 profiles ship out of the box:

- **CSV variants** (5) -- comma-delimited XYZ and station-based layouts. The default is `Name,X,Y,Z`.
- **Whitespace variants** (7) -- space- or tab-delimited equivalents.
- **LandXML** -- reads `<CgPoints>` from a LandXML file using the same column mapping abstraction.

Profiles can be renamed (with the active delimiter visible in the list) and reordered. Custom profiles are saved with the application settings.

## Importing measurements

Open the workbench from **File > Import Measurements...**.

### Two-tab workflow

The dialog has two tabs that share the same target alignment and line-definition selection:

1. **ASCII** -- pick one or more text files, choose a profile, parse, then commit.
2. **LandXML** -- pick a LandXML file and commit its CgPoints.

### Workflow

1. Choose the line definition(s) the imported points should populate. Multi-select is supported -- when multiple files are selected, each file binds to one line definition.
2. Pick the format profile. The **Auto-resolve** toggle lets TunnelCAD guess from the file extension and column count; switch it off to lock a profile manually.
3. Click **Parse**. The preview grid fills, the progress bar advances, and any rows that fail to bind to a section are flagged.
4. Pick the commit policy:

   Replace
   : Existing line data on the bound section is cleared once per (section, line-def) group, then replaced with the parsed points.

   Append
   : Parsed points are appended to whatever the section already holds.

   Skip
   : Sections that already have data for the chosen line def are left alone.

5. Click **Commit**. The activity log records the import as a single project event. See {doc}`/projects/calendar`.

### Snap-to-nearest binding

For XYZ inputs the engine projects each point onto the alignment via `MeasureOffset`. Points are snapped to the nearest configured section, not interpolated -- if your sections are sparse you will see clusters at each chosen station rather than a smooth curve.

## Exporting measurements

Open the workbench from **File > Export Measurements...**.

### Dialog options

File / folder
: Choose an output file. When multiple line definitions are selected the field is treated as a folder and each line is written to its own file (`<basename>_<linename>.<ext>`).

Profile
: Pick from the ASCII profiles. The LandXML profile is hidden here -- use **File > Export LandXML...** instead.

Line definitions
: Checklist of line defs on the active alignment. Each selected entry produces one file.

Station range
: Optional from / to limits.

Header
: Optional first line containing the column names plus the line definition name.

Preview
: Live preview memo showing what the first rows will look like with the chosen profile.

### Notes

- Bulges (arc tangent values) are not part of the cross-section .tun storage and are therefore not written.
- The progress bar advances per section; the dialog auto-closes on success.
- The activity log records the export as a single project event.

## Round-trip

The export side writes files that the import side can read. A common workflow is to export current measurements, edit in a spreadsheet, then re-import with the **Replace** policy to overwrite the original data.