# tile-id

**Repository Path**: proj4js/tile-id

## Basic Information

- **Project Name**: tile-id
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-30
- **Last Updated**: 2025-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tile-id

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

## 简介

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

## 安装

```bash
npm install tile-id
```

## 使用方法

```typescript
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` 坐标

## 示例

```javascript
// 基本使用
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