libmorton is a header-only Z-order codec for C++

A Z-order codec with no dependencies at all

libmorton is a C++ header-only library whose whole job is converting between Morton codes and 2D or 3D coordinates. The description names the format as Morton order, also known as Z-order or the Z-order curve, and the implementation covers 64, 32 and 16-bit codes in both 2D and 3D. Two properties define the library's appeal. It is header-only, so there is nothing to link and nothing to install, and it is portable, because the only dependencies are standard C++ headers. The trade-off is that portability is achieved by making the default path work on any CPU, so the fast paths are opt-in. The project also points to three of its own write-ups for background, on Morton encoding through bit interleaving, on the library itself, and on using the BMI2 instruction set, and it is careful to say that the benchmarks live in those blog posts rather than in the repository, so the performance story is a matter of reading the author's own measurements rather than running a suite here.

One include, and two families of implementation

The usage section is unusually blunt about how the library is structured. You include the header `include/libmorton/morton.h`, and that header always provides stub functions pointing at the most efficient way to encode and decode Morton codes. If you want to try alternative and possibly slower methods, they live in `include/libmorton/morton2D.h` and `include/libmorton/morton3D.h`. That is a useful pattern for a library like this: the default path hides the dispatch, and the individual implementations remain reachable for experiments, benchmarks and verification. All libmorton functionality sits in the `libmorton` namespace, which the documentation gives as the reason for it, to avoid conflicts with other code in the same translation unit. Since the library is a set of headers, integrating it means copying files into your project or pointing your include path at the repository, and there is no registry, no toolchain requirement and no version negotiation to think about.

Eight functions cover the whole surface

The documented API is a set of inline functions, and it is small enough to read in one pass. Encoding comes in 2D and 3D flavours at 32 and 64 bits, and decoding mirrors that with output coordinates passed by reference:

// ENCODING 2D / 3D morton codes, of length 32 and 64 bits
inline uint_fast32_t morton2D_32_encode(const uint_fast16_t x, const uint_fast16_t y);
inline uint_fast64_t morton2D_64_encode(const uint_fast32_t x, const uint_fast32_t y);
inline uint_fast32_t morton3D_32_encode(const uint_fast16_t x, const uint_fast16_t y, const uint_fast16_t z);
inline uint_fast64_t morton3D_64_encode(const uint_fast32_t x, const uint_fast32_t y, const uint_fast32_t z);

Note the width relationships that the signatures encode: a 32-bit code is produced from 16-bit coordinates, and a 64-bit code from 32-bit coordinates, so the code packs the interleaved bits of the input axes. Decoding has the matching shape, taking the code and writing back the two or three coordinates. A reader who wants to know what the library does with the gaps in a code, since the coordinate widths need not fill the code exactly, should look at the TODO list, which includes adding morton operations of the kind described in the Z-order curve article, and at the alternative implementations in the 2D and 3D headers.

Installation is copying the headers, or using vcpkg

The installation section is short because there is nothing to build. No compilation or installation is required, you just download the headers and include them. For anyone who prefers a managed environment, the documentation says libmorton is packaged for Microsoft's vcpkg system, which is offered as the route for people who want a more controlled environment for installing C++ packages. The repository itself carries a CMakeLists.txt at the root and a `test/` directory, a `data/` directory and the `include/` tree, plus a Travis configuration and GitHub Actions workflows, and the CMake badge in the header suggests the project is built in CI even though consumers do not need to be. The practical advice for a new user is to vendor two or three headers rather than to add a build dependency, and to keep the licence file next to them.

BMI2 is the documented speed path, AVX512 is experimental

In the standard case libmorton only uses operations supported on pretty much any CPU, and the speedups are enabled by defining a macro before including the header. The BMI2 instruction set path is described as definitely faster than the standard case and covers Intel Haswell CPUs and newer and AMD Ryzen CPUs and newer, enabled by defining `__BMI2__` before including `morton.h`. The AVX512 path is labelled experimental, applies to Intel Ice Lake CPUs and newer, uses `_mm512_bitshuffle_epi64_mask`, and is enabled by defining `__AVX512BITALG__`. The documentation also covers the toolchain side: with MSVC these options live under project properties under code generation and the enhanced instruction set, and with GCC version 9.0 or higher you can use `-march=haswell` or `-march=znver2` for BMI2 and `-march=icelake-client` for AVX512. Because the dispatch is macro driven, the same source compiles to different implementations depending on build flags, which is the main thing to get right when you vendor it.

The test suite is the acknowledged weak point

The repository has a `test/` folder containing the tools the author uses to test correctness and performance of the implementation, which the documentation says can be regarded as unit tests. The caveat comes immediately after: the section is under heavy re-writing but might contain some useful code for advanced usage. It can be built with the included Visual Studio 2019 project, with a makefile, or with CMake. The TODO list repeats the point, listing a better test suite with L1 and L2 trashing and better tests among the open items, along with the Morton operations and a better naming system, the last one prompted by the function names in the codebase. For a library this small, that is a fair amount of unfinished business: the code is easy to read and the algorithms are well documented in the linked posts, but the automated verification of correctness is the part that is still moving.

MIT licensed, with releases that stopped in 2023

The licence is MIT, and the project asks that anything published which uses libmorton should reference it, giving a BibTeX entry with the author Jeroen Baert and a 2018 year. The list of users the project points to includes Esri, Cesium Ion and the CLAIRE project, alongside several published papers on random graphs, Poisson disk sampling, lossy compression of 3D vector sets and numerical mesh generation, which is a reasonable indication of where the library has been applied. The maintenance picture is mixed. The most recent tagged releases are v0.2.10 on 2022-04-25, v0.2.11 on 2023-01-22 and v0.2.12 on 2023-05-24, while the last push to the repository was on 2026-06-16 and the repository is not archived. Work continues on the default branch without a new tag, so anyone depending on it should vendor a specific commit and keep their own copy of the headers rather than tracking a release that no longer moves.

Editorial conclusion

Engineers working on spatial data structures, mesh generation or octree style indexing who want a small, dependency free implementation they can read and vendor will find libmorton useful, and the header-only design removes the usual build system friction. It is the wrong choice if you need a maintained release line, because the latest tagged version is v0.2.12 from 2023, and it is the wrong choice if you rely on a test suite, because the documentation calls that section under heavy re-writing. Before adopting it, include `include/libmorton/morton.h` in a scratch project, compare its output against the alternative implementations in `include/libmorton/morton2D.h` and `include/libmorton/morton3D.h`, and check the TODO list in the repository for the known gaps.

Frequently asked questions

Official sources

1. Forceflow/libmorton on GitHub
2. Issues
3. License: MIT
4. README
5. Releases