This post is about a spatial coordinate system I’ve been playing around with, z-quads. Unlike most commonly used coordinate systems a z-quad doesn’t represent a point but a square with an area.

To the right are some examples of quads of increasing accuracy, gradually zooming in on Århus. (The quads are the red rectangles). The first one that covers northern Germany, some of England, and half of Denmark, is quad `637`

which has zoom level 5. The one that covers all of Århus is `163241`

which has zoom level 9. Going further down to zoom level 15 is `668638046`

which covers part of the center of Århus, and finally at zoom level 19 is `171171340006`

which covers just a couple of houses.

This should give a rough sense of how the system works. A quad is an integer, typically 64 bits, which represents some square area on the earth. Each quad has a zoom level associated with it and higher numbers have higher zoom levels. There’s a lot more to it than that but that’s the core of it.

Below I’ll describe how z-quads are constructed, which is pretty straightforward. Then I’ll look at how to operate on them: how to convert to and from them, zoom in and out, that kind of thing.

## Divide, divide, divide some more

For a hobby project I’m working on I needed to represent a large set of geographic coordinates. They happen to represent positions of bus and train stops but that’s not super important. To the right is a diagram that illustrates what I had in mind when I started playing around with this. What I wanted really was a way to divide the world evenly into squares of different sizes that I could divide my positions into. (For simplicity I’ve scaled the world down to a 1×1 unit square). Each of the three colored squares here should have some unique integer id. When I say “divide the world evenly” I mean that they’re not arbitrary squares, they’re on the grid you get if you divide the whole square into in four equal parts, then divide each of those into four as well, and so on and so on.

It seemed intuitively reasonable that you’d want the entire space to be represented by `0`

.

This is zoom level 0. Zooming down one level, you might divide `0`

into four parts and call them 1-4,

This is zoom level 1. Then you can keep going and do the same again to get zoom level 2,

At each new zoom level you add 4 times as many new quads as you had on the previous level so where level 2 has 16, level 3 will have 64 and level 4 will have 256.

This is how z-quads are constructed. Pretty simple right? Already, by the way, we know the id of the blue square from the beginning because it’s there at zoom level 2: it’s quad `14`

. And just as a reminder, at this point we’re playing around on the unit square but it’s just a matter of scaling the values back up to get coordinates on the earth. Here’s `14`

again, scaled back up:

One thing you may notice if you look closely at how the quads at zoom level 2 are numbered is that they look of out of sequence. You might expect them to be numbered 5-8 on the top row, 9-12 on the next, and so on. Instead they’re numbered in zig-zag, like this:

So they zig-zag within each of the four parts of the big square, and also when going between the four parts. That’s because it turns out to be really convenient when you divide a quad to have all the quads in the subdivisions be contiguous. So the children of 1 are 5-8, of 2 are 9-12, and so on. We’ll end up relying on that constantly later on. (The numbering within each level it known as a Z-order or *Moreton order* curve).

Okay, so now I’ve postulated way to divide the unit square, by which I mean the surface of the earth, into regular parts. The next step is to figure out how to operate on them which is where it’ll become clear why this number is is particularly appealing.

## Zoom bias

Given a quad there are many operations that you might conceivably want to perform. You might want to know which quad is its parent (that is, the quad that contains it at the zoom level above) or the parent’s parent, etc. Given two quads you might want to know whether one contains the other. Or you might want to find the most specific quad that contains both of them.

The first thing we’ll look at is how to get the parent of a quad. To explain that I need to introduce two contepts, *zoom bias* and a quad’s *scalar. *The zoom levels we’ve seen so far (and a few more) and the values of their quads are

- Zoom 0: 0
- Zoom 1: 1-4
- Zoom 2: 5-20
- Zoom 3: 21-84
- Zoom 4: 85-341

In general, at level *z* you have 4* ^{z}* quads, so at level 2 you have 4

^{2}=16, the first one being

`5`

. At level 3 you have 4^{3}=64, the first one being

`21`

, and so on.The value of the first quad for a given zoom level turns out to appear again and again when doing operations so I’ll give that a name: the *zoom bias*. When I talk about the zoom-3 bias, which I’ll typically write as *b _{3}*, what I’m referring to is 21 since that is the value of the first quad at zoom level 3.

The *scalar* of a quad is its value minus the bias of its zoom level. Here are the biases and scalars for zoom levels 1 to 3:

## Parents and children

Now we’re ready to look at how you get a quad’s parent. As mentioned, quads are numbered such that the subquads of each parent are contiguous. That obviously also holds for the scalars. That means that if you divide the scalar value by 4, the number of children in each parent, this happens:

You get the scalar of the parent. So given a quad *q* at zoom level *z*, the parent quad can be computed as

parent(*q*) = ((*q* – *b _{z}*) / 4) +

*b*

_{z}_{-1}

Unbias the quad to get the scalar, divide it by 4 to get the parent’s scalar, then add the parent’s zoom level bias to get back a quad. And in fact this can be simplified if you use the fact that the zoom biases are related like this,

*b _{z+1}* = 4

*b*+ 1

_{z}I’ll justify this in a moment but for now you can just take it as a given. If you plug this in and simplify you get that

parent(*q*) = (*q* – 1) / 4

(By the way, except when stated explicitly all values are integers so division implicitly rounds down). What’s neat about the simplified version is that *b _{z}* no longer appears so you can apply this without explicitly knowing the zoom level. It’s pretty easy to calculate the zoom level for a quad, I’ll go over that in a bit, but it’s even easier if you don’t have to.

How about going the other way? Given a quad, finding the value of one of its children? That’s the same procedure just going the other way: unbias the parent, multiply by 4, add the child’s index (a value from 0 to 3), rebias:

child(*q*, *i*) = 4(*q* – *b _{z}*) +

*i*+

*b*

_{z}_{+1}

Again this can be simplified by using the relation between the zoom biases to

child(*q*, *i*) = 4*q* + *i* + 1

If instead of the child’s index (from 0 to 3) you use its quad value (from 1 to 4) it becomes even simpler,

child(*q*, *i*) = 4*q* + *i*

This is part of why they’re called z-quads: it’s from all the z-words. The numbering zig-zags and it’s easy to zoom in and out, that is, get between a quad and its parent and children. (If, by the way, you’ve ever used a d-ary heap you may have noticed that this is the same operation used to get the child node in a 4-ary heap).

Since you can calculate the value of a child quad given its parent it also means that you can calculate the value of a quad one zoom level at a time, starting from `0`

. For instance, in the original example with the colored squares the blue square was child 2 of child 3 of `0`

. That means the value is

child(child(0, 3), 2) = 4 (4 0 + 3) + 2 = 4 3 + 2 = 12 + 2 = 14

Which we already knew from before of course. This isn’t how you would typically convert between positions and quads in a program, there’s a smarter way to do that, but I’ve found it useful for pen-and-paper calculations.

## Ancestors and descendants

Now we know how to go between a quad and its parent and children we can generalize it to going several steps. When going multiple steps, instead of talking about parents and children we’ll talk about *ancestors* and *descendants*. An ancestor of a quad is its parent or one of the parent’s ancestors. A descendant of a quad is one of its children or one of the children’s descendants.

It turns out that just as there’s a simple formula for getting a quad’s parent there is one for getting any of its ancestors:

ancestor(*q*, *n*) = (*q* – *b _{n}*) / 4

^{n}

Given a quad this gives you the ancestor *n* steps above it. The special case where *n* is 1 is the parent function from before, *b*_{1} being 1. Even though it might not seem sensible now it’s worth noting for later that this is also well-defined for *n*=0 where the result is *q*. So a quad is its own 0th ancestor.

It’s easy to prove that the ancestor function is correct inductively by using a second relation that holds between the *b _{z}*s:

*b _{z}*

_{+1}= 4

^{z}+

*b*

_{z}I won’t do the proof here but maybe we should take a short break and talk about why these relations between the biases hold. The bias at a zoom level is the index of the first quad at that level. At level 0 there is 1 (=4^{0}) quad so *b*_{1}, the next available index, is 1. At level 1 there are 4 (= 4^{1}) which start from 1 so the next bias is

*b*_{2} = 4^{0} + 4^{1} = *b*_{1} + 4^{1} = 5

If we keep going, the next level adds 16 (= 42) quads in addition to the 5 we already have which makes the next bias

*b*_{3} = 4^{0} + 4^{1} + 4^{2} = *b*_{2} + 4^{2} = 21

You can see how each bias is a sum of successive powers of 4 which gives you the relation I just mentioned above, that to get the next bias you just add the next power of 4 to the previous bias.

*b*_{3} = *b*_{2} + 4^{2}

It also gives us the other relation from earlier,

*b*_{3} = 4^{0} + 4^{1} + 4^{2} = 4^{0} + 4(4^{0} + 4^{1}) = 4 *b*_{2} + 1

Okay so back to ancestors and descendants. As with ancestors you can also get to arbitrarily deep descendants in one step,

descendant(q, c, n) = 4^{n} *q* + *c*

This gives you the descendant of *q* which relates to *q* the same way quad *c*, which has zoom level *n*, relates to the entire space. This can again be proven by induction with the base case being the child operation from before. And again this is well-defined for *n*=0 where the result is *q*.

So now we can jump directly between a quad and the quads related to it at zoom levels above and below it. This will be the building blocks for many other operations. But before we go on to the next part I’ll round off the ancestor/descendant relation with the concept of *descendancy*.

When you go from a quad to one of its ancestors you’re in some sense discarding information. If you start with a quad that covers the center of Århus from the initial example and zoom out to the one covering northern Europe, you’ve lost the information about where specifically in northern Europe you were. You can add that information back by using the descendant operation, but for that you need to know *c*, the quad that describes where within northern Europe the Århus quad is. That is, you need to know the *descendancy* of the Århus quad within the northern Europe quad. There is a simple way to calculate the descendancy of a quad within the ancestor *n* steps above it,

descendancy(*q*, *n*) = ((*q* – *b _{n}*) mod 4

^{n}) +

*b*

_{n}The descendancy is a little less intuitive than the others, that’s also why I’m not spending more time on how it’s derived or proving it correct, but it turns out that it’s actually quite useful when you work with quads in practice. And it definitely feels like the model would be incomplete without it. Note again, as always, this is well-defined when *n*=0 where it yields `0`

(as in, any quad spans the entirety of itself).

Now we have a nice connection between the three operations: for all *q* and *n* where the operations are well-defined it holds that,

*q* = descendant(ancestor(*q*, *n*), descendancy(*q*, *n*), *n*)

With these basic building blocks in place we’re ready to go on to some higher-level operations, the first ones will be the two containment operations. Given quads *q* and *s*, is *s* contained in *q*? And given two quads, determine the most specific ancestor that contains both of them. For those you’ll have to go on to the next post, z-quads: containment.

(Update: hacker news discussion)

(Update: added some references mentioned in the discussion: z-order, d-ary heaps. Remove part where I couldn’t find other non-point coordinate systems)