Rayshon High Performance GIS

本项目是一个基于 Cesium 的高性能 GIS 增强库，专为处理海量地理空间数据（如行政边界、成千上万的地名标注）而设计。通过使用 Cesium Primitive API、Web Worker 多线程解析 以及 离线缓存机制，在确保界面丝滑（无主线程卡顿）的同时，大幅提升了数据加载和渲染性能。

1. 行政边界渲染 (Boundary Rendering)

1.1 项目介绍

边界渲染模块通过解析 PBF 格式的地理数据，并将其转换为 Cesium 的 Primitive 对象进行渲染。相比传统的 Entity 模式，Primitive 能够支持更多数量级的线条绘制。

1.2 如何调用

使用 cesiumPrimitive 异步方法进行初始化加载。

import { cesiumPrimitive } from 'rayshon-high-performance-gis';

const boundaryLists = [
  {
    key: 'shanghaiBoundary',
    geoJson: '/data/shanghai.pbf',
    color: '#00FFFF',
    width: 2,
    show: true
  }
];

// 调用方法
await cesiumPrimitive(boundaryLists, viewer);

1.3 参数说明

cesiumPrimitive(dataInfo, mainViewer) 接收两个参数：

• dataInfo: 一个对象数组，每个对象包含以下字段：
  • key (string): 唯一标识符，用于后续控制显隐。
  • geoJson (string): PBF 数据文件的路径。
  • color (string): 颜色字符串（如 '#FF0000'）。
  • width (number): 线条宽度。
  • show (boolean): 初始显隐状态，默认为 true。
• mainViewer: 包含 Cesium Viewer 的实例对象。

1.4 如何隐藏/显示边界

使用 toggleDisplayBoundary 方法，通过 key 来一键切换显示状态。

import { toggleDisplayBoundary } from 'rayshon-high-performance-gis';

// 切换特定 key 的边界显隐
toggleDisplayBoundary('shanghaiBoundary');

2. 城市名称/地名标注 (Place Name Label)

2.1 项目介绍

PlaceNameProvider 专门用于渲染超大规模的地名标注。它采用分帧加载技术，在加载数万个点位时不会导致浏览器 UI 冻结。支持文字标注和图标（Billboard）同步渲染。

2.2 如何调用

使用 PlaceNameProvider.initLabelName 静态方法进行初始化。

import { PlaceNameProvider } from 'rayshon-high-performance-gis';

const labelLists = [
  {
    key: 'city_labels',
    geoJson: '/data/cities.pbf',
    show: true,
    distanceSmall: 0,
    distanceLarge: 500000,
    style: {
      labelSize: 18,
      labelColor: '#FFFFFF',
      labelBorderColor: '#000000CC',
      labelBorderWidth: 4
    }
  }
];

// 调用静态初始化方法
await PlaceNameProvider.initLabelName(viewer.cesium, labelLists);

2.3 参数说明

PlaceNameProvider.initLabelName(cesiumViewer, list) 接收两个参数：

• cesiumViewer: Cesium 的 Viewer 实例。
• list: 一个对象数组，每个对象包含以下字段：
  • key (string): 唯一标识符。
  • geoJson (string): PBF 数据文件路径。
  • show (boolean): 初始显隐状态。
  • distanceSmall / distanceLarge (number): 可选。标注显示的距离范围（对应 Cesium 的 DistanceDisplayCondition）。
  • style (object): 可选。配置标注的字体大小、颜色、描边等样式。

2.4 如何隐藏/显示标注

通过静态方法 getProvider 获取对应的实例，然后调用 setShow 方法。

// 隐藏标注
const provider = PlaceNameProvider.getProvider('city_labels');
if (provider) {
  provider.setShow(false);
}

// 显示标注
provider?.setShow(true);

3. 核心优势

• 流畅性: 所有 PBF 解析均在 Web Worker 中完成，不占用主线程。
• 性能: 使用低级 Primitive API，支持万级对象同屏。
• 防抖加载: 内置加载状态锁，防止同一资源并行重复加载引起显存溢出。
• 按需显隐: 提供一键式显隐控制，无需频繁销毁和创建对象。