@cveo/dsh-digital-earth 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 1.0.0
+
+首个公开版本（npm 包名 `@cveo/dsh-digital-earth`，面板名「数字地球 / Digital Earth」）。
+
+- 3D Tiles 浏览：b3dm / glb（3D Tiles 1.0 / 1.1）与 3DGS（`KHR_gaussian_splatting`，含 SPZ 压缩）。
+- 数据加载：本地目录递归扫描 `tileset.json`；在线 `http(s)` 地址（跨域失败自动走 Host 代理）；本机绝对路径。
+- 数据源管理：影像底图与地形数据源可在设置中增删改（XYZ / WMS / ArcGIS / Cesium 地形），选中的底图与地形持久化到 `$DSH_HOME/digital-earth/sources.json`，支持恢复默认。
+- 底图与地形：默认 Esri World Imagery 与 ArcGIS WorldElevation3D，均可关闭或切换；内置 7 个 Esri 底图预设（地形图 / 街道图 / 浅灰 / 晕渲 / 海洋 / 山体阴影），新增预设自动合并进已有配置。
+- 双语界面：跟随 DSH 语言（中文 / English），运行时切换即时生效（槽位 `locale` 命名空间 + 全局字典注册）。
+- 浅深主题：默认跟随 DSH / 系统；顶栏「外观」下拉提供 跟随系统 / 浅色 / 深色 三选，设置中亦可切换，仅作用于本面板（自有 `--mv-*` 变量 + Cesium 调色板同步）。
+- 图层面板：显隐、定位、移除、叠加，按图层统计瓦片 / 三角面 / 缓存。
+- 工具：测距、测面、测高、拾取属性、截图、复位视角。
+- 坐标 HUD：光标经纬度与高程在裸地球、地形、3D Tiles / 3DGS 三种情形下均可用（射线—椭球求交 + 模型深度拾取 + `globe.getHeight` 地形校正，~8 Hz，DOM 直写不触发重渲染）。
+- 数据源表单：XYZ 支持 TMS（Y 轴南起），并可直接选择本地 XYZ 瓦片目录作为底图（离线可用）。
+- 安全：Connection 会话 / 同源校验、一次性 token、本地目录白名单、代理内网地址拦截。
+- CesiumJS 1.147 自托管（中国大陆网络可用）。
+- 设置面板页脚展示维护团队：武汉大学 CVEO 课题组（https://www.whu-cveo.com/）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CVEO Research Group, Wuhan University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,13 @@
+dsh-digital-earth
+================
+
+This product bundles CesiumJS 1.147.0 (vendor/cesium), which is distributed
+under the Apache License, Version 2.0. A copy of that license is included at
+vendor/cesium/LICENSE.md; Cesium's own third-party notices are under
+vendor/cesium/ThirdParty.
+
+Cesium® is a registered trademark of Cesium GS, Inc. This plugin is not
+affiliated with or endorsed by Cesium GS, Inc.
+
+Imagery and elevation are streamed at runtime from public ArcGIS services and
+remain subject to Esri's terms of use.

package/README.en.md

@@ -0,0 +1,124 @@
+<div align="center">
+
+# Digital Earth
+
+**A DeepSeek Harness panel for 3D Tiles and 3DGS layers on a CesiumJS globe**
+
+[中文](README.md) · [English](README.en.md)
+
+![version](https://img.shields.io/badge/version-1.0.0-4f8cff)
+![license](https://img.shields.io/badge/license-MIT-2ea44f)
+![platform](https://img.shields.io/badge/platform-Web-8b5cf6)
+![DSH](https://img.shields.io/badge/DSH-%3E%3D0.2.1--rc.1-0ea5e9)
+
+</div>
+
+![Preview](preview.png)
+
+Digital Earth adds a CesiumJS globe to the DSH main workspace so photogrammetry and Gaussian-splatting deliverables can be explored in one panel. CesiumJS 1.147 is self-hosted: no Cesium ion token, no external static assets.
+
+## Features
+
+| Capability | Details |
+| --- | --- |
+| 3D Tiles & 3DGS | Recursive `tileset.json` discovery from a local folder; 3D Tiles 1.0 / 1.1 (b3dm, glb) and 3DGS (`KHR_gaussian_splatting`, SPZ included); multiple layers with show / hide, fly-to and remove |
+| Online & local paths | Paste an `http(s)` URL or an absolute local path; cross-origin failures fall back to the host proxy automatically |
+| Basemaps | Built-in Esri presets plus custom XYZ (TMS, projection, subdomains, max level) / WMS / ArcGIS services; the no-basemap mode stays fully usable |
+| Terrain | ArcGIS WorldElevation3D built in; any Cesium or ArcGIS terrain service can be added |
+| Local tiles | Point at a local XYZ / TMS tile folder and use it as a basemap offline |
+| Source management | Add, edit, delete, select and restore defaults in the settings panel; persisted to `$DSH_HOME/digital-earth/sources.json` |
+| Cursor HUD | Longitude / latitude plus elevation on the bare globe, terrain and 3D surfaces; ~8 Hz sampling without React re-renders |
+| Measurement | Distance, area, height difference, 3D Tiles property picking, PNG snapshot, reset view |
+| Layer statistics | Tiles, pending tiles, triangles and cache per layer; global FPS and camera height / heading |
+| Bilingual | Follows the DSH language and switches between Chinese and English at runtime |
+| Theme | Follows DSH or the system; explicit light / dark override scoped to this panel |
+
+## Requirements
+
+- DeepSeek Harness `>=0.2.1-rc.1 <0.3.0-0`
+- A modern browser with WebGL / WebGL2
+- Network access to the public ArcGIS services (`server.arcgisonline.com`, `elevation3d.arcgis.com`)
+
+## Install
+
+Search for “Digital Earth” in the plugin market, or use the CLI:
+
+```bash
+# from the npm registry
+dsh plugin --profile <profile> add @cveo/dsh-digital-earth
+
+# from a local folder or tarball
+dsh plugin --profile <profile> add "<path-to-plugin>"
+dsh plugin --profile <profile> add "./cveo-dsh-digital-earth-1.0.0.tgz"
+```
+
+Fully quit and reopen DSH after installing or updating: client bundles are registered when the host starts, so reloading the page alone is not enough. The “Digital Earth” entry then appears in the sidebar.
+
+## Usage
+
+| Entry | What it does |
+| --- | --- |
+| **Data ▾** | Open a local folder (`tileset.json` discovery), load an online URL or local path, clear measurements and picking results |
+| **Basemap ▾ / Terrain ▾** | Switch between configured sources, or turn basemap / terrain off |
+| **Measure ▾** | Distance, area, height, property picking; left click to add a point, double click to finish |
+| **Layers n** | Layer list: click a name to fly to it, ◉ toggles visibility, ✕ removes it |
+| **Appearance** | Follow system / light / dark |
+| **Settings** | Source management (imagery / terrain) and appearance |
+
+Cursor coordinates are sampled at roughly 8 Hz: a ray–ellipsoid intersection keeps the readout alive on the bare globe, the depth buffer provides 3D Tiles / 3DGS surface elevations, and `globe.getHeight` corrects terrain. HUD text is written straight to the DOM, so it never triggers React re-renders.
+
+## Data sources
+
+All built-in presets are token-free ArcGIS public services and can be enabled in one click from the settings panel:
+
+| Kind | Presets |
+| --- | --- |
+| Imagery | Esri World Imagery, World Topographic, World Street Map, Light Gray Canvas, World Shaded Relief, World Ocean, World Hillshade |
+| Terrain | ArcGIS WorldElevation3D |
+
+Custom sources support:
+
+- **XYZ tiles** — `{z}/{x}/{y}` templates, TMS (south-origin Y), Web Mercator / geographic projection, subdomains, maximum level, attribution
+- **WMS** — service URL plus layer names
+- **ArcGIS** — MapServer URL (level metadata is read automatically)
+- **Cesium terrain** — terrain service URL with optional vertex normals / water mask
+- **Local tile folders** — pick a folder right from the XYZ form; the host exposes it through its directory whitelist
+
+Selections persist with the rest of the catalog, so changing ports or restarting DSH never loses them.
+
+## How it works
+
+- **Host** (`index.js`) registers the `/api/3dviewer/*` routes: Cesium static assets, local folder scanning and whitelisting, tile serving, the cross-origin proxy and catalog persistence.
+- **Client** (`client.js`) loads as a DSH client module, claims the `sidebar.panellist` and `main` slots, and dynamically imports the self-hosted CesiumJS build.
+- **Security**: every route is bound to the DSH `connection` session and same-origin checks with a one-time token; `/tiles` only serves directories opened through the file picker; the `/remote` proxy rejects loopback and private addresses to prevent SSRF. The plugin never uploads data or reaches out on its own.
+- **Self-hosted CesiumJS**: `vendor/cesium` ships with the plugin — no CDN, no Cesium ion token.
+
+## Known limitations
+
+- The `/remote` proxy does not forward query strings yet, so WMS / WMTS requires a service that allows direct cross-origin requests; proxy query and redirect validation are planned.
+- Public Esri services can be unreachable on some networks; the basemap then renders empty, and a local tile source can be used instead.
+
+## Layout
+
+```text
+dsh-digital-earth/
+├── index.js            # host plugin: routes, proxy, local assets, persistence
+├── client.js           # client panel: Cesium scene, toolbar, source settings
+├── cordis.patch.yml    # bundle patch
+├── locale/             # plugin market metadata (zh / en)
+├── vendor/cesium/      # self-hosted CesiumJS 1.147
+├── icon.svg
+└── preview.png
+```
+
+## Feedback
+
+Issues and suggestions are welcome in the [issue tracker](https://github.com/CVEO/dsh-digital-earth/issues). Please make sure `node --check index.js && node --check client.js` passes before opening a pull request.
+
+## Team
+
+Maintained by the **CVEO Research Group, Wuhan University** · <https://www.whu-cveo.com/>
+
+## License
+
+MIT. CesiumJS is distributed under Apache-2.0; see [`NOTICE`](NOTICE) for third-party attribution.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+
+# 数字地球 · Digital Earth
+
+**在 CesiumJS 地球上叠加 3D Tiles / 3DGS 图层的 DeepSeek Harness 面板**
+
+[中文](README.md) · [English](README.en.md)
+
+![版本](https://img.shields.io/badge/版本-1.0.0-4f8cff)
+![许可](https://img.shields.io/badge/许可-MIT-2ea44f)
+![平台](https://img.shields.io/badge/平台-Web-8b5cf6)
+![DSH](https://img.shields.io/badge/DSH-%3E%3D0.2.1--rc.1-0ea5e9)
+
+</div>
+
+![预览](preview.png)
+
+数字地球是一个 DSH 插件：把 CesiumJS 三维地球嵌入主工作区，用统一的面板浏览实景三维与高斯泼溅成果。自托管 CesiumJS 1.147，不依赖 Cesium ion Token，不请求外网静态资源。
+
+## 功能
+
+| 能力 | 说明 |
+| --- | --- |
+| 实景三维叠加 | 本地目录递归扫描 `tileset.json`；3D Tiles 1.0 / 1.1（b3dm、glb）与 3DGS（`KHR_gaussian_splatting`，含 SPZ 压缩）；多图层同时叠加、显隐 / 定位 / 移除 |
+| 在线与本地路径 | 直接粘贴 `http(s)` 地址或本机绝对路径；跨域失败自动回退到宿主代理 |
+| 影像底图 | 内置多个 Esri 底图预设，可自定义 XYZ（TMS、投影、子域名、最大层级）/ WMS / ArcGIS 服务；无底图模式也完整可用 |
+| 地形 | 内置 ArcGIS WorldElevation3D，可接入任意 Cesium / ArcGIS 地形服务 |
+| 本地瓦片 | 直接把本地 XYZ / TMS 瓦片目录添加为底图，离线可用 |
+| 数据源管理 | 设置面板内增删改、单选启用、恢复默认，配置持久化到 `$DSH_HOME/digital-earth/sources.json` |
+| 坐标 HUD | 光标经纬度 + 高程；裸地球、地形、模型三种情形均可用，约 8 Hz 采样，不触发重渲染 |
+| 量测与工具 | 测距、测面、测高、拾取 3D Tiles 属性、PNG 截图、复位视角 |
+| 图层统计 | 每层瓦片数、待加载数、三角面数、缓存占用；全局 FPS 与相机高度 / 朝向 |
+| 双语 | 跟随 DSH 语言，中文 / English 运行时即时切换 |
+| 主题 | 跟随 DSH 或系统；可显式选择浅色 / 深色，仅作用于本面板 |
+
+## 环境要求
+
+- DeepSeek Harness `>=0.2.1-rc.1 <0.3.0-0`
+- 支持 WebGL / WebGL2 的现代浏览器
+- 中国大陆网络可直接访问 ArcGIS 公共服务（`server.arcgisonline.com`、`elevation3d.arcgis.com`）
+
+## 安装
+
+在插件市场中搜索「数字地球」，或使用命令行：
+
+```bash
+# 从 npm 注册表安装
+dsh plugin --profile <profile> add @cveo/dsh-digital-earth
+
+# 从本地目录 / 打包文件安装
+dsh plugin --profile <profile> add "<path-to-plugin>"
+dsh plugin --profile <profile> add "./cveo-dsh-digital-earth-1.0.0.tgz"
+```
+
+安装或更新后请**完全退出并重新打开 DSH** 一次：客户端 bundle 在宿主启动时注册，仅刷新页面不会重新注册。随后左侧栏出现「数字地球 / Digital Earth」入口。
+
+## 使用
+
+| 入口 | 作用 |
+| --- | --- |
+| **数据 ▾** | 打开本地目录（递归扫描 `tileset.json`）、加载在线地址 / 本地路径、清除量测与拾取结果 |
+| **底图 ▾ / 地形 ▾** | 在已配置的数据源之间切换，或关闭底图 / 地形 |
+| **量测 ▾** | 测距、测面、测高、拾取属性；左键取点，双击结束 |
+| **图层 n** | 图层面板：点名称定位、◉ 显隐、✕ 移除 |
+| **外观** | 跟随系统 / 浅色 / 深色 |
+| **设置** | 数据源管理（影像 / 地形）与外观设置 |
+
+鼠标坐标按约 8 Hz 采样：射线与椭球求交保证裸地球也有经纬度；命中 3D Tiles / 3DGS 时用深度缓冲取模型表面高程；有地形时用 `globe.getHeight` 校正。HUD 文本直接写入 DOM，不触发 React 重渲染。
+
+## 数据源
+
+内置预设均为免 Token 的 ArcGIS 公共服务，可在设置中一键启用：
+
+| 类型 | 预设 |
+| --- | --- |
+| 影像 | Esri World Imagery、World Topographic、World Street Map、Light Gray Canvas、World Shaded Relief、World Ocean、World Hillshade |
+| 地形 | ArcGIS WorldElevation3D |
+
+自定义数据源支持：
+
+- **XYZ 瓦片**：`{z}/{x}/{y}` 模板、TMS（Y 轴南起）、Web 墨卡托 / 地理坐标、子域名、最大层级、版权署名
+- **WMS**：服务地址 + 图层名
+- **ArcGIS**：MapServer 地址（自动读取层级信息）
+- **Cesium 地形**：地形服务地址，可选请求法线 / 水面掩膜
+- **本地瓦片目录**：在 XYZ 表单中直接选择目录，插件通过宿主白名单提供瓦片
+
+选中的底图与地形随配置持久化，换端口或重开 DSH 都不会丢失。
+
+## 工作原理
+
+- **宿主侧**（`index.js`）：注册 `/api/3dviewer/*` 路由，负责 Cesium 静态资源、本地目录扫描与白名单、瓦片服务、跨域代理、数据源配置读写。
+- **客户端**（`client.js`）：作为 DSH 客户端模块加载，声明 `sidebar.panellist` 与 `main` 槽位，按需动态 `import()` 自托管 CesiumJS。
+- **安全**：所有路由绑定 DSH `connection` 会话与同源校验，并带一次性 token；`/tiles` 仅服务经文件选择器加入白名单的目录；`/remote` 代理拒绝 loopback / 私网地址，避免 SSRF。插件不上传数据、不主动外联。
+- **自托管 CesiumJS**：`vendor/cesium` 随插件分发，无 CDN、无 Cesium ion Token。
+
+## 已知限制
+
+- `/remote` 代理不透传查询串，WMS / WMTS 需要服务端允许直连 CORS 才能使用；后续会补齐代理的查询串与重定向校验。
+- 在线 Esri 服务在部分网络环境可能不可达，此时底图会显示为空白，可切换为本地瓦片数据源。
+
+## 目录结构
+
+```text
+dsh-digital-earth/
+├── index.js            # 宿主插件：路由、代理、本地资源、配置持久化
+├── client.js           # 客户端面板：Cesium 场景、工具栏、数据源设置
+├── cordis.patch.yml    # bundle 补丁
+├── locale/             # 插件市场元数据（中 / 英）
+├── vendor/cesium/      # 自托管 CesiumJS 1.147
+├── icon.svg
+└── preview.png
+```
+
+## 反馈与贡献
+
+欢迎通过 [Issue](https://github.com/CVEO/dsh-digital-earth/issues) 报告问题或提出建议。提交前请确保 `node --check index.js && node --check client.js` 通过。
+
+## 团队
+
+由 **武汉大学 CVEO 课题组** 维护 · <https://www.whu-cveo.com/>
+
+## 许可
+
+MIT。CesiumJS 以 Apache-2.0 分发，第三方声明见 [`NOTICE`](NOTICE)。