DEV Community: Jimmy Utterström

The Missing Link Between AI Agents and the Code They Modify

Jimmy Utterström — Wed, 25 Mar 2026 12:07:47 +0000

AI coding agents write code confidently, but they don't know why your code looks the way it does. DLD (https://github.com/jimutt/dld-kit) is an open source framework that links code directly to the decisions behind it, so agents read the reasoning before modifying anything. This post covers how I got there and what I've learned so far.

Background

I've been coding since I was 11 or 12, and even though I have a bachelor's degree in embedded systems I'm self-taught in most areas. The main reason I got into this field is curiosity, a drive to understand how things work. That drive was complemented by a creative mind and a joy in building things.

While I find it interesting to understand the fundamentals of how a CPU is constructed at the hardware level, I've always found most joy in creating things that act, move or interact with their environment in other ways. Be it a standard backend service shuffling data between systems, moving pixels around on the screen, or building physical robots.

I suspect many engineers with a similar profile belong to the camp that follows the development of LLMs with both excitement and horror. Horror because we're not sure how the profession will shift, how our skills will be valued, whether we'll be able to adapt quickly enough. Excitement because maybe now is the time we'll actually realise a few more of those side project ideas. Even those of us, myself included, who have aged past 30 and found ourselves in a number of life contexts that consume much of our no longer endless spare time. I don't even have kids, but still find it extremely encouraging that I may now be able to build some of those projects I never thought would see the light of day.

The excitement of being able to realise more ideas is obviously present in professional contexts too, but it's more complex there. It's often combined with aggressive productivity gain targets tied to increased AI use. Many are facing worries that the added complexity from AI-driven development will be difficult to maintain over time with unchanged, or even leaner, staffing. There are many aspects that make the professional adoption of AI more complicated than the personal one, both practically and mentally. And then I'm not even mentioning any of the moral aspects.

Searching for the right way to leverage the mechanical advantage

The core question I keep coming back to is: how do you best leverage the mechanical advantage of using AI to build complex systems faster while not only counting on further future improvements of the performance of the LLMs themselves to guarantee a process that works also in the longer term?

I've been spending the past year or so trying different approaches. In my day job at Storytel, an audiobook and ebook streaming service, I work as a staff engineer with AI adoption as part of my responsibilities, which means I both get to experiment personally and get a broader view of how different teams approach the problem. And I've tried a lot of things: from fairly unstructured "vibe coding" to more disciplined spec-driven development approaches.

The unstructured approach works surprisingly well for small, isolated tasks. And as new models are released it starts working for larger and larger chunks of code. Write a prompt, get code, review it, move on. But once your project grows beyond a certain complexity and the related business context is no longer as clearly mirrored by the code, things start falling apart. The AI doesn't remember why that retry logic has a specific timeout, or why that validation step exists despite looking redundant. And honestly, after a long enough break, or a sufficiently ambitious round of layoffs, neither does anyone else.

Spec-driven development (SDD) was the next thing I explored: write a specification first, then let the AI implement against it. Tools like GitHub's Spec Kit, OpenSpec and similar frameworks have emerged to support this workflow. And they often help in achieving few-prompt implementation with reasonable functional correctness. But I found some friction points. Specs tend to drift from the actual implementation over time. The bigger the project gets, the harder it becomes to keep them in sync. And there's a certain all-or-nothing quality to many SDD approaches: either you write the full spec upfront, or you're back to unstructured prompting. For someone that often works in a hybrid mode, writing some things manually and having AI fill in other parts, that rigidity can feel like overhead rather than help. It can also be hard to combine with manual programming, where you want the flexibility to make implementation decisions as you go without first updating a spec document.

There's also a more fundamental issue that kept nagging me. Many SDD approaches encourage you to describe every edge case and behavior in the spec before implementation. But human language is inherently imprecise, and trying to exhaustively specify system behavior in prose is a bit like trying to describe a painting in enough detail that someone could reproduce it pixel by pixel. You can get close, but the closer you try to get, the more verbose and ambiguous it becomes. At some point the implementation is the spec, and any parallel description of it is just a lossy approximation that you now also need to maintain. It's a variation of the same problem we've seen with overly detailed UML diagrams, exhaustive requirements documents, and every other attempt to fully capture a system in a representation that isn't the system itself.

When it comes to ensuring correctness on a detailed level in software systems, my personal opinion is that it should be done through automated tests and not natural language specs. But you can of course try to combine the two by finding a good balance. Be it through Gherkin syntax and attempting to elevate the test cases so that they're accessible by more roles than only engineers, or by simply accepting that your tests are written on a level where general coding skills are still required for maintaining and validating their implementation.

The idea behind DLD

These experiences eventually led me to think about what I actually needed: not a complete specification document, but a way to preserve the reasoning behind implementation choices in a format that both I and AI agents could use effectively.

The initial concept for what became Decision-Linked Development (DLD) was actually born from a two-hour car drive. I spent the drive talking through my frustrations and ideas into a voice recorder, then had an LLM help me turn that raw transcript into a structured concept paper. Which felt fitting, given that the whole point of DLD is about capturing knowledge before it evaporates.

The core idea borrows from event sourcing: instead of maintaining a mutable specification document that you have to keep up to date, you maintain an append-only log of decisions. Each decision captures what was decided, why, and which parts of the code it relates to. Decisions can be superseded by newer decisions, but they're never edited or deleted. The full history is preserved.

The key mechanism is the @decision(DL-XXX) annotation in code. When an AI agent encounters this annotation while modifying code, it has an explicit signal to look up the referenced decision before proceeding. This transforms "the agent should intuitively know to check for context" from a hope into a reliable trigger. And if the planned change conflicts with an existing decision, the agent tells you about it and suggests recording a new decision instead of silently breaking things.

The consolidated specification, if you want one, is generated from the decision log. It's a derived view, never manually maintained. Like a materialised view in a database: useful for reading, but not the source of truth.

What it looks like in practice

The framework is used through a set of slash commands. A typical workflow for a new feature looks something like this:

/dld-plan breaks down the feature into a set of decisions interactively. You describe what you're building, and the agent helps you slice it into reasonably scoped decisions.
/dld-implement DL-001 takes a proposed decision and implements it: writes the code, adds @decision annotations, and marks the decision as accepted.
/dld-snapshot regenerates the overview documentation from the decision log.

For smaller, isolated changes like a bugfix or a single design choice, /dld-decide records one decision directly without the planning step.

A decision record is a markdown file with YAML frontmatter. Here's a real one from my bird recording project:

---
id: DL-045
title: "Species/hour activity matrix on dashboard"
status: accepted
namespace: web
tags: [web-dashboard]
references:
  - path: apps/web/src/components/ActivityMatrix.svelte
  - path: apps/web/src/components/Dashboard.svelte
---

## Context
The dashboard is the landing page. BirdNET-Go has a species/hour
activity matrix that shows detection counts per species per hour —
a compact way to see what's been active and when. This is the primary
visualization for the Gillerkvitter dashboard.

## Decision
Build a species/hour activity matrix as the main dashboard component:
- Rows: Species (sorted by total detections or recency)
- Columns: Hours of the day
- Cells: Detection count, with color intensity reflecting volume
- Default view: 24-hour period, scrolled to show the current 2-3 hours
- Live update: Matrix refreshes via API polling (per DL-040)

## Rationale
The hour-by-species matrix gives an immediate overview of activity
patterns — which species are present and when they're most active.

## Consequences
- Needs a backend query that returns detections grouped by species
  and hour
- Color intensity scale needs careful design to work with the nature
  palette (DL-044)
- Initial scroll position should auto-focus on the current time

Notice how it references other decisions inline (DL-040 for the polling approach, DL-044 for the color palette). That cross-referencing happens naturally as decisions accumulate, and it's one of the things that helps the AI agent understand how different parts of the system relate.

And the corresponding code annotation is just a comment:

// @decision(DL-008)
function retryWithBackoff(fn: () => Promise<Response>): Promise<Response> {
  // ...
}

When an AI agent encounters that annotation, it reads DL-008 before touching the function. If the change it's about to make conflicts with the decision, it stops and tells you.

The framework also includes /dld-audit for detecting drift between decisions and code, and a /dld-retrofit command for bootstrapping decisions from an existing codebase. You don't need to start from scratch.

What makes it practical for hybrid workflows

One thing I specifically wanted was for this to work in a casual, incremental way. A single decision log means you don't need to spend your thinking effort on deciding what belongs in a user story vs. a detailed implementation plan, whether you need to merge two specs because the feature scope changed, or how to handle a change that partially supersedes an earlier decision. You just record decisions as they come up, at whatever level of abstraction is natural for that particular choice. Some decisions are high-level product choices, others are low-level implementation details driven by infrastructure constraints. They all live in the same flat, sequential log.

You also don't need to use it for everything. It's perfectly fine to use DLD for the parts of your codebase where non-obvious decisions accumulate, and not bother annotating straightforward, idiomatic code that speaks for itself.

There's also a passive mode for teams that want living documentation without changing how they work day to day. You run the initial bootstrap once to generate decisions from the existing codebase, then schedule the audit and snapshot commands to run automatically via CI. The audit detects unreferenced code changes, infers new decisions, and back-annotates the code. No one needs to invoke any DLD commands during their normal workflow.

Testing it in practice

I've been using DLD on my personal side project, Gillerkvitter, an off-grid bird song recording station running on a solar-powered Raspberry Pi in northern Sweden. It records bird songs, runs them through BirdNET for species identification, and syncs the detections to a cloud server with a web dashboard. The system spans hardware, embedded software, a Bun.js backend API, PostgreSQL, and an Astro/Svelte frontend. Quite a few moving parts.

The project now has 99 accepted decisions in its log, and so far it's been a really encouraging test case for the framework. The added documentation has really helped both me and the coding agents to easily pick up from a previous session and not lose track of how things are connected. It's the kind of broad, multi-domain project where you can go weeks without touching a particular subsystem, and when you come back, the decision log tells you exactly why things look the way they do.

We're also trying it at Storytel in a team setting, with promising early results. One thing that's been interesting is how reviewing the proposed decisions before implementation can shift verification earlier in the process. You catch misunderstandings at the decision level rather than in code review, which sometimes makes it more comfortable to accept larger implementation PRs. You've already agreed on the approach; the PR is "just" the execution. And nobody had to get a master's degree in PRD writing to get there, since each decision is a small, focused artifact rather than a chapter in an ever-growing requirements novel.

Being honest about what this is

I want to be upfront: DLD in its current form is a collection of Claude Code skills. In practice that means markdown-based prompts that instruct the AI agent, backed by some Bash scripts for file management and validation. I'm neither ashamed of that, nor do I want to inflate what it is. The skills follow the Agent Skills open standard and work with Claude Code today, and through the Tessl "package manager" with other AI coding tools as well.

What matters to me is not the sophistication of the implementation, but whether the underlying idea holds up. And so far, based on my own experience and the early team usage at Storytel, it seems at least as promising as other approaches. The decision log is a simple concept, the annotations are just code comments, and the projections are generated markdown files. But combined, they solve a real problem: keeping decision context accessible when AI agents (and humans returning after a break) modify code they didn't write.

Try it out

If this resonates with your experience of AI-assisted development, you might find DLD useful. The project is open source at github.com/jimutt/dld-kit and still pre-v1, so expect rough edges and potentially breaking changes to the process. If you've ever come back to a project after a month and wondered "why on earth did I do it this way?", or if you've watched an AI agent cheerfully refactor away a workaround that existed for a very good reason, you know the problem DLD is trying to solve.

I started this post talking about curiosity and the joy of building things. DLD came from the same place: a genuine attempt to figure out how to keep building effectively as the tools change around us. It's not the final answer, but it's a practical step that's working for me so far, right here, right now. I'd love to hear if it works for you too.

Removed from Twitter for my actions 12 years ago (as a 12 year old)

Jimmy Utterström — Fri, 18 Oct 2019 18:28:21 +0000

Update: This night I got a new mail from Twitter saying that I might actually be able to get my account, including tweets, back. And I actually got a link to a reactivation page where I only needed to confirm my name and phone number. So that's great and more like how I would have expected it to work from the beginning. I'm not sure though whether their automated process for handling these issues is poorly designed and is supposed to work like this. Or if there's some kind of manual review step that needs to be done for these cases, before they tell you it might be possible to just unlock the account.

I'm happy that it seems like it might get resolved, but it remains an extremely poor user experience.

Twitter is a popular platform among many web developers, myself included, which is why I want to share an important lesson I learned today: don't try to correct past mistakes in order to be honest, and never forget anything you did before you turned 13, you WILL be punished

What follows is a text full of self pity where I'm whining about Twitters policy to punish and never forgive in the name of GDPR. You'll most likely want to go read an other DEV post.

I've had my @jimutt Twitter account for a pretty long time. But I didn't actually start using it actively until the last couple of years. I've been slightly annoyed by the fact that my Twitter account's date of birth has been incorrect. I'm born 1994 but on Twitter it said 1993.

So, as a victim of my own stupidity I thought "Why not change the year to be correct and honest". And so I did, thinking that I'd probably misclicked during the account creation and selected the wrong year. I changed it and didn't get any kind of warning about what would happen next; immediately after changing my birth date my account was locked and made completely inaccessible. The reason stated was the fact that Twitter is only available for people who are 13 years or older. And that they suspect I was under 13 when I created my account. I don't know if it's true or not, because I don't remember which websites I signed up for 12 years ago, but I'll trust that they hopefully at least have got my account registration date correct.

What I fail to see is why locking the account of a, now 24 year old, adult is to be considered the preferred choice. Wouldn't it make a little more sense to perhaps delete the tweets (if any) I made as 12 year old? Guess not..

Now I've read that they've started to reactivate some accounts that has been locked because of an invalid age. But if there is to be any chance at all to get my account reactivated I guess I at the very least will need to trust them with a copy of my driving license. With my small amount of followers I'll probably just create a new one though, and make sure to be very careful when touching my account settings in the future. 🙄

Rant over!

Debugging Svelte apps with the newly released Svelte Devtools

Jimmy Utterström — Sat, 28 Sep 2019 13:37:29 +0000

A minor nuisance with using Svelte 3 (if you're coming from Vue or React) might be the lack of a browser plugin like Vue devtools, it offers convenient ways to inspect the app's component tree and direct access to component state.

There is now a community created devtools extension for Svelte, made by Timothy Johnson, which gives you some of the basic functionality found in similar tools for other frameworks.

Installation

Firefox - Install from the official store
Chrome - The extension is, at the time of writing, under review for Chrome so you'll have to manually download a zip package according to the instructions in the Readme: https://github.com/RedHatter/svelte-devtools/blob/master/README.md

Usage

Svelte Devtools only work with Svelte version 3.12 or greater, so you might want to make sure that you've updated your Svelte NPM dependency.

1. Create a new Svelte app and compile it with development mode enabled

If you don't have a custom Svelte 3 project to use you can just go with the basic app template:

npx degit sveltejs/template svelte-app
cd svelte-app
npm install

npm run dev

2. Open the app in Firefox or Chrome, press F12 and select the "Svelte tab"

3. Inspect state & components and filter what's shown

In the main panel you can view and inspect all components and the HTML elements they contain. A component's props are shown both in the element/component view and in the state panel to the right.

Props and state can be updated directly from the devtools:

You can also filter which information you want to be shown, for example if you'd like to hide HTML elements and only show components.

Like what you see? At least make sure to star the repo on GitHub (https://github.com/RedHatter/svelte-devtools) and perhaps check if RedHatter wants any help on improving the tool.

Also check out my earlier post on Svelte: Boost your legacy apps with Svelte 3 components

How to write Go code and make it run on Adafruit Feather or Arduino

Jimmy Utterström — Tue, 27 Aug 2019 10:09:50 +0000

Did you know that you can use Go for embedded systems (like the Arduino Uno or Adafruit Feather)? TinyGo is a light-weight Go compiler specifically created for that purpose. Though the project is still very young, so there are quirks and missing functionality that hasn't been implemented yet.

TinyGo supports a subset of the Go programming language, for a more detailed description please refer to this page. Still, many parts of the language are already supported, and for example Goroutines seems to be working reasonably well. The documentation is still not very extensive and the AVR compilation (for use with for example Arduino Uno) seems to be quite experimental at the time of writing. Therefore I will be using an Adafruit Feather M0 board with an ARM MCU for this post.

This guide will tell you how to setup your computer for TinyGo development and how to flash a simple blinking LED program to the board. The instructions have been tested on an Adafruit Feather M0 board, but should also work for these two boards (if the compilation target is changed to the corresponding board):

Adafruit ItsyBitsy M0 (build -target=itsybitsy-m0)
Adafruit Trinket M0 (build -target=trinket-m0)

We will be using the UF2 bootloader which makes the Feather appear as a USB drive when in bootloader mode; allowing easy copy-paste of the compiled binary. The Feather will then restart and load the program.

Prerequisites

Very basic Go knowledge
Knowing how to use the Arduino IDE together with a Feather Board (to install the UF2 bootloader)
A compatible dev board

TinyGo Installation

Linux

Download and install TinyGo:

$ wget https://github.com/tinygo-org/tinygo/releases/download/v0.7.1/tinygo_0.7.1_amd64.deb

$ sudo apt-get install ./tinygo_0.7.1_amd64.deb

Add TinyGo to PATH (log out and in again for the changes to be applied): Open ~/.profile in your editor of choice and add the below line to the end of the file:

export PATH=$PATH:/usr/local/tinygo/bin

Windows

If you've enabled Windows Subsystem for Linux (WSL) you should be able to follow the Linux instructions above. Otherwise I recommend looking at the Docker image provided by the TinyGo team: https://tinygo.org/getting-started/using-docker/

macOS

I'm unfortunately not a Mac user so I won't be able to provide any help here, but installation on macOS is of course covered by the official docs: https://tinygo.org/getting-started/macos/

Configure UF2 bootloader

The UF2 bootloader removes the need of installing separate tooling for flashing (the BOSSA cli in this case). Instead, flashing is done through dropping a file onto a removable drive.

1. Enter Bootloader mode

Connect the Feather M0 board to the computer.
Double-press the reset button quickly - the board should now go into Bootloader mode, and the red built-in #13 LED should start fade in and out.

Now check if your computer has detected a new USB drive (should be present in /media/{your_user}/ on Linux). If that's the case, you're already ready to go (pun intended) and can skip the next part! If not, you need to install the UF2 Bootloader first.

2. Install Bootloader if necessary

Using the standard Arduino IDE, flash the correct UF2 Bootloader to your board. Please refer to the official Adafruit documentation for this step: https://learn.adafruit.com/installing-circuitpython-on-samd21-boards/installing-the-uf2-bootloader

If you're feeling too lazy to read the documentation: on the Feather M0 board you need to download this sketch file and upload it to the board through the Arduino IDE)

IMPORTANT! Make sure you download the correct bootloader file for your board, or you will risk bricking it.

Build and flash/upload a simple program

The classic "blink an LED" example for microcontrollers may be overused and not very fancy. As this post's primary purpose is bringing attention to TinyGo and showing how to get started, you will have to wait until later for more interesting use cases though.

1. Create directory and an empty Go file

Create a new directory called "feather-blink". Navigate to the directory and create an empty feather-blink.go file.

2. Make the LED blink

Add the following skeleton to the feather-blink.go file:

package main

import (
     "machine"
     "time"
)

func main() {
}

The "machine" import, which will be automatically resolved when compiling, allows access to the hardware. The available APIs in the machine package differ depending on the board used. To know exactly which types, constants, and methods that are available, you can look at the source code in the TinyGo repository. I suppose this type of information will most likely be included in written documentation later on.

Generic machine.go with definition and methods for the "Pin" type
board_feather-m0.go - Contains board-specific constants for PIN bindings, UART, SPI etc.

To make the on-board LED blink we can access it through the machine.LED constant (LED = D13) which has already been declared for us. We then configure it as an output. In the main loop, we use the Sleep function from the time package to add a delay before toggling the pin.

package main

import (
     "machine"
     "time"
)

func main() {
     led := machine.LED
     led.Configure(machine.PinConfig{Mode: machine.PinOutput})

     for {
          led.Low()
          time.Sleep(time.Millisecond * 1000)
          led.High()
          time.Sleep(time.Millisecond * 1000)
     }
}

That's it! Now we just need to build the program and flash it to the board.

3. Build program and flash it onto the Feather

Connect the Feather board to the computer and touble-click the reset button to put it in bootloader mode.
Check the path for the new USB drive (on Linux it's most likely /media/{your username}/FEATHERBOOT)
Build the program and point the output to the Feather device

$ tinygo build -target=feather-m0 -o=/media/{your_user}/FEATHERBOOT/flash.uf2 feather-blink.go

If the build is successful, the Feather should now automatically restart and run the the program. You should be able to verify it by checking that the LED is blinking, as specified in the code, instead of fading in and out as it did in the bootloader mode.

If you want to flash a new version to the board you need to first put it into the bootloader mode again.

Resources and further reading

TinyGo Website
TinyGo has its own channel in the Gophers slack. Get your invite here: https://invite.slack.golangbridge.org/
Buy a Feather M0 board: https://www.adafruit.com/product/2772 (it's available in different versions, there's for example one with an Micro SD card slot as well)
If you're new to Go you might want to checkout this interactive walkthrough: https://tour.golang.org

Boost your legacy apps with Svelte 3 components

Jimmy Utterström — Fri, 21 Jun 2019 14:15:01 +0000

There sure has been some well deserved fuzz around Svelte 3 lately, but maybe not enough? It's an amazing light-weight framework without a heavy runtime and with very little overhead. This makes it a suitable choice for more than just SPAs and isomorphic web apps.

Did you know that you can create a Svelte component and with almost no extra steps distribute- and use it like any classic old Javascript library through a global constructor (let myComponent = new MyComponent())?

Svelte components by default compiles to standard JavaScript classes so you only need to add an IIFE build with your component. I'll briefly show you how that's done with Rollup and how the component is used. It's not a big difference to the official app starter template (https://github.com/sveltejs/template) but I think it can be easy to miss how convenient Svelte is for distributing and consuming individual components.

I will use a simple example component of mine to demonstrate. It renders a Leaflet map and lets the user select a position. An event is emitted when the selected location changes (which can be used in order to update a form field for example) and the map allows props for configuring for example initial lat/lng and zoom level.

The component can be found here: https://github.com/jimutt/svelte-pick-a-place

It can also be installed with npm: npm install svelte-pick-a-place

(the component is primarily created for experimental use and it's simple enough to argue that using Svelte to build might be overkill)

If you were to use it within a Svelte app it would probably look something like this:

<script>
  import PickAPlace from 'svelte-pick-a-place';
</script>

<PickAPlace leaflet={leaflet} on:update={() => console.log('Update!')} on:save={() =>
console.log('On save!')} />

But what if we want to use it in a legacy app built with for example Bootstrap 3 and lots of jQuery where there's no sign of Node.js? No problem! We'll just use the IIFE build and instantiate the component class through its global constructor:

<link rel="stylesheet" href="https://unpkg.com/svelte-pick-a-place@latest/dist/pick-a-place.css">
<script src="https://unpkg.com/svelte-pick-a-place@latest/dist/pick-a-place.min.js"></script>

let pickAPlace = new PickAPlace({
  target: document.getElementById('map'),
  props: {
    leaflet: window.L,
    buttons: false
  }
});

// Listen to events through component.$on('eventName', callback)
pickAPlace.$on('update', ({ detail }) => {
  console.log('New position: ', detail);
  // Here we could for example populate an input field with the new value
});

// Update a prop with $set, or set the 'accessors' compiler option
// to true to automatically generate getters and setters for all props
pickAPlace.$set({ buttons: true });

Codepen demo with Bootstrap: https://codepen.io/jimutt/pen/ZgaYBP

As you can see props and events can be easily accessed through the class API. Unfortunately there's not a convenient way to add slot content at the moment though.

Build config

For the Pick a place component the production build entry point is the file src/components/components.module.js:

export { default } from './PickAPlace.svelte';

It contains a default export with the PickAPlace component. If you were to export multiple components in the same package and wanted to instantiate them namespaced like new MyPackageName.Component1() you could use named exports instead.

The file is specified as the input for production builds in rollup.config.js:

//rollup.config.js
input: !production ? 'src/main.js' : 'src/components/components.module.js',

In rollup.config.js we've added several outputs to support multiple ways of consuming the component:

//rollup.config.js
output: [
   { file: 'dist/index.min.mjs', format: 'es' },
   { file: 'dist/index.min.js', format: 'umd', name },
   { file: 'dist/pick-a-place.min.js', format: 'iife', name }
]
// "name" is set to PickAPlace

As you've probably already figured out it's the last output definition that should be by legacy apps. With the above output configuration we allow consuming the component both from a modern app with a Node.js-based environment and from legacy apps.

The PickAPlace component was created from this project template and then slightly adapted: https://github.com/YogliB/svelte-component-template

That's all I had to say! Just wanted to post a quick reminder of Svelte's versatility and that it's a great choice for more than just complete web apps!

Generate merged GeoTIFF imagery from web maps (xyz tile servers) with Python

Jimmy Utterström — Wed, 05 Jun 2019 21:07:51 +0000

This guide will show you how to programmatically download map imagery from a web map (often referred to as slippy maps) tile server, georeference it and save it as a GeoTIFF. The GeoTIFF image can later be used for other purposes, in my case I used it to colorize a LIDAR data point cloud.

Prerequisites:

Very basic Python knowledge (I'm really not a Python dev myself)
GDAL with its Python bindings (if you're using Conda you can just follow along with the instructions below)

If you're just here looking for the finished source code you'll find it in this repo: https://github.com/jimutt/tiles-to-tiff

Web maps and the XYZ tile format

Most online maps uses a shared way to render the map. Most maps are visualized by using multiple 256x256px raster tiles. The correct tiles are loaded by providing their x, y and z coordinates. Where z corresponds to the current zoom level.

For example Open Street Map tiles can be fetched with an URL following this pattern: https://a.tile.openstreetmap.org/{z}/{x}/{y}.png

The x, y and z parameters are integers and works as described on the OSM wiki:

X goes from 0 (left edge is 180 °W) to 2^zoom − 1 (right edge is 180 °E)
Y goes from 0 (top edge is 85.0511 °N) to 2^zoom − 1 (bottom edge is 85.0511 °S) in a Mercator projection

For the curious, the number 85.0511 is the result of arctan(sinh(π)). By using this bound, the entire map becomes a (very large) square.

For a zoom level of n the number of tiles needed to cover the whole world is equal to 2^n × 2^n .

Project setup

We'll be using Python together with GDAL which provides lots of convenient utilities for manipulation of geospatial raster data.

I'm using Conda to manage my Python environment as I find it to be very convenient for setting up isolated environments with easy installation of third party dependencies.

Create and activate a new Conda environment with gdal as a dependency:

conda create -n env_name gdal
conda activate env_name

Convert latitude and longitude to corresponding tiles

Create a file called tile_convert.py for conversion from WGS84 coordinates to the corresponding tile at the specified zoom level (this fill will be containing various utility functions for transformation between WGS84 coordinates and tile names):

from math import log, tan, radians, cos, pi


def sec(x):
    return(1/cos(x))


def latlon_to_xyz(lat, lon, z):
    tile_count = pow(2, z)
    x = (lon + 180) / 360
    y = (1 - log(tan(radians(lat)) + sec(radians(lat))) / pi) / 2
    return(tile_count*x, tile_count*y)

In order to derive tile name from latitude and longitude a number of operations has to be executed. Combine the below steps and you'll end up with the latlon_to_xyz function:

Calculate the total number of tiles at the current zoom level:
tile_count = 2^z
Reproject lat and lon to the Mercator projection (EPSG:3857).
x = lon
y = log(tan(lat) + sec(lat))
Transform x and y values to fit within the range of 0 - 1 and set origin to top left corner.
x = (lon + 180) / 360
y = (1 − (y / π)) / 2
Multiply x and y by the number of tiles.

Next we'll add a new function (to the same file) which allows us to get the range of tiles for a specified rectangular area/bounding box:

def bbox_to_xyz(lon_min, lon_max, lat_min, lat_max, z):
    x_min, y_max = latlon_to_xyz(lat_min, lon_min, z)
    x_max, y_min = latlon_to_xyz(lat_max, lon_max, z)
    return(floor(x_min), floor(x_max),
           floor(y_min), floor(y_max))

Now we know how to calculate which individual tiles we need in order to cover a bounding box which corners are specified as WGS84 coordinates!

Tile download

To download a map tile all you need to do is to send a GET request that matches the URL specification provided by the tile server. But make sure that you follow the user agreement/terms of service for the tile server you're accessing!

Create a new Python file called tiles_to_tiff.py. This will be our main script which will use download the required tiles, georeference each tile and then merge them into a single image.

import math
import urllib.request
import os

#---------- CONFIGURATION -----------#
tile_server = "https://api.mapbox.com/v4/mapbox.satellite/{z}/{x}/{y}.png?access_token=" + os.environ.get(
    'MAPBOX_ACCESS_TOKEN')
temp_dir = os.path.join(os.path.dirname(__file__), 'temp')
output_dir = os.path.join(os.path.dirname(__file__), 'output')
zoom = 16
lon_min = 21.49147
lon_max = 21.5
lat_min = 65.31016
lat_max = 65.31688
#-----------------------------------#


def download_tile(x, y, z, tile_server):
    url = tile_server.replace(
        "{x}", str(x)).replace(
        "{y}", str(y)).replace(
        "{z}", str(z))
    path = f'{temp_dir}/{x}_{y}_{z}.png'
    urllib.request.urlretrieve(url, path)
    return(path)

The download_tile function calls the specified tile server to download the requested tile and saves it as a PNG file in the output directory.

Create an empty "temp" folder in your workspace and add the below line to tiles_to_tiff.py:

download_tile(0,0,0, tile_server)

Run it to validate that the download function is working:

$ python tiles_to_tiff.py

If you're able to execute the script successfully you should now see a 256x256px PNG image showing the whole world in the temp directory.

Download tiles that intersects bounding box

Chances are high that you need a large image with higher resolution than what fits within a single tile. Therefore we'll use the bbox_to_xyz function to get the range of tiles needed and then we'll loop through every tile and pass it to the download function. This could be done with multiple parallel requests to make it more efficient, but for now it's being kept as simple as possible.

x_min, x_max, y_min, y_max = bbox_to_xyz(
    lon_min, lon_max, lat_min, lat_max, zoom)

print(f"Downloading {(x_max - x_min + 1) * (y_max - y_min + 1)} tiles")

for x in range(x_min, x_max + 1):
    for y in range(y_min, y_max + 1):
        print(f"{x},{y}")
        download_tile(x, y, zoom, tile_server)

print("Download complete")

The above code will download all required tiles as standard, non georeferenced, PNG images. Later we are going to merge all tiles to a single picture and for that we'll use the handy gdal_merge.py script. Though it requires that we georeferenced the input imagery first.

Georeferencing

In order to georeference the downloaded tiles we first need to reverse the translation we performed from latitude and longitude to the tile name format. We need to know the coordinates for each of the four corners of the tile. Then we'll use gdal.Translate to save the image as a TIFF file with embedded geolocation data.

If we remember the steps needed to go from WGS84 coordinates to the XYZ tile names we can also figure out how to retrieve the min and max longitude from a tile with the following function. Add the function to the tile_convert.py file.

def x_to_lat_edges(x, z):
    tile_count = pow(2, z)
    unit = 360 / tile_count
    lon1 = -180 + x * unit
    lon2 = lon1 + unit
    return(lon1, lon2)

For the latitude conversion we'll use the same approach but an additional function is added to translate back from the Mercator projection:

def mercatorToLat(mercatorY):
    return(degrees(atan(sinh(mercatorY))))


def y_to_lat_edges(y, z):
    tile_count = pow(2, z)
    unit = 1 / tile_count
    relative_y1 = y * unit
    relative_y2 = relative_y1 + unit
    lat1 = mercatorToLat(pi * (1 - 2 * relative_y1))
    lat2 = mercatorToLat(pi * (1 - 2 * relative_y2))
    return(lat1, lat2)

With these functions in place we'll write a function that returns an array with the min and max longitude and latitude values in the same order as expected by the outputBounds parameter for the gdal.Translate method. Add the tile_edges function to tile_Convert.py.

def tile_edges(x, y, z):
    lat1, lat2 = y_to_lat_edges(y, z)
    lon1, lon2 = x_to_lon_edges(x, z)
    return[lon1, lat1, lon2, lat2]

Finally we will write a georeference_raster_tile function in tiles_to_tiff.py and then call the function from the download loop:

def georeference_raster_tile(x, y, z, path):
    bounds = tile_edges(x, y, z)
    filename, extension = os.path.splitext(path)
    gdal.Translate(filename + '.tif',
                   path,
                   outputSRS='EPSG:4326',
                   outputBounds=bounds)

for x in range(x_min, x_max + 1):
    for y in range(y_min, y_max + 1):
        print(f"{x},{y}")
        png_path = download_tile(x, y, zoom, tile_server)
        georeference_raster_tile(x, y, zoom, png_path)

Merge tiles to one large image

As we've already included a dependency to GDAL I chose to also use a GDAL python script to merge the tile images. We'll be invoking gdal_merge.py to do the work for us. You will need to add imports for glob and subprocess first.

def merge_tiles(input_pattern, output_path):
    merge_command = ['gdal_merge.py', '-o', output_path]

    for name in glob.glob(input_pattern):
        merge_command.append(name)

    subprocess.call(merge_command)

Create a folder called "output" in your workspace. Set the lon_min, lon_max, lat_min and lat_max to your liking as well as the zoom. I'm using these settings:

zoom = 15
lon_min = 21.49147
lon_max = 21.5
lat_min = 65.31016
lat_max = 65.31688

Add a call to the merge_tiles function at the bottom of tiles_to_tiff.py.

for x in range(x_min, x_max + 1):
    for y in range(y_min, y_max + 1):
        print(f"{x},{y}")
        png_path = download_tile(x, y, zoom, tile_server)
        georeference_raster_tile(x, y, zoom, png_path)

print("Download complete")

print("Merging tiles")
merge_tiles(temp_dir + '/*.tif', output_dir + '/merged.tif')
print("Merge complete")

Clear temp directory

Before we run the script and take a look at the results you might want to add an automatic cleanup of the temp folder. I'm doing it by importing shutil for removing the temp directory to then recreate it:

shutil.rmtree(temp_dir)
os.makedirs(temp_dir)

Showtime!

Now let's run the script and inspect the output. I'm using the bounding box specified earlier and aerial imagery from Mapbox.

$ python tiles_to_tiff.py

Output:

Downloading 8 tiles
36680,16917
36680,16918
36680,16919
36680,16920
36681,16917
36681,16918
36681,16919
36681,16920
Download complete
Merging tiles
0...10...20...30...40...50...60...70...80...90...100 - done.
Merge complete

When inspecting the "output" folder it now contains a single stitched TIFF image of the specified area.

When opened in a standard image viewer it looks just like any other raster image, but if you import it to QGIS you'll be able to visually verify that it has been georeferenced correctly:

There you go! Source is available here: https://github.com/jimutt/tiles-to-tiff