# Quick Start Tutorial

This tutorial walks you through creating a basic tunnel monitoring project from scratch. By the end you will have a project with an alignment, design templates, measured cross-sections, and volume results.

## 1. Launch TunnelCAD

Run the `TunnelCAD` executable. On first launch the application creates a default settings file and opens with an empty workspace.

## 2. Create a new project

Go to **File > New Project** (or press **Ctrl+N**). A new project tab appears in the workspace with the name "Untitled".

## 3. Add a tunnel

Go to **Tunnel > Add Tunnel**. In the dialog that appears, enter:

- **Name** -- a descriptive name for the tunnel (e.g., "Main Bore")
- **Start Chainage** -- the starting station of the tunnel (e.g., 0.000)
- **End Chainage** -- the ending station (e.g., 500.000)

Click **OK**. The tunnel appears in the project tree on the left.

```{tip}
You can import an existing horizontal and vertical alignment from an `.alm` file via **Tunnel > Import Geometry**. This defines the 3D centreline of the tunnel.
```

## 4. Define line definitions

Line definitions describe the types of measured data lines you will use (e.g., "Excavation", "Final Lining", "Shotcrete"). Each line definition has a name and a display style (color, linetype, weight).

1. Go to **File > Settings** (or click the **Settings** button) to open the Tunnel Settings dialog.
2. Navigate to the **Line Definitions** section.
3. Add entries for each type of measured line your project requires.
4. Assign a color and linetype to each so they are visually distinct on the canvas.

```{note}
Line definitions are per-tunnel. If your project has multiple tunnels, define them for each one.
```

## 5. Define template line definitions

Template line definitions work the same way as measured-line definitions, but they describe the lines used in design templates (e.g., "Design Profile", "Clearance Envelope").

Configure these in the same Tunnel Settings dialog under the **Template Line Definitions** section.

## 6. Create a design template

A template defines the theoretical cross-section shape of the tunnel at a given location. Templates are made up of template lines, each referencing a template line definition.

1. Go to **Template > Edit Templates** (or click the **Assign** button on the ribbon).
2. In the Template Editor, click **Add** to create a new template.
3. Draw the design profile by adding points. For arcs, set the bulge value on the relevant segment.
4. Assign each line segment to a template line definition.

```{warning}
When defining arcs, always add the end point first, then set the bulge value on that segment. The bulge array requires at least two points to be present.
```

## 7. Assign templates to station ranges

Templates are applied to specific chainage ranges via station definitions. This tells TunnelCAD which design profile to use at each cross-section location.

In the Template Editor, use the **Station Definitions** panel to assign your template to a start and end chainage. You can assign different templates to different ranges along the tunnel.

## 8. Add cross-sections

Cross-sections represent the measured tunnel profile at a specific station.

1. Click **Add** on the **Section** pane of the ribbon.
2. In the Add Section dialog, choose:
   - **Single** mode to add one section at a specified station, or
   - **Range** mode to add sections at regular intervals over a chainage range.
3. Enter the station chainage and section name.
4. Click **OK**.

The new section appears in the Sections canvas showing the assigned template overlay.

## 9. Import measured data

You have several options for getting measured data into your sections:

- **LandXML import** -- go to **File > Import LandXML** to import cross-section data from a LandXML 1.2 or 2.0 file.
- **DXF import** -- import measured profiles from DXF template files.
- **Point cloud extraction** -- load a point cloud via **Point Cloud > Import**, then use the Section Viewer to extract profiles at each station.
- **Manual entry** -- add individual points directly on the Sections canvas.

```{tip}
When importing from LandXML, TunnelCAD auto-detects the schema version (1.2 or 2.0) and maps cross-section offset/elevation data to the correct line definitions.
```

## 10. Review deviation analysis

Switch to the **Sections** canvas tab. The current cross-section displays measured lines overlaid on the design template. Deviations between measured and design profiles are immediately visible.

Use the ribbon **Prev**/**Next** buttons to step through sections and review each station. The **Section Details** tab on the right panel shows numerical data including bearing, elevation, gradient, and offsets.

Section Edit tools on the ribbon help clean up measured data:

- **Sort** reorders points within each line
- **Filter Elev** removes outlier points by elevation
- **Filter DR** removes points exceeding a deviation threshold
- **Closed** / **Close to Lvl** / **Close Invert** help close open profiles for accurate area calculations

## 11. Define volumes

Volume definitions pair a measured line with a template line to compute overbreak, underbreak, or material quantities between them.

1. Go to the **Volume** menu or expand the **Volumes** node in the project tree.
2. Open the Volume Editor to create a new volume definition.
3. Select the measured line (e.g., "Excavation") and the template line (e.g., "Design Profile").
4. Choose the calculation type (overbreak, underbreak, or a custom formula).

## 12. View the mass table

After defining volumes, compute results and view them in the mass table:

1. Click **Compute** to calculate volumes across all sections.
2. Open the **Mass Table** to see a tabulated summary of areas and volumes for each section interval.
3. Export results to CSV or spreadsheet format for reporting.

```{note}
Volume calculations use the area between measured and template polylines at each section, then integrate along the alignment between stations. Results are displayed in the project's configured units.
```

## 13. Save the project

Go to **File > Save** (or press **Ctrl+S**) to save the project as a `.tun` file. TunnelCAD uses an XML-based format that stores all alignment data, templates, sections, volume definitions, and style libraries in a single file.

If this is a new project, you will be prompted to choose a file name and location.

```{tip}
TunnelCAD tracks unsaved changes and will prompt you to save when closing a project or exiting the application. Look for the `*` in the title bar to see if there are pending changes.
```

## Next steps

With the basics covered, explore these areas to get more from TunnelCAD:

- **[Templates](../templates/index.md)** -- advanced template design with arcs, multi-line profiles, and superelevation
- **[Volumes](../volumes/index.md)** -- custom volume formulas, volume reports, and mass table export
- **[Point Cloud](../point-cloud/index.md)** -- importing scan data and extracting cross-sections
- **[Analytics](../analytics/index.md)** -- quality grading, clearance reports, and statistical analysis
- **[Import/Export](../import-export/index.md)** -- LandXML workflows, DXF templates, and legacy TCM conversion