{"id":13419366,"url":"https://github.com/Forceflow/libmorton","last_synced_at":"2025-03-15T05:31:03.171Z","repository":{"id":11049898,"uuid":"13387584","full_name":"Forceflow/libmorton","owner":"Forceflow","description":"C++ header-only library with methods to efficiently encode/decode Morton codes in/from 2D/3D coordinates","archived":false,"fork":false,"pushed_at":"2023-08-26T12:11:25.000Z","size":12378,"stargazers_count":580,"open_issues_count":8,"forks_count":70,"subscribers_count":29,"default_branch":"main","last_synced_at":"2024-07-31T22:47:36.135Z","etag":null,"topics":["c-plus-plus","decoding","encoding","morton"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Forceflow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2013-10-07T15:30:11.000Z","updated_at":"2024-07-25T14:02:02.000Z","dependencies_parsed_at":"2023-02-12T16:45:45.949Z","dependency_job_id":"1328540b-92d6-41c0-8ca3-b007690e25bd","html_url":"https://github.com/Forceflow/libmorton","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forceflow%2Flibmorton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forceflow%2Flibmorton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forceflow%2Flibmorton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forceflow%2Flibmorton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Forceflow","download_url":"https://codeload.github.com/Forceflow/libmorton/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221541870,"owners_count":16840113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","decoding","encoding","morton"],"created_at":"2024-07-30T22:01:14.949Z","updated_at":"2024-10-26T14:31:33.809Z","avatar_url":"https://github.com/Forceflow.png","language":"C++","readme":"# Libmorton v0.2.12\n[![CMake](https://github.com/Forceflow/libmorton/actions/workflows/cmake.yml/badge.svg)](https://github.com/Forceflow/libmorton/actions/workflows/cmake.yml) [![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://opensource.org/licenses/MIT) [![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.me/forceflow)\n\n * Libmorton is a **C++ header-only library** with methods to efficiently encode/decode 64, 32 and 16-bit Morton codes and coordinates, in 2D and 3D. *Morton order* is also known as *Z-order* or *[the Z-order curve](https://en.wikipedia.org/wiki/Z-order_curve)*.\n * Libmorton is a **lightweight and portable** library - the only dependencies are standard C++ headers. Architecture-specific optimizations are available.\n * More info and some benchmarks in these blogposts: [*Morton encoding*](http://www.forceflow.be/2013/10/07/morton-encodingdecoding-through-bit-interleaving-implementations/), [*Libmorton*](http://www.forceflow.be/2016/01/18/libmorton-a-library-for-morton-order-encoding-decoding/) and [*BMI2 instruction set*](http://www.forceflow.be/2016/11/25/using-the-bmi2-instruction-set-to-encode-decode-morton-codes/)\n\n## Usage\nJust include the header `include/libmorton/morton.h`. This will always have stub functions that point to the most efficient way to encode/decode Morton codes. If you want to test out alternative (and possibly slower) methods, you can find them in `include/libmorton/morton2D.h` and `include/libmorton/morton3D.h`. **All libmorton functionality is in the `libmorton` namespace to avoid conflicts**.\n\n\u003cpre\u003e\n// ENCODING 2D / 3D morton codes, of length 32 and 64 bits\ninline uint_fast32_t morton2D_32_encode(const uint_fast16_t x, const uint_fast16_t y);\ninline uint_fast64_t morton2D_64_encode(const uint_fast32_t x, const uint_fast32_t y);\ninline uint_fast32_t morton3D_32_encode(const uint_fast16_t x, const uint_fast16_t y, const uint_fast16_t z);\ninline uint_fast64_t morton3D_64_encode(const uint_fast32_t x, const uint_fast32_t y, const uint_fast32_t z);\n// DECODING 2D / 3D morton codes, of length 32 and 64 bits\ninline void morton2D_32_decode(const uint_fast32_t morton, uint_fast16_t\u0026 x, uint_fast16_t\u0026 y);\ninline void morton2D_64_decode(const uint_fast64_t morton, uint_fast32_t\u0026 x, uint_fast32_t\u0026 y);\ninline void morton3D_32_decode(const uint_fast32_t morton, uint_fast16_t\u0026 x, uint_fast16_t\u0026 y, uint_fast16_t\u0026 z);\ninline void morton3D_64_decode(const uint_fast64_t morton, uint_fast32_t\u0026 x, uint_fast32_t\u0026 y, uint_fast32_t\u0026 z);\n\u003c/pre\u003e\n\n## Installation\nNo compilation / installation is required (just download the headers and include them), but I was informed libmorton is packaged for [Microsoft's VCPKG system](https://github.com/Microsoft/vcpkg) as well, if you want a more controlled environment to install C++ packages in.\n\n## Instruction sets\nIn the standard case, libmorton only uses operations that are supported on pretty much any CPU you can throw it at. If you know you're compiling for a specific architecture, you might gain a speed boost in encoding/decoding operations by enabling implementations for a specific instruction set. Libmorton ships with support for:\n * **BMI2 instruction set**: Intel: Haswell CPU's and newer. AMD: Ryzen CPU's and newer. Define `__BMI2__` before including `morton.h`. This is definitely a faster method when compared to the standard case.\n * **AVX512 instruction set (experimental)**: Intel Ice Lake CPU's and newer. Uses `_mm512_bitshuffle_epi64_mask`. Define `__AVX512BITALG__` before including `morton.h`. For more info on performance, see [this PR](https://github.com/Forceflow/libmorton/pull/40).\n \nWhen using MSVC, these options can be found under _Project Properties -\u003e Code Generation -\u003e Enable Enhanced Instruction set_.\nWhen using GCC (version 9.0 or higher), you can use `-march=haswell` (or `-march=znver2`) for BMI2 support and `-march=icelake-client` for AVX512 support.\n\n## Compiling the test suite\nThe `test` folder contains tools I use to test correctness and performance of the libmorton implementation. You can regard them as unit tests. This section is under heavy re-writing, but might contain some useful code for advanced usage. \n\nYou can build the test suite:\n * With the included [Visual Studio 2019](https://visualstudio.microsoft.com/) project in `test\\msvc*`\n * Using make: `test\\makefile`\n * Using Cmake (thanks [@shohirose](https://github.com/shohirose))\n\n## Citation\nIf you use libmorton in your published paper or work, please reference it, for example as follows:\n\u003cpre\u003e\n@Misc{libmorton18,\nauthor = \"Jeroen Baert\",\ntitle = \"Libmorton: C++ Morton Encoding/Decoding Library\",\nhowpublished = \"\\url{https://github.com/Forceflow/libmorton}\",\nyear = \"2018\"}\n\u003c/pre\u003e\n \n ## Publications / products that use libmorton\n I'm always curious what libmorton ends up on. If you end up using it, send me an e-mail!\n  * Thomas Bläsius, Tobias Friedrich et al, 2019. _Efficiently Generating Geometric Inhomogeneous and Hyperbolic Random Graphs_ ([link](https://arxiv.org/abs/1905.06706))\n  * Alexander Dieckmann, Reinhard Klein, 2018. _Hierarchical additive poisson disk sampling_ ([link](https://dl.acm.org/citation.cfm?id=3307667))\n  * Sylvain Rousseau and Tamy Boubekeur, 2017. _Fast lossy compression of 3D unit vector sets_ ([PDF](https://perso.telecom-paristech.fr/boubek/papers/UVC/UVC.pdf))\n  * Jan Watter, 2018. _Generation of complex numerical meshes using space-filling curves_ ([PDF](http://www.cie.bgu.tum.de/publications/bachelorthesis/2018_Watter.pdf))\n  * [Esri](https://www.esri.com/en-us/home)\n  * [Cesium Ion](https://cesium.com/ion/opensource)\n  * [CLAIRE](https://github.com/andreasmang/claire#clairedoc)\n  \n  ## Thanks / See ALso\n * To [@gnzlbg](https://github.com/gnzlbg) and his Rust implementation [bitwise](https://github.com/gnzlbg) for finding bugs in the Magicbits code \n * [@kevinhartman](https://github.com/kevinhartman) made a C++14 library that supports N-dimensional morton codes [morton-nd](https://github.com/kevinhartman/morton-nd). He upstreamed a lot of fixes back to libmorton - thanks!\n * Everyone making comments and suggestions on the [original blogpost](http://www.forceflow.be/2013/10/07/morton-encodingdecoding-through-bit-interleaving-implementations/)\n * [@Wunkolo](https://github.com/Wunkolo) for AVX512 implementation\n * Fabian Giesen's [post](https://fgiesen.wordpress.com/2009/12/13/decoding-morton-codes/) on Morton Codes\n \n ## Contributing\n \n See [Contributing.md](https://github.com/Forceflow/libmorton/blob/master/CONTRIBUTING.md)\n\n## TODO\n * Add morton operations like described [here](https://en.wikipedia.org/wiki/Z-order_curve#Coordinate_values)\n * Write better test suite (with L1/L2 trashing, better tests, ...)\n * A better naming system for the functions, because m3D_e_sLUT_shifted? That escalated quickly.\n","funding_links":["https://www.paypal.me/forceflow"],"categories":["TODO scan for Android support in followings","Mathematics"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FForceflow%2Flibmorton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FForceflow%2Flibmorton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FForceflow%2Flibmorton/lists"}