tdt-cesium

天地图（Tianditu）在 Cesium 中的影像、地形与矢量标注支持：

• TdtImageryProvider — 使用天地图官方 WMTS 服务加载影像、矢量底图及对应注记图层。
• TdtTerrainProvider — 解析天地图压缩高程瓦片（gzip/deflate + 自定义定点编码），作为 Cesium 的 TerrainProvider 使用。
• TdtLabelLayer — 在 Viewer 上叠加天地图矢量瓦片（地形 POI + 路网标注），随相机移动增量加载、缓存瓦片与 label，并做屏幕空间碰撞检测（避让重叠标注）。

安装

pnpm add tdt-cesium cesium

cesium 是对等依赖，需要项目自行安装（>=1.144.0）。除此之外本包没有运行时依赖，GEOPOI protobuf 瓦片由内置的零依赖读取器解码。

本包与 map-cesium-utils 相互独立：可以只安装其中一个，也可以在同一个 Cesium Viewer 中组合使用。仓库内可运行的接入示例位于 packages/example 的 /map-cesium 页面。

公共导出

| 导出 | 类型 | 说明 | | --- | --- | --- | | TdtImageryProvider | 类 | 天地图 WMTS 影像提供器。 | | TdtImageryProviderOptions | 接口 | 影像提供器构造参数。 | | TdtImageryLayer / TdtImageryLayerBase | 类型 | 支持的天地图图层名称。 | | TdtTerrainProvider | 类 | 天地图压缩高程瓦片提供器。 | | TdtTerrainProviderOptions | 接口 | 提供器构造参数。 | | TdtTerrainDataType | 类型 | 原始高程数据类型：int16、float 或 float32。 | | TerrainArrayBufferFetcher | 类型 | 可替换的高程瓦片请求函数。 | | TdtLabelLayer | 类（同时为默认导出） | 天地图 POI/路网矢量标注图层。 | | TdtLabelLayerOptions | 接口 | 标注图层构造参数。 | | TdtLabelLayerBoundingBox / TdtLabelLayerTileMetadata / TdtLabelLayerTile | 接口 | 标注瓦片的范围、元数据与坐标描述。 |

TdtImageryProvider

import { ImageryLayer, Viewer } from 'cesium'
import { TdtImageryProvider } from 'tdt-cesium'

const viewer = new Viewer('cesiumContainer')
const provider = new TdtImageryProvider({
  token: 'YOUR_TIANDITU_TOKEN',
  layer: 'img'
})

viewer.imageryLayers.add(new ImageryLayer(provider))

常见底图通常由底图与注记两层组合，例如影像底图使用 img + cia，矢量底图使用 vec + cva。img 与 img_w 两种写法等价。

配置项

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | token | string | — | 必填，天地图服务 Token。 | | layer | TdtImageryLayer | — | 必填，支持 img、vec、cia、cva、ter、cta、eia、eva、ibo 及对应的 _w 形式。 | | url | string | 官方 WMTS 服务 | 支持 {layer}、{token} 及 Cesium WMTS 瓦片占位符的 URL 模板。 | | subdomains | string \| string[] | ['0', ..., '7'] | URL 中 {s} 的候选子域。 | | style | string | 'default' | WMTS 样式。 | | format | string | 'tiles' | WMTS 图片格式。 | | tileMatrixSetID | string | 'w' | WMTS 瓦片矩阵集。 | | minimumLevel / maximumLevel | number | 0 / 18 | 可请求的最小、最大层级。 |

其他 Cesium WebMapTileServiceImageryProvider.ConstructorOptions 参数也可按需传入。

TdtTerrainProvider

import { Viewer } from 'cesium'
import { TdtTerrainProvider } from 'tdt-cesium'

const viewer = new Viewer('cesiumContainer', {
  terrainProvider: new TdtTerrainProvider({
    token: 'YOUR_TIANDITU_TOKEN'
  })
})

配置项

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | token | string | — | 必填，天地图服务 Token。 | | url | string | 官方高程服务 | 瓦片 URL 模板，{s}/{token}/{x}/{y}/{z} 会在请求前替换；默认使用 mapservice/swdx?T=elv_c&...。 | | subdomains | readonly string[] | ['0', ..., '7'] | {s} 的可选子域列表，按 (x+y) % length 轮询。 | | dataType | 'int16' \| 'float' \| 'float32' | 'int16' | 服务端高程数据的原始类型。 | | topLevel | number | 5 | Cesium 层级小于该值时返回零高程占位瓦片，不发请求。 | | bottomLevel | number | 12 | Cesium 层级达到该值后不再请求（超出服务端最大层级）。 | | tilingScheme | Cesium.TilingScheme | Cesium 默认 | 传给底层 CustomHeightmapTerrainProvider。 | | ellipsoid | Cesium.Ellipsoid | Ellipsoid.WGS84 | 同上。 | | credit | Cesium.Credit \| string | — | 同上。 | | fetchArrayBuffer | (url, request?) => Promise<ArrayBuffer> \| undefined | Resource.fetchArrayBuffer | 自定义请求适配器，便于接入代理、鉴权或模拟请求。 |

topLevel 必须小于 bottomLevel，否则构造函数会抛错。

TdtLabelLayer

import { Viewer } from 'cesium'
import { TdtLabelLayer } from 'tdt-cesium'

const viewer = new Viewer('cesiumContainer')

const layer = new TdtLabelLayer(viewer, {
  token: 'YOUR_TIANDITU_TOKEN'
})

layer.initTDT() // 首次加载当前视野内的瓦片

// 不再需要时
layer.destroy()

TdtLabelLayer 构造后不会自动开始请求；请调用 initTDT() 或 activate() 启动当前视野的加载。组件卸载或销毁 Viewer 前应调用 destroy()，释放定时器、相机事件、未完成请求和已创建的 Entity。destroy() 可重复调用；销毁后的 initTDT()、activate() 与 bindEvent() 不再启动任务。

配置项

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | token | string | — | 必填，url/icoUrl/roadUrl 共用的天地图服务 Token。 | | url | string | 官方 POI 服务 | 地形 POI 矢量瓦片 URL 模板（{s}/{token}/{x}/{y}/{z}），默认包含必需的 version=1.0.0。 | | icoUrl | string | 官方图标服务 | POI 图标 URL 模板（{s}/{token}/{id}），默认使用 SYMBOLID={id} 并包含 version=1.0.0。 | | roadUrl | string | '' | 路网标注瓦片 URL 模板（JSON，{s}/{token}/{x}/{y}/{z}）。 | | proxy | { proxy: string } | — | 所有瓦片/图标请求前拼接的代理前缀。 | | metadata | { boundingBox, minLevel, maxLevel } \| false | 全球、1–18 级 | 地形 POI 瓦片的可用范围与层级；传入 false 可关闭地形 POI 请求。 | | roadMetadata | 同上 | — | 路网标注瓦片的可用范围与层级；不设置则不请求路网标注。 | | labelGraphics | Cesium.LabelGraphics.ConstructorOptions & { bold?: boolean } | 内置默认样式 | 在内置默认值上做顶层浅覆盖。bold 是本库扩展字段。 | | billboardGraphics | Cesium.BillboardGraphics.ConstructorOptions | 内置默认样式 | 在内置默认值上做顶层浅覆盖。 | | serverFirstStyle | boolean | false | 开启后优先使用服务端下发的字号/颜色/描边等样式覆盖默认样式。 | | autoCollide | boolean | true | 开启屏幕空间碰撞检测，按 priority 隐藏被遮挡的标注。 | | collisionPadding | [top, right, bottom, left] | [3, 5, 3, 5] | 碰撞检测时每个标注矩形的内边距。 | | subdomains | string[] | ['t0', ..., 't7'] | {s} 的可选子域列表。 |

方法

| 方法 | 说明 | | --- | --- | | initTDT(tiles?) | 初始化并加载瓦片；不传参数时使用当前相机视野。 | | activate() | 清空"上次渲染瓦片"记录并强制按当前视野重新加载。 | | destroy() | 幂等移除所有已添加的 entity、定时器和相机事件，并取消未完成的请求。 | | collisionDetection() | 手动触发一次碰撞检测（autoCollide: true 时会自动周期调用）。 | | bindEvent() / unbindEvent() | 手动绑定/解绑相机 moveEnd/changed 事件。 |

地形 POI 与路网标注分别按来源分组和 oid 去重；同一来源的视野瓦片重复返回时不会重复创建 Entity。碰撞检测使用完整矩形相交判断，也能识别一方完全覆盖另一方的情况。

开发与验证

# 在仓库根目录执行
pnpm --dir packages/tdt-cesium build
pnpm --dir packages/tdt-cesium check:types  # 目前覆盖 src 与 poi-proto 测试
pnpm --dir packages/tdt-cesium test         # build + check:types + node:test
pnpm --dir packages/tdt-cesium dev
pnpm lint:check                             # 仓库统一的只读 lint

# 构建集成了 tdt-cesium 的 Vue 示例
pnpm --dir packages/example build

当前 Node 测试覆盖影像 Provider 参数，Label 样式、请求竞态、生命周期、缓存去重和包围盒相交，以及 GEOPOI protobuf 解码（三代协议、缺省值、未知字段跳过与必填字段校验）。check:types 暂未纳入 imagery-provider 与 label-layer 两个测试文件，它们大量 stub Cesium 内部对象，需要单独一轮补类型。外网天地图服务未纳入 E2E，以避免 Token、网络和服务可用性导致 CI 不稳定；涉及真实瓦片、相机与 Entity 渲染的行为仍需在示例应用 /map-cesium 页面手动验证。

许可证

MIT