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:

<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.

<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.

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

<AlignmentStyles>: Shared library of alignment display styles.

<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:

<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 Forepoling Umbrellas.

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.