Maps on Man-You

Freddie part 2: from tiles to map

Tue, 24 Mar 2026 12:00:00 +0100

In part 1 I covered the hard problems: COG multi-resolution, SDF raster smoothing, and Barbapapa topology-preserving Laplacian smoothing. Freddie could generate good-looking 10m land cover vector tiles. This post is about what happened next: killing the algorithm I spent a week perfecting, solving a surprisingly dumb storage problem, and wiring the tiles all the way through to the map SDK.

Barbapapa is dead

I killed Barbapapa a few weeks after shipping it.

It stung a little. Seven revisions, the hole vertex bug that ate two days, the Jacobi-style simultaneous updates, the deterministic iteration fix. Elegant stuff. But after staring at enough tiles side by side, the conclusion was unavoidable: Barbapapa was lying.

Land cover at 10m resolution doesn’t have smooth boundaries. A forest edge is where a satellite sensor switched from “tree” to “grass” at some pixel boundary. It’s inherently jagged. Barbapapa was manufacturing gentle curves that were never in the data: aesthetically pleasing, but dishonest. The tiles looked better in the way a retouched photo looks better. Not more accurate, just smoother.

Meanwhile, the chain-based Douglas-Peucker simplifier I’d built alongside it was doing more useful work with less ceremony.

Edge DP

Edge DP operates on the same half-edge topology that Barbapapa used, but the philosophy is opposite. Instead of moving vertices closer to their neighbors to manufacture curves, it removes the vertices that don’t carry information. Less romantic, more honest.

The core idea: find the topologically significant vertices (junctions where three or more land cover classes meet) and treat everything between them as a chain. Each chain can be simplified independently without breaking the topology.

Five phases:

1. Find junctions. Walk every vertex and count how many distinct classes touch it. Three or more classes makes it a junction, an anchor in the topology skeleton. Tile boundary vertices are also pinned.

2. Extract chains. Walk each polygon ring, breaking at junctions and class transitions. Two adjacent faces sharing a boundary reference the same chain object. Simplify it once, both faces see the result. This is the same principle that made Barbapapa work (shared topology) but applied to vertex removal instead of vertex movement.

3. Douglas-Peucker per chain. The textbook recursive algorithm: find the vertex farthest from the line between endpoints, keep it if it exceeds the threshold, recurse on both sides. Nothing clever here. The cleverness is in applying it at chain granularity instead of per-polygon, where it would tear shared boundaries apart.

4. Reconcile. If any chain needs a vertex, it stays. Prevents holes at multi-chain junctions where one chain would remove a vertex another one depends on.

5. Rebuild twins. Remove the marked vertices from all rings and relink half-edge twin pointers so the topology stays consistent.

The result: aggressive vertex reduction with guaranteed topological consistency. No gaps, no overlaps, no invented curves. What you see is what the sensor saw, with fewer vertices saying it.

Z14Factor

One subtlety at high zoom: SDF upscaling leaves residual staircase artifacts. The Gaussian blur approximates class boundaries but doesn’t eliminate the pixel grid entirely. A Z14Factor of 0.6 multiplies the DP threshold at z14 and above, a less aggressive simplification that preserves more of the SDF-smoothed detail. Base threshold of 2.0 becomes 1.2 at z14, keeping vertices that would otherwise be culled. The SDF already did the heavy lifting on boundary shape. DP just needs to not undo that work. Small tweak, noticeable difference.

What got deleted

This was the satisfying part. With Edge DP handling everything alone, I got to delete a lot of code:

Barbapapa: gone (~6,800 lines including tests and docs)
Visvalingam-Whyatt: gone (experimental, Edge DP outperformed it everywhere)
SimplifyFaces: gone (subsumed by Edge DP’s chain extraction)
Ten per-class viewer layers: collapsed into one fill layer with zoom-interpolated colors
Duplicated config across freddie and freddie-server: unified into a single ProcessingConfig struct

The pipeline description shrank to one line: SDF (blur=6.0, minZ=10) + mode filter 7×7 + edge DP (threshold=2.0).

Painter’s algorithm

Collapsing ten per-class layers into one fill layer immediately broke rendering. Enclosed faces could paint over their parents. A lake surrounded by forest would disappear under green because the forest polygon rendered last. Obvious in hindsight, invisible until you actually try it.

The fix: topological sorting before MVT encoding. For each face, ray-cast to check whether it’s enclosed by another face, then depth-first sort so parents paint first. A lake inside a forest inside a continent renders in the right order. Combined with placing the landcover layer right after the map background in the style, one MapLibre fill layer handles everything correctly. Fewer layers, less complexity, better result.

The 200GB problem

Freddie generates beautiful tiles. But beautiful tiles sitting on my laptop don’t help anyone. They need to end up in the actual map, served alongside the base tiles: roads, buildings, POIs, all the stuff Planetiler generates.

The obvious approach: merge the two mbtiles files offline into one. Base map (~80GB) + landcover (~60GB) = one file, ship it. I built freddie-merge for exactly this. Iterated over every tile in both files, combined the MVT layers, wrote the result. Clean, simple, done.

The merged output was over 200GB. I stared at the number for a while.

The reason is embarrassing. Planetiler stores identical tiles once through content-addressed deduplication. Vast stretches of ocean at low zoom are the same tile: one copy, millions of references. Merging landcover into every tile makes each one unique, so deduplication collapses entirely. 80 + 60 doesn’t equal 200, but 80 (heavily deduplicated) + 60 (heavily deduplicated) merged together becomes 200 (nothing deduplicated). I’d undone one of Planetiler’s best optimizations without realizing it.

Runtime MVT concatenation

The fix is almost too simple to be satisfying.

MVT layers are top-level protobuf fields. Two valid MVT byte streams concatenated together produce a valid MVT byte stream. No parsing, no reencoding, no schema reconciliation, just append bytes. I had to read the protobuf spec twice to convince myself this was actually legal.

So: don’t merge at build time. Keep both tile pyramids as separate mbtiles files and concatenate at read time:

Fetch base tile from mbtiles A
Fetch landcover tile from mbtiles B
Decompress both (gzip)
Concatenate, landcover first, so it paints behind everything
Recompress, serve

When there’s no landcover configured, the merge path is never entered. Zero overhead for the existing setup. Both files keep their original deduplication intact. And freddie-merge (the tool I built, debugged, optimized with ATTACH JOIN, rewrote to iterate the smaller set) joins the growing pile of deleted code.

Layer ordering matters: landcover sits right after the map background, before roads and buildings and labels. At high zoom where ESA WorldCover runs out of detail, the existing OSM landcover_wood and landcover_grass layers take over with a minzoom of 12.

Teaching the SDK about fill colors

The last piece of the puzzle was the rendering SDK. It already had a multiclass styling system for POIs: one MapLibre layer that renders different icons and text labels depending on the feature class. I naively assumed landcover would slot right in. Same system, different data, right?

No. POIs and landcover need fundamentally different MapLibre expression shapes, and the difference is annoyingly subtle.

A POI layer uses case at the root to pick an icon, with interpolate nested inside for zoom-dependent sizing:

["case",
 ["==", ["get", "class"], "park"], "park-icon",
 ["==", ["get", "class"], "school"], "school-icon",
 "default-icon"]

A landcover fill layer needs the structure inverted: interpolate at the root for smooth color transitions across zoom, with case nested inside each zoom stop to pick the per-class color:

["interpolate", ["linear"], ["zoom"],
 0, ["case",
 ["==", ["get", "class"], "wood"], "#1a3d1a",
 ["==", ["get", "class"], "grass"], "#2d5a1e",
 "transparent"],
 14, ["case",
 ["==", ["get", "class"], "wood"], "#2d6b2d",
 ["==", ["get", "class"], "grass"], "#4a8c3f",
 "transparent"]]

The inversion matters because MapLibre can’t interpolate between case results. You have to case-select within each interpolation stop. I spent an embarrassing amount of time trying the other way before reading the spec carefully enough to understand why.

A new ClassMetadata type carries zoom color stops instead of flat color strings, and the expression builder constructs the full interpolate+case tree from the metadata. The POI path stays untouched, just extracted into its own methods so the two flows don’t tangle. One of those changes where the diff is medium-sized but the head-scratching that preceded it was substantial.

Four repos, one pipeline

Stepping back, the whole story spans four repositories and a surprising amount of deleted code:

freddie generates 10m land cover vector tiles: SDF smoothing, Edge DP simplification, painter’s algorithm sorting, mbtiles output
data-pipeline spins up a beefy ARM instance, downloads ~100GB of ESA WorldCover source TIFFs from S3, runs freddie, uploads the result, self-destructs
maps serves tiles with runtime MVT concatenation: no offline merge, no deduplication loss, zero overhead when landcover isn’t configured
maps-js renders them with zoom-interpolated fill colors through the multiclass style system

From satellite raster to styled vector on screen. GeoTIFF in, mbtiles out, MVT over HTTP, MapLibre expressions in the style JSON. Each piece does one thing.

The part that surprised me most wasn’t any individual algorithm. It was how cleanly everything composed once each piece had well-defined inputs and outputs. Freddie doesn’t know about the map SDK. The map server doesn’t know about SDF smoothing. The SDK doesn’t know the tiles came from satellite imagery. They just agree on protobuf bytes and the rest takes care of itself.

Also: I wrote and then deleted an entire smoothing algorithm, an entire merge tool, and three simplification strategies. The codebase got smaller as the feature got bigger. That might be the most satisfying part of this whole project.

When "mostly aligned" stops being enough

Sat, 07 Mar 2026 22:41:00 +0100

Every product starts by depending on open source it doesn’t fully understand. That’s fine. It’s the whole point. You stand on the shoulders of people who solved problems you haven’t even encountered yet, and you ship. The dependency is invisible because it works.

Then the product grows, and you start noticing the edges. The upstream project makes choices you wouldn’t have made. The schema carries fields you don’t use. The routing engine takes a turn you can’t explain. The update process becomes a gamble: bump to the latest version and hope nothing changed in a way that breaks your use case. You’re accountable to your customers for software you treat as a black box.

This is the story of how that played out for us across map tiles, routing, and rendering, and why the hardest part isn’t the engineering.

Not all dependencies are equal

We depend on dozens of open source projects. FastAPI, Django, Pydantic, httpx, pytest, the list goes on. If FastAPI disappeared tomorrow, we’d rewrite some decorators and route definitions. It would be work, but the product would still be the product. These are plumbing. They shape the surface (how requests arrive, how responses leave) but they don’t define what the product is.

Map tiles and routing are different. Without tiles, the maps SDK renders nothing. Without a routing engine, the distance API returns nothing. These aren’t tools we use to build the product. They are the product, or at least the foundation it stands on. An empty shell without them.

The dependency risk isn’t about how many lines of code use a library. It’s about how much of the product’s core value lives in upstream code you don’t control. When that answer is “most of it,” the relationship with that upstream project stops being a convenience and starts being an existential question.

The illusion

Here’s the part nobody talks about.

When you ship an MVP built on third-party foundations, the customer doesn’t know. They don’t know the tiles come from MapTiler. They don’t know the routing runs on Valhalla. They see a Woosmap maps API and a Woosmap distance API. They think they bought a product.

And they did, from their perspective. The API works. The tiles render. The routes compute. The fact that most of the core value is someone else’s software, running in your infrastructure, with your branding on top, is an implementation detail they never see.

So when you sell the MVP, you’re implicitly selling the product three years from now. The customer is buying what they think exists. Leadership is reporting on what they think the team built. And the engineering team knows the truth: that the product, as everyone imagines it, doesn’t exist yet. What exists is a thin layer on top of open source that happens to work.

This creates a brutal dynamic. When you invest in actually building the foundations (replacing vendor tiles with your own schema, understanding the routing engine you depend on, building a style compiler) it looks like you’re doing nothing. No new features. No visible progress. The maps still render. The routes still compute. From the outside, nothing changed.

Worse, the transition introduces blips. You’re replacing running systems with new ones you wrote, and you’re human, so mistakes happen. A regression in tile rendering. A routing edge case the old system handled that yours doesn’t yet. For a brief window, you’ve made things slightly worse in pursuit of making them fundamentally better. And nobody outside the team has the context to understand why.

You’re in a fight against everyone’s perception: customers, leadership, sometimes other engineering teams. Living up to what people think the product already does while quietly building the thing they assumed was there all along.

The pattern

It starts the same way every time.

Phase 1: it works. You adopt the open source project. It does 90% of what you need. The remaining 10% you work around. The trade-off is obvious and good: building from scratch would take months, this takes days. You ship.

Phase 2: it mostly works. The product grows. The 10% gap becomes visible to customers. You can’t change it because it’s upstream. You file issues, maybe contribute patches, but the project’s priorities aren’t your priorities. They’re building for a community. You’re building for a product.

Phase 3: you’re accountable. A customer reports a bug that lives in the upstream code. You can’t just say “that’s an open source issue.” It’s your product. You need to fix it, but fixing it means understanding a codebase that wasn’t written for you, by people who had different goals. The gap between “using” and “maintaining” becomes real.

Phase 4: the fork in the road. You have three options. Contribute upstream and hope the community accepts your direction. Fork and maintain your own version. Or rebuild the parts you need from scratch.

Map tiles: from vendor to vertical integration

Buying tiles

The first version of Woosmap Maps didn’t generate tiles at all. We licensed vector tiles from MapTiler, a flat yearly fee for an MBTiles pyramid. Predictable, simple. We focused entirely on the SDK: the Mapbox GL fork, the Google Maps compatibility layer, the service clients. The tiles were someone else’s problem.

This was the right call. We were building a maps product, not a geodata pipeline. MapTiler tiles worked, the OpenMapTiles schema was well-documented, and we could ship without learning anything about OSM data processing.

By the time we started thinking about generating tiles ourselves, the pricing model had changed. I don’t remember the exact structure anymore, but it was enough of a signal: the terms we’d signed up for weren’t the terms going forward. Beyond pricing, tiles carried 16 layers with attributes we never read, the update cadence wasn’t ours, and the OpenMapTiles CC-BY 4.0 license required visible attribution, which was friction in every enterprise sales conversation.

Running OpenMapTiles ourselves

We took the OpenMapTiles stack in-house. PostgreSQL-based: import OSM data with imposm3 into PostGIS, run generated SQL scripts to transform it layer by layer, then generate vector tiles through per-tile PostgreSQL queries. Same schema, our infrastructure.

It worked, but planet generation took days and the database needed hundreds of gigabytes. And we still had the same schema, the same unused attributes, the same attribution requirements. We’d replaced a vendor bill with an infrastructure bill while keeping every constraint.

Planetiler

Planetiler (originally Flatmap) changed the equation. Java, streaming processing, no database. A full planet in hours on a single machine instead of days on a database cluster. We ran it with the planetiler-openmaptiles profile: same output, fraction of the cost.

But we still had the schema problem. Faster generation of tiles you don’t control is still tiles you don’t control.

Clean-room schema

The real break was writing our own Planetiler profile from scratch. Not a fork of OpenMapTiles. A clean-room reimplementation with our own layer names, our own attributes, and nothing we don’t use.

transportation became roads. transportation_name became road_labels. housenumber got dropped entirely. Almost every layer is written in Kotlin because the logic is too specific for declarative YAML: transit network propagation from OSM relations, building height arithmetic, multi-script labels across 85 languages, roads pre-split by bridge/tunnel structure.

The style compiler

Owning the tile schema without owning the style is half the job. A production Mapbox GL style is thousands of lines of JSON. Roads alone need six variants each across eight road classes.

Elzar, our style compiler, generates that JSON from Python code. The tile schema and the style are designed in lockstep. When the Kotlin tile generator emits a hide_3d attribute on buildings, the style compiler references it in the same PR. Schema and style can’t drift because they live in the same repo.

The spec question

Once you own both the tiles and the style generation, a new question surfaces: does the Mapbox GL style spec itself actually fit what you’re building?

The spec was designed for a general-purpose renderer serving a general-purpose schema. It has no concept of road structure, so a single road class needs six style layers (tunnel casing, tunnel fill, road casing, road fill, bridge casing, bridge fill) because brunnel is just another filter attribute. Eight road classes times six variants is 48 layers just for roads, before labels and shields. It’s like using assembly to build a web server: technically possible, but is it reasonable? Complex logic gets encoded as JSON expression trees (nested arrays of ["case", ["all", ["has", "name:nonlatin"], ...]]) that are technically correct and practically unreadable.

Elzar makes this manageable. Define a road once, get six variants. Use ~Q(hide_3d__exists=True) instead of raw filter arrays. Pre-splitting roads into roads_tunnel, roads, and roads_bridge at the tile level was our way of optimizing around the spec, moving work from render time to tile generation time because the style format couldn’t express it efficiently.

Elzar would stay regardless of the output format. Even if we designed a custom style spec, we’d still want to define styles in Python (something executable, debuggable, testable) rather than editing a declarative format by hand. The compiler’s value isn’t papering over the Mapbox spec. It’s that Python is a better authoring language for styles than any JSON dialect ever will be. The compiler stays. Only its target changes.

The renderer

That’s where Nimbus, the GPU map renderer experiment in Rust, enters the picture. If you control the renderer, you control the style format. The Mapbox spec stops being a constraint and becomes a choice. You can support it for compatibility while designing something better for the pipeline you actually have.

A style format designed for our schema wouldn’t need six layers per road class. It would know about brunnel structure because the tiles already express it. Tiles that carry exactly the data the style describes. A style format that maps naturally to the tile schema. A renderer that understands both natively. And Elzar at the center, generating whatever output the renderer needs from the same Python definitions we already have.

Routing: the black box problem

OSRM

The distance API started on OSRM. It’s fast and well-proven. But it loads the entire road graph into RAM, and for a world-scale service, that’s a hard constraint. The memory footprint made it impractical for the coverage we needed.

Valhalla

Valhalla solved the memory problem. Tile-based graph storage means you can serve the world without loading it all into RAM. We migrated, it worked, and for a while the “mostly aligned” phase was comfortable.

Then we started hitting the edges.

Valhalla is a massive C++ codebase maintained by a community with its own priorities. When a customer reports a routing bug (a wrong turn cost, a route through a service road that should be avoided) we can’t just fix it. We’d need to understand why the cost model works the way it does, trace through code that wasn’t written for our use case, and either patch it locally or convince the upstream community that our fix is the right one.

The tile update process is where the black box problem gets painful. When we want to regenerate Valhalla tiles with fresh OSM data, we typically also bump Valhalla to the latest version, because the version that generates tiles and the version that serves them sometimes need to match. But a version bump means inheriting every change the community made since our last update. New cost model tweaks we didn’t ask for. Behavioral changes we don’t understand. Route quality regressions we discover from customer complaints, not from changelogs.

We’re accountable for this software. Customers don’t care that Valhalla is open source. They see a Woosmap API returning a bad route and they file a ticket with us. And we’re stuck between “we don’t understand why it does that” and “we can’t change it without forking a C++ project we don’t deeply know.”

The C++ ecosystem makes this harder. Build systems, dependency management, debugging tooling: none of it is as accessible as the JVM or Rust’s cargo. Taking deeper ownership of Valhalla isn’t just a knowledge problem, it’s an ergonomics problem.

Calculon

Calculon is the “what if we built it ourselves” experiment: a routing engine in Rust. Bidirectional A*, many-to-many distance matrices, driving/cycling/pedestrian profiles, Valhalla-compatible API. It reuses Valhalla’s tile format (designing a graph format from scratch would be its own project) but everything else is new code.

It’s not a Valhalla replacement yet. But when a cost model produces a weird route, we can read the code. When we want to change how turn penalties work, we change them. When we bump a dependency, it’s a Rust crate with a changelog we understand, not a C++ monolith where any subsystem might have shifted.

There’s a middle path too: taking deeper ownership of Valhalla itself, contributing changes that serve our use case. But that requires investing heavily in a C++ codebase whose architecture and community may or may not align with where we need to go.

When replacing a black box makes things better

The pattern isn’t always painful. Sometimes replacing a dependency you don’t control with something you wrote yourself turns out to be a straight upgrade.

The Woosmap Store Locator used Mapnik (a C++ rendering library) to generate map tiles showing store locations. Mapnik is a serious piece of software, battle-tested for raster map rendering. But it wasn’t designed for our use case: rendering MVT vector tiles with point data. It had become a dependency we couldn’t easily update, couldn’t debug when it misbehaved, and couldn’t adapt to our evolving needs.

We replaced it with a Python renderer built on Cairo. The new renderer was simpler: written in a language the whole team knows, doing exactly what we need and nothing more. And it turned out to be more performant. Less load on the database. Enough of an improvement that we could scale down the RDS instance.

A full-featured C++ rendering engine, replaced by a focused Python implementation, and the result was faster and cheaper. Not because Python is faster than C++. Obviously it isn’t. But because a tool built for your specific problem, that you understand completely, can be optimized in ways a general-purpose tool never will be. You know which queries to run, which data to skip, which shortcuts are safe. The black box can’t know any of that.

The ones still early in the cycle

Not every dependency has reached the accountability phase yet. Maparazzo, our static maps renderer, wraps Mapbox GL Native’s C++ core in a Python library for headless map image generation. Right now it’s in phase 1: it works. The C++ renderer produces correct images, the Python wrapper makes it callable from our FastAPI services, and static maps ship to customers.

But the signs are already there. The C++ renderer leaks memory: OpenGL contexts hold state after objects are destroyed. We’ve worked around it by pooling Map instances and reusing GL contexts, but the leak is in code we inherited, not code we wrote. When it misbehaves, debugging means diving into a massive C++ codebase with its own conventions, its own build system, its own history of decisions we weren’t part of.

It’s comfortable enough today. The problems will come. And when they do, Nimbus (which can already render our tiles headlessly from Rust) is the path out. Same pattern, different timeline.

The open source dependency lifecycle

The uncomfortable truth is that depending on open source unknowingly makes you a maintainer. Not in the “you have commit access” sense. In the “you’re responsible for its behavior in your product” sense.

For an MVP, “mostly aligned” is enough. The open source project does 90% of what you need, the community is active, the abstractions hold. You’d be foolish to build from scratch. And the community’s goals don’t need to perfectly match yours. They just need to overlap enough that you can ship.

But products have customers. Customers have expectations. When the open source project’s goals diverge from yours, even slightly, you feel it. Not as a single breaking change, but as accumulated friction. Features you can’t add because the schema doesn’t support them. Bugs you can’t fix because the codebase is impenetrable. Updates you can’t skip because the format requires version parity.

And ownership doesn’t stop at the obvious dependencies. Once you own the data and the generation, you discover that the formats and specs are dependencies too. The Mapbox style spec. Valhalla’s tile format. These are constraints you inherited from the ecosystem, and they shape what’s easy and what’s hard in ways that aren’t visible until you try to push past them.

The question isn’t whether to take ownership. It’s when, of what, and how deep. Do the changes you need benefit the community? Would they accept a PR, or is your direction orthogonal to theirs? Is the ecosystem accessible enough to invest in, or is the cost of understanding it higher than the cost of rebuilding?

For tiles, we kept Planetiler as the engine and own everything else: schema, style, and the compiler that connects them. For routing, the answer is still forming. For the style format and the renderer, we can work around the constraints today, but we can see the path to not having to.

“We have no vision”

I’ve heard this from engineers on the team. That we’re only reactive. That we just respond to customer requests and there’s no plan. And I understand why it looks that way: if you think phase 1 is the end, then everything after looks like firefighting.

But if you lay out the phases, the vision is obvious. We have years of deliberate work ahead: owning the tile schema, closing the style spec gap, making the renderer a first-class citizen, taking control of routing. Each phase builds on the last. Each one makes the product more ours and less a wrapper around someone else’s decisions. That’s not reactive. That’s a roadmap.

The problem is that this roadmap is invisible to anyone who thinks the product was finished when the MVP shipped. And that’s the majority of people: customers, leadership, and yes, most engineers. They see the API, it works, so the hard part must be done. Everything after is maintenance.

This is exactly the same problem as technical debt, just at a different scale. Everyone will sign up for taking on debt if they think it ships something faster. Add a dependency you don’t understand. Skip the tests. Use the upstream schema as-is. Ship it. Move on to the next thing, take on more debt there too. And when someone proposes paying it down (replacing Mapnik with our own renderer, writing a clean-room tile schema, building a style compiler) the response is “why? it works.”

It works until it doesn’t. And by then the debt has compounded. The codebase is half-rotten, everyone complains about it, but nobody wants to stop adding features long enough to fix it. The boy scout rule (leave the code better than you found it) gets dismissed as slowing things down. So the rot spreads.

Supply chain debt works the same way. Every dependency you don’t understand is a loan against your future ability to move fast. The interest is paid in debugging time, in workarounds, in version bumps that break things you can’t explain, in customers waiting for fixes that live in upstream code you can’t change. And just like financial debt, the longer you ignore it, the more it costs.

The vision isn’t a feature roadmap. It’s the systematic transfer of ownership from upstream to us, one layer at a time, while the product keeps running. It’s unglamorous, often invisible, and it’s the only way to build something that lasts.

My role as CTO is to grow the technological asset of the company. Features are what the product does. The asset is what the product is. The PO grows the former. I grow the latter. When the asset is a thin wrapper around upstream dependencies, it’s fragile. Anyone can replicate it. Every phase of ownership makes it thicker, harder to reproduce, more valuable. That’s not maintenance. That’s building the company’s core value.

And that means making these phases crystal clear to everyone. If the team doesn’t see the multi-phase roadmap, they’ll assume there isn’t one. If leadership doesn’t understand why replacing a working renderer with a new one matters, they’ll see wasted effort. If engineers think phase 1 is the destination, they’ll resist every investment in phase 2 through 5 as unnecessary complexity.

And here’s where I haven’t done a good enough job. When the foundational work isn’t visible (or worse, when I end up doing it on my own because it’s hard to justify in sprint planning) it creates the illusion that there’s only one stream of work: the product owner’s backlog. Feature requests, customer issues, integration tickets. That becomes the only work that feels real, the only work that gets discussed in standups, the only work that counts.

Engineers naturally gravitate toward pleasing the PO. The PO has the backlog, the priorities, the stakeholder pressure. The CTO has… a vague sense that the foundations need work. If I haven’t made the supply chain roadmap as concrete and visible as the feature backlog, I can’t blame anyone for treating it as optional.

But it’s a dangerous dynamic. A team that only serves the PO’s backlog is a team that only adds features to an MVP while the foundations quietly rot. The PO’s job is to maximize customer value now. The CTO’s job is to make sure the product can still deliver that value in two years. Those aren’t opposing goals, but they operate on different timescales, and if the long-term one isn’t articulated clearly enough, it loses every single sprint planning meeting.

The vision exists. It’s in the progression from bought tiles to clean-room schema. It’s in Calculon sitting next to Valhalla. It’s in Elzar generating styles that match a tile schema we designed. The work speaks for itself, but only if someone tells the story clearly enough that it becomes a roadmap, not a side project. And that someone is me.

There’s a harder question underneath all of this: is growing the technological asset even possible when the company is purely ARR-driven?

ARR optimizes for now. Ship the feature that closes the deal. Fix the bug that stops the churn. Hit the number this quarter. Every sprint is a negotiation between what moves the metric today and what makes the product real. And the metric always wins, because it’s concrete: a number on a dashboard, a target in a board deck.

The technological asset doesn’t have a dashboard. There’s no metric for “we now own our tile schema” or “we can debug a routing issue in hours instead of weeks.” The value is real but it compounds invisibly: faster iteration, fewer black-box surprises, the ability to say yes to product requests that would have been impossible before. None of that shows up in ARR until months or years later, and by then nobody connects the cause to the effect.

A company that’s purely ARR-driven will always deprioritize foundational work. Not out of malice. Out of measurement. If the only thing that counts is what moves the number this quarter, then building the asset that makes next year’s numbers possible will always lose. And you end up in a trap: a product that looks successful from the revenue side while its foundations quietly thin out, making it harder and more expensive to deliver on the promises that drive that very revenue.

The uncomfortable truth is that ARR and the technological asset need each other. ARR without the asset is a product that gets harder to maintain every quarter. The asset without ARR is an engineering project with no customers. The CTO’s job is to make the case that both need investment, and that starving one to feed the other is a debt that always comes due.

You start by depending. You end by being accountable. What happens in between is the difference between an MVP and a product.

Scaling Freddie to 10m landcover

Tue, 10 Feb 2026 12:00:00 +0200

Serving vector tiles from 10-meter resolution land cover data. What breaks when you 100x the input resolution, and how topology-preserving smoothing fixes the ugly parts.

Background

Freddie is our tile server for land cover data. It reads GeoTIFF raster files (pixels classified as wood, grass, built-up, water, etc.) and serves them as vector tiles or raster tiles over HTTP. Nothing fancy. Read pixels, make shapes, encode, serve.

The original setup used ESA WorldCover at ~100m resolution. Native resolution sits around z8 in Web Mercator, so serving z0–z8 tiles was straightforward. Sample pixels, run-length encode, merge adjacent faces of the same class, encode to MVT. Done. It just worked, and I didn’t think much about it.

Then we switched to the 10m dataset. Native resolution jumps to ~z13–z14. The source TIFFs balloon to 36,000 x 36,000 pixels each. Everything that worked at 100m either broke or looked terrible. This is the story of fixing all of it.

What breaks

Three problems, in order of how quickly you notice them.

Staircase boundaries

At zoom levels above native resolution (z15, z16), each source pixel stretches across 4–16 tile pixels. The vector boundaries follow pixel edges exactly: 90-degree staircase patterns everywhere. At 100m this was never visible because nobody zoomed past z8. At 10m you can zoom to z16 and the pixel grid is right there, staring back at you. Minecraft terrain, basically.

Performance at low zoom

A z0 tile covers the entire world. With a 36,000 x 36,000 source TIFF, generating that tile means sampling millions of pixels. At 100m the source was small enough that brute force worked. At 10m, a single z0 request could take seconds. I watched the first one come back and thought the server had hung.

Topology seams

The naive fix for staircases (smooth each polygon independently) creates gaps and overlaps between adjacent regions. Two polygons that share a boundary get smoothed in different directions. You end up with visible seams, z-fighting, or missing pixels at class boundaries. Fix one problem, create another. Classic.

COG multi-resolution

The performance problem, at least, has a clean solution: Cloud Optimized GeoTIFF.

A COG file stores the full-resolution image plus downsampled overviews, typically at 2x, 4x, 8x, 16x, 32x reductions. Instead of one 36,000 x 36,000 image, you get a pyramid:

Level	Size	Use for
0	36,000 x 36,000	z10+
1	18,000 x 18,000	z8–z9
2	9,000 x 9,000	z6–z7
3	4,500 x 4,500	z4–z5
4	2,250 x 2,250	z2–z3
5	1,125 x 1,125	z0–z1

The heuristic is simple: levelIndex = (maxZoom - zoom) / 2. A z0 tile now samples from a 1,125 x 1,125 overview instead of the full image. About 1,000x less data to read.

Resolution level selection

func (tc *TiffCollection) selectLevel(zoom int) int {
 levelIndex := (tc.maxZoom - zoom) / 2
 if levelIndex >= len(tc.levels) {
 levelIndex = len(tc.levels) - 1
 }
 return levelIndex
}

The TiffCollection manages multiple TIFF files with spatial indexing: a 3 x 3 degree grid for fast lookups. At tile boundaries where multiple TIFFs overlap, deterministic ordering ensures consistent output.

z0 tiles went from seconds to milliseconds. Problem one down, two to go.

The smoothing problem

With COG handling performance, the real challenge is visual quality. Run-length encoding produces pixel-aligned polygons. At native resolution that’s fine: the boundaries are detailed enough. But zoom in past native and you see the grid. It’s ugly, and no amount of squinting makes it acceptable.

Two complementary approaches: smooth the raster before vectorizing, or smooth the vectors after. I ended up doing both.

SDF raster filtering

Signed Distance Fields are typically used in font rendering. Valve popularized them for GPU text back in 2007. Turns out the same idea applies beautifully to classified rasters.

For each class in the tile:

Compute a distance transform (Meijster algorithm, O(n) per dimension): every pixel gets its Euclidean distance to the nearest boundary
Sign it: positive inside the class region, negative outside
Gaussian blur the SDF
Reclassify pixels based on the blurred SDF values

Blurring an SDF instead of blurring raw pixel values is the key insight. Raw blur smears class boundaries into garbage. SDF blur produces smooth, continuous boundaries that still snap cleanly to class assignments.

The blur radius scales with the upscale factor:

z14 (native, 1x): blur = 6.0 source pixels
z15 (2x upscale): blur = 3.0 source pixels
z16 (4x upscale): blur = 1.5 source pixels
z17+ (8x+): clamped to 1.0

A 5 x 5 mode filter can run before SDF to remove isolated single-pixel noise, common in land cover data where a lone “built-up” pixel appears in a forest.

Barbapapa: topology-preserving vector smoothing

SDF smoothing handles the raster level. But even with pre-smoothed rasters, the vectorized output still has pixel-aligned vertices. Near native resolution, where SDF barely does anything, the staircases are still there. We need vector-level smoothing too.

The fundamental problem: polygons that share a boundary must be smoothed identically along that boundary. Smooth them independently and you get gaps and overlaps. I tried independent smoothing first. It looked like the polygons were trying to escape from each other.

The solution uses the half-edge data structure (DCEL) that Freddie already maintains for face merging. Adjacent polygons share vertex references through twin half-edges. Move a shared vertex and it moves for both polygons simultaneously. The topology enforces consistency.

I named the algorithm Barbapapa, after the cartoon character that can reshape into anything while staying the same blob. The algorithm has five stages:

1. Vertex deduplication. After face merging, some vertices at identical coordinates are separate objects. Canonicalize them so shared boundaries reference the same vertex instance.

Vertex deduplication

canonical := make(map[[2]int]*vertex)
for _, v := range allVertices {
 key := [2]int{v.X, v.Y}
 if existing, ok := canonical[key]; ok {
 // Repoint all half-edges from v to existing
 replaceVertex(v, existing)
 } else {
 canonical[key] = v
 }
}

2. Edge subdivision. Laplacian smoothing can only move existing vertices: it can’t add curvature where there are no points. Subdivide edges by inserting midpoints, spaced at ~3.5 source pixels apart. Both sides of a shared edge (the half-edge and its twin) get subdivided identically.

3. Identify immovable vertices. Tile boundary vertices must not move (adjacent tiles need matching edges). Vertices that exist only on hole boundaries are also pinned (I’ll get to why that caveat matters in a moment).

4. Laplacian smoothing. For each movable interior vertex, compute the centroid of its neighbors and blend:

new_position = (1 - alpha) * current + alpha * centroid

Jacobi-style: compute all new positions first, then apply all updates simultaneously. This avoids order-dependent results. Three to four iterations with alpha = 0.5–0.6 produces good results.

5. Collision prevention. Ensure no vertex collapses onto another. Sorted vertex iteration guarantees deterministic output.

The algorithm overhead is under 5% of total tile generation time. Most time is still spent on TIFF reading and face merging. Good: the smoothing is essentially free.

The hole vertex problem

Version 1 of Barbapapa had a subtle bug that killed 93% of its effectiveness. I shipped it thinking it was working. It was barely doing anything.

Here’s the setup: small classified regions (a pond in a forest, a building in a field) appear both as a face (the pond) and as a hole in the surrounding face (the forest). The vertices on these boundaries are shared between the face’s outer ring and the surrounding face’s hole ring.

My original code marked all hole-boundary vertices as immovable. The reasoning seemed sound: holes have specific shapes that shouldn’t be distorted.

The problem: a vertex on a small face’s outer boundary is also on the surrounding face’s hole boundary. So marking all hole vertices as immovable pinned almost every interior vertex. In test datasets, 110 out of 118 interior faces had zero smoothing applied. The algorithm was running, doing math, producing output, and changing almost nothing. I only caught it when I added per-face metrics and saw the numbers.

The fix: only pin vertices that appear exclusively on hole boundaries and never on any face’s outer boundary. After the fix, unsmoothed interior faces dropped from 110 to 8, the remaining 8 being sub-pixel features too small to matter. Suddenly Barbapapa actually worked.

Zoom-adaptive parameters

Smoothing needs vary wildly across zoom levels. At z14 (native resolution) the pixels are small, so light smoothing is fine. At z16 (4x upscale) the pixel grid is screaming at you, so you need to be aggressive. Below native, the data is already downsampled and naturally smooth.

Rather than hardcoding per-zoom parameters, everything scales with sourcePixelSize: how many tile pixels each source pixel occupies:

Adaptive smoothing parameters

func GetEffectiveParams(sourcePixelSize float64) (iterations int, alpha float64) {
 if sourcePixelSize < 1.0 {
 // Below native: scale down proportionally
 scale := sourcePixelSize
 return int(3.0 * scale), 0.5 * scale
 }
 // Above native: boost with log curve, cap at reasonable limits
 iterBoost := math.Log2(sourcePixelSize) * 0.75
 alphaBoost := math.Log2(sourcePixelSize) * 0.05
 return min(int(3.0+iterBoost), 8), min(0.5+alphaBoost, 0.8)
}

Using pixel size directly instead of zoom level means the same code works regardless of source resolution. Swap in a different dataset and the smoothing adapts automatically. One less thing to tune by hand.

Pipeline system

With multiple raster filters and vector simplifiers, the number of possible combinations grew fast. I was adding flags to the server every other day (--sdf, --mode-filter, --barbapapa-iterations, --sdf-blur-radius) and it was getting out of hand. So I built a pipeline system instead.

A pipeline is a named sequence of processing steps:

TIFF Data → [Raster Filters] → Vectorization → [Vector Simplifiers] → MVT

Built-in pipelines cover common configurations:

Pipeline	Raster filters	Vector simplifiers
raw	none	SimplifyFaces
default	none	SimplifyFaces, Barbapapa
smooth-sdf	SDF	SimplifyFaces, Barbapapa
smooth-mode5x5	Mode 5x5	SimplifyFaces, Barbapapa
smooth-combined	Mode 5x5, SDF	SimplifyFaces, Barbapapa
aggressive	Mode 5x5, SDF (8px)	SimplifyFaces, Barbapapa (8 iter), Douglas-Peucker

Each step collects metrics (timing, face counts, vertex counts) so you can see exactly where time is spent. This turned out to be invaluable for debugging: when a tile looks wrong, you can trace exactly which step mangled it.

Running with a pipeline

./freddie-server --pipeline smooth-combined

One flag instead of six. Custom pipelines can still be composed from individual filters if you want to experiment.

Determinism

This one bit me late. Go maps have non-deterministic iteration order. It’s by design, to prevent people from depending on it. When iterating over faces to apply smoothing, different runs could produce different vertex orderings, leading to different (though equally valid) output. Visually identical, but different bytes.

For tile caching that’s a disaster. You want the same input to always produce the exact same bytes, otherwise your cache never hits. The fix: an OrderedFaceMap that sorts keys once at construction and iterates in sorted order. Combined with Jacobi-style (simultaneous) updates in Barbapapa, the output is now bit-for-bit reproducible. Run it twice, get the same file. Should have been obvious from the start, but Go’s map randomization is the kind of thing you forget about until it ruins your afternoon.

Performance

Numbers matter, so here they are. Benchmarks on M1 Max, single tile at z8:

Operation	Time	Memory	Allocations
GetWebMercatorTileMVT	345ms	152MB	599k
GetBitmapTileWithMargins	259ms	117MB	10k
GetWebMercatorTilePNG	247ms	113MB	10k

With 10 workers: ~35ms per tile, ~286 tiles/second. A full z0–z8 pyramid (21,845 tiles) generates in about 90 seconds.

I built a benchmark harness that runs multiple pipelines across multiple regions and zoom levels, spitting out per-tile metrics and SVG/PNG outputs for visual comparison. Change a value, regenerate, compare. Without this I would have been guessing at parameter values forever. The difference between “looks right” and “is right” is hard to eyeball across thousands of tiles.

The algorithm’s evolution

Barbapapa went through seven revisions. Each one was driven by a specific visual artifact I found while staring at tiles, the kind of bug where you zoom into some random patch of Indonesia and go “wait, what is that.”

v1.0: Basic Laplacian smoothing. Worked, but barely visible. I thought the whole approach was a dead end.
v1.1: Edge subdivision. Suddenly there were actual curves instead of straight lines. The moment it clicked.
v1.2: Vertex deduplication. Enabled cross-face consistency. Shared boundaries finally moved together.
v1.3: Linked twin subdivision. Topological correctness for shared edges, fixing the cases where v1.2 missed a link.
v1.4: Zero-length edge prevention. Eliminated degenerate geometry that made the MVT encoder choke.
v2.0: Hole-only vertex identification. The 93% fix. The algorithm finally did what it was supposed to do all along.
v2.1: Deterministic iteration. Reproducible output for caching, after Go’s map randomization burned me.

The benchmark harness made this iteration loop possible. Every revision got validated against the full test suite before shipping: no visual regressions, no degenerate geometry, no byte-level surprises.

Known limitations

Two artifacts I decided to live with.

Fish-tail spikes at z14+. Where two smoothing forces compete at narrow polygon tips, V-shaped spikes can appear. They’re small, they’re rare, and fixing them would mean adding a post-smoothing vertex cleanup pass that I don’t want to maintain.

Integer coordinate quantization. MVT uses integer coordinates. Smoothed positions get rounded, which at very high zoom can produce slightly uneven curves. Floating-point vertices would fix it, but that’s a change that ripples through the entire encoding pipeline. Not worth it for an artifact you have to zoom to z17 to notice.

What changed architecturally

Looking back, the 10m upgrade touched four areas of the codebase, and the interesting thing is how little of the original code it replaced:

Multi-resolution TIFF handling: COG support with automatic level selection. The TiffCollection manages spatial indexing across multiple files. This was the most “engineering” change: straightforward but essential.
Half-edge topology operations: Safe edge chaining, twin linking, subdivision. Error handling for topology invariant violations. This is the foundation that makes Barbapapa possible, and the part I’m most proud of. Getting the DCEL right was hard, but once it worked, everything built on top of it was clean.
Pipeline system: Composable raster and vector processing steps with metrics. Named pipelines for one-command configuration. Born out of flag fatigue.
Adaptive parameters: Everything scales with sourcePixelSize instead of zoom level. Swap the dataset and the system adapts. The kind of design decision that pays for itself the first time someone asks “can we try a different source?”

The core tile serving path (HTTP handler, TIFF sampling, face merging, MVT encoding) stayed the same. The new code wraps around it rather than replacing it. I like that.

Where it stands

Freddie serves 10m land cover data from z0 to z16. Low zoom tiles are fast thanks to COG overviews. High zoom tiles look smooth thanks to Barbapapa and optional SDF filtering. The pipeline system makes it easy to experiment with different filter combinations without touching server code.

The 10m dataset covers the full globe at a resolution where you can see individual fields and city blocks. At 100m everything was green-or-gray blobs. At 10m you can tell a park from a garden.

Building a maps SDK from a Mapbox GL fork

Sun, 08 Feb 2026 14:00:00 +0200

Rewriting the Woosmap Maps SDK on top of a Mapbox GL JS fork, with a Google Maps-compatible API surface, built with Bun, and an experiment in offscreen rendering.

Why

The Woosmap Maps SDK depended on Mapbox GL JS. Then Mapbox changed the license. Version 2.0 moved to the Business Source License, not open source anymore. The last truly open version was 1.13.1 (December 2020). No more upstream bug fixes, no WebGL2 improvements, no new features. We were stuck on a frozen codebase.

Staying on 1.13 forever wasn’t viable. Browser APIs move, WebGL evolves, security patches stop. Switching to Mapbox 2.x meant accepting the BSL and its usage restrictions. MapLibre forked from the same 1.13 base, but taking a dependency on another project’s roadmap puts you in the same position, just with different maintainers.

So we forked 1.13.1 ourselves, ported the whole thing to TypeScript, and built a Google Maps-compatible API wrapper on top. Our customers use the Google Maps API surface: new woosmap.map.Map(), woosmap.map.Marker, woosmap.map.event.addListener. Switching to a Mapbox-style API would break every integration. One codebase, two API surfaces: Mapbox GL rendering engine underneath, Google Maps API on top.

Architecture

Two layers, cleanly separated.

Mapbox GL fork (src/mapbox-gl/): the rendering engine. WebGL2 context management, vector tile decoding, style evaluation, symbol placement with collision detection, gesture handling. 57 GLSL shaders, vertex and fragment pairs for fill, line, symbol, heatmap, hillshade, raster, extrusion. The full Mapbox style spec expression engine: get, has, match, case, interpolate, step, let/var, coalesce, arithmetic, string ops, comparisons.

Woosmap layer (src/woosmap/): the Google Maps compatibility wrapper. Map, Marker, InfoWindow, OverlayView, Data layer, pane management, gesture handling overlay. Plus service clients: stores, distance matrix, localities autocomplete, datasets, transit, directions.

The Woosmap Map class wraps the Mapbox Map:

src/woosmap/map.ts

import { default as MapBoxMap } from "../mapbox-gl/ui/map";

class Map extends MVCObject {
 _mapboxMap: MapBoxMap;

 constructor(element: HTMLElement, options: MapOptions) {
 // Create the Mapbox map internally
 this._mapboxMap = new MapBoxMap({ container: element, style, ... });
 // Wire up Google Maps-style events, panes, controls
 }
}

Properties fire change events automatically through MVCObject. Set marker.position and position_changed fires. Same pattern Google Maps uses.

The style system

Woosmap customers use Google Maps-style JSON rules to customize maps. Hue shifts, saturation, lightness, gamma correction, invert, applied hierarchically by feature type.

src/woosmap/map-style/map-style.ts

type MapStyler = {
 color?: string; // hex color
 hue?: string; // extract hue, keep lightness/saturation
 saturation?: number; // shift saturation
 lightness?: number; // shift lightness
 gamma?: number; // gamma correction on lightness
 invert_lightness?: boolean;
 visibility?: string; // "on" | "off"
 weight?: number; // line/label weight
};

A LayerRegistry maps Google’s feature type hierarchy (road.highway, poi.park, water) to Mapbox GL layer IDs. Style rules walk the tree, match layers, apply HSL transforms. The result: customers keep their existing style configurations, the renderer is completely different underneath.

Styles load dynamically from the Woosmap API via StyleFetcher, not baked into the bundle. Change your style server-side, maps update without redeployment.

Three bundles

Not every integration needs a full map. Some just need geocoding or store search. Building one monolithic bundle wastes bandwidth.

Bun builds three separate bundles from three entry points:

scripts/builder.ts

// Full SDK: map + services + worker
await Bun.build({
 entrypoints: ["./src/maps.ts", "src/worker.ts", "src/painter.ts"],
 splitting: true, minify: true, sourcemap: "linked",
 loader: { ".glsl": "text" },
});

// Services only: API clients, no WebGL
await Bun.build({ entrypoints: ["src/services.ts"], ... });

// Localities: place autocomplete widget
await Bun.build({ entrypoints: ["src/localities.ts"], ... });

GLSL shaders load as text strings via Bun’s loader plugin. No webpack shader-loader, no build-time compilation. The shader source gets inlined in the bundle and compiled at runtime by WebGL.

Environment configuration (local, staging, production) injects API endpoints at build time through define:

retVal[`Bun.env.API_BASE_URL`] = JSON.stringify(environment.API_BASE_URL);
retVal[`Bun.env.ASSETS_BASE_URL`] = JSON.stringify(environment.ASSETS_BASE_URL);

Worker architecture

Tile processing is expensive: protobuf decoding, geometry clipping, feature indexing. Doing it on the main thread blocks interactions.

The SDK spins up web workers from a blob URL constructed at load time:

src/maps.ts

const scriptURL = import.meta.url.replace("maps.js", "worker.js");
const response = `import "${scriptURL}";`;
const blob = new Blob([response], { type: "application/javascript" });
const workerUrl = URL.createObjectURL(blob);

Workers handle tile deserialization and geometry processing. The main thread handles rendering, events, and camera updates. Communication is message-based. Tiles arrive asynchronously, trigger geometry extraction, and the painter picks them up on the next frame.

Offscreen rendering experiment

The maps-offscreen.ts entry point pushes further: move the entire WebGL renderer into a worker using OffscreenCanvas + comlink.

The OnscreenMap lives on the main thread: handles DOM events, gesture recognition, camera state. The OffscreenMap lives in a worker: owns the WebGL context, runs the painter, processes tiles. Camera updates flow from main thread to worker, rendered frames appear on the transferred canvas.

src/woosmap/onscreen-map.ts

export class OnscreenMap {
 offscreenMap: Remote<OffscreenMap>;
 handlers: HandlerManager;
 transform: Transform;

 constructor(element: HTMLElement, options?: object) {
 this.canvas = document.createElement("canvas");
 const offscreen = this.canvas.transferControlToOffscreen();
 // Transfer canvas to worker, all GL happens there
 }
}

The tricky part is camera update batching. Every pan/scroll event would trigger a worker message, overwhelming the channel. The solution: batch camera updates with a timer and requestAnimationFrame, send at most one update per frame interval. Immediate sends for significant zoom changes, deferred sends for continuous panning.

Still experimental. Safari’s OffscreenCanvas support has quirks, and synchronizing the transform state between threads without jank requires careful debouncing.

Symbol placement

Text labels on maps are deceptively hard. The Mapbox GL fork handles:

Glyph atlasing: PBF glyph format, dynamically growing texture atlas (1024x1024 initial, doubles when full), SDF rendering for clean scaling at any size
Collision detection: grid-based spatial index, labels grouped by feature (icon + text placed together, all-or-nothing), sorted by layer priority and symbol-sort-key
Cross-tile continuity: CrossTileSymbolIndex maintains label placement across tile boundaries so labels don’t pop in and out when panning
Variable anchor: if a label’s primary anchor collides, try alternatives. Pre-compute screen positions for each variant, test in order
CJK text: local ideograph font families bypass the glyph server for Chinese, Japanese, Korean characters. Properly sized using browser font metrics

The symbol size evaluation is complex. text-size gets evaluated at five different zoom levels per feature for layout, collision boxes, line placement, and shader interpolation.

One practical fix we added: a maximum label count per bucket to prevent repeated line labels from overflowing. Road names on long highways would generate hundreds of labels. Now they’re capped.

Services integration

The Woosmap layer isn’t just rendering. It includes API clients for the full Woosmap platform:

StoresService: store locator with search, autocomplete, radius queries
DistanceService: matrix routing, isochrones, multiple travel modes (driving, walking, cycling)
LocalitiesService: place autocomplete supporting 70+ languages
DatasetService: query and overlay custom geospatial datasets
TransitService: public transportation routing
DirectionsService: turn-by-turn directions with renderer

Each service handles its own error taxonomy (INVALID_REQUEST, REQUEST_DENIED, OVER_QUERY_LIMIT, MAX_ELEMENTS_EXCEEDED) and throws typed errors (BadRequestError, ForbiddenError, TooManyRequestsError).

Overlays (StoresOverlay, DatasetsOverlay, DirectionsRenderer) connect service responses directly to map layers. Fetch stores, get markers. Compute a route, get a polyline.

Testing

97 test files. Vitest with Playwright for browser testing. The WebGL context needs a real browser, not jsdom.

Handler tests cover the full gesture matrix: mouse drag pan, scroll zoom, keyboard navigation, touch zoom/rotate, double-click zoom, box zoom. Each handler type has its own test file, testing event sequences and resulting transform states.

Style-spec tests validate the expression engine: filter compilation, color space conversions (RGB, HSL, LAB), interpolation, type coercion. These are ported from the Mapbox GL test suite and adapted for the TypeScript rewrite.

Visual regression tests capture screenshots and diff against baselines. Useful for catching rendering changes across the 57 shaders.

bun run test:browser # Vitest + Playwright (Chromium)
npx biome check src # Lint

What’s there

The basics are solid. Fill, line, symbol, raster, background, heatmap, hillshade, fill-extrusion layers all render. The full style expression engine works. Collision detection, variable anchor, text wrapping, cross-tile symbol continuity. Markers with labels, info windows, data layer with per-feature styling. All five service clients.

536 TypeScript files, 57 GLSL shaders. The Google Maps API compatibility layer means existing Woosmap integrations can switch renderers without code changes.

What’s still rough:

Offscreen rendering works but the camera synchronization needs more tuning for smooth panning on slower devices
Complex text shaping is 1:1 codepoint-to-glyph. Arabic, Thai, and other complex scripts need a proper shaper
Bundle size could be smaller with better tree-shaking of the Mapbox GL fork
Line rendering has no dash patterns or gradients yet

About 5MB of TypeScript source. The output bundles are significantly smaller after minification and tree-shaking.

A map style compiler in Python

Sat, 07 Feb 2026 16:00:00 +0200

BAM!

Generating Mapbox GL GL style JSON from Python code instead of editing 3,000-line JSON files by hand. Hierarchical style resolution, a Django-style filter DSL, injection-based layer ordering, and a Go sprite generator called from Python via ctypes.

The problem with style JSON

A Mapbox GL GL style is a single JSON file that describes everything about how a map looks. Background color, road widths at every zoom level, label fonts, icon placement, landcover tints, building extrusion heights. All of it.

A real production style runs to thousands of lines. Ours had over 150 layers. Roads alone need six layer variants each (tunnel casing, tunnel fill, road casing, road fill, bridge casing, bridge fill), and there are eight road classes. That’s 48 road layers before you count labels, oneway arrows, or rail.

Editing this by hand is slow and error-prone. Change the motorway color and you need to find it in six places. Add a new road class and you need to insert layers at exactly the right positions between tunnels and bridges. Reorder a layer and you break z-ordering for everything above it.

Python instead of JSON

The style compiler replaces hand-edited JSON with Python code. You define layers, colors, filters, and style properties in Python. The compiler resolves everything and emits a Mapbox GL GL style JSON file.

python -m map_style --style=streets -o style/streets_classic.json

The output is a standard Mapbox GL GL style: the renderer doesn’t know or care that it was generated. But the source is modular, typed, and DRY.

Layer definitions

A road is defined once. ClassicRoadDataNode generates all six variants:

streets_classic/roads.py

ClassicRoadDataNode(
 "motorway",
 classes=["motorway"],
 feature_type="road.highway.motorway",
 extra_filter=~Q(ramp__eq=1),
 casing_feature_type="road.highway.motorway",
)

This produces:

tunnel_motorway_casing: tunnel stroke
tunnel_motorway: tunnel fill
road_motorway_casing: road stroke
road_motorway: road fill
bridge_motorway_casing: bridge stroke
bridge_motorway: bridge fill

Each variant gets the correct brunnel filter automatically. Tunnel layers filter on brunnel == "tunnel", bridge on brunnel == "bridge", normal roads on brunnel not in ["bridge", "tunnel"].

Rail works the same way: ClassicRailDataNode generates tunnel, road, and bridge variants with optional hatching layers for the cross-ties pattern.

Injection points

With 150+ layers, ordering is everything. Roads must render above landcover. Bridges must render above buildings. Labels above everything. Getting one layer out of place breaks the visual hierarchy.

Instead of maintaining an explicit ordered list, the system uses injection points: named slots that define the rendering order:

generator/data.py

class InjectionsNames(Enum):
 TUNNEL_ROAD_CASING = "tunnel_road_casing"
 TUNNEL_ROAD = "tunnel_road"
 ROAD_AREA = "road_area"
 ROAD_CASING = "road_casing"
 ROAD = "road"
 BUILDING = "_building_injection"
 BRIDGE_ROAD_CASING = "bridge_road_casing"
 BRIDGE_ROAD = "bridge_road"
 BUILDING_3D = "building_3d"
 LABEL = "labels"
 POI_SYMBOL = "poi_symbol"

Layers insert themselves before a named injection point:

stack.add_layer_before(InjectionsNames.ROAD, Layer("road_motorway", ...))
stack.add_layer_before(InjectionsNames.BRIDGE_ROAD, Layer("bridge_motorway", ...))

The Stack maintains the order. Injection points themselves are stripped from the final output. They’re scaffolding, not layers. Adding a new road class doesn’t require knowing the index of every other layer. You just say “this goes in the ROAD group” and the system handles placement.

Filter DSL

Mapbox GL filters are nested JSON arrays. Writing them by hand is unreadable:

["all", ["==", ["get", "class"], "motorway"], ["!", ["in", ["get", "brunnel"], ["literal", ["bridge", "tunnel"]]]]]

The compiler uses Django-style Q objects instead:

Q(class__eq="motorway") & ~Q(brunnel__in=["bridge", "tunnel"])

& means AND, | means OR, ~ means NOT. The ExpressionSet class compiles Q trees to Mapbox GL expressions:

generator/filters.py

OPERATORS = {
 "eq": "==", "neq": "!=",
 "gt": ">", "gte": ">=",
 "lt": "<", "lte": "<=",
}

# Q(class__in=["motorway"]) becomes:
# ["in", ["get", "class"], ["literal", ["motorway"]]]

# Q(brunnel__exists=False) becomes:
# ["!", ["has", "brunnel"]]

Filters compose naturally. The ramp filter for motorway links:

Q(class__in=["motorway"]) & Q(ramp__eq=1)

The non-ramp filter for main motorways:

Q(class__in=["motorway"]) & ~Q(ramp__eq=1)

The Case class builds conditional expressions for layers that vary by feature class, like different icon colors per POI type:

case = Case({"restaurant": Q(class__eq="restaurant"), "hospital": Q(class__eq="hospital")})
case.resolve({"restaurant": "#e74c3c", "hospital": "#3498db"}, default="#666")
# ["case", ["==", ["get", "class"], "restaurant"], "#e74c3c",
# ["==", ["get", "class"], "hospital"], "#3498db", "#666"]

Hierarchical style resolution

A StyleTree organizes paint and layout properties in a dot-separated hierarchy. Child selectors inherit from parents:

streets_classic/style.py

styles = {
 "road": StyleElement(paint=LinePaint(line_cap="round")),
 "road.highway": StyleElement(paint=LinePaint(line_color=ROAD_HIGHWAY_FILL_COLOR, line_width=4)),
 "road.highway.motorway": StyleElement(paint=LinePaint(line_width=6)),
}

Resolving road.highway.motorway walks the tree from root to leaf, collecting all StyleElement instances along the path. Properties merge: the motorway gets line_cap="round" from road, line_color="#fc8" from road.highway, and line_width=6 from its own node.

generator/styler.py

def resolve(self, selector_path: str) -> list[StyleElement]:
 nodes = self.get_node_path(selector_path)
 elements: list[StyleElement] = []
 for node in nodes:
 elements += node.elements
 return elements

Same pattern as CSS cascade, but explicit. You see exactly what inherits from where by reading the selector paths. No specificity wars.

Colors

The color module parses hex, RGB, RGBA, HSL, and HTML color names. More usefully, it does HSL-based transformations:

generator/color.py

Color("#fc8").darken(-0.3).to_rgba()
# Shifts lightness down by 30%, used for deriving label colors from fill colors

All colors live in one file per style:

streets_classic/colors.py

BACKGROUND_COLOR = "rgba(252, 247, 229, 1)"
WATER_COLOR = "rgba(134, 204, 250, 1)"
ROAD_HIGHWAY_FILL_COLOR = "#fc8"
ROAD_HIGHWAY_STROKE_COLOR = "#e9ac77"
ROAD_MINOR_FILL_COLOR = "#fff"
ROAD_MINOR_STROKE_COLOR = "hsl(35, 6%, 80%)"

Change a color constant, regenerate, and every layer using it updates. No grep through JSON.

Pydantic models for the style spec

Every Mapbox GL layer type has a corresponding Pydantic v2 model with strict validation:

generator/mapbox_style.py

class LinePaint(BaseModel):
 model_config = ConfigDict(populate_by_name=True)

 line_color: str | list[Any] | None = Field(None, alias="line-color")
 line_width: float | list[Any] | None = Field(None, alias="line-width")
 line_opacity: float | list[Any] | None = Field(None, alias="line-opacity")
 line_dasharray: list[float] | None = Field(None, alias="line-dasharray")
 line_cap: str | None = Field(None, alias="line-cap")
 # ...

The alias parameter handles the mismatch between Python identifiers (underscores) and Mapbox GL property names (hyphens). line_color in Python becomes line-color in JSON output.

Pydantic catches type errors at definition time, not when the renderer fails to parse the JSON. Pass a string where a number is expected and you get an immediate error.

Sprite generation

Map icons (POI markers, highway shields, oneway arrows) are packed into a sprite sheet: a single PNG with a JSON manifest mapping icon names to pixel regions.

The sprite generator is written in Go for performance. Python calls it through ctypes:

generator/sprite.py

lib = ctypes.CDLL(lib_path)
lib.GenerateSprite.argtypes = [ctypes.c_char_p, ctypes.c_char_p, ctypes.c_int]
lib.GenerateSprite.restype = ctypes.c_char_p

result = lib.GenerateSprite(
 icon_library_path.encode(),
 output_path.encode(),
 pixel_ratio, # 1 for sprite.png, 2 for sprite@2x.png
)

The Go library handles SVG rasterization, SDF (signed distance field) generation for runtime-colorable icons, bin-packing into a texture atlas, and both 1x and 2x output.

Template-based icon names resolve from filter context. When a layer uses icon-image: "{class}_15", the compiler extracts which class values the filter allows and registers each concrete icon (restaurant_15, hospital_15, etc.) for sprite generation.

POI metadata

POI layers carry metadata beyond what Mapbox GL needs. The Woosmap API uses it to support dynamic styling at runtime:

class POIMetadata:
 filter: list[Any]
 symbol_color: str
 text_color: str
 icon: str
 visible: bool

This metadata embeds in the layer’s metadata field (which Mapbox GL ignores but passes through). The API can query which POI categories exist, their colors, and their visibility, without parsing the style expressions.

Feature types follow a hierarchy: poi.school, poi.sports_complex, transit.station.rail. The LayerRegistry maps these to the concrete Mapbox GL layers they affect, enabling Google Maps-style feature type styling through the Woosmap SDK.

Multiple styles

The architecture supports multiple style variants from the same infrastructure. streets_classic is the production style. streets_satellite reuses the same layer definitions, road nodes, and filter DSL with a different color palette tuned for satellite imagery overlay: higher contrast labels, semi-transparent fills, no background color.

Adding a new style variant means writing a new color file and adjusting a few layer properties. The layer structure, injection points, and filter expressions stay the same.

What this gets you

The streets_classic style has ~150 renderable layers. The Python source is organized across about a dozen files: colors, roads, mapping, style tree, POI definitions. Each file is under 300 lines.

The equivalent hand-maintained JSON was one file, thousands of lines, with duplicated filter expressions and no inheritance. Every road color change required finding and editing six layer definitions. Every new road class required inserting layers at the correct positions relative to all other layers.

Now it’s: change a constant in colors.py, run the compiler, get a valid style JSON. Type-checked, with the layer ordering handled by injection points instead of manual index management.