OMRAT – Open Maritime Risk Analysis Tool

OMRAT is a QGIS plugin that calculates how often ships in a waterway are expected to run aground, collide with structures, or collide with each other. It implements the IWRAP methodology (Friis-Hansen 2008, Pedersen 1995) as an open-source tool, so the result is comparable with the IALA reference implementation but everything happens inside QGIS.

Given a shipping route, traffic volume per ship type, a bathymetry layer, and a list of structures, OMRAT returns expected accidents per year for each of the main accident types:

• Drifting grounding / allision / anchoring – ships that lose propulsion and drift into shallow water, a structure, or anchor successfully.

• Powered grounding / allision – ships under power that fail to turn at a bend and continue straight into an obstacle.

• Ship-ship collisions – head-on, overtaking, crossing, and bend collisions.

Three ways to read this documentation

Pick the path that fits what you’re trying to do.

I want to…	Read
run OMRAT for the first time on the supplied example project	Quickstart
learn what each tab of the plugin does	User Guide
understand what the risk numbers mean	Theory (what is calculated), then Drifting Risk Calculations / Ship-Ship Collision Calculations / Powered Grounding and Allision
understand how the calculation is implemented (function by function, call tree)	Code Flow: From “Run Model” to Results, then the per-accident chapters Code Flow: Drifting Model / Code Flow: Ship-Ship Collision Model / Code Flow: Powered Grounding & Allision (Cat II)
look up a specific field in the .omrat JSON file or the data dict passed to the calculation	.omrat data format

The two-track philosophy

Every accident type has two chapters:

• A theory chapter (Track 1) explaining what the calculation measures, deriving the formulas, and listing the assumptions. Read this if you’re an analyst interpreting a result or comparing against IWRAP.

• A code-flow chapter (Track 2) walking the actual function calls that happen when Run Model is pressed. Read this if you’re a developer tracing an output back to the code that produced it, or extending / reviewing the calculation.

The two tracks deliberately overlap so you can start reading in one and cross over to the other without getting lost.

Contents

Getting Started

• Project Overview
  • What OMRAT does
  • Who OMRAT is for
  • The methodology in one paragraph
  • Background and funding
  • What’s next
• Installation
  • Prerequisites
  • Installing the Plugin (recommended)
  • Manual dependency install (fallback)
  • Verifying the Installation
• Quickstart
  • Before you start
  • 1. Open the plugin
  • 2. Load the example project
  • 3. Sanity-check each tab (30 seconds)
  • 4. Run the model
  • 5. Inspect the map result layers
  • 6. Where to read next
  • Troubleshooting
• Quickstart - from scratch
  • 1. Open the plugin (no project loaded)
  • 2. Place legs on the map
  • 3. Bring in depth data
  • 4. Define obstacles (objects)
  • 5. Settings: drift, ship categories, causation, AIS
  • 6. Run the model
  • 7. Inspect the results

Using OMRAT

• Concepts
  • Route, segment, leg
  • Direction
  • Traffic cell
  • Wind rose
  • Drift corridor
  • Obstacle shadow
  • Probability hole (\(h_X\))
  • Repair-time distribution and \(P_{NR}\)
  • Anchoring
  • Causation factor
  • Category I vs Category II (powered)
  • Lateral distribution
  • Standard nautical compass convention
  • The data dict
  • Run Model vs Run Analysis
• User Guide
  • The dock widget
  • Route tab
  • Traffic tab
  • Depths tab
  • Objects tab
  • Distributions tab
  • Drift Analysis tab
  • Results tab
  • Settings menu
  • File menu
  • Run history (Previous runs)
  • Tips and best practices
• Workflows
  • Build a project from scratch (no AIS)
  • Build a project from AIS
  • Import an existing IWRAP XML
  • Export for use in IWRAP
  • Inspect the dominant obstacle on a risk number
  • Debug why a number looks wrong
  • Speed up a slow calculation
  • Reproduce an old result
  • Run a calculation without the QGIS UI (headless)
  • Compare two result sets

Theory (what is calculated)

• Theory (what is calculated)
  • The IWRAP framework in one equation
  • Default causation factors
  • Lateral traffic distribution
  • Coordinate systems
  • Compass convention
  • References
• Drifting Risk Calculations
  • Overview of the Drifting Model
  • run analysis vs run model
  • Common Parameters Used in the Examples
  • Exposure Base
  • Repair Time and \(P_{NR}\)
  • The Probability “Hole” \(h_X\)
  • Directional Distance to an Obstacle
  • Level 1 — Single Polygon, Single Ship, Single Leg
  • Level 1b — Distance from the Leg Centreline vs the Distribution Centre
  • Level 2 — Two Legs, Multiple Ship Categories
  • Level 3 — Blocking Polygon (Shadow Coverage)
  • Level 4 — Anchoring
  • Level 5 — Complete Cascade
  • Shadow Algorithm (Quad-Sweep)
  • Drift Corridor Visualisation (run analysis only)
  • Pipeline and Source Code Pointers
  • Summary
• Ship-Ship Collision Calculations
  • Overview
  • Head-On Collisions
  • Overtaking Collisions
  • Crossing Collisions
  • Bend Collisions
  • Calculation Workflow
  • Summary of Equations
• Powered Grounding and Allision
  • Overview
  • Category I: Direct Overlap
  • Category II: Missed Turn at Bend
  • Shadow-Aware Ray Casting
  • Draft Filtering for Grounding
  • Computation Pipeline
  • Visualization
  • Combined Powered Risk
  • Comparison with Drifting Risk
  • Causation Factor Summary

Code Flow (how it is calculated)

• Code Flow: From “Run Model” to Results
  • Reading map
  • Entry point: the “Run Model” button
  • Background orchestration: CalculationTask
  • Where the inputs come from
  • The Calculation facade
  • Completion and UI fan-out
• Code Flow: Drifting Model
  • Entry point
  • Top-level call tree
  • _build_transformed(): lat/lon -> UTM
  • _compute_reach_distance()
  • Depth merging (optional)
  • Phase 1: _precompute_spatial() (spatial, 0–40 %)
  • Phase 2: _precompute_shadow_layer() (shadow, 0–50 %)
  • Phase 3: _precompute_bucket_memo() (shadow, 50–100 %)
  • Phase 4: _iterate_traffic_and_sum() (cascade, 60–90 %)
  • Completion (layers, 90–100 %)
  • Function reference
  • Debug trace
• Code Flow: Ship-Ship Collision Model
  • Entry point
  • Top-level call tree
  • Data pulled from data
  • run_ship_collision_model(): orchestrator
  • Shared helpers
  • _calc_head_on_collisions()
  • _calc_overtaking_collisions()
  • _calc_bend_collisions()
  • _calc_crossing_collisions()
  • The pure-math helpers
  • Output
  • Function reference
• Code Flow: Powered Grounding & Allision (Cat II)
  • Entry points
  • Top-level call tree
  • Shared inputs
  • Projection: SimpleProjector
  • run_powered_grounding_model()
  • run_powered_allision_model()
  • _build_legs_and_obstacles()
  • _run_all_computations()
  • _compute_cat2_with_shadows()
  • _extract_edges_local()
  • Output: the traffic accumulation loop
  • Interactive visualiser
  • Function reference

Reference

• .omrat data format
  • Top-level layout
  • pc – causation factors
  • drift – drifting model parameters
  • traffic_data – traffic matrix per leg/direction
  • segment_data – per-leg geometry and parameters
  • depths – bathymetry polygons
  • objects – structure polygons
  • ship_categories – type + LOA bin definitions
  • Output keys (round-tripped, not inputs)
  • Optional / developer-only flags
  • Run history: master DB + per-run GeoPackages
  • Minimal valid project (synthetic)
• Code Architecture
  • Directory Structure
  • Data Flow
  • Key Classes
  • Data Structures
  • Background Task Execution
  • IWRAP Integration
  • Project Persistence
• API Reference
  • compute.basic_equations
  • compute.run_calculations
  • geometries.drift
  • geometries.calculate_probability_holes
  • geometries.result_layers
  • omrat_utils

Indices

• Index

• Module Index

• Search Page

Citing OMRAT

If you use OMRAT in a publication, please cite the project repository (https://github.com/axelande/OMRAT) together with the IWRAP references it implements (Friis-Hansen 2008, Pedersen 1995). A full bibliography is at the bottom of Theory (what is calculated).