Mapbox UTFGrid 交互式地图数据编码方案详解

什么是 UTFGrid

UTFGrid 是一种高效的空间数据编码方案，专门为浏览器环境设计，用于在地图瓦片上实现交互功能（如悬停显示工具提示）。它通过网格化方式存储每个像素关联的信息，解决了浏览器直接渲染矢量多边形性能不足的问题。

核心设计原理

网格化数据结构

UTFGrid 采用 JSON 格式存储数据，专为 256×256 像素的方形瓦片设计：

1. 网格分辨率：默认使用 2×2 网格，将 256×256 像素降采样为 128×128 的网格单元
2. ID 编码：每个网格单元存储一个 Unicode 码点作为键值
3. 空间效率：当 ID 数量少于 96 个时，原始数据约 64KB，经 Gzip 压缩后可降至 2KB 以下

编码机制

UTFGrid 巧妙利用 UTF-8 的变长编码特性：

• 前 94 个码点（0x20-0x7F，跳过控制字符和特殊符号）使用单字节编码
• 更高数值的 ID 使用多字节编码
• 通过算法跳过 JSON 不允许直接表示的字符（如控制字符、" 和 \）

技术实现细节

ID 编解码算法

编码过程：

1. 原始 ID 值加 32
2. 若结果 ≥ 34 则再加 1
3. 若结果 ≥ 92 则再加 1

解码过程：

1. 若码点 ≥ 93 则减 1
2. 若码点 ≥ 35 则减 1
3. 最后减 32

数据检索流程

1. 坐标转换：

   factor = 256 / grid_size
   row = y / factor
   col = x / factor
   

2. 获取编码 ID：

   encoded_id = json.grid[row].charCodeAt(col)
   

3. 解码 ID： 使用上述解码算法

4. 获取关联数据：

   key = json.keys[decoded_id]
   data = json.data[key] // 如果data存在
   

数据结构示例

典型的 UTFGrid JSON 文件包含三个核心部分：

{
  "grid": ["...编码字符串..."],
  "keys": ["key1", "key2", ...],
  "data": {
    "key1": {...关联数据...},
    "key2": {...关联数据...}
  }
}

特殊处理规则

1. 空字符串键 "" 表示该像素无可用信息
2. 当 data 属性不存在时，客户端应查询本地存储或向服务器请求缺失键
3. 网格尺寸必须是 2 的幂次方（如 64, 128, 256 等）

实际应用场景

UTFGrid 特别适合以下场景：

• 需要显示大量要素属性信息的交互式地图
• 低带宽环境下的地图交互
• 老旧设备上的地图应用
• 需要快速响应悬停事件的场景

通过这种编码方案，开发者可以在不牺牲交互体验的前提下，显著降低数据传输量和客户端处理负担。