🌍 Cesium PBF Loader

一个用于在 CesiumJS 中轻松加载 PBF（Protobuf Binary Format）矢量瓦片的插件。

English | 简体中文

✨ 功能特性

• 🚀 高性能渲染 - 使用 Canvas 2D 高分辨率渲染，支持 2x 像素比
• 🎨 灵活的样式配置 - 支持 Mapbox Style 风格的样式定义
• 🗺️ 多坐标系支持 - 支持 XYZ（Google/OSM）和 TMS（Tile Map Service）坐标系
• 🎯 空间查询 - 基于 Turf.js 的高效空间查询功能
• 📦 TypeScript 支持 - 完整的类型定义，提供优秀的开发体验
• 🔧 易于集成 - 继承自 UrlTemplateImageryProvider，无缝集成到 Cesium
• 🎪 多图层支持 - 支持点、线、面三种几何类型
• 🌐 开源标准 - 支持 OpenMapTiles、Mapbox Vector Tiles (MVT) 等标准格式

📦 安装

使用 npm

npm install cesium-pbf-loader

使用 yarn

yarn add cesium-pbf-loader

使用 pnpm

pnpm add cesium-pbf-loader

🚀 快速开始

基础用法

import * as Cesium from "cesium";
import { VectorTileProvider } from "cesium-pbf-loader";

// 创建 Cesium Viewer
const viewer = new Cesium.Viewer("cesiumContainer");

// 创建矢量瓦片提供者
const provider = new VectorTileProvider({
  url: "https://your-server.com/tiles/{z}/{x}/{y}.pbf",
  style: {
    layers: [
      {
        "source-layer": "water",
        type: "fill",
        paint: {
          "fill-color": "#0080ff",
          "fill-opacity": 0.5,
        },
      },
      {
        "source-layer": "roads",
        type: "line",
        paint: {
          "line-color": "#ff9e3f",
          "line-width": 2,
        },
      },
      {
        "source-layer": "buildings",
        type: "fill",
        paint: {
          "fill-color": "#999999",
          "fill-opacity": 0.8,
          "fill-outline-color": "#666666",
        },
      },
    ],
  },
  minimumLevel: 0,
  maximumLevel: 14,
  tileScheme: "xyz", // 或 'tms'
});

// 添加到 Cesium
const imageryLayer = viewer.imageryLayers.addImageryProvider(provider);

📖 API 文档

VectorTileProvider

构造函数

new VectorTileProvider(options: VectorTileProviderOptions)

配置选项 (VectorTileProviderOptions)

| 参数 | 类型 | 必填 | 默认值 | 说明 | | -------------- | ----------------- | ---- | ------- | ---------------------------------------------------------- | | url | string | ✅ | - | 瓦片 URL 模板，例如：https://example.com/{z}/{x}/{y}.pbf | | style | VectorTileStyle | ✅ | - | 矢量瓦片样式配置 | | minimumLevel | number | ❌ | 0 | 最小缩放级别 | | maximumLevel | number | ❌ | 20 | 最大缩放级别 | | tileScheme | 'xyz' \| 'tms' | ❌ | 'xyz' | 瓦片坐标系 |

样式配置 (VectorTileStyle)

interface VectorTileStyle {
  layers: LayerStyle[];
}

interface LayerStyle {
  "source-layer": string; // PBF 中的图层名称
  type?: "circle" | "line" | "fill"; // 几何类型
  paint?: CircleStyle | LineStyle | FillStyle; // 绘制样式
}

样式类型

点样式 (CircleStyle)

interface CircleStyle {
  "circle-radius"?: number; // 半径（像素）
  "circle-color"?: string; // 填充颜色（支持 hex、rgb、rgba）
  "circle-opacity"?: number; // 透明度（0-1）
}

线样式 (LineStyle)

interface LineStyle {
  "line-color"?: string; // 线条颜色
  "line-width"?: number; // 线条宽度（像素）
  "line-opacity"?: number; // 透明度（0-1）
}

面样式 (FillStyle)

interface FillStyle {
  "fill-color"?: string; // 填充颜色
  "fill-opacity"?: number; // 填充透明度（0-1）
  "fill-outline-color"?: string; // 边界颜色
}

方法

requestImage()

requestImage(x: number, y: number, level: number): Promise<HTMLCanvasElement>

请求并渲染指定的瓦片。此方法由 Cesium 自动调用。

drawTile()

drawTile(tile: VectorTile, z: number, x: number, y: number): HTMLCanvasElement

将 PBF 矢量瓦片绘制到 Canvas。

turfQueryFeaturesByPosition()

turfQueryFeaturesByPosition(lon: number, lat: number, level: number): FeatureHit[]

根据经纬度查询要素。

参数：

• lon - 经度
• lat - 纬度
• level - 缩放级别

返回：

• FeatureHit[] - 命中的要素数组

示例：

// 添加点击事件查询要素
const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction((movement) => {
  const cartesian = viewer.camera.pickEllipsoid(
    movement.position,
    viewer.scene.globe.ellipsoid
  );

  if (cartesian) {
    const cartographic = Cesium.Cartographic.fromCartesian(cartesian);
    const lon = Cesium.Math.toDegrees(cartographic.longitude);
    const lat = Cesium.Math.toDegrees(cartographic.latitude);
    const level = Math.round(viewer.camera.positionCartographic.height / 50000);

    // 查询要素
    const features = provider.turfQueryFeaturesByPosition(lon, lat, level);

    if (features.length > 0) {
      console.log("找到要素：", features);
      // 处理查询结果
      features.forEach((feature) => {
        console.log("图层：", feature.layerName);
        console.log("属性：", feature.properties);
      });
    }
  }
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

🎨 样式配置示例

完整示例

const style = {
  layers: [
    // 水域（面）
    {
      "source-layer": "water",
      type: "fill",
      paint: {
        "fill-color": "#0080ff",
        "fill-opacity": 0.5,
      },
    },
    // 道路（线）
    {
      "source-layer": "transportation",
      type: "line",
      paint: {
        "line-color": "#ff9e3f",
        "line-width": 2,
      },
    },
    // 建筑物（面+轮廓）
    {
      "source-layer": "building",
      type: "fill",
      paint: {
        "fill-color": "#999999",
        "fill-opacity": 0.8,
        "fill-outline-color": "#666666",
      },
    },
    // 兴趣点（点）
    {
      "source-layer": "poi",
      type: "circle",
      paint: {
        "circle-radius": 4,
        "circle-color": "#ff0000",
        "circle-opacity": 0.8,
      },
    },
  ],
};

🗺️ 坐标系说明

XYZ（Google/OSM 标准）

Y = 0 在北边（上）
Y = 2^z - 1 在南边（下）

适用于：Google Maps、OpenStreetMap、Mapbox 等

TMS（Tile Map Service）

Y = 0 在南边（下）
Y = 2^z - 1 在北边（上）

适用于：Tippecanoe、GeoServer 等

使用示例：

// TMS 坐标系
const provider = new VectorTileProvider({
  url: "https://your-tms-server.com/tiles/{z}/{x}/{y}.pbf",
  tileScheme: "tms", // 指定为 TMS
  style: {
    /* ... */
  },
});

🛠️ 开发指南

克隆仓库

git clone https://github.com/LionelSZ/VectorTileImageryProvider.git
cd VectorTileImageryProvider

安装依赖

npm install

构建

npm run build

构建产物位于 dist/ 目录：

• dist/index.es.js - ES Module 格式
• dist/index.umd.js - UMD 格式
• dist/index.d.ts - TypeScript 类型定义

运行示例

# 启动开发服务器
npm run dev

然后访问 http://localhost:5173/examples/ 查看示例。

测试

npm run test

📁 项目结构

VectorTileImageryProvider/
├── src/
│   ├── CesiumPbfLayer.ts      # 核心类
│   ├── types.d.ts             # 类型定义
│   ├── index.ts               # 入口文件
│   └── utils/
│       ├── index.ts           # 工具函数
│       └── parser.ts          # PBF 解析器
├── examples/
│   ├── index.html             # 示例页面
│   └── main.js                # 示例代码
├── dist/                      # 构建产物
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md

🤝 贡献指南

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启一个 Pull Request

📄 许可证

本项目采用 ISC 许可证 - 详见 LICENSE 文件。

🙏 致谢

• CesiumJS - 优秀的 3D 地球可视化库
• @mapbox/vector-tile - PBF 矢量瓦片解析
• Turf.js - 地理空间分析工具
• OpenMapTiles - 开源矢量瓦片标准

📮 联系方式

• 作者：LionelSZ
• GitHub：@LionelSZ
• 问题反馈：Issues

🔗 相关链接

• Cesium 官方文档
• Mapbox Vector Tile Spec
• OpenMapTiles Schema
• Turf.js 文档

如果这个项目对您有帮助，请给一个 ⭐️ Star！

Made with ❤️ by LionelSZ