tile-id

高性能的瓦片坐标编码/解码库，用于将瓦片坐标 (z, x, y) 与唯一数字 ID 之间相互转换。

简介

在地图瓦片系统中，经常需要将三维的瓦片坐标 (z, x, y) 转换为唯一的数字标识符，以便于存储和检索。本库提供了高效的编码和解码函数，利用位运算实现极佳的性能。

安装

npm install tile-id

使用方法

import { toID, toZXY } from 'tile-id';

// 将瓦片坐标转换为唯一ID
const id = toID(3, 2, 1); // 返回 323

// 将唯一ID转换回瓦片坐标
const coords = toZXY(323); // 返回 Uint32Array([3, 2, 1])
// 访问坐标值:
// coords[0] = z (层级)
// coords[1] = x (x坐标)
// coords[2] = y (y坐标)

API

toID(z: number, x: number, y: number): number

将瓦片坐标 (z, x, y) 编码为唯一数字 ID。

参数:

• z: 瓦片缩放层级 (0-31)
• x: 瓦片x坐标
• y: 瓦片y坐标

返回值: 唯一数字ID

toZXY(id: number): Uint32Array

将唯一数字 ID 解码为瓦片坐标 [z, x, y]。

参数:

• id: 由 toID 生成的唯一数字 ID

返回值: 包含 [z, x, y] 坐标的 Uint32Array 数组

性能特点

• 使用位运算优化，性能极高
• 避免了字符串操作和复杂计算
• 使用 Uint32Array 减少内存分配开销
• 时间复杂度: O(1)
• 空间复杂度: O(1)

编码原理

编码过程

1. 使用位运算 (y << z) + x 计算平面索引
2. 左移 5 位 (相当于乘以 32) 为层级信息预留空间
3. 加上层级 z 值形成最终唯一 ID

解码过程

1. 通过 id & 31 提取层级 z 值 (因为 31 = 0x1F，低5位)
2. 通过 (id - z) >>> 5 计算平面索引 (无符号右移5位，相当于除以32)
3. 根据 z 值计算 dimension = 2^z (该层级的行列数)
4. 通过位运算从平面索引中提取 x 和 y 坐标

示例

// 基本使用
import { toID, toZXY } from 'tile-id';

// 编码示例
console.log(toID(0, 0, 0)); // 0
console.log(toID(1, 0, 0)); // 1
console.log(toID(1, 1, 0)); // 33
console.log(toID(3, 2, 1)); // 323

// 解码示例
console.log(toZXY(0));   // Uint32Array([0, 0, 0])
console.log(toZXY(1));   // Uint32Array([1, 0, 0])
console.log(toZXY(33));  // Uint32Array([1, 1, 0])
console.log(toZXY(323)); // Uint32Array([3, 2, 1])

// 验证双向转换
const original = [5, 12, 7];
const id = toID(...original);
const decoded = toZXY(id);
console.log(
  original[0] === decoded[0] && 
  original[1] === decoded[1] && 
  original[2] === decoded[2]
); // true

适用场景

• 地图瓦片系统
• 空间索引
• 数据库键值设计
• 缓存键生成
• 瓦片存储优化

许可证

MIT