UVoxID (Rust)

Universal Voxel Identifier (UVoxID) — a deterministic, 192-bit encoding scheme for spherical spatial coordinates at micrometer precision.

Think of it as a globally consistent voxel address system: every point in space has a permanent ID, valid from Earth’s core to interstellar distances.

✨ Features

192-bit encoding: (radius, latitude, longitude) → one integer.
Deterministic & exact: no floating-point drift.
Compact: 24 bytes per position, globally unique.
Rust-native: safe, simple API for encode/decode.
Tested: round-trip encoding/decoding verified.

📦 Installation

cargo add uvoxid

Or add manually to Cargo.toml:

[dependencies]
uvoxid = "0.1"

🔍 Example

use uvoxid::{encode_uvoxid, decode_uvoxid};

fn main() {
    // Earth mean radius in µm
    let earth_r_um: u64 = 6_371_000_000_000;

    // At equator, prime meridian
    let id = encode_uvoxid(earth_r_um, 0, 0);

    println!("UVoxID: {:#x}", id);

    let (r, lat, lon) = decode_uvoxid(id);
    println!("Decoded: r = {} µm, lat = {} µ° , lon = {} µ°", r, lat, lon);
}

Output:

UVoxID: 0x59fb8c83f100000000000055d4a8000000000aba950
Decoded: r = 6371000000000 µm, lat = 0 µ°, lon = 0 µ°

📖 API

`encode_uvoxid(r_um: u64, lat_microdeg: i64, lon_microdeg: i64) -> UvoxId`

r_um: radius in micrometers (µm), stored as an unsigned 64-bit value.
lat_microdeg: latitude in millionths of a degree (−90e6 to +90e6). Encoded internally as a u64 offset by +90,000,000.
lon_microdeg: longitude in millionths of a degree (−180e6 to +180e6). Encoded internally as a u64 offset by +180,000,000.
Returns: a UvoxId (192-bit packed struct with (r, lat, lon)).

`decode_uvoxid(id: UvoxId) -> (u64, i64, i64)`

Input: a UvoxId struct (192-bit packed).
Output: (r_um, lat_microdeg, lon_microdeg) with offsets reversed so you get back the signed coordinates you passed in.

🛠 Development

Run tests:

cargo test

Format code:

cargo fmt

uvoxid 0.2.0