Loongship Cesium SDK

简介

Loongship Cesium SDK 是一个基于 Cesium 的海事 GIS 前端 SDK，面向海事业务开发、GIS 可视化、船舶态势、航线轨迹、海洋气象和业务系统集成场景。

SDK 运行在浏览器端，适用于 Vue、React、原生 JavaScript 以及 AI Agent / Vibe Coding 辅助开发工作流。

支持能力包括：

• 全球船舶展示
• AIS 船舶数据接入
• 海量船舶渲染
• 航迹回放
• 海洋气象图层
• 插件扩展体系

功能特性

船舶

• 全球船舶展示
• AIS 实时更新
• MMSI 查询定位
• 船舶轨迹
• 船舶点击、悬停、选中和业务弹窗

渲染

• 10 万级船舶渲染
• GPU 批量渲染扩展
• Worker 数据预处理
• LOD 远中近切换
• 点、三角船舶符号和 glTF 模型展示

GIS

• Cesium 三维地球
• 地图、影像、海图、地形和 3D Tiles 图层管理
• GeoJSON / CZML / KML 数据接入
• 绘制、测量、Popup、Tooltip、ContextMenu
• 插件机制

安装

npm install @loongship-gis/cesium cesium

Cesium 是 SDK 的 peer dependency，需要由业务项目显式安装，以确保宿主与 SDK 共用同一份 Cesium 运行时。

三维地图默认使用 theme: "classic"，控件、Tooltip、Popup 和菜单采用与冻结二维经典视觉协调的变量；销毁地图时会恢复容器原有主题类。小范围试用项目如需保留此前未设主题的三维视觉，可显式传入 theme: "default"。暗色 unified 主题继续通过 @loongship-gis/cesium/unified.css 提供。主题只改变呈现，不改变公共 API 和资源生命周期。

快速开始

新业务可使用与 Leaflet 一致的 Core 地图契约。Cesium 的 zoom 由相机高度近似换算；创建时选择引擎，单个实例不支持运行中热切换。

import { createMap } from "@loongship-gis/cesium";

const map = await createMap({
  engine: "cesium",
  container: "map",
  center: { longitude: 121.8, latitude: 31.2 },
  zoom: 8,
  baseLayer: false
});

await map.flyTo(
  { center: { longitude: 122.2, latitude: 29.9 }, zoom: 9 },
  { durationMs: 800 }
);

const canvasTiles = await map.addCanvasTileLayer({
  url: "https://tiles.example.com/{z}/{x}/{y}.png"
});
const vectorTiles = await map.addVectorTileLayer({
  data: geojson,
  style: { color: "#f97316", weight: 3, fillColor: "#f59e0b", fillOpacity: 0.3 }
});

vectorTiles.destroy();
canvasTiles.destroy();
map.destroy();

这两个方法与 Leaflet 共享最低公共契约。Cesium 将 Canvas URL 图层适配为 ImageryLayer，因此忽略 enableDpi / drawDelayMs；将 Vector GeoJSON 适配为 DataSource，因此不承诺 Leaflet GeoJSON-VT 的客户端切片、原生命中或 Popup。输入 GeoJSON 使用 WGS84，返回句柄负责显隐和销毁。

script 标签

全局构建只包含 LoongShip SDK 和 Core 契约，Cesium 引擎、CSS、Workers 和静态资源由宿主页面提供。CESIUM_BASE_URL 必须在加载 Cesium 前设置，并指向包含 Assets、ThirdParty、Widgets 和 Workers 的 Cesium 构建目录。

<link rel="stylesheet" href="/Cesium/Widgets/widgets.css">
<script>window.CESIUM_BASE_URL = "/Cesium/";</script>
<script src="/Cesium/Cesium.js"></script>
<script src="/vendor/loongship-cesium.global.js"></script>
<script>
  LoongShip.createMap({
    engine: "cesium",
    container: "map",
    center: { longitude: 121.8, latitude: 31.2 },
    zoom: 8,
    baseLayer: false
  });
</script>

全局文件随 npm 包发布为 dist/loongship-cesium.global.js，默认船模从包内 shipModels/ 解析。Leaflet 和 Cesium 的全局构建都会占用 window.LoongShip，同一页面需要双引擎时应使用模块化入口，并在切换时销毁旧实例后重建。

需要三维图层、船舶、轨迹和气象等 Cesium 专属能力时，通过 map.getNativeSdk() 获取当前 MaritimeGisSDK。统一领域模块会在后续阶段继续映射，未声明的能力不会静默降级。

下面示例使用 JavaScript。

import { MaritimeGisSDK } from "@loongship-gis/cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

const sdk = await MaritimeGisSDK.create({
  container: "map",
  baseLayer: "chart",
  baseLayers: {
    chart: {
      type: "shipdt-chart",
      url: "/tiles/chart/{z}/{y}/{x}.png"
    }
  },
  controls: {
    scale: true,
    zoomChange: true,
    fullscreen: true,
    mapChange: true,
    position: "topright",
    layout: "vertical"
  }
});

await sdk.setView({
  longitude: 121.8,
  latitude: 31.2,
  height: 90000
});

const vessels = await sdk.createVesselLayer({
  vessels: [{ mmsi: "412000001", name: "Demo", longitude: 121.5, latitude: 31.2 }]
});

vessels.on("click", ({ vessel }) => vessels.selectVessel(vessel.mmsi ?? vessel.id));

普通与全球船舶 Core 句柄的 click 都只派发事件；示例中的显式 selectVessel() 才改变选择，避免切换引擎后出现不同副作用。

Cesium 影像必须允许 WebGL 跨域读取。内置 ShipDT 海图端点不返回所需 CORS 响应头，因此直接选择默认 chart 会以 BASE_LAYER_CORS_PROXY_REQUIRED 拒绝并保留当前可用底图。应用应通过 baseLayers.chart 配置支持 CORS 的海图源，或像上例一样提供同源代理；SDK 不会用空白或假图层冒充成功。

运行时地形通过 sdk.setTerrain(config) 切换。world、url、ion、custom 和 false 共用事务契约：Provider 创建与首批瓦片在 timeoutMs（默认 15 秒）内就绪后才发出 terrain-change；失败或超时发出 terrain-error，已应用的新地形会回滚，未应用时旧地形保持不变。 自定义 Provider factory 接收 AbortSignal，切换被替代或 SDK 销毁时会取消等待：

import { EllipsoidTerrainProvider } from "cesium";

await sdk.setTerrain({
  type: "custom",
  timeoutMs: 10_000,
  factory: async ({ signal }) => {
    signal.throwIfAborted();
    return new EllipsoidTerrainProvider();
  }
});

sdk.on("terrain-change", () => {
  // 此时再初始化依赖地形首批瓦片的地名或业务覆盖物。
});

Token、ACL、代理和第三方地名插件仍由应用提供；SDK 不会把外部服务失败伪装为成功。

HTML 容器示例：

<div id="map" style="width: 100vw; height: 100vh;"></div>

Vue3 项目接入

下面示例为 Vue3 + JavaScript，包含组件挂载、SDK 初始化和销毁处理。

<template>
  <div ref="mapRef" class="map-view"></div>
</template>

<script setup>
import { onBeforeUnmount, onMounted, ref } from "vue";
import { MaritimeGisSDK } from "@loongship-gis/cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

const mapRef = ref(null);
let sdk;

onMounted(async () => {
  sdk = await MaritimeGisSDK.create({
    container: mapRef.value,
    baseLayer: {
      type: "shipdt-chart"
    },
    controls: {
      scale: true,
      navigation: true,
      baseLayer: true
    }
  });

  await sdk.setView({
    longitude: 122.2,
    latitude: 29.9,
    height: 120000
  });
});

onBeforeUnmount(() => {
  sdk?.destroy();
  sdk = undefined;
});
</script>

<style scoped>
.map-view {
  width: 100%;
  height: 100vh;
}
</style>

React 项目接入

下面示例为 React + JavaScript。

import { useEffect, useRef } from "react";
import { MaritimeGisSDK } from "@loongship-gis/cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";

export default function MaritimeMap() {
  const mapRef = useRef(null);

  useEffect(() => {
    let sdk;
    let disposed = false;

    async function init() {
      sdk = await MaritimeGisSDK.create({
        container: mapRef.current,
        baseLayer: {
          type: "shipdt-chart"
        },
        controls: {
          scale: true,
          navigation: true,
          baseLayer: true
        }
      });

      if (disposed) {
        sdk.destroy();
        return;
      }

      await sdk.setView({
        longitude: 122.2,
        latitude: 29.9,
        height: 120000
      });
    }

    init();

    return () => {
      disposed = true;
      sdk?.destroy();
    };
  }, []);

  return <div ref={mapRef} style={{ width: "100%", height: "100vh" }} />;
}

核心场景

GlobalShipTileScene

GlobalShipTileScene 是全球船舶业务场景，适合接入真实船舶接口，按当前视野加载全球船舶数据。

特点：

• 业务接口驱动
• BBox 请求
• 缓存
• 渐进加载
• MMSI 去重
• 船舶搜索、选中、点击和悬停
• 绑定式 Tooltip 和点击选中

示例：

const globalShips = sdk.createGlobalShipTileScene("global-ships", {
  url: "https://example.com/ship/getAreaShip",
  params: {
    shipStatus: "SAILING,STOP",
    nationalityType: "1,2,3"
  },
  renderer: "cesium",
  rendererOptions: {
    mode: "auto",
    enabledRenderModes: {
      point: true,
      triangle: true,
      model: true
    },
    modelFallback: "triangle"
  },
  lod: {
    enableModel: true
  }
});

globalShips.bindTooltip("default", {
  content: (ship) => ship.name ?? ship.mmsi ?? ship.id ?? "未知船舶"
});

globalShips.bindInteractions({
  hoverTooltip: true,
  clickSelect: true,
  emitShipEvents: true
});

await globalShips.refresh({ force: true });

const matches = globalShips.searchShips("413000000");
if (matches[0]) {
  globalShips.selectShip(String(matches[0].id ?? matches[0].mmsi));
}

mode: "auto" 表示按视角在点、三角和模型之间切换；是否加载近景模型仍由 lod.enableModel 和模型资源共同决定。模型不可用时可通过 rendererOptions.modelFallback 选择回退默认模型、三角、点或隐藏。

TrackLayer

TrackLayer 用于船舶历史轨迹回放，支持播放、暂停、倍速、当前点插值、历史点显示、屏幕像素流光和可选尾迹。

双引擎业务优先使用 Core MapEngine#createTrackLayer()：Cesium 适配器现以 Billboard 呈现 图片目标旋转，按状态色、速度色、默认色的顺序绘制分段，并用描边/光环显示 selectedTrackId；selectTrack()、隐藏、数据替换和销毁都会同步重建或释放这些 Primitive。

const track = sdk.createTrackLayer("track-playback", {
  points: {
    visible: true,
    maxVisible: 3000,
    color: "#38bdf8",
    collision: {
      enabled: true,
      minPixelDistance: 18,
      viewer: sdk.getViewer()
    },
    tooltip: {
      content: (point, context) => `${context.formatTime(point.timestamp)} / ${point.speed} kn`
    },
    label: {
      visible: true,
      content: (point) => `${point.speed.toFixed(2)}kn ${point.timestamp}`,
      minPixelDistance: 90,
      viewer: sdk.getViewer()
    }
  },
  flow: {
    enabled: true,
    color: "rgba(255,255,255,0.96)",
    glowColor: "rgba(255,255,255,0.72)",
    width: 5,
    lengthPx: 36,
    gapPx: 34,
    speedPxPerSecond: 80,
    maxSegments: 80,
    viewer: sdk.getViewer()
  }
});

track.loadTrack([
  { longitude: 121.5, latitude: 31.1, timestamp: 0, heading: 60, speed: 8 },
  { longitude: 121.8, latitude: 31.2, timestamp: 60, heading: 80, speed: 10 },
  { longitude: 122.0, latitude: 31.35, timestamp: 120, heading: 95, speed: 12 }
]);

track.play({ speed: 2, loop: true });

MassiveShipScene

MassiveShipScene 是海量船舶渲染场景，适合验证或展示 10 万级船舶渲染能力。

特点：

• 10 万级船舶
• GPU 渲染扩展
• Worker 预处理
• LOD 切换
• AIS 批量更新

示例：

const massiveShips = sdk.createMassiveVesselLayer("massive-ships", {
  mode: "auto",
  worker: true,
  culling: {
    enabled: true
  }
});

await massiveShips.load([
  {
    id: "ship-1",
    mmsi: "413000000",
    name: "DEMO SHIP",
    longitude: 122.15,
    latitude: 29.92,
    heading: 90,
    speed: 12,
    vesselType: "cargo"
  }
]);

GlobalShipTileScene 与 MassiveShipScene 是独立场景。前者面向真实全球船舶业务接口，后者面向海量渲染能力验证。不要把两者混用，也不要为了修改一个场景而改动另一个场景。

AI / Vibe Coding 支持

SDK npm 包中包含 AI 友好文档：

ai/
├── AGENTS.md
├── API_INDEX.md
├── ARCHITECTURE.md
├── EXAMPLES.md
├── RULES.md
└── SDK_MANIFEST.json

AI Agent 推荐优先阅读：

• ai/AGENTS.md
• ai/API_INDEX.md
• ai/ARCHITECTURE.md
• ai/EXAMPLES.md

适用于：

• Codex
• Claude Code
• Cursor
• Gemini CLI
• Windsurf

安装后可在以下目录直接访问：

node_modules/@loongship-gis/cesium/ai/

License

Copyright (c) 2026 LoongShip. 本包依据随包提供的 LoongShip GIS SDK Commercial License 授权，详见 LICENSE。shipModels/ 中现有及后续更新的 LoongShip 自有船模适用独立的 shipModels/LICENSE。