# UVoxID (Rust)
[](https://crates.io/crates/uvoxid)
[](https://docs.rs/uvoxid)
[](./LICENSE)
**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
```bash
cargo add uvoxid
```
Or add manually to `Cargo.toml`:
```toml
[dependencies]
uvoxid = "0.1"
```
---
## 🔍 Example
```rust
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:
```bash
cargo test
```
Format code:
```bash
cargo fmt
```
---
## 📎 Links
- [Crates.io](https://crates.io/crates/uvoxid)
- [Docs.rs](https://docs.rs/uvoxid)
- [Source Code](https://github.com/JDPlumbing/uvoxid-rs)
---
## 📄 License
MIT © JD Plumbing