gis-view-webgl2 0.1.5 → 0.1.7

package/README.md

@@ -2,14 +2,14 @@
 
 不依赖任何图形库的 WebGL2 矢量视图：点、线、背景层（图片 / GeoJSON）与首屏落位（`initialView`）都通过 `createGisView(dom, options)` 创建，宽高默认跟随传入的 DOM 容器；跨项目复用的视图级逻辑用 `plugins` 挂载。
 
-本轮围绕鹰眼图尺寸与拖拽澄清：沿用主图规则时，节点 / 线路按「小图视口 ÷ 主图视口」的较小比例缩放，主图放大不再改变它们的大小；只有小图自身放大时才按 `pointZoomScale` / `lineZoomScale` 联动；`pointSizeScale` / `lineWidthScale` 是独立于两边缩放的整体倍数，自有规则与沿用主图的要素都乘这一份。另有 `dragAction: 'box'` 不依赖手动缩放、`zoomable: 'follow'` 与 `followZoomScale` 整体范围跟随主图，以及 `extentFollowCamera` 默认关闭避免包围盒跳动；新增通道草稿的示例点可显隐 / 分端配色 / 换形状，示例线路层级可配，端点严格落在节点中心；`commitAddChannel` 可直接接收本次新增的线路 / 通道对象。
+本轮按 `问题.txt` 继续深挖整体性能，并补上后续做增量与自建视图时常用的三个公开能力：线路样式新增「只改线宽 / 颜色 / 透明度」的窄路（1000 点 + 50000 线连续 5 次交替，换色稳态 **10.1 ~ 11.7 ms → 6.1 ~ 7.4 ms**、换宽 **9.2 ~ 10.4 ms → 5.8 ~ 6.4 ms**，均约 40%；存在线路规则、热力图、虚线或效果时自动回退整份解析），解析与窄路共用 `resolveLinePaintInto`，逐线自身样式仍优先；实例新增 `flyToCamera({ center?, scale? }, { duration, easing })`（直接飞相机、不经过要素解析，缺省字段沿用当前相机）、只读 `dataVersion`（数据变更递增，样式变更不递增，并与 `onDataChange` 载荷同步）与 `getLineStyle(index)`（线路解析后的线宽 / RGBA / 透明度 / 层级快照）。`?demo=search-filter` 增加固定相机飞行、线路换色 / 加宽、改点与版本读数，可直接试这三个能力；相关手册、API 速查、逐方法示例、性能页与自测同步扩充。另新增 `selectAt(clientX, clientY)`：按客户端坐标模拟普通单击选中，通道回线仍按 `channelSelectMode` 摊开。公开实例成员增至 **265**（**260** 个方法 + **5** 个属性），options / 数据字段 / 事件 / 功能开关保持 **96 / 250 / 43 / 17**。
 
 - 渲染层：原生 WebGL2（GLSL ES 3.00 + 实例化绘制），没有任何运行时依赖，也不需要 Vue。
 - 交互层：拖拽平移、滚轮缩放、按关键字搜索并定位（节点 / 线路 / 通道）、点击 / 双击拾取、点拖拽（相连线路同步移动）、Shift 拖动框选与 Ctrl 点击累加多选（多选后整组同步移动；`selectionKinds` 可限定只选节点 / 线路 / 通道或任意组合）、复制只带选中要素、节点合并可指定保留端并改写最终信息与样式、线路拐点编辑与通道多回线，全部走配置与回调 —— **这些能力缺省全关**，要哪一项显式打开（`features` 预设 / 开关表，或 `interactive: true` / `clickable: true` / `draggable: true` 这类详细配置，见 `docs/GisView.md` 的「功能开关」）。
 - 数据层：按属性筛选（点被过滤时绑在它身上的线路与通道一起消失，大数据量走 Web Worker）、按属性批量配色 / 换符号、节点标签（内容、贴边方式、HTML 定制、数量与显隐可配，十万级数据下有候选上限兜底）与点 / 线 / 通道的悬浮提示，筛选、规则与标签共用同一套条件语言；节点标签与线路标签分开配置、都支持 `auto`（智能隐藏）/ `always` / `hidden` 三种显隐策略，线路标签的位置沿线走（比例 / 百分比 / 绝对距离）、候选还会按屏幕小格摊开（通道里的并行回线不会把扫描名额占光），线路上还能按同样的位置写法挂图片或 SVG 装饰（`decorations`，通道回线可以用 `linePropsByMember` 逐条配；装饰缺省 `auto` —— 线路上没有拐点时按比例跟随（挂在中点就一直保持中点），有了拐点就跟拐点一样钉在线路上（位置不再沿路径挪动，线路几何一变就把锚点投回线身最近的点），写 `anchor: 'follow'` 强制一直跟随、`anchor: 'fixed'` + `at: [x, y]` 则固定在写死的坐标上；装饰与线路标签都能写 `parallel: true` 跟着线路方向转，通道里的每条回线也能各显示各的标签）。节点也能用 `points[].decorations` 挂图片 / SVG：`offset` 或 `distance` + `direction` 是相对节点的屏幕像素偏移（缩放时保持像素距离），`anchor: 'fixed'` / `at` 是固定世界坐标，`connector` 可从节点中心画连接线。平移 / 缩放 / 拖拽期间两类标签都能各自配 `hideOnInteract`（`true` 或者「标签数超过 N 才收」），收起时只切一个 class、不写标签 DOM，停手自动补齐；线路标签另有 `followOnInteract`（默认开）—— 没收起时拖节点 / 拖拐点期间跟着线路走，关掉则停手后统一归位；通道回线的提示范围用 `tooltip.channelScope` 在整条通道 / 所属分组 / 单条回线之间切。
 - 大数据与导出：`denseMode` 缺省 `'auto'`，按可见节点数（4000）、屏幕密度（每百万 CSS 像素 3000）或数据总量（5 万）自动进入密集档，标签切到避让 / 截断、线路动点与节点涟漪暂停，退出留 22% 回滞并恢复用户原来的 `effects`，当前状态看 `getStats().dense`；导出统一收口到 `exportData({ scope, parts, format })`，`scope` 选全量 / 视口 / 选中，`parts` 选场站 / 线路 / 通道 / 拐点。需要自己画 WebGL 标记或特效时，用 `webglLayers` / `addWebGLLayer()` 或直接取 `view.gl`。
 - 动态装饰器：`beginDecorationDraft` 用 `target` 选择只挂线路、只挂节点或两类同时开启（`both` 时按屏幕距离取更近者、等距优先节点，最近目标不可用时回退另一类）；线路侧保留单线 / 分组 / 整条通道三种范围与平行方向，节点侧可切相对偏移 / 固定坐标 / 鼠标位置并画连接线。触发半径默认收紧到 14px，离开目标立即收掉；`maxPerLine` / `maxPerPoint` 分别限制每线 / 每点数量，`allowedLines` / `allowedChannels` / `allowedGroups` / `allowedPoints` 限定白名单，超限或不在白名单的目标静默不触发，提交前还会按最新数据复核；`allowDuplicate: false` 时按 `duplicateDistance` 检测同一位置，`duplicateStrategy` 可选自动避让或直接拒绝。空白处松手不发事件，只有命中的左键松开才发 `ready`；确认走 `commitDecorationDraft` 一次批量写入（线路与节点同一批、一条历史），取消走 `cancelDecorationDraft`，数据与历史在确认前不动。演示页可从左侧图标拖到线路，也可分别开启节点 / 线路装饰并现场调吸附方式、白名单与重复策略。
-- 界面尽量不内置：控制面板、读数、图例都不生成，组件只提供画布与实例方法，样式完全由使用方决定（标签与提示框是覆盖层，默认外观可以整体改写）；唯一可选的界面是内置鹰眼图——配 `minimap` 才挂一层小地图（位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`offset` 可动态移动整张图、`container` 可挂到外部 `div`。`extentFollowCamera` 默认关闭，外围要素消失时不会自行收窄包围盒；`zoomable` 三态互斥：`false` 关闭、`true` 手动缩放小图自身、`'follow'` 让整体范围跟随主图（`followZoomScale` 调指数，`setMinimapZoom` / `zoomMinimapBy` 在跟随档不抢控制权）。空白处拖动可以平移小图、或直接框选让主图显示过去（`dragAction`；`box` 不依赖缩放，手动模式下 Ctrl / ⌘ 才切换动作），每格倍率 `zoomStep` 单独配，`channelCircuits: false` 时按当前可见成员逐顶点平均成一根居中代表线；小图同样吃规则——`pointRules` / `lineRules` 决定每个节点 / 每条线的颜色、大小与层级，`levels` 只看某几层、`layered` 控制分层叠画、`pointZoomScale` / `lineZoomScale` 让节点与线路跟着小图倍数放大，不配自己的规则时自动沿用主图规则的颜色 / 层级 / 最终节点尺寸与图标 / 样式链线宽，沿用尺寸时按「小图视口 ÷ 主图视口」的较小比例缩放，主图放大缩小不改变它们的大小；`pointSizeScale` / `lineWidthScale` 对所有要素生效，`pointMapZoomScale` / `lineMapZoomScale` 只作用于小图自有规则 / 样式；自定义内容可以用 `layers` 按 `placement` 分到数据前 / 数据后、段内按 `order` 叠放，旧的单层 `draw` 仍兼容，手势完成时可通过 `onInteraction` 获取类型 / 世界坐标 / 相机，`maxPixelRatio` 可限制高分屏 / 宿主放大时的备份倍率），不配不产生任何 DOM。
+- 界面尽量不内置：控制面板、读数、图例都不生成，组件只提供画布与实例方法，样式完全由使用方决定（标签与提示框是覆盖层，默认外观可以整体改写）；唯一可选的界面是内置鹰眼图——配 `minimap` 才挂一层小地图（位置、尺寸、节点 / 线路 / 视口框三份样式与交互都可配，`offset` 可动态移动整张图、`container` 可挂到外部 `div`。`extentFollowContent` 默认关闭，首次铺好后外围要素消失不会收窄包围盒；`extentFollowCamera` 再控制相机在数据 / 底图间的取舍；`getMinimapElement()` 配合 `offset` 可做整图拖动（`?demo=minimap` 有可拖手柄）；`zoomable` 三态互斥：`false` 关闭、`true` 手动缩放小图自身、`'follow'` 让整体范围跟随主图（`followZoomScale` 调指数，`setMinimapZoom` / `zoomMinimapBy` 在跟随档不抢控制权）。空白处拖动可以平移小图、或直接框选让主图显示过去（`dragAction`；`box` 不依赖缩放，手动模式下 Ctrl / ⌘ 才切换动作），每格倍率 `zoomStep` 单独配，`channelCircuits: false` 时按当前可见成员逐顶点平均成一根居中代表线；小图同样吃规则——`pointRules` / `lineRules` 决定每个节点 / 每条线的颜色、大小与层级，`levels` 只看某几层、`layered` 控制分层叠画、`pointZoomScale` / `lineZoomScale` 让节点与线路跟着小图倍数放大，不配自己的规则时自动沿用主图规则的颜色 / 层级 / 最终节点尺寸与图标 / 样式链线宽，沿用尺寸时按「小图视口 ÷ 主图视口」的较小比例缩放，主图放大缩小不改变它们的大小；`pointSizeScale` / `lineWidthScale` 对所有要素生效，`pointMapZoomScale` / `lineMapZoomScale` 只作用于小图自有规则 / 样式；自定义内容可以用 `layers` 按 `placement` 分到数据前 / 数据后、段内按 `order` 叠放，旧的单层 `draw` 仍兼容，手势完成时可通过 `onInteraction` 获取类型 / 世界坐标 / 相机，`maxPixelRatio` 可限制高分屏 / 宿主放大时的备份倍率），不配不产生任何 DOM。
 - 数据切换与加载信号：`updateData(points, lines, channels)` 一次换完整个场景（也收 `{ points, lines, channels }`；接口列名不一样时先在调用方映射成这三列，见 [06 数据与场景更新](docs/manual/06-数据与场景更新.md#接口列名不一样映射放在调用方)），场站 / 回线按批补用 `addPoints` / `addChannels`（批量通道只重排一次、只记一步历史），`onDataRendered` / `whenRendered` / `whenDataRendered` 给出「这一份数据已经画到屏幕上」的信号 —— loading 遮罩在这之后收，不会闪一帧旧画面。
 - 整包只有一个组件：`gis-view`，只从根入口导出；扩展点集中在插件、自定义图元 / 条件运算符、自定义导出格式（`defineExportFormat` / `registerExportFormat`）、WebGL 自定义层与实例命令（`registerCommand`），不需要改组件源码。
 
@@ -31,7 +31,7 @@ npm run dev
 
 源码本身就是 JS：`src/gis-view/*.js` 逐文件带中文注释，对外类型集中在 `src/gis-view/types.d.ts`（构建时复制成 `dist/index.d.ts`），不用先编译就能直接读。想照着从零写一遍看 [从 0 到完整的实现](docs/从0到完整的实现.md)，里面有一份可以照抄的 mini 实现与验收清单。
 
-想知道组件到底有哪些属性和方法：[GisView 文档](docs/GisView.md) 的「实例方法」一节把 257 个实例成员（方法 + `el` / `canvas` / `gl` 这类属性）与 96 个 `options` 键逐个列全；demo 的「视图 · 交互」页签里有同一份清单（`?demo=full`，可搜索、点一条就对当前视图求值）；`node docs/steps/check-doc-coverage.mjs` 负责 10 项双向对账，改完源码或文档先跑 `node docs/steps/gen-api-index.mjs` 重生成 demo 读的那一份（三类查询的口径见 [docs/steps/README.md](docs/steps/README.md) 的「怎么查全部属性与方法」）。
+想知道组件到底有哪些属性和方法：[GisView 文档](docs/GisView.md) 的「实例方法」一节把 261 个实例成员（方法 + `el` / `canvas` / `gl` / `cameraAnimating` 这类属性）与 96 个 `options` 键逐个列全；demo 的「视图 · 交互」页签里有同一份清单（`?demo=full`，可搜索、点一条就对当前视图求值）；`node docs/steps/check-doc-coverage.mjs` 负责 10 项双向对账，改完源码或文档先跑 `node docs/steps/gen-api-index.mjs` 重生成 demo 读的那一份（三类查询的口径见 [docs/steps/README.md](docs/steps/README.md) 的「怎么查全部属性与方法」）。
 
 ## 构建 npm 包
 
@@ -394,3 +394,6 @@ view.zoomTo(12).zoomToBounds({ minX: 116, minY: 39, maxX: 117, maxY: 40 }, 60)
 - 这一轮（「修改.txt」：channelDemo 分组弹框参考图片改为整组编辑）：`docs/demos/ChannelDemo.vue` 新增居中的「线路分组」弹框，按分组卡片列出回线与「分组 N / N 条线路」，入口在通道分组面板和右键交互框；每行可连续选择目标组并「确认移入」，行内操作只改本地草稿，取消 / Esc / 点遮罩都不写组件数据；底部「确定分组」才调用一次 `splitChannelGroups(channelId, groups)`，整份 groups 一次落地，避免逐条请求与多步历史。右键框原有的逐条分配 / `moveChannelLine` 保留。`selftest-demos.html` 补 4 条断言（弹框分组与副标题、行内移入只改草稿、取消不写数据、确定只调用一次整组方法），292 → **296** 条；四页共 **1190** 条 0 失败，`npx tsc --noEmit`、`npm run check:docs`、`node docs/steps/gen-api-index.mjs --check`、`npm run build` 与 `git diff --check` 全通过；实例成员 / 方法 / 数据字段 / options 保持 **249 / 246 / 242 / 91**。
 
 - 这一轮（「修改.txt」两条：Ctrl 加点高亮范围 / 分组拐点拖动类型）：① `channelSelectMode` 现在同时管普通点选和 Ctrl / ⌘ + 点击线路加点后的选中集，`line` 只高亮被加点回线、`group` 连所在分组、`channel` 连整条通道；切换仍只重画、不重排。② 新增 `channelWaypointDragMode`（缺省 `parallel`，可选 `vertex`）：`vertex` 拖动只把当前分组同一 `pathIndex` 的拐点按相同世界增量平移，相邻顶点与其它分组不动，结果写进 `groups[].waypointOffsets`（键按含首尾端点的骨架序号，值支持 `[dx, dy]` / `{ x, y }`）。`getChannelGroups()` / `getChannelGroupWaypoints()` / `getChannels()` 带偏移，`getParallelGroups()` 与 `exportData` 的 `group_route` 已叠成实际路由；增删拐点时偏移序号同步平移，切回 `parallel` 不会清空已有偏移。③ `ChannelDemo` 加模式下拉与「准备两分组拐点」，拐点后端请求同时带 `path` 和 `waypointOffsets`。自测 `selftest-features` 603 → **611**、`selftest-demos` 296 → **297**，四页共 **1199** 条 0 失败；`node --check`、`npx tsc --noEmit`、`npm run check:docs`（249 个成员 / 246 个方法 / 245 个数据字段 / 92 个 options）、`node docs/steps/gen-api-index.mjs --check`、`npm run build` 与 `git diff --check` 全部通过。
+- 这一轮（「修改.txt」：继续深度优化 gis-view 整体性能）：`engine.js` 新增 160 ms 的程序化相机运动窗口，`zoomBy` / `setCamera` / `centerOn` / `flyToCamera` 的运动帧与指针交互共用细线 `gl.LINES` 和非 MSAA 后备缓冲；同一位置重复 `setCamera` 不续期，停稳后自动补一张全质量帧并刷新通道宽度 / 恢复符号预烤。聚合脏标记改为只在聚合启用且当前档可能变化、或上一帧确有聚合结果时标脏，关闭聚合后连续缩放不再空跑 `layoutScene()` 与整份点实例上传；相机引起的成员变化只在运动期沿用旧档，停稳后重算，没画出轻量帧也会因延迟聚合补帧。10 万点 / 5 万线实测连续缩放 p50 **67.9 → 22.5 ms**、p95 **76.2 → 25.1 ms**、avg **60.77 → 20.57 ms**；四页自测 `full 94 / demos 365 / docs 134 / perf 181` 共 **774** 条通过 / 0 失败，终态 `thinLines=false`、`noMsaa=false`。没有新增公开实例成员、options 或数据字段。
+
+- 这一轮（「修改.txt」：继续优化 gis-view，确认「这样改完性能提升了吗」）：先按 CPU profile 排除 JS —— 10 万线交互时约 **98.6% idle**、`render` 自身约 **0.1%**；之前主要省的是场景重排与相机调度，GPU 片元仍在为每条线执行虚线取模 / `smoothstep` / 光晕分支。`shaders.js` 新增 `THIN_LINE_FRAGMENT_SHADER`（交互期 `gl.LINES` 只输出颜色）与 `SOLID_LINE_FRAGMENT_SHADER`（全实线、非光晕四边形跳过虚线取模 / `smoothstep` / 光晕分支，保留非 MSAA 边缘覆盖率）；`engine.js` 按批切换，细线仍然保留端点圆头，所有运动帧仍按画布全分辨率绘制，没有重新引入模糊。无头 Chrome + ANGLE / AMD D3D11、1280×800、`quality: 'high'`：10 万点 / 5 万线缩放 p50 **23.2 → 16.7 ms**、p95 **28.6 → 16.8 ~ 16.9 ms**；10 万点 / 10 万线缩放三次中位 p50 **42.6 → 18.0 ms**、p95 **46.3 → 21.4 ms**、平移 p50 **16.7 ms**。16 ~ 18 ms 已接近 60Hz 帧节拍，继续明显提速要减少可见线段数 / 覆盖面积，而不是继续抠 JS；2px 实线因细线门槛（最大半宽 ≤ 0.6 设备像素且无虚线）不会走 `gl.LINES`，本轮只靠轻量四边形片元从约 **82.4 → 63.9 ms**。`selftest-perf` **182 / 1**（共 183 条；新增像素对拍通过，标签读数失败在 HEAD 已复现）；九个定向自测页 **1504 / 0**、`selftest-scale` **117 / 2**（既有 `onFilter` 计数失败）。