Inside the Engine | ArgoRoute

Building the World

Written in Rust. Every decision about what is water, how deep it is and where that number came from is made at build time, so the server never touches a raster or a shapefile.

Coastline is the judge

OpenStreetMap land polygons decide what is water and what is land, at vector precision. A hexagon survives only if it touches no land at all — the finer the cell, the closer it hugs the shore.
The cascade

Each H3 cell is tested before its seven children are. Open ocean stops at resolution 3; coasts refine to resolution 10; 35 named passages carry their own leaf resolution, down to 13 for the Panama locks and the Corinth Canal.
Hazards close water

1.60 million hazard polygons and 1.25 million hazard lines from OSM seamarks are merged into the land index; historic and non-dangerous wrecks stay out of it but are still reported along the route. A charted rock closes its whole leaf cell — about 130 m — which is the safe direction to err.
Depth from GEBCO

Every surviving cell takes the GEBCO 2026 pixel at its centre. A coarse open-water cell exists only where every pixel beneath it is deeper than 20 m, so it cannot hide a shoal. Depths are never averaged: a vessel runs aground at one point, not on average.
Published depths where the raster lies

A 464 m pixel over a 200 m canal reads the banks, not the water. Inside declared corridors and along fairway centre lines the canal or port authority's published depth replaces the dirty sample — Suez 20.1 m, Panama 15.2 m, Kiel 9.5 m, Corinth 7.3 m.
Bridge repair and provenance

Basins the raster sealed off from the sea are reopened with an estimated depth taken from the water on either side, and every cell records its origin: surveyed, baseline, canal, bridged, river, track-observed. Three million nodes were opened this way — and each one says so.

🗄️

One File, Memory-Mapped

The planet graph is a single 16.7 GB file: a sorted array of H3 indexes doubles as coordinate store and spatial index, so finding the nearest cell is a binary search and no decoding happens on open. The server's own memory footprint is around 29 MiB; everything else is the operating system's page cache.

⚓

Ports Are Part of the Graph

18,740 harbours and terminals are read at build time and 10,148 of them are linked to navigable water inside the graph. Commercial profiles snap to the nearest port automatically, so a container ship never plans a departure from a beach.

Routing Across It

Three strategies, chosen by geometry, so that the short answer is instant and the long one is still right.

📐

Line of Sight

If the straight line between two pins crosses no coastline and keeps the requested shore clearance, the route is a two-point great circle that never touches the graph. Open-water queries cost nothing.

⭐

A* With a Budget

Per-query state lives in 16 KiB pages allocated on demand, so a search's footprint follows what it explores, not the size of the planet. A search that exceeds 10 million nodes is refused rather than served slowly.

🌐

Hierarchical Overlay

The coarse ocean layer is only 87,347 cells. Routes of 2,500 nm and more are assembled from a 16 MB overlay that stores the fine path between every pair of coarse cells, then searched only from each pin outward. Routability on 400 random port pairs went from 64 % to 98 %.

Measured on the planet graph: a canal transit in 0.11 s, a coastal hop in 0.3 s, a 2,000 nm ocean leg in about 3 s. Rotterdam to Singapore through Suez: 8,887 nm; the same vessel one metre deeper goes round the Cape at 12,585 nm — because the graph, not a rule, says the canal is too shallow.

A pin on land routes from the nearest coast and flags the walk as a land leg, so a tap anywhere on a Mediterranean island works; a pin more than 50 nm from navigable water is refused. A pin in water whose cell is too shallow for the draught snaps to water the vessel can actually leave — a deep pocket ringed by shoals is not a departure point.

How the Engine Thinks

The open sea is the easy part. Canals, fjords, harbour approaches and the neck of a bay are where a world map of depths is at its worst — and where a boat is most likely to touch bottom. Here is how ArgoRoute reasons about those places, told the way you would explain it in a classroom.

👥

Lesson 1 · Two witnesses

Imagine two witnesses describing the same coast. The first walked every metre of the shoreline with a pen and drew exactly where the water begins — but never put a foot in it. That is the coastline map. The second flew over the whole planet with a blurry camera, and can tell you roughly how deep the water is everywhere — but each picture covers five football pitches. That is the depth grid.

The engine's first rule: when the two disagree about whether there is water, believe the walker. When they agree there is water, ask the camera how deep.

📷

Lesson 2 · The blurry photograph

Now point that camera at the Verige strait in the Bay of Kotor: 340 m of water between two steep hills. One blurry pixel covers the hill on the left, the water, and the hill on the right, and reports the average — 95 m of solid rock, where a ferry sails every hour. The same thing happens to every canal, every fjord, every river mouth narrower than a pixel.

So the second rule: a depth from a pixel that also touched land is a contaminated number. It is like measuring the height of a class by averaging the pupils with the teacher. We keep the number, but we mark it as "sampled across the shore" and we never let it decide a passage on its own.

🪧

Lesson 3 · Read the sign at the gate

Every big canal has a sign at the entrance: "maximum draught 20.1 m" at Suez, 15.2 m at Panama, 9.5 m at Kiel, 7.3 m at Corinth. Ports publish the depth of their dredged channel the same way. Where the walker says "water" and the camera says "rock", we do not guess — we copy the sign. And where there is no sign, the passage honestly claims no depth at all.

🔍

Lesson 4 · Zoom in until you find the water

For the places we know are hard — 35 canals, straits and approaches — we tell the engine: keep zooming. Where the map would normally stop at cells 130 m wide, inside a declared passage it keeps dividing each cell into seven smaller ones, down to seven metres in the Panama locks, until the thin ribbon of water the walker drew actually appears in the mesh. Precision is spent only where the water is narrow.

🧵

Lesson 5 · A thread across the lake

Sometimes the camera is wrong the other way round. The Great Bitter Lake, in the middle of the Suez Canal, is a wide, shallow lake with a 24 m channel dredged across it. The pixels there are clean water, so the engine trusted them — and the deep channel became a pocket nothing above 2 m could leave. For those places we trace the channel's centre line from a real transit and lay the published depth along it like a thread, without touching the shallows either side.

🚪

Lesson 6 · A door in the wall, with a sign on it

Picture a bay whose only entrance is a narrow neck the blurry camera painted as land. The bay is on the map, but no road leads to it; thousands of bays and lagoons were cut off like this by a single bad pixel. After the build the engine looks for every such sealed basin, walks along its wall to the thinnest spot, checks that there is proper water on both sides, and opens a door. Then it hangs a sign on the door: depth estimated from the water either side — nobody measured it. Go through on sonar, or not at all.

⛵

Lesson 7 · A wake proves a way, not a depth

The depth grid also remembers where a ship once passed with its echo sounder running. A wake like that proves there is a way through. It does not tell us how big the ship was — it may have been a survey launch drawing a metre and a half. So a wake can settle that a passage exists, and never that your keel will clear it. The route tells you which cells rest on a wake alone.

📝

Lesson 8 · The exam

A fix in one place can break another far away — a corridor added at Hamburg once severed the Kiel Canal, forty kilometres off. So every new build sits an exam: nineteen passages it must route, a baseline of ports it must still reach, and a list of places it must not connect, like the Caspian Sea. A build that scores lower than the last one does not ship, however good the change looked.

The rules we never break. We do not invent a depth where nobody has published or measured one. We do not reopen water that a charted rock or wreck has closed. We do not sharpen the open ocean to make a guessed depth look precise. We go up a river only as far as sea-going ships go — the Elbe to Hamburg, the Mississippi to New Orleans — and not the Danube or the Rhine. And we never hide a repaired passage behind an average: a route is graded by its weakest cell, and that cell tells you what it is.

Named Passages

Where a global raster cannot see the water, human engineering knowledge fills in. Each passage carries its own grid resolution and, where one is published, the authority's maximum draught.

ArgoRoute isobaths through the Strait of Messina between Sicily and Calabria, showing the deep channel and the shallow harbour of Messina — The Strait of Messina, one of the named passages, meshed at resolution 10. The harbour reads red for a 2 m draught; the strait itself drops past 100 m within a mile of shore.

Type	Passages	Published max draught
Canals	Suez, Panama, Kiel, Corinth, Cape Cod, Chesapeake–Delaware, Welland	Suez 20.1 m · Panama 15.2 m · Chesapeake–Delaware 10.7 m · Cape Cod 9.8 m · Kiel 9.5 m · Welland 8.1 m · Corinth 7.3 m
Straits	Bosphorus, Dardanelles, Malacca, Singapore, Messina, Dover, Klaipėda	Natural depth from the grid; Klaipėda 14.3 m
River and estuary approaches	Rotterdam, Antwerp, Hamburg, Bremerhaven, London, New Orleans, Portland, Savannah, Houston, Buenos Aires, Shanghai, Ho Chi Minh City, Bangkok, Shantou, Modaomen	Rotterdam 14.5 m · Savannah 14.3 m · Houston 13.7 m · New Orleans 13.7 m · Hamburg 13.5 m · Antwerp 13.1 m · London 11.0 m · Bangkok 8.5 m
Harbours and archipelagos	Boston inner harbour, Stockholm inner archipelago, Ningbo-Zhoushan, Teluk Kalabahi, Teluk Ambon	Ningbo 22.5 m · Boston 12.2 m
Fairways	Centre lines with their own depth and no corridor box: Suez, Panama (Limón Bay and Balboa), Houston, Limfjord, Curonian Lagoon	Limfjord 4.0 m · Curonian Lagoon 2.1 m

Canal limits are transcribed from the authorities and floored to the metre, not measured. Beam is not modelled yet — at Corinth, beam is the binding limit. Check the current notice to mariners before a commercial transit.

The Same Graph as a Map

A separate tile service extracts three arrays from the graph — cell, depth, origin — into a 1 GB read-only file and serves Mapbox Vector Tiles from it: 72 million cells pre-aggregated per zoom, always keeping the shallowest sample. Depth areas and isobaths are contoured per tile with a minimum filter, so a lone shoal survives the smoothing.

Tiles are immutable per graph build and carry the build in their URL, so a CDN can cache them for a year and a new build reaches the apps by itself. Measured on one CPU: about 6,900 tiles per second, 0.1 to 10 KB each.