# Coordinate and Measurement Conventions

This page documents the sign conventions, coordinate systems, and units used throughout TunnelCAD.

## Coordinate Systems

### World Coordinates

TunnelCAD uses a standard surveying coordinate system:

- **Northing** = Y axis
- **Easting** = X axis
- **Elevation** = Z axis

The Alignment canvas tab displays data in world coordinates.

### Section Local Coordinates

Cross-sections are displayed in a local coordinate system relative to the alignment axis at that station:

- **X** = horizontal offset from the alignment axis
- **Y** = elevation

## Offset Convention

Offsets are measured perpendicular to the alignment, looking in the direction of increasing chainage:

- **Positive (+)** = right of the alignment axis
- **Negative (-)** = left of the alignment axis

This convention applies to all offset values in section data, template definitions, and setout calculations.

## Angular Conventions

ALM arc/spiral sign
: **Positive (+)** = right turn (clockwise). **Negative (-)** = left turn (counter-clockwise).

Bearing display
: Bearings shown in the interface use the surveying convention, converted from the internal math angle via: `surveying bearing = Pi/2 - math angle`.

## Gradient

Gradient values are stored and displayed in **percent (%)**. The value read from the alignment engine is already in percent -- it must not be multiplied by 100 again.

## Deviation Radial (DR)

The deviation radial is the difference between the measured section and the design template at a given angular position:

- **Positive DR** = overbreak (the measured point is outside the template envelope)
- **Negative DR** = underbreak (the measured point is inside the template envelope)

DR text labels use a default height of **0.15 m** in model units.

## Section Point Ordering

Section points are ordered **clockwise** starting from the bottom (negative Y axis direction) after radial sorting around the section center.

## Template Bulge

Template line segments may include an arc defined by a bulge value:

- **Positive bulge** = arc bulging to the left
- **Negative bulge** = arc bulging to the right

```{note}
When constructing templates programmatically, the bulge value must be set after adding the end point of the segment, because the bulge array requires at least two points to exist.
```

## Elevation in Setout Calculations

Two related but distinct elevation values appear in setout offset data:

Elevation
: The elevation of the alignment offset axis at the section station. This value is constant for a given station regardless of lateral position.

PointHeight
: The actual elevation at a specific lateral offset, which varies according to superelevation (cross-fall) applied at that station.