{"_id":"@duanhansong/cesium-sdk","_rev":"2-6943e978432d8c74e0919fd37c29cf03","name":"@duanhansong/cesium-sdk","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@duanhansong/cesium-sdk","version":"1.0.0","license":"MIT","_id":"@duanhansong/cesium-sdk@1.0.0","maintainers":[{"name":"duanhansong","email":"1530904047@qq.com"}],"dist":{"shasum":"4a27c1d769a38a9ed47209ad2d53e31af3650dd2","tarball":"https://registry.npmjs.org/@duanhansong/cesium-sdk/-/cesium-sdk-1.0.0.tgz","fileCount":5,"integrity":"sha512-Vn8oxpC601n5sDMEy9UxyYunJZzQvwvjsOHF5tltKaK5ti03igcBkXzsZAFxa6E6vooyRp4z67b6T3pe7yPO2w==","signatures":[{"sig":"MEUCIQCOSlE/CtFgHEXFN3GPgWXIFj1GkbPRZmrvRo44NLYz+wIgU86bsc+J8xdpOlPZHX7E0mG6ngtoANso8KVbp19Ca8Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":84634},"main":"./dist/cesium-sdk.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/cesium-sdk.es.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/cesium-sdk.es.js","require":"./dist/cesium-sdk.cjs"}},"gitHead":"d139e2c31ffadbff0e74010a43433d5d0707fba0","scripts":{"dev":"vite","test":"npm run build && node --test tests/*.test.mjs","build":"npm run typecheck && vite build && npm run minify:dist && npm run check:dist","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","test:unit":"node --test tests/*.test.mjs","typecheck":"tsc --noEmit","check:dist":"node scripts/check-dist.mjs","minify:dist":"node scripts/minify-dist.mjs","prepublishOnly":"npm run test"},"_npmUser":{"name":"duanhansong","email":"1530904047@qq.com"},"_npmVersion":"10.9.2","description":"A Cesium-based GIS SDK for urban planning, emergency command, military simulation, and data visualization","directories":{},"sideEffects":false,"_nodeVersion":"22.14.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^6.3.0","cesium":"1.136.0","terser":"^5.48.0","typescript":"^5.7.0","vite-plugin-dts":"^4.5.0"},"peerDependencies":{"cesium":"^1.136.0"},"_npmOperationalInternal":{"tmp":"tmp/cesium-sdk_1.0.0_1780388175295_0.7421142292277663","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@duanhansong/cesium-sdk","version":"1.0.1","type":"module","description":"A Cesium-based GIS SDK for urban planning, emergency command, military simulation, and data visualization","main":"./dist/cesium-sdk.cjs","module":"./dist/cesium-sdk.es.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/cesium-sdk.es.js","require":"./dist/cesium-sdk.cjs","default":"./dist/cesium-sdk.es.js"}},"typesVersions":{"*":{"*":["dist/index.d.ts"]}},"publishConfig":{"access":"public"},"sideEffects":false,"scripts":{"dev":"vite","build":"npm run typecheck && vite build && npm run minify:dist && npm run check:dist","test":"npm run build && node --test tests/*.test.mjs","test:unit":"node --test tests/*.test.mjs","typecheck":"tsc --noEmit","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs","clean":"node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"","minify:dist":"node scripts/minify-dist.mjs","check:dist":"node scripts/check-dist.mjs","prepublishOnly":"npm run test"},"engines":{"node":">=18"},"peerDependencies":{"cesium":"^1.136.0"},"devDependencies":{"cesium":"1.136.0","terser":"^5.48.0","typescript":"^5.7.0","vite":"^6.3.0","vite-plugin-dts":"^4.5.0","vitepress":"^1.6.4"},"license":"MIT","_id":"@duanhansong/cesium-sdk@1.0.1","gitHead":"d139e2c31ffadbff0e74010a43433d5d0707fba0","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-tCvF00HuMqAgH8vZdBEmwb9nn0rW4FLFav2CK4VrVGxnz7bJQBL9j9fPD5Wi2rSSQdXn3LYMRpgguv4IUY4Igg==","shasum":"205b9ce729e96332251f14ba1973c9b6882b2c30","tarball":"https://registry.npmjs.org/@duanhansong/cesium-sdk/-/cesium-sdk-1.0.1.tgz","fileCount":5,"unpackedSize":90159,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIG121eVaGmeXrZSjeJNifJSJMcGOn+rcYGkcLOmkz5uEAiAOCP2KkEN2c2AQ7588knFCnq1OvTPUnwF5wSVKAoxXxw=="}]},"_npmUser":{"name":"duanhansong","email":"1530904047@qq.com"},"directories":{},"maintainers":[{"name":"duanhansong","email":"1530904047@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cesium-sdk_1.0.1_1780391845068_0.8218744550987083"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-02T08:16:15.110Z","modified":"2026-06-02T09:17:25.323Z","1.0.0":"2026-06-02T08:16:15.434Z","1.0.1":"2026-06-02T09:17:25.217Z"},"license":"MIT","description":"A Cesium-based GIS SDK for urban planning, emergency command, military simulation, and data visualization","maintainers":[{"name":"duanhansong","email":"1530904047@qq.com"}],"readme":"# Cesium SDK\n\n`@duanhansong/cesium-sdk` 是一个 framework-agnostic 的 TypeScript Cesium SDK。当前版本聚焦于 Cesium Viewer 生命周期、影像图层、基础 Entity 图形、相机视角控制、插件生命周期和通用工具能力。\n\n## Requirements\n\n- Node.js 18+\n- Cesium 1.136.x，由宿主应用安装和配置\n\nCesium 是 peer dependency。SDK 不打包 Cesium，也不接管宿主应用的 assets、workers、token 和 bundler 配置。\n\n## Install\n\n```bash\nnpm install cesium @duanhansong/cesium-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { CesiumSDK } from \"@duanhansong/cesium-sdk\";\n\nconst sdk = new CesiumSDK(\"cesiumContainer\", {\n  ionAccessToken: \"your-token\",\n  cesiumBaseUrl: \"/cesium\",\n  shouldAnimate: true,\n});\n\nawait sdk.ready();\n\nconst point = sdk.entity.addPoint(\n  \"beijing\",\n  { longitude: 116.391, latitude: 39.907, height: 0 },\n  { pixelSize: 12, color: \"#ffcc00\" },\n);\n\nawait sdk.camera.flyToPosition({\n  longitude: 116.391,\n  latitude: 39.907,\n  height: 10000,\n});\n\npoint.setStyle({ color: \"#00aaff\" });\n\nawait sdk.destroy();\n```\n\n`sdk.layer`、`sdk.entity`、`sdk.camera`、`sdk.getCesiumViewer()` 和插件相关 API 需要在 `await sdk.ready()` 之后使用。`destroy()` 后 SDK 实例不可复用，需要重新创建实例。\n\n## Package Output\n\n`package.json` 当前声明的构建产物：\n\n- ESM: `dist/cesium-sdk.es.js`\n- CommonJS: `dist/cesium-sdk.cjs`\n- Type declarations: `dist/index.d.ts`\n\n包入口仅导出根路径：\n\n```typescript\nimport { CesiumSDK } from \"@duanhansong/cesium-sdk\";\n```\n\n## SDK Entry\n\n`CesiumSDK` 负责组合各个 manager，并提供统一生命周期：\n\n- `ready()`：初始化 Cesium Viewer，并创建 `LayerManager`、`EntityManager`、`CameraManager`、`PluginManager`。\n- `destroy()`：销毁插件、图形、图层、Viewer 和本地资源引用。\n- `use(plugin)`：安装插件。\n- `getPlugin(name)`：读取已安装插件。\n- `onLifecycle(hook, callback)`：监听 `beforeInit`、`afterInit`、`beforeDestroy`、`afterDestroy`。\n- `getCesiumViewer()`：获取底层 `Cesium.Viewer`。\n- `initialized` / `disposed`：读取 SDK 状态。\n\n初始化参数来自 `SDKConfig` 与 `ViewerInitOptions`：\n\n- SDK config: `ionAccessToken`、`cesiumBaseUrl`、`logLevel`。\n- Viewer options: `baseLayerPicker`、`geocoder`、`homeButton`、`sceneModePicker`、`navigationHelpButton`、`animation`、`timeline`、`fullscreenButton`、`vrButton`、`infoBox`、`selectionIndicator`、`shadows`、`shouldAnimate`、`debugShowFramesPerSecond`、`msaaSamples`、`extra`。\n\n## ViewerManager\n\n`ViewerManager` 负责 Cesium Viewer 的创建、销毁和生命周期 hook。\n\n主要能力：\n\n- `init()`：创建 `Cesium.Viewer`。\n- `destroy()`：销毁 viewer 并清理 Cesium 全局资源。\n- `getViewer()` / `getCesiumTarget()`：获取底层 `Cesium.Viewer`。\n- `isReady`：读取 viewer 是否初始化完成。\n- `lifecycle`：管理 viewer lifecycle hook。\n\n## LayerManager\n\n`LayerManager` 当前只管理影像图层。\n\n主要能力：\n\n- `addImageryLayer(provider, options)`：添加 `Cesium.ImageryProvider`，返回 `ImageryLayer`。\n- `get(id)`：按 id 获取图层。\n- `getAll()`：返回图层 Map snapshot。\n- `getByType(type)`：按 `LayerType` 查询图层。\n- `remove(id)`：移除指定图层。\n- `removeAll()`：移除全部图层。\n- `count`：读取图层数量。\n\n`ImageryLayer` 支持：\n\n- `visible`、`show()`、`hide()`：控制显隐。\n- `opacity`：读取或设置透明度，范围 `0` 到 `1`。\n- `flyTo()`：飞到该影像图层。\n- `remove()`：从 viewer 中移除图层。\n- `getCesiumTarget()`：获取底层 `Cesium.ImageryLayer`。\n\n## EntityManager\n\n`EntityManager` 当前支持 point、polyline、polygon 三类基础图形。\n\n主要能力：\n\n- `addPoint(id, position, style)`：添加点。\n- `addPolyline(id, positions, style)`：添加线，至少 2 个坐标。\n- `addPolygon(id, positions, style)`：添加面，至少 3 个坐标。\n- `get(id)`：按 id 获取图形。\n- `getAll()`：返回图形 Map snapshot。\n- `getByType(type)`：按 `GraphicType` 查询图形。\n- `remove(id)`：移除指定图形。\n- `removeAll()`：移除全部图形。\n- `count`：读取图形数量。\n\n图形对象公共能力：\n\n- `visible`、`show()`、`hide()`：控制显隐。\n- `flyTo(options)`：飞到图形。\n- `remove()`：移除图形。\n- `getCesiumTarget()`：获取底层 `Cesium.Entity`。\n\n各图形更新能力：\n\n- `PointGraphic`: `getPosition()`、`setPosition(position)`、`getStyle()`、`setStyle(style)`。\n- `PolylineGraphic`: `getPositions()`、`setPositions(positions)`、`getStyle()`、`setStyle(style)`。\n- `PolygonGraphic`: `getPositions()`、`setPositions(positions)`、`getStyle()`、`setStyle(style)`。\n\n## CameraManager\n\n`CameraManager` 负责视角读取、飞行、定位、跟踪和书签。\n\n主要能力：\n\n- `getCurrentViewpoint()`：获取当前相机视角。\n- `flyTo(viewpoint, options)`：飞到指定 `Viewpoint` 或 `ViewpointData`。\n- `flyToPosition(coord, options)`：按 WGS84 坐标飞行。\n- `setView(viewpoint)`：立即设置视角。\n- `zoomGlobal(duration)`：缩放到全局视角。\n- `zoomTo(target, duration)`：飞到 `Cesium.Entity`、`Cesium.EntityCollection` 或 `Cesium.DataSource`。\n- `lockTo(entity)` / `unlock()`：设置或取消 `trackedEntity`。\n- `addBookmark(id, name, viewpoint)`：添加视角书签，未传 viewpoint 时使用当前视角。\n- `getBookmark(id)`、`getAllBookmarks()`、`removeBookmark(id)`、`flyToBookmark(id, options)`：管理和使用书签。\n- `getCesiumTarget()`：获取底层 `Cesium.Camera`。\n- `destroy()`：清理相机 manager 内部状态。\n\n## PluginManager\n\n插件通过 `CesiumSDK.use(plugin)` 安装。插件接口为：\n\n```typescript\ninterface ISDKPlugin {\n  readonly name: string;\n  install(sdk: CesiumSDK): void | Promise<void>;\n  destroy(): void | Promise<void>;\n}\n```\n\n`PluginManager` 支持插件注册、卸载、查询、批量销毁和数量统计。`CesiumSDK.destroy()` 会自动调用已安装插件的 `destroy()`。\n\n## Utilities\n\n当前根入口导出以下通用能力：\n\n- Common: `SDKError`、`ErrorCode`、`EventEmitter`、`ConfigStore`、`DisposePool`、`Logger`、`LogLevel`、`SDK_VERSION`、`WGS84`、`DEG_TO_RAD`、`RAD_TO_DEG`。\n- Util: `CoordinateUtil`、`MathUtil`、`ColorUtil`、`MemoryUtil`、`ValidationUtil`。\n- Types: `SDKOptions`、`SDKEvents`、`SDKConfig`、`ViewerInitOptions`、`WGS84Coordinate`、`ScreenCoordinate`、`RGBA`、`ViewpointLike`、`AddImageryLayerOptions`、`PointStyle`、`PolylineStyle`、`PolygonStyle`、`FlyToOptions`、`ViewpointBookmark`、`ViewpointData`、`ISDKPlugin`。\n\n## Error Behavior\n\n运行时参数校验由 `ValidationUtil` 负责。常见错误行为：\n\n- 空 id、非法坐标、非法颜色、非法透明度、非法 duration 等参数会抛出 `SDKError(ErrorCode.INVALID_OPTIONS, ...)`。\n- 重复图层 id 会抛出 `SDKError(ErrorCode.LAYER_ALREADY_EXISTS, ...)`。\n- 重复实体 id 会抛出 `SDKError(ErrorCode.ENTITY_ALREADY_EXISTS, ...)`。\n- 重复插件 name 会抛出 `SDKError(ErrorCode.PLUGIN_ALREADY_INSTALLED, ...)`。\n- 未初始化时访问 manager 会抛出 `SDKError(ErrorCode.VIEWER_NOT_INITIALIZED, ...)`。\n- 已销毁资源继续访问会抛出 `SDKError(ErrorCode.RESOURCE_DISPOSED, ...)`。\n\n## Not Implemented Yet\n\n以下能力不是当前公开实现的一部分，不应作为当前 API 使用：\n\n- Terrain layer\n- 3D Tiles layer\n- Billboard graphic\n- Model graphic\n- Drawing\n- Measurement\n- Spatial analysis\n- Roaming\n\n## Build And Test\n\n```bash\nnpm run typecheck\nnpm run build\nnpm test\n```\n\n如果 PowerShell execution policy 阻止 `npm.ps1`，可以直接运行底层命令：\n\n```bash\nnode .\\node_modules\\typescript\\bin\\tsc --noEmit\nnode .\\node_modules\\vite\\bin\\vite.js build\nnode --test tests\\*.test.mjs\n```\n\n## Development Notes\n\n- 源码使用 UTF-8 编码。\n- SDK 保持 framework-agnostic，不假设 React、Vue 或其他宿主框架。\n- Cesium assets、workers、token 由宿主应用负责。\n- 内部 Cesium cleanup helper 可能触碰 Cesium private API，升级 Cesium 时需要重点验证。\n","readmeFilename":"README.md"}