# TUN File Format Reference

TunnelCAD's native file format is an XML-based format referred to as IQML. Files use the `.tun` extension and are human-readable plain text.

## Document structure

The root element is `<TunnelProject>` with `version` and `name` attributes:

```text
<TunnelProject version="2.0" name="My Project">
  <Units ... />
  <SectionLineStyles>...</SectionLineStyles>
  <AlignmentStyles>...</AlignmentStyles>
  <Tunnels active="...">
    <Tunnel ...>...</Tunnel>
  </Tunnels>
</TunnelProject>
```

### Top-level elements

`<Units>`
: Project-wide unit settings including angular unit mode, coordinate decimal places, and display preferences.

```text
<Units angularUnit="2" coordDecimals="3" ... />
```

`<SectionLineStyles>`
: Shared library of section line display styles. Each style is a `<TSLStyle>` element defining color, line weight, and other visual properties. These styles are shared across all tunnels in the project.

```text
<SectionLineStyles>
  <TSLStyle name="Standard" color="..." lineWidth="..." ... />
</SectionLineStyles>
```

`<AlignmentStyles>`
: Shared library of alignment display styles.

```text
<AlignmentStyles>
  <AlStyle name="Standard" color="..." ... />
</AlignmentStyles>
```

`<Tunnels>`
: Container for all tunnel alignments. The `active` attribute names the currently selected tunnel.

## Tunnel element

Each `<Tunnel>` element is a self-contained tunnel alignment with all its associated data:

```xml
<Tunnel name="Main Tunnel" startChainage="0.000" endChainage="1250.000"
        description="Left bore" styleName="Standard">
  <AlignmentEngine version="1.0">...</AlignmentEngine>
  <LineDefinitions>...</LineDefinitions>
  <TemplateLineDefinitions>...</TemplateLineDefinitions>
  <TunnelTemplates>...</TunnelTemplates>
  <TemplateStationDefs>...</TemplateStationDefs>
  <TunnelSections>...</TunnelSections>
  <VolumeDefinitions/>
  <Umbrellas>...</Umbrellas>
</Tunnel>
```

### Tunnel sub-elements

`<AlignmentEngine>`
: Horizontal and vertical alignment geometry (lines, arcs, spirals, PVIs).

`<LineDefinitions>`
: Definitions of section line types used in this tunnel. Each `<LineDef>` specifies a name, style reference, and behavior.

`<TemplateLineDefinitions>`
: Definitions of template line types. Each `<TmplLineDef>` maps a template line to its display properties.

`<TunnelTemplates>`
: Design profile templates. Each `<Template>` contains point arrays defining the cross-section shape, with optional bulge values for arc segments.

`<TemplateStationDefs>`
: Rules that assign templates to chainage ranges. Each `<StationDef>` specifies which template applies at a given station or range of stations.

`<TunnelSections>`
: Measured cross-section data. Each `<Section>` contains point arrays and bulge arrays for each line in the section.

`<VolumeDefinitions>`
: Volume computation definitions including formula assignments and zone boundaries.

`<Umbrellas>`
: Forepoling umbrellas on this tunnel. Each `<Umbrella>` stores the design inputs only: name, collar chainage, template line, crown window (`fromCrownDeg`, `toCrownDeg`), spacing, radial standoff, pipe length, lookout, diameter, and `decreasingStation` (`1` or `0`). Angles in the file are degrees. Collar and tip coordinates are calculated from the alignment and are not stored. See {doc}`/projects/forepoling`.

## Color serialization

Colors are stored as hexadecimal RGB strings (e.g., `"FF0000"` for red). The special value `clByLayer` (used when a color should inherit from the layer or parent style) is serialized as the string `"ByLayer"` rather than a numeric code.

```{warning}
When editing `.tun` files by hand, always use the string `"ByLayer"` for layer-inherited colors. Writing the numeric sentinel value (`$01000000`) as a hex string will produce `"000000"` (black), making lines invisible on dark backgrounds.
```

## Section data

Each `<Section>` stores its measured and computed lines as arrays of points. Points are recorded as offset and elevation pairs relative to the alignment axis at that station. Arc segments between consecutive points are represented by bulge values in a parallel array.

## Style library behavior

Style libraries (`<SectionLineStyles>` and `<AlignmentStyles>`) live at the project level and are shared by all tunnels. Each tunnel references styles by name. The built-in `"Standard"` style cannot be deleted.

```{tip}
The `.tun` format is plain XML text. You can inspect or diff project files with any text editor or XML tool, which can be useful for troubleshooting or version control.
```