CubeRank

CubeRank is a small C11 primitive that provides a dense, deterministic and reversible mapping between centered signed 3D coordinates and uint64_t indices.

Properties

• C11, integer-only implementation
• No heap allocation or recursion
• O(1) memory and bounded execution
• Dense, reversible mapping

Range

• Coordinate radius: 1,321,122
• Last valid index: 18,446,724,184,312,856,124

Example

#include <inttypes.h>
#include <stdio.h>
#include "cuberank.h"

int main(void)
{
    uint64_t index;
    int32_t x, y, z;

    if (!cuberank_rank_i32(-12, 4, 7, &index)) return 1;
    if (!cuberank_unrank_u64(index, &x, &y, &z)) return 1;
    printf("index=%" PRIu64 " point=(%" PRId32 ",%" PRId32 ",%" PRId32 ")\n",
           index, x, y, z);
    return 0;
}

Build

cmake -S . -B build -DCUBERANK_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

CubeRank can also be included with add_subdirectory(CubeRank) and linked using target_link_libraries(app PRIVATE cuberank).

Validation

Validated results: independent oracle PASS; r=0..128 exhaustive PASS; 10M coordinate stress PASS; 10M index stress PASS; 20M mixed operations PASS; ASan PASS; UBSan PASS; ESP32-S3 PASS; host/HW checksum match.

License

Apache-2.0. See LICENSE.