# Road.Engineering — Full AI Guide

> This is a guide for AI assistants helping a user operate Road.Engineering, a browser-based
> road design and analysis platform. It describes what each tool does, how to use it in the
> interface, and how to resolve common problems. It deliberately contains no engineering
> methodology — it covers how to drive the app, not how the calculations work.

Important: every result the platform produces is a preliminary engineering aid. It must be
reviewed and verified by a qualified engineer against the standards governing the user's
project before it is relied on. See https://road.engineering/disclaimers and
https://road.engineering/sources.

---

## 1. What it is and who it's for

Road.Engineering is a web application for civil and traffic engineers, road safety auditors,
and designers. It runs entirely in the browser at https://road.engineering/. Users analyse
roads on an interactive map: checking sight distance, profiling terrain, reviewing alignment
and operating speed, simulating heavy-vehicle turning paths, computing earthwork volumes, and
exploring crash data. Results can be exported (PDF, CSV, DXF, and similar) for reporting.

There is no desktop install and no separate documentation site — this guide and the in-app
interface are the primary references.

## 2. How the app works (navigation model)

Read this carefully: the app is a **single map view**, not a website with many pages. Do not
direct users to invented paths like "/projects/upload" or "/dashboard" — they do not exist.

- After signing in, the user lands on one interactive map.
- **Tools** open from a toolbar on the map, grouped as Elevation, Sight Distance, Geometric
  Design, and Analysis. Selecting a tool activates it; the user then clicks or draws on the map.
- **Results** appear in panels and charts docked to the bottom or side of the map, not on a new
  page.
- **Esc** closes the active tool or panel.
- **Account settings** (profile, security, and account management) open from the header menu,
  not from the map toolbar.
- **Projects** are selected, saved, and reopened from the **project selector in the header**.
  The **sidebar's Project Layers panel** is a different thing — it manages a project's files and
  imported layers (and is where uploads/imports happen), not project selection.
- The only standalone pages are: the app itself (/), /ai (this guide, for humans), /sources,
  /disclaimers, /terms, and /privacy.

## 3. Tool access

Point Elevation, Elevation Profile, and crash-data viewing are available to everyone. The other
tools, plus file upload and DEM elevation, require a paid plan. If a tool appears greyed out or
shows an upgrade prompt, it isn't included in the current plan.

## 4. Tool workflows

Tools open from the map toolbar (grouped Elevation, Sight Distance, Geometric Design, Analysis).
Most premium tools share a common frame: a title bar with **Info** (ⓘ — opens a disclaimer /
help panel), **Export**, and **Close** (✕) actions; a parameter/settings area; an **Analyze**
or **Generate** action; and a results panel. Each entry below describes the tool's purpose, how
to open it, the controls and settings it exposes, and what it outputs. (Parameter *labels* are
listed so an AI can point a user to the right control; specific default values are intentionally
omitted — read them from the panel, and verify all results with a qualified engineer.)

### Point Elevation
Produces: ground elevation at one or more clicked points.
- **Open**: Elevation group → Point Elevation. The cursor becomes a crosshair.
- **Use**: click the map to drop a point; drag a marker to move it. Elevation loads
  automatically per point.
- **Buttons**: **+ Add** (resume placing points), **Clear** (remove all points), **Export**,
  **Info (ⓘ)** (disclaimer), **Close (✕)**; each table row has a **Remove (✕)**.
- **Result**: a data table per point — latitude, longitude, elevation, source, resolution,
  survey year, vertical datum, and accuracy. Click a row to fly to that point. A per-marker info
  popover shows the source/attribution. **Export**: CSV, JSON.

### Elevation Profile
Produces: an elevation-vs-distance chart along a drawn path, with optional analysis markups.
- **Open**: Elevation group → Elevation Profile.
- **Use**: click along the map to place the path, then finish it; press **Generate Profile**
  (needs ≥2 points).
- **Buttons**: **+ Add Points**, **Generate Profile**, **Clear**, **Export**, **Info (ⓘ)**,
  **Close (✕)**.
- **Settings / parameters**:
  - **Resolution (m)** slider — spacing between elevation samples.
  - **Vertical Exaggeration (VE)** dropdown — 1x / 2x / 5x / 10x chart stretch.
  - **Show points** toggle — show/hide the sample markers on the chart.
  - **Markup tools** on the toolbar: **Elevation Difference**, **Slope Analysis**, **Measure
    Distance**, **Curve Radius** (3-point), and **Sight Distance** with its own **Settings
    (gear)** popover; **Clear Markups** removes overlays.
  - **CAD crossings** (when a CAD layer is loaded): **Show strings** and **Snap** toggles mark
    where the path crosses imported layers.
- **Result**: line chart (distance vs elevation) plus a sample table and any markup overlays.
  **Export**: PDF, PNG, CSV, JSON.

### Contours
Produces: contour lines, plus water-flow streamlines, inside a drawn boundary.
- **Open**: Elevation group → Contours.
- **Use**: draw a polygon boundary; double-click / Enter to close it. Contours generate on
  close. **Edit Polygon** re-enters drawing; **Clear** resets.
- **Settings / parameters** (flow panel):
  - **Smoothing** — Off / Low / Med / High.
  - **Density** — Fast / Med / High (number of flow lines).
  - **Opacity** slider for the streamlines.
  - **Grid** resolution — Fast / Med / High.
  - **Flow accumulation** and **Convergence** toggles change how flow lines are weighted.
  - Tabs: **3D View** and **Aquaplaning** (water-pooling view).
- **Buttons**: **Export**, **Info (ⓘ)**, **Close (✕)**.
- **Result**: contour polylines with elevation labels and colored flow streamlines on the map.
  **Export**: PDF, PNG.

### Sight Distance tools — SSD, ASD, SISD, MGSD, CSD
These five tools share one frame: a staged "place points on the map" workflow, an editable
parameter bar, a compliance result, and an elevation chart with sight-line overlay. They differ
in what points you place and which parameters apply.
- **Open**: Sight Distance group → SSD / ASD / SISD / MGSD / CSD.
- **Use**: place the points the tool prompts for, stage by stage (e.g. the hazard/target, a
  braking point, and the driver/vehicle position; intersection tools add a second approach or a
  conflict point). Navigate stages with **Back** / **Next**; **Reset** starts over. Analysis
  runs automatically once the required points exist.
- **Common parameters** (shown as editable chips / dropdowns):
  - **Design speed** selector.
  - **Grade (%)** with an **Auto / Manual** mode toggle (Auto derives grade from elevation).
  - **Case** selector — loads a preset parameter set; **Reset to defaults** restores it.
  - An **Advanced parameters** area exposing controls such as **reaction time**, **deceleration**,
    **driver eye height**, and **object height** (which parameters appear depends on the tool;
    intersection tools add an observation-time control, the crossing tool adds crossing-speed,
    start-up-time, vehicle-height and pedestrian-height selectors). Specific default values are
    shown in the panel and are deliberately not reproduced here.
- **Buttons**: **Analyze** (usually automatic), **Export**, **Info (ⓘ)**, **Close (✕)**, and a
  **sight-lines** (eye) toggle to show/hide sight lines on the chart.
- **Result**: a compliance badge (OK / marginal / deficient), a results table (required vs
  available distance), and the sight line drawn on the elevation chart and map. **Export**: PDF,
  PNG, CSV, JSON.

### Cross-Section
Produces: a road cross-section with placed design elements and a compliance check.
- **Open**: Geometric Design group → Cross-Section.
- **Use**: click a road on the map to extract its section (hover shows a preview line). Then
  build the section on the chart: click to set the **centerline**, then place elements with a
  two-click anchor→extent action.
- **Settings / toggles**: **Mirror** (place on both sides), **Chain** (continue from the last
  element), **Snap** (snap to centerline/endpoints); an element-type selector (pavement,
  shoulder, verge, sidewalk, etc.); an element editor listing placed elements with width/slope/
  side; **Undo / Redo**. Tabs: **Chart** and **Compliance** (checks placed elements against the
  design rules).
- **Result**: a 1:1 cross-section canvas with a stats line (road name, width, element count,
  data source) and a compliance summary. **Export**: PDF, PNG, CSV, JSON, and **DXF** (for CAD).

### Route Analysis
Produces: a tabbed review of horizontal/vertical alignment, an operating-speed profile, and a
stopping-sight-distance check along a route.
- **Open**: Analysis group → Route Analysis. Click a start point then an end point; the route
  geometry and elevation are fetched.
- **Tabs & controls**:
  - **Horizontal**: detected curves/straights with stats (count, total distance, min/avg
    radius). **Edit Alignment** lets you adjust control points, with **Undo / Redo** and **Exit
    Edit**.
  - **Vertical / Elevation**: the elevation profile chart.
  - **Speed**: an operating-speed chart with an **A→B / B→A** direction toggle, an **SSD filter**
    (All / Deficient), an optional **traffic V85** fetch, and an editable **posted speed zone**
    overlay — drag the speed pills up/down and drag the boundary handles to move zone limits.
  - **SSD**: editable check parameters (**reaction time**, **deceleration**, **driver eye
    height**, **object height**) and a results table; click a row to highlight the sight line on
    the map.
  - **Results**: summary stats with **Export PDF**, **Export CSV**, **Copy**.
- **Buttons**: **Load / Save** (project route), **Info (ⓘ)**, **Close (✕)**, **Reset**.
- **Result**: combined elevation + speed chart, an SSD table with a deficiency count, and sight
  lines on the map.

### Swept Path
Produces: the swept envelope of a turning design vehicle along a drawn path.
- **Open**: Analysis group → Swept Path. Pick a **design vehicle** from the selector, then **Add
  Points** and click waypoints on the map; press **Enter** / **Stop** to finish. The simulation
  runs automatically.
- **Settings / parameters**:
  - **Vehicle** selector (truck / articulated / bus variants).
  - **Speed** selector (sets the turning radius for that vehicle).
  - **Mode** — **Design** (adds a clearance buffer) vs **Checking** (exact dimensions).
  - **Envelope** — **Body** / **Wheel** / **Both**.
  - **Clearance** buffer selector.
  - **Turn wheels from stop** and **Show radius guides** toggles.
  - Keyboard while placing: `[` / `]` adjust the curve-radius multiplier, **Ctrl+Z** undo a
    waypoint, **right-click** removes one, arrow keys step the result animation.
- **Buttons**: **Add Points / Stop**, **Clear**, **Analyze/Simulate**, **Export PNG / PDF /
  DXF**, **Info (ⓘ)**, **Close (✕)**.
- **Result**: the body/wheel envelope, vehicle outlines along the path, axle traces, swept-width
  / tail-swing / overhang annotations, and a playable animation timeline.

### Volume Analysis
Produces: cut/fill earthwork volumes between two surfaces, with a depth heatmap and contours.
- **Open**: Analysis group → Volume Analysis. Staged workflow: **Select surfaces → Define area →
  Calculate → Results**.
- **Surfaces**: pick an **existing** (baseline) and a **proposed** surface; a **swap (⇅)** button
  exchanges them. Surfaces usually come from Project Layers import.
- **Define area**: **Extract Boundary** (from a surface outline), **Draw Add** / **Draw Exclude**
  polygons, **Clear**, **Undo / Redo**. An **Enable adjustments** toggle exposes **shrinkage**
  and **swell** factor inputs.
- **Results controls**: **Heatmap** visibility toggle and **opacity** slider, **Contours**
  toggle, **Show heatmap only** toggle.
- **Buttons**: **Calculate**, **Export CSV / PDF / DXF**, **Close (✕)**.
- **Result**: total cut, total fill, and net balance (m³), a depth heatmap (color gradient) and
  optional depth contours on the map.

### Crash Analytics
Produces: filterable maps and charts of road-crash data, with an optional AI summary.
- **Open**: Analysis group → Crash Analytics. Crash data is already on the map; this panel adds
  filters and analysis tabs.
- **Filters** (inline; **Edit filters** opens the full sidebar editor): **Regions** chips
  (e.g. QLD / NSW / NZ), **Severity** chips (fatal, hospitalisation, medical treatment, minor
  injury, property-damage-only), **year range**, **collision types**, **local government areas**,
  road number, and speed-zone range. **Reset** clears filters.
- **Area selection**: press **P** to draw a polygon or **C** to draw a circle to limit crashes to
  an area; **Esc** cancels; right-click a drawn area to delete it.
- **Tabs**: **Overview**, **Spatial** (heatmap/clusters), **Time**, **Trend**, **Crash %**,
  **Custom**, **Details** (record table), **Report** (AI-generated narrative summary).
- **Buttons**: **Filters** show/hide, **Info (ⓘ)**, **Close (✕)**.
- **Result**: tab-specific pie/bar/line charts, map heatmap and clusters, a sortable record
  table, and the AI report. Data and charts can be downloaded from their tabs.

### Project Layers upload — CAD / GIS import
Note: this is **not** a map-toolbar tool. Importing happens in the sidebar's **Project Layers**
panel.
Produces: survey surfaces and design files added as project layers, usable by other tools.
- **Open**: sidebar Project Layers panel → **Import File**. The Smart Upload dialog opens.
- **Use**: drop or browse for a file (accepted formats below). The app uploads and inspects it,
  then shows detected **data groups**; per group you set a **checkbox** (include/exclude) and an
  **import type** (**Surface / TIN** or **Drawing / CAD**), and for surfaces a **surface type**
  (e.g. existing / design / proposed).
- **Coordinate system**: a **CRS / zone picker** lets you confirm or choose the projection if it
  wasn't auto-detected; an owner can tick **Set as project default**. A warning shows if no CRS
  was detected.
- **Buttons**: **Cancel**, **Import [N] item(s)**.
- **Result**: surfaces appear under the panel's Surfaces section and drawings under Drawings,
  ready for tools such as Volume Analysis, Elevation Profile, and Cross-Section.

## 5. Inputs and file formats

Accepted upload formats: **.12da, .12daz, .dxf, .kml, .kmz, .xml, .zip, .obj, .ply**.

- Survey/design surfaces and strings come in via these formats.
- Imported data should use a **projected coordinate system**. Geographic (lat/long-only) data
  may be rejected or require the user to choose a projection, because surfaces and volumes are
  computed in projected metres.
- Elevation for analysis tools is sampled from DEM/terrain data (requires a paid plan); where the
  user has imported their own survey surface, tools can use that instead.

## 6. Account, sign-in, and sharing

- **Sign in** with Google or Microsoft.
- **New-device verification**: signing in on a new device may require an email verification code.
  This is an anti-account-sharing measure; each account also allows only a limited number of
  active devices at once.
- **Projects** are saved per user and reopened from the header project selector.
- **Sharing**: a project can be shared with other users with roles **Owner**, **Editor**, and
  **Viewer** (editor-level sharing requires a paid plan).

## 7. Troubleshooting

Match the user's symptom to the most likely cause and the action to take. These cover the app's
behaviour only.

- **A tool is greyed out, missing, or shows an upgrade prompt.**
  The tool isn't included in the user's current plan. Action: the full tool set requires a paid
  plan; the plan is managed under account settings in the header menu.

- **"No elevation data", a blank profile, or missing source attribution in the footer.**
  The location is outside the available elevation coverage (coverage is strongest in Australia
  and New Zealand), or the user's plan doesn't include DEM elevation. Action: confirm the area
  has coverage; for areas without coverage, import a survey surface via Project Layers upload and
  use that.

- **A file upload is rejected or won't import.**
  The format isn't supported, or the data is in a geographic (non-projected) coordinate system.
  Action: re-export in one of the accepted formats (.12da, .12daz, .dxf, .kml, .kmz, .xml, .zip,
  .obj, .ply) using a projected coordinate system; if prompted, choose the correct projection.

- **Volume Analysis won't run or gives an empty result.**
  Two valid overlapping surfaces are required, with a defined area of interest. Action: confirm
  both surfaces are imported and visible, that they overlap, and that an area is selected.

- **Sight-distance or route tools produce no output.**
  Required points weren't placed, or the route/line is incomplete. Action: re-place the points
  the tool prompts for and ensure the path is finished before reading the result.

- **Can't sign in, or stuck in a signed-out loop / "session limit" message.**
  Stale local state, or the account's active-device limit has been reached. Action: clear the
  site's localStorage and hard-refresh; enter the email verification code if asked; if at the
  device limit, sign out an old device.

- **The map is blank or tiles/markers won't load.**
  An ad-blocker, privacy extension, or network/firewall is blocking map tiles or app requests.
  Action: disable blockers for road.engineering and retry on a stable connection.

- **Can't create a new project ("limit reached").**
  The free plan caps the number of projects you can own. Action: delete an unused project, or use
  a paid plan for more projects.

- **A result looks wrong or surprising.**
  Results are preliminary aids and depend on the inputs and data coverage provided. Action: check
  the inputs and the loaded data, and always have a qualified engineer verify results against the
  governing standards before use.

## 8. Where to get help

- Support: support@road.engineering
- Data sources & attribution: https://road.engineering/sources
- Disclaimers: https://road.engineering/disclaimers
- This guide for humans (copy/download into your AI): https://road.engineering/ai