# Quickstart

This chapter walks you from fresh install to a first calculated risk number on the supplied example project in under ten minutes. It is deliberately thin: it only shows the clicks needed to produce a result. Every concept used here (leg, obstacle, traffic cell, drift corridor, causation factor, …) is defined in Concepts, and every tab is documented in detail in User Guide.

Note

This quickstart uses the bundled example project, which already has its traffic matrix populated – you can produce a risk number without an AIS database at all. If you want to run OMRAT against your own route, you’ll either fill in the Traffic tab by hand or pull live counts from a PostGIS AIS database. The end-to-end guide to standing up that database – schema, raw-NMEA / CSV ingestion, vessel-lookup table, and the Update AIS button – is Database setup and AIS ingestion. Read it before you start a real project.

## Before you start

You need:

- QGIS 3.30 or newer (see Installation).

- OMRAT installed via the Plugin Manager. On first run the `qpip` plugin will offer to install the Python dependencies – accept it.

- The example project `tests/example_data/proj.omrat` shipped with the source repository. If you installed from source, the file is already in your clone. If you installed via the Plugin Manager, download `proj.omrat` from https://github.com/axelande/OMRAT/tree/main/tests/example_data.

## 1. Open the plugin

Click the OMRAT icon in the QGIS toolbar. The dock widget docks on the right side of the window.

The OMRAT icon in the QGIS plugins toolbar.

OMRAT’s dock widget. All the plugin’s tabs live here.

## 2. Load the example project

In the dock widget:

1. File -> Load.

2. Select `proj.omrat` from wherever you placed the example file.

3. When asked Clear & Load or Merge, choose Clear & Load.

The map canvas shows the example shipping route with two legs, the depth polygons, and the two structure polygons.

Loaded project: blue route legs on the map, depth polygons in greens/blues, structure polygons in orange.

## 3. Sanity-check each tab (30 seconds)

Open each tab in the dock widget and scan the fields. You do not need to change anything. What to look for:

Tab | What should be there
--- | ---
Route | Four segments (`1`, `2`, `3`, `4`) with `Start_Point` / `End_Point` filled in.
Traffic | For each segment and direction, non-zero numbers in the Frequency, Speed, Draught, Height rows (21 ship types x 15 LOA bins).
Depths | 17 rows, each with a depth value and a polygon WKT.
Objects | 2 rows, each with a height value and a polygon WKT.
Distributions | A PDF plot showing the combined lateral distribution. The curve should be centred near zero with reasonable spread.
Drift Analysis | Empty until you run the model.
Results | Empty until you run the model.

## 4. Run the model

Go to the Results tab and click Run Model.

The “Run Model” button on the Results tab.

A notification appears in the QGIS message bar saying the calculation has started in the background. Progress is shown in the QGIS task manager tray (bottom of the QGIS window). Four phases run in order:

1. Drifting model (largest, typically 60–80 % of total time)

2. Ship-ship collisions

3. Powered grounding

4. Powered allision

The QGIS task tray shows percent complete and the current phase.

When the run finishes, the Results tab fills in with probability numbers (expected accidents per year).

Results tab after the run. Each line-edit shows the expected annual frequency for that accident type, in scientific notation (e.g. `1.148e-01`).

## 5. Inspect the map result layers

After a run, OMRAT writes a per-run GeoPackage to your output folder and lists the run on the Run Analysis tab. Click Add results to map on that row to overlay every non-empty result layer on the canvas:

Layer | Geometry | What it shows
--- | --- | ---
Drifting Allision Results | Polygon | Each structure polygon, coloured by its share of the total drifting-allision probability.
Drifting Grounding Results | Polygon | Each depth polygon (or merged depth band), coloured by its share of the total drifting-grounding probability.
Powered Allision Results | Polygon | Each structure, coloured by its share of the powered Cat II allision probability (failure-to-turn-at-bend hits).
Powered Grounding Results | Polygon | Each depth polygon, coloured by its share of the powered Cat II grounding probability.
Ship-Ship Collision (per leg) | Line | One line per route leg, coloured by the head-on + overtaking collision probability for that leg.
Ship-Ship Collision (waypoints) | Point | One point at every shared waypoint, coloured by the crossing + bend collision probability there.

All layers share the same green -> yellow -> red graduated ramp: green = lowest contributor, red = the hotspots that dominate the total. A layer only appears when the corresponding probability total is non-zero, so a clean canvas means a clean risk picture for that accident type.

A finished run with several layer types visible at once: red structure polygons (high drifting-allision contribution), red / yellow line segments along the legs (head-on + overtaking collisions), a red waypoint (crossing/bend collision hotspot), and green polygons / points where the contribution is small.

Click any feature to open the attribute table – every result layer carries a per-leg breakdown (`leg_1`, `leg_2`, …) so you can trace which leg drove the colour.

## 6. Where to read next

You now have a working run. From here:

- Want to understand the numbers? -> Theory (what is calculated) for the big picture, Drifting Risk Calculations for a worked example.

- Want to run OMRAT on your own data? -> User Guide walks every tab.

- Want a glossary of terms? -> Concepts.

- Want to know what the code did under the hood? -> Code Flow: From “Run Model” to Results.

## Troubleshooting

The Run Model button does nothing.

  Check that the Route, Traffic, Depths, and Objects tabs all have data – an empty traffic matrix short-circuits the calculation to zero.

All result values are zero.

  Same cause as above, plus check Settings -> Drift Settings: if `drift_p` (blackout rate) is zero, drifting risk is zero.

The calculation runs for more than 10 minutes on the example.

  That is much longer than expected (a few minutes on a modern laptop). Open View -> Panels -> Log Messages Panel -> OMRAT and look for warnings. If shapely is missing, qpip’s first-run install may not have completed – see Manual dependency install (fallback).

I want to interrupt the run.

  Click the cancel button next to the OMRAT task in the QGIS task tray. The next progress-callback check will abort the calculation.