DEV Community

tgscope
tgscope

Posted on

Drawing 150 countries and 152 street maps on one canvas without freezing the page

We at TGscope built a world map of Telegram channels: 278,975 channels tied to 150 countries, and 152 cities drawn with roads, water and district borders. You can zoom from the whole planet down to a street in one motion.

There is no map library under it. Channels are points in a small WebGL engine, and everything under them (land, borders, cities) is plain Canvas 2D. This post is about that second part, because it is where all the interesting problems were.

Problem 1: the outline of the world is heavy

Country outlines come from Natural Earth at 1:10m. After topological simplification, so that a shared border is simplified once and the fill of a country meets its border line point for point, the file is still big.

Two things made it shippable.

Delta-encoded integers. Coordinates are stored as integers with a step of 1e-6 map units, and every point is the difference from the previous one. Small numbers compress well: the file is about 2.9 MB raw and 1.15 MB gzipped. Decoding is a running sum:

function decode(line, q) {
  const n = line.length;
  const out = new Float64Array(n);
  let x = 0;
  let y = 0;
  for (let i = 0; i < n; i += 2) {
    x += line[i];
    y += line[i + 1];
    out[i] = x * q;
    out[i + 1] = y * q;
  }
  return out;
}
Enter fullscreen mode Exit fullscreen mode

Levels of detail. The worker keeps six copies of the outlines, simplified with growing tolerance, and picks one by the current scale. At world zoom it draws a copy with a fraction of the points, and a frame takes 2 to 4 ms. For huge rings like Russia or Canada, points that fall outside the viewport are collapsed before they reach lineTo.

Problem 2: drawing must never block panning

All of this runs in a Web Worker on an OffscreenCanvas. The main thread only moves bitmaps around. But a worker frame arrives late by definition, so while you zoom, you would see blank edges or a blurry stretched picture.

The fix is three layers stacked under the points:

  1. a sharp frame: the screen plus a margin, at full resolution;
  2. a wide frame: about five screens around the view at a third of the resolution;
  3. an overview of the whole world, drawn once.

When you zoom out, the sharp frame shrinks and the wide one shows from under it. It is soft for a moment, but it is the right picture, not a 100x upscale of the overview. On zoom-out the worker is also asked for the next sharp frame ahead of time, for a view larger than the current one.

Browsers that cannot give a worker an OffscreenCanvas (iOS before 16.4) get a fallback: simplified outlines drawn on the main thread, without cities.

Problem 3: cities

A city is a separate package: outline, districts, water and roads from OpenStreetMap. It loads when the camera gets close. Before that the city is a single dot.

Two details mattered more than expected:

  • A city fades in, and its roads fade out again when the city is small on screen. Without that, a road network squeezed into 100 pixels turns into a white blob.
  • Roads, water and district lines are clipped to the city outline, so nothing sticks out into the neighbouring region.

Problem 4: cities that own a piece of the sea

This one produced the ugliest bug. In OpenStreetMap the administrative boundary of a coastal city often includes its waters. Ho Chi Minh City owns a large wedge of the South China Sea. Our renderer erased the land under a city and repainted it with the city fill, so a polygon the size of the city itself was painted far into open water.

It turned out 23 of 152 cities had this: New York, Los Angeles, Tokyo, Singapore, Hong Kong, Baku and others.

The build step now rasterizes two things onto the same 640-pixel grid: the city outline and the land of all countries. No geometry library is involved, only a scanline fill written in numpy with the even-odd rule, plus scipy.ndimage for distances and connected parts. If more than 3% of the outline and more than 20 km² of it is not land, the package gets a flag sea. The city's bounding box, centre and camera frame are then computed from the land part only.

In the renderer the flag switches one branch:

if (c.sea) {
  ctx.globalCompositeOperation = 'source-atop';
} else {
  trace(c.rings, s, cx, cy);
  ctx.globalCompositeOperation = 'destination-out';
  ctx.fill('evenodd');
  ctx.globalCompositeOperation = 'source-over';
  ctx.fillStyle = CITY;
  ctx.fill('evenodd');
}
Enter fullscreen mode Exit fullscreen mode

With source-atop, everything the city draws lands only on pixels that are already opaque, and the only opaque pixels at that moment are land. Rivers, roads and district lines keep working, the sea stays sea, and the coastline of the world runs through the city uninterrupted.

[КАРТИНКА: D:\work\tglist\Publications\articles\331\2-new-york.jpg — New York: the city is painted only over land]

[КАРТИНКА: D:\work\tglist\Publications\articles\331\3-ho-chi-minh-city.jpg — Ho Chi Minh City after the fix: the outline no longer runs into the sea]

You can compare with New York, where the two rivers around Manhattan are the world's sea showing through the city.

Problem 5: slow devices and Safari

Two smaller things that cost a day each.

Adaptive quality. The map measures the median frame time while the view is moving. If it is worse than 22, 36 or 50 ms, the quality level steps down: lower resolution for the background, the map frames and the point engine. It never steps back up within a session, because flipping between levels looks worse than staying low.

The address bar. The URL follows the camera, so any view can be shared. Safari throws a SecurityError after 100 history.replaceState calls in 30 seconds. The map writes the URL once every 400 ms while moving, which stays under the limit with room to spare.

What we would do again

  • Keep geometry in a worker and treat the main thread as a compositor.
  • Solve "is this polygon on land" with a raster, not with polygon clipping. A 640-pixel grid is precise enough for a city, and the code is thirty lines.
  • Version the data folder. Browsers cache these files forever, so a rebuild goes to a new path.

How the channels themselves are placed, by country, city and district, is described on the page about how the maps are built.

Top comments (0)