roxy-cobewebgl 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# roxy-cobewebgl
+
+Cobe 风格的高性能点阵地球：纯 WebGL + GLSL，可选 **OffscreenCanvas Worker** 渲染（主线程只做交互），不支持时自动 **主线程 WebGL 回退**。以 **ESM** 发布，可在 Vite / Webpack 5+ 等打包器中使用。
+
+## 安装
+
+```bash
+npm install roxy-cobewebgl
+# 或
+pnpm add roxy-cobewebgl
+```
+
+## 快速开始
+
+```html
+<canvas id="globe" width="600" height="600" style="width:100%;max-width:800px;height:400px;"></canvas>
+<script type="module">
+  import { createGlobe } from 'roxy-cobewebgl';
+
+  const canvas = document.getElementById('globe');
+  const instance = await createGlobe(canvas, {
+    // 不传 map / mapUrl 时默认加载包内精简地图 globe.min.json
+    arcs: [],
+  });
+  if (!instance) {
+    console.error('无法创建地球（WebGL 或地图加载失败）');
+  }
+</script>
+```
+
+本地调试示例：
+
+```bash
+pnpm install
+pnpm dev
+```
+
+浏览器将打开 [examples/playground/index.html](examples/playground/index.html)：本地直连 `src/` 源码，带参数面板与示例弧线（**不**打进 npm 包）。
+
+## 地图数据
+
+| 文件 | 说明 |
+|------|------|
+| `globe.json` | 完整国界 GeoJSON，体积大，精度高 |
+| `globe.min.json` | 由脚本精简（仅几何、降精度、无 properties），默认使用 |
+
+从 npm 引用资源 URL（在支持 `import.meta.resolve` 或打包器解析的环境下）：
+
+```js
+import { getDefaultMapMinUrl, getDefaultMapFullUrl } from 'roxy-cobewebgl';
+
+const url = getDefaultMapMinUrl();
+// 或完整版
+const full = getDefaultMapFullUrl();
+```
+
+也可把 JSON 放到自己的 CDN，通过 `mapUrl` 传入。
+
+重新生成 `globe.min.json`（需先有根目录 `globe.json`）：
+
+```bash
+pnpm run build:globe
+```
+
+对应脚本为 [scripts/slim-globe.mjs](scripts/slim-globe.mjs)。
+
+## API
+
+### `createGlobe(canvas, options?)`
+
+- **canvas** `HTMLCanvasElement`：目标画布。Worker 模式下会 `transferControlToOffscreen()`，主线程不要再对该 canvas 调用 `getContext`。
+- **返回** `Promise<GlobeInstance | null>`：主线程回退路径需异步加载地图；失败或拿不到 WebGL 时为 `null`。
+
+#### `options` 一览
+
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `map` | `object` | — | GeoJSON `FeatureCollection`，结构化克隆进 Worker |
+| `mapUrl` | `string \| URL` | 包内 `globe.min.json` | 可 `fetch` 的地址；与 `map` 同时传时以 `map` 为准 |
+| `preferWorker` | `boolean` | `true` | `false` 时强制主线程渲染（便于对照调试） |
+| `arcs` | `GlobeArc[]` | `[]` | 大圆飞行弧线动画；空数组不创建弧线程序 |
+| `onError` | `(err: Error) => void` | `console.error` | Worker / 网络 / WebGL 错误 |
+| `debugShowTexture` | `boolean` | `false` | **仅回退模式**：在页面固定角显示陆域纹理缩略图 |
+
+外观与着色器 uniform（均可后续 `setState`）：
+
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `phi` | `number` | `0.3` | 绕 Y 旋转（弧度），Worker 内会随 `autoRotate` 递增 |
+| `theta` | `number` | `0.15` | 绕 X 倾斜 |
+| `dots` | `number` | `800` | 斐波那契点数量 |
+| `dotSize` | `number` | `0.008` | 点大小阈值 |
+| `globeRadius` | `number` | `0.55` | 屏幕空间中球半径比例 |
+| `glowOn` | `number` | `1` | 边缘发光开关，`0`/`1` |
+| `opacity` | `number` | `0.9` | 球体表面不透明度 |
+| `baseColor` | `[r,g,b]` | 暗蓝 | 海洋 / 底色，0–1 |
+| `glowColor` | `[r,g,b]` | 蓝 | 发光颜色 |
+| `dotColor` | `[r,g,b]` | 亮青 | 陆地点颜色 |
+| `arcColor` | `[r,g,b]` | 橙 | 弧线未指定 `color` 时的兜底 |
+| `debug` | `number` | `0` | `0` 正常；`1` 全点；`2` UV；`3` 纹理诊断 |
+| `autoRotate` | `boolean` | `true` | 是否每帧增加 `phi` |
+| `rotationSpeed` | `number` | `0.003` | 每帧 `phi` 增量 |
+
+**弧线** `GlobeArc`：`startLat`, `startLng`, `endLat`, `endLng`（度），可选 `color`（如 `#ff6633`），可选 `order`（绘制顺序，越小越早启动）。
+
+### `GlobeInstance`
+
+- **`setState(partial)`**：合并更新参数。  
+  - **Worker 模式**：仅把你通过 `setState` 写过的键周期性发给 Worker；`phi` 默认由 Worker 推进，除非你也对其 `setState`，否则不会被主线程覆盖。  
+  - **回退模式**：内部为完整状态对象，行为与普通 React-less 状态合并一致。
+- **`resize()`**：按当前 CSS 尺寸与 `devicePixelRatio` 更新绘图缓冲；库已监听 `window.resize`，一般不必调用。
+- **`destroy()`**：取消动画帧、移除监听、`Worker.terminate()`（若使用 Worker）。
+
+### 辅助函数
+
+- **`getDefaultMapMinUrl()`**：包内 `globe.min.json` 的绝对 URL（便于传给 `mapUrl` 或下载器）。
+- **`getDefaultMapFullUrl()`**：包内 `globe.json`。
+
+## 子路径导出（package exports）
+
+- `roxy-cobewebgl` — 主入口
+- `roxy-cobewebgl/globe.worker.js` — Worker 源码（多数场景无需直接 import）
+- `roxy-cobewebgl/globe.min.json` / `roxy-cobewebgl/globe.json` — 地图文件
+
+创建 Worker 时使用 `new URL('./globe.worker.js', import.meta.url)`（库内部已处理）；自有打包配置需保留对 Worker 文件的解析。
+
+## 打包与 SSR
+
+- 须在**客户端**调用 `createGlobe`（依赖 `document`、`Worker`、WebGL）。
+- Vite / Webpack 5+ 对 `new Worker(new URL(...), { type: 'module' })` 有较好支持；若遇路径问题，检查是否把 `node_modules/roxy-cobewebgl/src/globe.worker.js` 打进资源。
+
+## 协议
+
+ISC