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-cesium

Cesium 已作为运行依赖随 SDK 安装。业务项目不需要额外单独安装 Cesium。

快速开始

下面示例使用 JavaScript。

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

const sdk = await MaritimeGisSDK.create({
  container: "map",
  baseLayer: {
    type: "shipdt-chart"
  },
  controls: {
    scale: true,
    navigation: true,
    baseLayer: true
  }
});

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

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

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-cesium/ai/

License

Copyright (c) Loongship. License 以项目实际授权为准。