qqsl-ngx-cesium 0.0.1

package/README.md

@@ -0,0 +1,163 @@
+# qqsl-ngx-cesium 使用文档
+
+`qqsl-ngx-cesium` 是一套基于 Angular + Cesium 的地图/河流渲染组件库，当前主组件为 `NgxCesiumMapComponent`。
+
+## 1. 依赖说明
+
+- Angular 15.x
+- `cesium@1.118.2`
+- `@angular/common`、`@angular/core`
+
+库内部默认会读取 Cesium 资源目录：
+
+```ts
+export const CESIUM_ASSET_BASE_URL = '/assets/cesium';
+```
+
+所以宿主项目需要提前准备 Cesium 静态资源。
+
+## 2. 最小接入
+
+### 2.1 引入模块
+
+```ts
+import { NgxCesiumMapModule } from 'qqsl-ngx-cesium/map';
+```
+
+如果你的项目是 standalone 组件：
+
+```ts
+imports: [NgxCesiumMapModule]
+```
+
+### 2.2 模板使用
+
+```html
+<ngx-cesium-map
+  style="width: 100%; height: 100%;"
+  [center]="center"
+  [riverPath]="riverPath"
+  [meshList]="meshList"
+  [flowSpeedPoints]="flowSpeedPoints"
+  [riverDepthPoints]="riverDepthPoints"
+  [tilesetUrl]="tilesetUrl"
+></ngx-cesium-map>
+```
+
+### 2.3 常用输入
+
+- `center`：初始相机中心点
+- `riverPath`：河道轮廓点
+- `riverWidth`：河宽
+- `meshList`：模型列表
+- `flowSpeedPoints`：分段流速边界点
+- `riverDepthPoints`：水深散点数组，每项为 `{ lng: number | string, lat: number | string, depth: number | string }`
+- `tilesetUrl`：倾斜摄影地址
+- `showRiverDepthGradient`：水深渐变层开关
+- `showFlowSpeedPoints`：流速调试点开关
+- `riverDepthStyle`：水深图层样式。默认 `depthRangeMode: 'auto'`，按当前有效水深动态拉伸色带；如需固定 `0-15m`，传 `{ depthRangeMode: 'fixed', fixedDepthRange: { min: 0, max: 15 } }`
+
+## 3. 开发联调方案
+
+如果目标是“组件库代码改动后，外部项目立刻看到变化，而且不需要先打包”，推荐直接走源码联调，不走 `ng build` / `yalc`。
+
+### 方案 A：同一工作区联调
+
+这个仓库里已经配置好了路径别名：
+
+- `qqsl-ngx-cesium` -> `./dist/qqsl-ngx-cesium`
+- `qqsl-ngx-cesium/*` -> `./projects/qqsl-ngx-cesium/*`
+
+所以在同仓库里的 demo 或其他应用中，可以直接从源码路径导入：
+
+```ts
+import { NgxCesiumMapModule } from 'qqsl-ngx-cesium/map';
+```
+
+联调时只需要运行宿主应用的开发服务，例如：
+
+```bash
+npm run start
+```
+
+这样你修改 `projects/qqsl-ngx-cesium/**` 下的代码后，宿主应用会在重新编译时直接吃到最新源码，不需要先构建库包。
+
+### 方案 B：其他项目联调，但不打包
+
+如果是另一个独立项目，推荐把这个库源码以本地目录或符号链接的方式接进来，再在消费项目的 `tsconfig` 里把包名指向源码目录。
+
+示例思路：
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "qqsl-ngx-cesium": ["<本地源码路径>/projects/qqsl-ngx-cesium"],
+      "qqsl-ngx-cesium/*": ["<本地源码路径>/projects/qqsl-ngx-cesium/*"]
+    }
+  }
+}
+```
+
+然后在消费项目里直接引入：
+
+```ts
+import { NgxCesiumMapModule } from 'qqsl-ngx-cesium/map';
+```
+
+这类方式的核心是“源码直连”，不是 npm 包安装，所以组件库文件一改，消费项目重新编译后就能看到更新。
+
+### 联调建议
+
+- 宿主项目保持 `ng serve` 常驻
+- 组件库不要先 `ng build qqsl-ngx-cesium`
+- 需要稳定观察变化时，优先改源码路径联调，而不是推 `dist`
+
+## 4. 生产使用方案
+
+生产环境建议走标准库发布流程：
+
+1. 构建库：
+
+```bash
+npm run build:qqsl-ngx-cesium
+```
+
+2. 发布到 npm：
+
+```bash
+npm run publish:qqsl-ngx-cesium
+```
+
+3. 在业务项目中安装并使用：
+
+```ts
+import { NgxCesiumMapModule } from 'qqsl-ngx-cesium';
+```
+
+如果你的消费项目需要保持和当前仓库一致的源码引用习惯，也可以继续用 `qqsl-ngx-cesium/map`，但前提是你的构建/发布方式已经把该路径纳入可解析范围；生产环境更推荐以包根入口为准。
+
+## 5. 运行时注意点
+
+- 需要提前准备 Cesium 静态资源，并保证 `CESIUM_ASSET_BASE_URL` 可访问
+- 如果使用倾斜摄影，`tilesetUrl` 要保证跨域和鉴权可用
+- `flowSpeedPoints` 的语义是“从当前边界开始，到下一个边界之前”这一段使用当前点的速度
+- `showFlowSpeedPoints`、`showRiverSamplePoints`、`showRiverDepthGradient` 这些开关适合联调阶段打开
+- `riverDepthPoints` 现在按散点渲染水深，组件会用 KNN + IDW 对水面网格做平滑插值；落在河道外的散点会被忽略。可以参考 `projects/qqsl-ngx-cesium/map/test-depth-data.ts`
+
+水深散点示例：
+
+```ts
+const riverDepthPoints = [
+  { lng: 120, lat: '12', depth: 20 },
+  { lng: 120.001, lat: 12.001, depth: 12.5 },
+];
+```
+
+## 6. 示例入口
+
+仓库里的示例页面可以参考：
+
+- `projects/demo/src/app/pages/cesium/cesium-test.component.ts`
+
+它演示了 `NgxCesiumMapModule` 的基本接入方式，也包含了水深、流速、倾斜摄影等常用输入。

package/esm2020/map/cesium-defaults.mjs

@@ -0,0 +1,23 @@
+export const CESIUM_ASSET_BASE_URL = '/assets/cesium';
+export const CESIUM_ION_ACCESS_TOKEN = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJjMTk2YzRhNy05MmRmLTRkMWYtOTc3Mi1iMjI1ZWM1Y2MyZDkiLCJpZCI6NDExNTU4LCJpYXQiOjE3NzQ5MjMwNzB9.Qe_Do-L3pr0etJ4l_rhXoTQGFNgIqASs3ngsKgtRdoQ';
+export const cesiumDefaultCenter = {
+    lng: 120.237,
+    lat: 30.247,
+    height: 3500,
+};
+export const defaultRiverWidth = 900;
+export const defaultRiverSpeed = 0.35;
+export const defaultRiverSegmentSpeed = 1.2;
+export const defaultRiverFoamStrength = 1.15;
+export const defaultRiverWaterColor = '#1b6f9b';
+export const defaultRiverChannelTextureUrl = 'https://i.mji.rip/2026/04/01/ac37e20edaef28e633d67708daa5ee80.jpeg';
+export const defaultRiverEntityHeight = 0;
+// 河床层高度 = baseHeight + defaultRiverBedOffset。
+// 负值表示河床在基准面之下，正值表示之上。
+// 必须小于 waterOffset，否则几何体零厚度导致 z-fighting，水面波浪效果消失。
+export const defaultRiverBedOffset = 0;
+// 河面层高度 = baseHeight + defaultRiverSurfaceOffset。
+// 正值表示水面在基准面之上。河流实体厚度 = waterOffset - bedOffset。
+export const defaultRiverSurfaceOffset = 3;
+export const defaultRiverBankFadeWidth = 4;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2VzaXVtLWRlZmF1bHRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vLi4vcHJvamVjdHMvcXFzbC1uZ3gtY2VzaXVtL21hcC9jZXNpdW0tZGVmYXVsdHMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBWUEsTUFBTSxDQUFDLE1BQU0scUJBQXFCLEdBQUcsZ0JBQWdCLENBQUM7QUFDdEQsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQUcsdUxBQXVMLENBQUM7QUFDL04sTUFBTSxDQUFDLE1BQU0sbUJBQW1CLEdBQW9CO0lBQ2xELEdBQUcsRUFBRSxPQUFPO0lBQ1osR0FBRyxFQUFFLE1BQU07SUFDWCxNQUFNLEVBQUUsSUFBSTtDQUNiLENBQUM7QUFFRixNQUFNLENBQUMsTUFBTSxpQkFBaUIsR0FBRyxHQUFHLENBQUM7QUFDckMsTUFBTSxDQUFDLE1BQU0saUJBQWlCLEdBQUcsSUFBSSxDQUFDO0FBQ3RDLE1BQU0sQ0FBQyxNQUFNLHdCQUF3QixHQUFHLEdBQUcsQ0FBQztBQUM1QyxNQUFNLENBQUMsTUFBTSx3QkFBd0IsR0FBRyxJQUFJLENBQUM7QUFDN0MsTUFBTSxDQUFDLE1BQU0sc0JBQXNCLEdBQUcsU0FBUyxDQUFDO0FBQ2hELE1BQU0sQ0FBQyxNQUFNLDZCQUE2QixHQUFHLG9FQUFvRSxDQUFDO0FBQ2xILE1BQU0sQ0FBQyxNQUFNLHdCQUF3QixHQUFHLENBQUMsQ0FBQztBQUMxQyw4Q0FBOEM7QUFDOUMsdUJBQXVCO0FBQ3ZCLG1EQUFtRDtBQUNuRCxNQUFNLENBQUMsTUFBTSxxQkFBcUIsR0FBRyxDQUFDLENBQUM7QUFDdkMsa0RBQWtEO0FBQ2xELGlEQUFpRDtBQUNqRCxNQUFNLENBQUMsTUFBTSx5QkFBeUIsR0FBRyxDQUFDLENBQUM7QUFDM0MsTUFBTSxDQUFDLE1BQU0seUJBQXlCLEdBQUcsQ0FBQyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IGludGVyZmFjZSBDZXNpdW1NYXBDZW50ZXIge1xuICBsbmc6IG51bWJlcjtcbiAgbGF0OiBudW1iZXI7XG4gIGhlaWdodD86IG51bWJlcjtcbn1cblxuZXhwb3J0IGludGVyZmFjZSBDZXNpdW1NYXBQb2ludCB7XG4gIGxuZzogbnVtYmVyO1xuICBsYXQ6IG51bWJlcjtcbiAgaGVpZ2h0PzogbnVtYmVyO1xufVxuXG5leHBvcnQgY29uc3QgQ0VTSVVNX0FTU0VUX0JBU0VfVVJMID0gJy9hc3NldHMvY2VzaXVtJztcbmV4cG9ydCBjb25zdCBDRVNJVU1fSU9OX0FDQ0VTU19UT0tFTiA9ICdleUpoYkdjaU9pSklVekkxTmlJc0luUjVjQ0k2SWtwWFZDSjkuZXlKcWRHa2lPaUpqTVRrMll6UmhOeTA1TW1SbUxUUmtNV1l0T1RjM01pMWlNakkxWldNMVkyTXlaRGtpTENKcFpDSTZOREV4TlRVNExDSnBZWFFpT2pFM056UTVNak13TnpCOS5RZV9Eby1MM3ByMGV0SjRsX3JoWG9UUUdGTmdJcUFTczNuZ3NLZ3RSZG9RJztcbmV4cG9ydCBjb25zdCBjZXNpdW1EZWZhdWx0Q2VudGVyOiBDZXNpdW1NYXBDZW50ZXIgPSB7XG4gIGxuZzogMTIwLjIzNyxcbiAgbGF0OiAzMC4yNDcsXG4gIGhlaWdodDogMzUwMCxcbn07XG5cbmV4cG9ydCBjb25zdCBkZWZhdWx0Uml2ZXJXaWR0aCA9IDkwMDtcbmV4cG9ydCBjb25zdCBkZWZhdWx0Uml2ZXJTcGVlZCA9IDAuMzU7XG5leHBvcnQgY29uc3QgZGVmYXVsdFJpdmVyU2VnbWVudFNwZWVkID0gMS4yO1xuZXhwb3J0IGNvbnN0IGRlZmF1bHRSaXZlckZvYW1TdHJlbmd0aCA9IDEuMTU7XG5leHBvcnQgY29uc3QgZGVmYXVsdFJpdmVyV2F0ZXJDb2xvciA9ICcjMWI2ZjliJztcbmV4cG9ydCBjb25zdCBkZWZhdWx0Uml2ZXJDaGFubmVsVGV4dHVyZVVybCA9ICdodHRwczovL2kubWppLnJpcC8yMDI2LzA0LzAxL2FjMzdlMjBlZGFlZjI4ZTYzM2Q2NzcwOGRhYTVlZTgwLmpwZWcnO1xuZXhwb3J0IGNvbnN0IGRlZmF1bHRSaXZlckVudGl0eUhlaWdodCA9IDA7XG4vLyDmsrPluorlsYLpq5jluqYgPSBiYXNlSGVpZ2h0ICsgZGVmYXVsdFJpdmVyQmVkT2Zmc2V044CCXG4vLyDotJ/lgLzooajnpLrmsrPluorlnKjln7rlh4bpnaLkuYvkuIvvvIzmraPlgLzooajnpLrkuYvkuIrjgIJcbi8vIOW/hemhu+Wwj+S6jiB3YXRlck9mZnNldO+8jOWQpuWImeWHoOS9leS9k+mbtuWOmuW6puWvvOiHtCB6LWZpZ2h0aW5n77yM5rC06Z2i5rOi5rWq5pWI5p6c5raI5aSx44CCXG5leHBvcnQgY29uc3QgZGVmYXVsdFJpdmVyQmVkT2Zmc2V0ID0gMDtcbi8vIOays+mdouWxgumrmOW6piA9IGJhc2VIZWlnaHQgKyBkZWZhdWx0Uml2ZXJTdXJmYWNlT2Zmc2V044CCXG4vLyDmraPlgLzooajnpLrmsLTpnaLlnKjln7rlh4bpnaLkuYvkuIrjgILmsrPmtYHlrp7kvZPljprluqYgPSB3YXRlck9mZnNldCAtIGJlZE9mZnNldOOAglxuZXhwb3J0IGNvbnN0IGRlZmF1bHRSaXZlclN1cmZhY2VPZmZzZXQgPSAzO1xuZXhwb3J0IGNvbnN0IGRlZmF1bHRSaXZlckJhbmtGYWRlV2lkdGggPSA0O1xuIl19