Rayshon High Performance GIS 说明文档

rayshon-high-performance-gis 是一个专为 Cesium 打造的高性能地理空间数据增强库。它针对海量数据（如超大规模行政边界、数万级地名标注）进行了深度优化，通过底层 Primitive API、Web Worker 多线程解析和离线缓存机制，确保在处理复杂地理信息时，主线程依然保持丝滑流畅。

🚀 核心优势

• 极致流畅：所有 PBF 数据解析均在 Web Worker 中完成，避免阻塞 UI 主线程。
• 超高性能：采用低级 Primitive API 代替 Entity，支持万级对象同屏渲染而不掉帧。
• 防抖加载：内置加载状态锁，防止同一资源并行重复加载导致的内存溢出。
• 按需受控：提供一键式显隐切换与范围控制，无需频繁创建/销毁对象。

🛠 前期准备

1. 安装依赖

   yarn add rayshon-high-performance-gis

2. 数据转换
   • 准备好边界或标注的原始 GeoJSON 文件。
   • 使用内部转义工具 http://192.168.1.44:10700/ 将 GeoJSON 转义为 PBF 文件以获取最佳解析速度。

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

1.1 基本调用

使用 cesiumPrimitive 异步方法初始化边界加载。

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

const boundaryLists = [
  {
    key: "shanghaiBoundary",
    geoJson: "/data/shanghai.pbf",
    color: "#00FFFF",
    width: 2,
    show: true,
    clampToGround: true,
    isOpenDistance: true,
    distanceSmall: 10000,
    distanceLarge: 60000,
  },
];

// 初始化渲染
cesiumPrimitive(boundaryLists, viewer);

1.2 参数说明 (dataInfo 对象属性)

| 参数名 | 类型 | 默认值 | 描述 | 版本要求 | | :----------------- | :-------- | :------ | :------------------------------------------------------ | :--------- | | key | string | - | 必传。唯一标识符，用于后续控制显隐。 | - | | geoJson | string | - | 必传。PBF 格式数据文件的路径。 | - | | color | string | - | 线条颜色（如 '#FF0000'）。 | - | | width | number | - | 线条像素宽度。 | - | | show | boolean | true | 初始显示状态。 | - | | clampToGround | boolean | false | 是否开启贴地渲染。 | >= 1.0.7 | | isOpenDistance | boolean | false | 是否开启可视范围显隐控制。开启后必须传距离参数。 | >= 1.0.8 | | distanceSmall | number | - | 显示的最小相机距离（对应 DistanceDisplayCondition）。 | >= 1.0.8 | | distanceLarge | number | - | 显示的最大相机距离。 | >= 1.0.8 |

1.3 管理方法

| 方法名 | 说明 | 示例 | | :--------------------------------------- | :----------------------------------------------- | :------------------------------------------- | | toggleDisplayBoundary | 切换特定 key 的显隐状态。 | toggleDisplayBoundary('shanghaiBoundary') | | destroyBoundary | 彻底卸载边界并释放显存（需传入 viewer）。 | destroyBoundary(viewer) | | toggleAllBoundariesDistanceCondition | 全局切换是否遵循可视范围过滤（传入 boolean）。 | toggleAllBoundariesDistanceCondition(true) |

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

2.1 基本调用

使用 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,
    },
  },
];

// 静态初始化
PlaceNameProvider.initLabelName(viewer.cesium, labelLists);

2.2 参数说明 (list 对象属性)

| 参数名 | 类型 | 描述 | | :---------------- | :-------- | :------------------------------- | | key | string | 必传。唯一标识符。 | | geoJson | string | 必传。PBF 标注文件路径。 | | show | boolean | 初始显示状态。 | | distanceSmall | number | 标注显示的最小可视范围。 | | distanceLarge | number | 标注显示的最大可视范围。 | | style | object | 样式配置对象（可选），详见下表。 |

style 配置项详情

| 属性名 | 类型 | 描述 | | :------------------- | :------- | :----------------------- | | labelSize | number | 字体大小（单位：像素）。 | | labelColor | string | 字体填充颜色。 | | labelBorderColor | string | 字体描边颜色。 | | labelBorderWidth | number | 字体描边宽度。 |

2.3 动态控制

由于标注系统采用 Provider 模式管理，可以通过 key 获取实例进行细粒度控制。

// 获取实例
const provider = PlaceNameProvider.getProvider("city_labels");

if (provider) {
  // 隐藏标注
  provider.setShow(false);
  // 显示标注
  provider.setShow(true);
}