gis-view-webgl2 0.1.1 → 0.1.3

package/docs/steps/selftest-perf.html

@@ -28,11 +28,78 @@
 			// 拾取用的节点：线路只挂在前面 8000 个节点上，取后面的才不会被线抢走命中
 			const clearPoint = 15000
 			try {
-				const { createGisView: createGisViewRaw, QUALITY_LEVELS, QUALITY_MODES, createQualityGovernor, normalizeQualityOptions } = await import('../../src/gis-view/index.js')
-				// 性能断言是照「优化档」（限数 + 避让）测的老口径：统一带上 labelOptimize: true
-				const createGisView = (host, options = {}) => createGisViewRaw(host, { labelOptimize: true, ...options })
-
-				/* ---------------- 档位表与归一（纯函数） ---------------- */
+				const { createGisView: createGisViewRaw, QUALITY_LEVELS, QUALITY_MODES, createQualityGovernor, normalizeQualityOptions } = await import('../../src/gis-view/index.js')
+				const { normalizePointCluster, pointClusterZoomActive } = await import('../../src/gis-view/cluster.js')
+				const { createHeatmap } = await import('../../src/gis-view/heatmap.js')
+				const { normalizeDensity, renderDensityField } = await import('../../src/gis-view/density.js')
+				const clusterDefault = normalizePointCluster(true)
+				const clusterClamped = normalizePointCluster({ enabled: true, radius: 2, minPoints: 1, maxZoom: -3 })
+				check('点聚合：true 用缺省档（半径 60 / 最少 2 点 / 不限缩放）',
+					clusterDefault.enabled && clusterDefault.radius === 60 && clusterDefault.minPoints === 2 && clusterDefault.maxZoom === 0,
+					JSON.stringify(clusterDefault))
+				check('点聚合：半径 / 最少点数 / maxZoom 都夹到可用区间', clusterClamped.radius === 8 && clusterClamped.minPoints === 2 && clusterClamped.maxZoom === 0,
+					JSON.stringify(clusterClamped))
+				check('点聚合：maxZoom 按相机比例 / 基准比例判定，超过后展开',
+					pointClusterZoomActive({ enabled: true, maxZoom: 2 }, 1.5, 1) === true && pointClusterZoomActive({ enabled: true, maxZoom: 2 }, 2.1, 1) === false,
+					'1.5× 聚合 / 2.1× 展开')
+				// 性能断言是照「优化档」（限数 + 避让）测的老口径：统一带上 labelOptimize: true
+				const createGisView = (host, options = {}) => createGisViewRaw(host, { labelOptimize: true, ...options })
+				/* ---------------- 热力图语义键：只改密度画法不重采要素 ---------------- */
+				let semanticHeatmapOption = {
+					enabled: true,
+					field: 'value',
+					targets: ['point', 'line'],
+					domain: [0, 100],
+					colors: ['#0b3d91', '#ffd166', '#ff5e5e'],
+					density: { opacity: 1, layer: 'below', radius: 24 }
+				}
+				const semanticHeatmap = createHeatmap(() => semanticHeatmapOption, () => [])
+				const styleKeyBefore = semanticHeatmap.styleKey()
+				const weightKeyBefore = semanticHeatmap.weightKey()
+				semanticHeatmapOption = {
+					...semanticHeatmapOption,
+					density: { ...semanticHeatmapOption.density, opacity: 0.25, layer: 'top', radius: 40 }
+				}
+				check('热力图语义键：只改 density 的透明度 / 画层 / 核半径，样式键与权重键都不变',
+					semanticHeatmap.styleKey() === styleKeyBefore && semanticHeatmap.weightKey() === weightKeyBefore)
+				const densityOnlyStyleKey = semanticHeatmap.styleKey()
+				const densityOnlyWeightKey = semanticHeatmap.weightKey()
+				semanticHeatmapOption = { ...semanticHeatmapOption, colors: ['#123456', '#7ce0b0', '#ff8a3d'] }
+				check('热力图语义键：换色带只改样式键，权重键保持不动',
+					semanticHeatmap.styleKey() !== densityOnlyStyleKey && semanticHeatmap.weightKey() === densityOnlyWeightKey)
+				const colorWeightKey = semanticHeatmap.weightKey()
+				semanticHeatmapOption = { ...semanticHeatmapOption, field: 'score' }
+				check('热力图语义键：换取值字段时两个键都变（密度场要重新采样）',
+					semanticHeatmap.weightKey() !== colorWeightKey && semanticHeatmap.styleKey() !== densityOnlyStyleKey)
+
+				/* ---------------- 热力图密度场：透明边缘的 RGB 预乘 alpha ---------------- */
+				const premultOptions = normalizeDensity({ style: 'smooth', max: 1, radius: 6, resolution: 64, threshold: 0, core: 0 })
+				const premultPalette = {
+					bands: [[1, 0, 0, 1]],
+					smooth: [[1, 0, 0, 1], [1, 0, 0, 1]],
+					core: null
+				}
+				const premultField = renderDensityField([{ x: 0, y: 0, ratio: 1 }], premultOptions, premultPalette)
+				let premultPartial = 0
+				let premultBad = 0
+				if (premultField) {
+					for (let offset = 0; offset < premultField.pixels.length; offset += 4) {
+						const alpha = premultField.pixels[offset + 3]
+						if (alpha === 0 || alpha === 255) {
+							continue
+						}
+						premultPartial += 1
+						// 纯红色带：预乘后 R 应与 A 同值、G/B 都还是 0；旧实现固定写 R=255，透明边缘会发灰。
+						if (premultField.pixels[offset] !== alpha || premultField.pixels[offset + 1] !== 0 || premultField.pixels[offset + 2] !== 0) {
+							premultBad += 1
+						}
+					}
+				}
+				check('热力图密度场：透明边缘的 RGB 已预乘（R 跟 A 同降、G/B 为 0，不再留灰边）',
+					Boolean(premultField) && premultPartial > 0 && premultBad === 0,
+					`${premultField?.width ?? 0}×${premultField?.height ?? 0} / 半透明 ${premultPartial} 格 / 未预乘 ${premultBad} 格`)
+
+				/* ---------------- 档位表与归一（纯函数） ---------------- */
 				check('QUALITY_MODES 是五档：四个固定档 + auto', QUALITY_MODES.join(',') === 'high,balanced,lean,fast,auto', QUALITY_MODES.join(','))
 				check('QUALITY_LEVELS 从高到低，越往下省得越多', QUALITY_LEVELS.length === 4 &&
 					QUALITY_LEVELS[0].glow && QUALITY_LEVELS[0].ornament && QUALITY_LEVELS[0].scale === 1 &&
@@ -81,6 +148,28 @@
 				fixed.sample(50)
 				check('固定档不受帧耗时影响', fixed.state().name === 'balanced' && fixed.state().glow === false && fixed.state().scale === 1, `${fixed.state().name} glow=${fixed.state().glow}`)
 
+				/* ---------------- 视口可见性：离开视口停动画，回来再续 ---------------- */
+				const visibilityHost = document.createElement('div')
+				visibilityHost.style.cssText = 'position:fixed;left:-10000px;top:0;width:320px;height:200px'
+				document.body.append(visibilityHost)
+				const visibilityView = createGisView(visibilityHost, {
+					points: [{ id: 'visibility-point', x: 0, y: 0 }],
+					lines: [],
+					effects: { point: { radius: 16, period: 1.5, count: 1 } },
+					showGrid: false
+				})
+				visibilityView.fitView()
+				await sleep(260)
+				const hiddenAnimating = visibilityView.getStats().animating
+				visibilityHost.style.left = '0px'
+				await sleep(260)
+				const shownAnimating = visibilityView.getStats().animating
+				check('画布离开视口时连续动画停住，回到视口后再继续',
+					hiddenAnimating === false && shownAnimating === true,
+					`视口外 animating=${hiddenAnimating} / 视口内 animating=${shownAnimating}`)
+				visibilityView.destroy()
+				visibilityHost.remove()
+
 				/* ---------------- 大数据密集档：手动开关 / auto 阈值 / 效果恢复 ---------------- */
 				const denseHost = document.createElement('div')
 				denseHost.style.cssText = 'width:420px;height:280px'
@@ -1189,10 +1278,63 @@
 				const heatFreshView = createGisView(heatFreshHost, { points: heatPoints, lines: heatLines, heatmap: heatB, width: 640, height: 380, quality: 'high' })
 				heatFreshView.setCamera({ center: [320, 200], scale: 1 })
 				const heatFreshText = JSON.stringify(heatFreshView.snapshotScene())
-				check('样式快路径：同一份热力图配置原样再发一次，值域按当前数据重算（与整份重建一致）',
-					heatRefreshedText !== heatAfter && heatRefreshedText === heatFreshText,
-					heatRefreshedText === heatFreshText ? `快照 ${heatRefreshedText.length} 字节，逐字段一致` : diffText(heatRefreshedText, heatFreshText))
-				heatFreshView.destroy()
+				check('样式快路径：同一份热力图配置原样再发一次，值域按当前数据重算（与整份重建一致）',
+					heatRefreshedText !== heatAfter && heatRefreshedText === heatFreshText,
+					heatRefreshedText === heatFreshText ? `快照 ${heatRefreshedText.length} 字节，逐字段一致` : diffText(heatRefreshedText, heatFreshText))
+				// 密度场：只改 opacity 时复用上一份采样与贴图；换色带 / 换要素值才重烤。
+				// 判断重烤用 heatDensityStats 的对象身份：只改画法那条快路不会换它。
+				const densityOption = {
+					enabled: true,
+					field: 'value',
+					targets: ['point'],
+					domain: [0, 100],
+					colors: ['#0b3d91', '#ffd166', '#ff5e5e'],
+					density: { opacity: 1, radius: 22, resolution: 192, levels: 8 }
+				}
+				const densityHost = document.createElement('div')
+				document.querySelector('#map').append(densityHost)
+				const densityView = createGisView(densityHost, {
+					points: heatPoints,
+					lines: [],
+					heatmap: densityOption,
+					width: 640,
+					height: 380,
+					quality: 'high',
+					showGrid: false,
+					background: null
+				})
+				densityView.fitView()
+				await densityView.whenRendered()
+				await densityView.whenRendered()
+				const densityFirst = densityView.getStats().heatDensity
+				check('热力图密度场：首帧烤出有效场（有采样数、贴图尺寸非零）',
+					Boolean(densityFirst) && densityFirst.samples > 0 && densityFirst.width > 0 && densityFirst.height > 0,
+					JSON.stringify(densityFirst))
+				const opacityOption = { ...densityOption, density: { ...densityOption.density, opacity: 0.35 } }
+				const opacityStarted = now()
+				densityView.updateOptions({ heatmap: opacityOption })
+				const opacityUpdateMs = now() - opacityStarted
+				await densityView.whenRendered()
+				const densityAfterOpacity = densityView.getStats().heatDensity
+				check('热力图密度场：只改 density.opacity 不重采、不重烤（复用同一份烘焙读数）',
+					densityAfterOpacity === densityFirst)
+				const colorOption = { ...opacityOption, colors: ['#123456', '#7ce0b0', '#ff8a3d'] }
+				const colorStarted = now()
+				densityView.updateOptions({ heatmap: colorOption })
+				const colorUpdateMs = now() - colorStarted
+				await densityView.whenRendered()
+				const densityAfterColor = densityView.getStats().heatDensity
+				check('热力图密度场：换色带会重烤（生成新一份烘焙读数）',
+					densityAfterColor !== densityAfterOpacity && densityAfterColor.samples === densityAfterOpacity.samples)
+				densityView.updatePoint('h0', { value: 7 })
+				await densityView.whenRendered()
+				const densityAfterPoint = densityView.getStats().heatDensity
+				check('热力图密度场：定向 updatePoint 改要素值后场跟着重烤（不再停在旧数据上）',
+					densityAfterPoint !== densityAfterColor && densityAfterPoint.samples === densityAfterColor.samples)
+				diag('热力图密度场更新', `纯透明度 ${opacityUpdateMs.toFixed(2)} ms / 换色带 ${colorUpdateMs.toFixed(2)} ms；烘焙 ${densityAfterColor.ms.toFixed(1)} ms`)
+				densityView.destroy()
+				densityHost.remove()
+				heatFreshView.destroy()
 				heatFreshHost.remove()
 				heatView.destroy()
 				heatHost.remove()
@@ -1669,16 +1811,18 @@
 				document.body.appendChild(thinHost)
 				const thinPoints = Array.from({ length: 12 }, (unused, index) => ({ id: `tp-${index}`, x: index * 10, y: index % 3 * 6, name: `小点 ${index}` }))
 				const thinLines = thinPoints.slice(1).map((point, index) => ({ id: `tl-${index}`, from: thinPoints[index].id, to: point.id }))
-				const thinView = createGisView(thinHost, {
+				const thinView = createGisView(thinHost, {
 					points: thinPoints,
 					lines: thinLines,
 					pointStyle: { size: 6 },
 					lineStyle: { width: 1 },
 					fitPadding: 20,
 					// 交互期的那几条读数（细线快路径 / 后备缓冲）靠拖动触发：平移显式打开
-					features: { pan: true }
-				})
-				await sleep(400)
+					features: { pan: true }
+				})
+				// 页面底部的临时画布先滚进视口：动画与交互帧只在可见时连续推进
+				thinHost.scrollIntoView({ block: 'center', inline: 'nearest' })
+				await sleep(400)
 				const thinCanvas = thinHost.querySelector('canvas')
 				const thinPointerId = 91
 				const fireThin = (type, at) => thinCanvas.dispatchEvent(new PointerEvent(type, {
@@ -1820,15 +1964,17 @@
 					channelLines.push({ id: `cm-${index}`, from: 'p1', to: 'p2' })
 					channelLineIds.push(`cm-${index}`)
 				}
-				const channelView = createGisView(channelHost, {
+				const channelView = createGisView(channelHost, {
 					points: channelPoints,
 					lines: channelLines,
 					channels: [{ id: 'ch-cost', from: 'p1', to: 'p2', lineIds: channelLineIds, path: [[100, 30]] }],
 					fitPadding: 20,
-					waypointEditable: true
-				})
+					waypointEditable: true
+				})
 				channelView.selectFeatures('cm-0')
-				await sleep(200)
+				// 拐点拖动靠真实指针命中：先把这张临时画布滚进视口，别让命中坐标落在视口外
+				channelHost.scrollIntoView({ block: 'center', inline: 'nearest' })
+				await sleep(200)
 				const channelCanvas = channelHost.querySelector('canvas')
 				const channelWaypoint = channelView.getWaypoints(0).find(item => item.pathIndex === 1)
 				const channelSkeletonBefore = channelView.getChannelGroups('ch-cost')[0].skeleton.map(coordinate => coordinate[0])
@@ -1903,9 +2049,136 @@
 				const goCostBest = Math.min(...goCostMerge)
 				diag('分组编辑（2 万回线、只写 groups 的通道，合并一次）', `最快 ${goCostBest.toFixed(1)} ms`)
 				check('2 万回线的通道合并分组：40 ms 以内（成员池一次建表 + 集合去重，老的逐条 includes 是平方级）', goCostBest < 40, `最快 ${goCostBest.toFixed(1)} ms`)
-				check('只写 groups 的通道合并之后成员一条不少（2 万条只走声明，不靠顶层 lineIds）', goCostMergedLines === goCostCount, `${goCostMergedLines} / ${goCostCount}`)
-
-				thinView.destroy()
+				check('只写 groups 的通道合并之后成员一条不少（2 万条只走声明，不靠顶层 lineIds）', goCostMergedLines === goCostCount, `${goCostMergedLines} / ${goCostCount}`)
+
+				/* ---------------- 点聚合：展示成员、拾取、点击语义与 maxZoom ---------------- */
+				const clusterPointCount = 12000
+				const clusterRandom = (() => {
+					let seed = 20261021
+					return () => {
+						seed = (seed * 1664525 + 1013904223) % 4294967296
+						return seed / 4294967296
+					}
+				})()
+				const clusterCenters = [[0, 0], [120, 0], [60, 90]]
+				// 留出几个远离簇中心的点，覆盖 getClusters() 的单成员分支；它们仍计入总点数。
+				const clusterIsolated = [
+					[-360, -170], [380, -170], [-360, 200], [380, 200],
+					[-440, 20], [460, 20], [20, -220], [20, 240]
+				]
+				const clusterPoints = new Array(clusterPointCount)
+				for (let index = 0; index < clusterPointCount; index += 1) {
+					const isolatedIndex = index - (clusterPointCount - clusterIsolated.length)
+					if (isolatedIndex >= 0) {
+						clusterPoints[index] = {
+							id: `cp${index}`,
+							x: clusterIsolated[isolatedIndex][0],
+							y: clusterIsolated[isolatedIndex][1],
+							name: `独立点 ${index}`
+						}
+						continue
+					}
+					const center = clusterCenters[index % clusterCenters.length]
+					clusterPoints[index] = {
+						id: `cp${index}`,
+						x: center[0] + (clusterRandom() - 0.5) * 24,
+						y: center[1] + (clusterRandom() - 0.5) * 24,
+						name: `聚合点 ${index}`
+					}
+				}
+				const clusterHost = document.createElement('div')
+				clusterHost.style.cssText = 'width:640px;height:380px'
+				document.body.appendChild(clusterHost)
+				let clusterEvents = 0
+				let plainEvents = 0
+				let lastClusterPayload = null
+				const clusterView = createGisView(clusterHost, {
+					points: clusterPoints,
+					width: 640,
+					height: 380,
+					pointStyle: { size: 4 },
+					features: 'view',
+					fitPadding: 24,
+					pointCluster: { enabled: true, radius: 60, minPoints: 2 }
+				})
+				clusterView.on('clusterClick', payload => {
+					clusterEvents += 1
+					lastClusterPayload = payload
+				})
+				clusterView.on('click', () => {
+					plainEvents += 1
+				})
+				await clusterView.whenRendered()
+				const clusterStats = clusterView.getStats()
+				check('点聚合：一万二千点建出多成员圆，统计口径自洽',
+					clusterStats.clusterCount > 0 && clusterStats.clusterPointCount >= clusterStats.clusterCount && clusterStats.clusterMs >= 0,
+					JSON.stringify({ clusterCount: clusterStats.clusterCount, clusterPointCount: clusterStats.clusterPointCount, clusterMs: clusterStats.clusterMs }))
+				check('点聚合：getPointCluster() 给出归一化配置与 active',
+					clusterView.getPointCluster()?.active === true && clusterView.getPointCluster()?.radius === 60,
+					JSON.stringify(clusterView.getPointCluster()))
+				const clusterGroups = clusterView.getClusters()
+				const multiClusters = clusterGroups.filter(item => item.count > 1)
+				const singletonGroups = clusterGroups.filter(item => item.count === 1)
+				check('点聚合：getClusters() 含单成员，单成员 count=1、多成员 id 以 cluster: 开头',
+					singletonGroups.length > 0 && multiClusters.length > 0 && singletonGroups.every(item => item.count === 1 && item.pointIndexes.length === 1) && multiClusters.every(item => item.id.startsWith('cluster:')),
+					`${clusterGroups.length} 组（${singletonGroups.length} 单成员 / ${multiClusters.length} 多成员）`)
+				check('点聚合：原始数据与 getData() 一条不少',
+					clusterView.getData().points.length === clusterPointCount && clusterView.listPoints({ visibleOnly: false }).length === clusterPointCount,
+					`getData ${clusterView.getData().points.length} / listPoints ${clusterView.listPoints({ visibleOnly: false }).length}`)
+				const visibleSingletons = clusterView.listPoints({ visibleOnly: true })
+				let visitedSingletons = 0
+				clusterView.forEachPointInView(clusterView.getViewRect(), () => {
+					visitedSingletons += 1
+				})
+				check('点聚合：聚合内部成员不出现在 visibleOnly / forEachPointInView',
+					visibleSingletons.length === clusterPointCount - clusterStats.clusterPointCount && visitedSingletons === visibleSingletons.length,
+					`可见 ${visibleSingletons.length} / 遍历 ${visitedSingletons} / 隐藏 ${clusterStats.clusterPointCount}`)
+				const clusterPick = clusterView.pick(multiClusters[0].screen[0], multiClusters[0].screen[1])
+				check('点聚合：聚合圆拾取返回 type=cluster，带 count / pointIds / bounds',
+					clusterPick?.type === 'cluster' && clusterPick.count >= 2 && clusterPick.pointIds.length === clusterPick.count && Boolean(clusterPick.bounds),
+					JSON.stringify({ type: clusterPick?.type, count: clusterPick?.count, ids: clusterPick?.pointIds?.length }))
+				const selectionProbe = visibleSingletons[0]
+				clusterView.selectFeatures([selectionProbe.item.id])
+				await clusterView.whenRendered()
+				const selectedBefore = clusterView.getSelections().map(entry => entry.item?.id ?? entry.index).join(',')
+				const clusterCanvas = clusterHost.querySelector('canvas')
+				// 合成指针事件使用真实客户端坐标：先把画布滚进视口，避免 clientY 落在窗口外
+				clusterCanvas.scrollIntoView({ block: 'center' })
+				await sleep(50)
+				const clickPick = clusterView.pick(multiClusters[0].screen[0], multiClusters[0].screen[1])
+				const clickScreen = clickPick?.screen ?? multiClusters[0].screen
+				const clickClient = clusterView.screenToClient(clickScreen[0], clickScreen[1])
+				const fireCluster = type => clusterCanvas.dispatchEvent(new PointerEvent(type, {
+					bubbles: true, cancelable: true, pointerId: 93, pointerType: 'mouse', button: 0,
+					buttons: type === 'pointerup' ? 0 : 1, clientX: clickClient[0], clientY: clickClient[1]
+				}))
+				fireCluster('pointerdown')
+				fireCluster('pointerup')
+				await sleep(30)
+				const selectedAfter = clusterView.getSelections().map(entry => entry.item?.id ?? entry.index).join(',')
+				check('点聚合：点击聚合只发 clusterClick，不发普通 click，选中集不变',
+					clusterEvents === 1 && plainEvents === 0 && selectedAfter === selectedBefore && lastClusterPayload?.action?.type === 'clusterClick' && lastClusterPayload?.action?.data?.type === 'cluster',
+					`clusterClick=${clusterEvents} click=${plainEvents} 选中 ${selectedBefore} → ${selectedAfter} action=${lastClusterPayload?.action?.type} clickPick=${clickPick?.type ?? 'null'} clickScreen=${clickScreen.map(value => value.toFixed(1)).join(',')} client=${clickClient.map(value => value.toFixed(1)).join(',')}`)
+				const fitScale = clusterView.getCamera().scale
+				clusterView.updateOptions({ pointCluster: { enabled: true, radius: 60, minPoints: 2, maxZoom: 2 } })
+				clusterView.setCamera({ scale: fitScale * 3 })
+				await clusterView.whenRendered()
+				const zoomedStats = clusterView.getStats()
+				check('点聚合：缩放超过 maxZoom 后展开原始点（active=false、聚合圆清空）',
+					clusterView.getPointCluster()?.active === false && zoomedStats.clusterCount === 0 && clusterView.listPoints({ visibleOnly: true }).length === clusterPointCount,
+					JSON.stringify({ active: clusterView.getPointCluster()?.active, clusterCount: zoomedStats.clusterCount, visible: clusterView.listPoints({ visibleOnly: true }).length }))
+				clusterView.setCamera({ scale: fitScale })
+				await clusterView.whenRendered()
+				clusterView.updateOptions({ pointCluster: false })
+				await clusterView.whenRendered()
+				const disabledStats = clusterView.getStats()
+				check('点聚合：关掉之后原始点全部恢复，getPointCluster().enabled=false',
+					clusterView.getPointCluster()?.enabled === false && clusterView.getPointCluster()?.active === false && disabledStats.clusterCount === 0 && disabledStats.clusterPointCount === 0,
+					JSON.stringify({ cluster: clusterView.getPointCluster(), stats: { count: disabledStats.clusterCount, points: disabledStats.clusterPointCount } }))
+				clusterView.destroy()
+				clusterHost.remove()
+
+				thinView.destroy()
 				thinHost.remove()
 				big.destroy()
 				bigHost.remove()

package/docs/steps/selftest-scale.html

@@ -123,6 +123,7 @@
 				const plainView = createGisView(host(320, 200), {
 					points: [{ id: 'p0', x: 0, y: 0 }, { id: 'p1', x: 40, y: 0 }],
 					lines: [{ id: 'pl0', from: 'p0', to: 'p1', start: [-20, -20], end: [60, -20] }],
+					lineFollowsNode: false,
 					filterWorker: false
 				})
 				await settle()
@@ -132,8 +133,8 @@
 					`首顶点 ${JSON.stringify(firstVertex())}`)
 				plainView.updatePoint('p0', { visible: false })
 				await settle()
-				check('无筛选：visible: false 的节点当场退场（绑定线的端点退回自身坐标）',
-					plainView.isPointVisible(0) === false && firstVertex()?.[0] === -20,
+				check('无筛选：lineFollowsNode: false 时 visible: false 只收起节点，绑定线停在最后坐标',
+					plainView.isPointVisible(0) === false && firstVertex()?.[0] === 0,
 					`首顶点 ${JSON.stringify(firstVertex())}`)
 				plainView.updatePoint('p0', { visible: true })
 				await settle()
@@ -776,36 +777,58 @@
 				const claimPath = claimView.getLine('cl')?.path
 				check('追加被线路按 id 认领的节点：回落整份重建，线跟着出来', claimPath?.length === 2 && Math.abs(claimPath[1][0] - 200) < 0.5 && claimView.getStats().pointCount === 3, `${claimPath?.length} 个顶点 / ${claimView.getStats().pointCount} 个点`)
 				claimView.destroy()
-				/* 自适应比例（zoomScaleAuto）与重定基准（setZoomBaseScale）：包围盒 / 比例一变，节点与通道间距一起变 */
-				const autoView = createGisView(host(640, 320), {
-					points: [{ id: 'z0', x: 0, y: 0, size: 10 }, { id: 'z1', x: 600, y: 0, size: 10 }],
-					lines: [{ id: 'zl', from: 'z0', to: 'z1', width: 2 }],
-					zoomScaleAuto: true,
-					showGrid: false
-				})
+				/* 适应视图的节点间距（fitSpacing）：远处孤立点撑大包围盒时，按最近可见节点中心距反推比例 */
+				const spacingPoints = [
+					{ id: 'f0', x: 0, y: 0, size: 10 },
+					{ id: 'f0b', x: 0, y: 0, size: 10 },
+					{ id: 'f1', x: 60, y: 0, size: 10 },
+					{ id: 'f2', x: 200, y: 0, size: 10 },
+					{ id: 'f3', x: 0, y: 200, size: 10 },
+					{ id: 'fx', x: 10000, y: 10000, size: 10 }
+				]
+				const fitSpacingBaseView = createGisView(host(640, 320), { points: spacingPoints, showGrid: false })
+				const spacingView = createGisView(host(640, 320), { points: spacingPoints, fitSpacing: { minDistance: 24, maxZoom: 0 }, showGrid: false })
 				await settle(140)
-				const autoFit = autoView.getCamera().scale
-				const autoSizeFit = autoView.snapshotScene({ background: false }).points[0]?.size ?? 0
-				check('自适应比例：开关写进 getOptions（面板回显读得到）', autoView.getOptions().zoomScaleAuto === true, String(autoView.getOptions().zoomScaleAuto))
-				check('自适应比例：联动基准缺省取首次适应视图时的比例', Math.abs(autoView.getZoomBaseScale() - autoFit) < 1e-9, `基准 ${autoView.getZoomBaseScale()} / 相机 ${autoFit}`)
-				autoView.setCamera({ scale: autoFit * 2, center: [0, 0] })
-				await settle(60)
-				const autoSizeZoom = autoView.snapshotScene({ background: false }).points[0]?.size ?? 0
-				check('自适应比例：相机放大 2 倍，节点绘制尺寸跟着翻倍（没写 pointZoomScale 时按 1 算）', Math.abs(autoSizeZoom - autoSizeFit * 2) < 0.02, `${autoSizeFit} → ${autoSizeZoom}`)
-				autoView.setZoomBaseScale()
+				const plainFit = fitSpacingBaseView.getCamera().scale
+				const spacingFit = spacingView.getCamera().scale
+				check('适应节点间距：配置写进 getOptions（面板回显读得到）', spacingView.getOptions().fitSpacing?.minDistance === 24, JSON.stringify(spacingView.getOptions().fitSpacing))
+				check('适应节点间距：远处孤立点撑大包围盒后仍提高比例（重合点不算最近距离）', spacingFit > plainFit * 5, `${plainFit} → ${spacingFit}`)
+				const spacingCenter = spacingView.getCamera().center
+				check('适应节点间距：相机保持在普通适应的包围盒中心', Math.abs(spacingCenter[0] - 5000) < 0.5 && Math.abs(spacingCenter[1] - 5000) < 0.5, JSON.stringify(spacingCenter))
+				const spacingViewport = spacingView.getViewport()
+				const spacingCenterScreen = spacingView.project(5000, 5000)
+				check('适应节点间距：放大围绕普通适应中心发生，不跳到最近节点对', Math.abs(spacingCenterScreen[0] - spacingViewport.cssWidth / 2) < 0.1 && Math.abs(spacingCenterScreen[1] - spacingViewport.cssHeight / 2) < 0.1, JSON.stringify(spacingCenterScreen))
+				const spacingScreen0 = spacingView.project(0, 0)
+				const spacingScreen1 = spacingView.project(60, 0)
+				const spacingScreen = Math.hypot(spacingScreen1[0] - spacingScreen0[0], spacingScreen1[1] - spacingScreen0[1])
+				check('适应节点间距：最近节点中心距达到 minDistance（CSS 像素）', Math.abs(spacingScreen - 24) < 0.1, String(spacingScreen))
+				spacingView.updateOptions({ fitSpacing: { minDistance: 24, maxZoom: 2 } })
+				spacingView.fitView()
 				await settle(60)
-				const autoSizeBased = autoView.snapshotScene({ background: false }).points[0]?.size ?? 0
-				check('重定基准：不传参数取当下相机比例，比例系数回到 1（节点回到原样大小）', Math.abs(autoView.getZoomBaseScale() - autoFit * 2) < 1e-9 && Math.abs(autoSizeBased - autoSizeFit) < 0.02, `基准 ${autoView.getZoomBaseScale()} / ${autoSizeZoom} → ${autoSizeBased}`)
-				autoView.updateOptions({ pointZoomScale: 0 })
-				autoView.setCamera({ scale: autoFit, center: [0, 0] })
+				const spacingCapped = spacingView.getCamera().scale
+				check('适应节点间距：maxZoom 限制相对普通适应比例的上限', Math.abs(spacingCapped - plainFit * 2) < 1e-6, `${plainFit} → ${spacingCapped}`)
+				spacingView.updateOptions({ fitSpacing: false })
+				spacingView.fitView()
 				await settle(60)
-				const autoSizeExplicit = autoView.snapshotScene({ background: false }).points[0]?.size ?? 0
-				check('自适应比例：显式写过指数就以显式值为准（写 0 即这一项不跟随）', Math.abs(autoSizeExplicit - autoSizeFit) < 0.02, `${autoSizeFit} / ${autoSizeExplicit}`)
-				autoView.updateOptions({ zoomScaleAuto: false })
-				autoView.setCamera({ scale: autoFit * 2, center: [0, 0] })
-				await settle(60)
-				check('自适应比例：关掉开关之后节点尺寸不再跟随（比例只按显式指数算）', Math.abs((autoView.snapshotScene({ background: false }).points[0]?.size ?? 0) - autoSizeFit) < 0.02, String(autoView.snapshotScene({ background: false }).points[0]?.size))
-				autoView.destroy()
+				const spacingOff = spacingView.getCamera()
+				check('适应节点间距：关闭后恢复普通适应比例与包围盒中心', Math.abs(spacingOff.scale - plainFit) < 1e-9 && Math.abs(spacingOff.center[0] - 5000) < 0.5, `${spacingCapped} → ${spacingOff.scale} / ${JSON.stringify(spacingOff.center)}`)
+				/* 规则网格里最近距离满地都是：比例仍按最近距离算，相机中心继续沿用普通适应的包围盒中心 */
+				const gridPoints = []
+				for (let row = 0; row < 5; row += 1) {
+					for (let column = 0; column < 5; column += 1) {
+						gridPoints.push({ id: `g${column}_${row}`, x: column * 10, y: row * 10, size: 10 })
+					}
+				}
+				gridPoints.push({ id: 'gx', x: 10000, y: 10000, size: 10 })
+				const gridSpacingView = createGisView(host(640, 320), { points: gridPoints, fitSpacing: { minDistance: 24, maxZoom: 0 }, showGrid: false })
+				await settle(140)
+				const gridCenter = gridSpacingView.getCamera().center
+				check('适应节点间距：最近距离并列时只调整比例，相机仍停在普通适应中心',
+					Math.abs(gridCenter[0] - 5000) <= 0.5 && Math.abs(gridCenter[1] - 5000) <= 0.5,
+					JSON.stringify(gridCenter))
+				gridSpacingView.destroy()
+				fitSpacingBaseView.destroy()
+				spacingView.destroy()
 			}
 			catch (error) {
 				check('页面没有抛错', false, String(error && error.stack ? error.stack : error).split('\n').slice(0, 3).join(' | '))

package/docs/steps/step-10-full.js

@@ -76,7 +76,7 @@ export const createFullView = (target, options = {}) => {
 		draggable: true,
 		boxSelect: true,
 		waypointEditable: true,
-		features: { pan: true, zoom: true, hover: true, select: true, contextMenu: true, keyboard: true, channelDraft: true, channelMenu: true },
+		features: { pan: true, zoom: true, hover: true, select: true, contextMenu: true, keyboard: true, channelDraft: true },
 		// 组件的回调都带载荷：type / index / item 就是「当前是哪个元素」，world 是光标处的世界坐标
 		onHover: payload => forward.onHover?.(payload),
 		onClick: payload => forward.onClick?.(payload),

package/docs/steps/step-12-events.js

@@ -119,7 +119,7 @@ export const createActionView = (target, options = {}) => {
 		draggable: true,
 		boxSelect: true,
 		waypointEditable: true,
-		features: { pan: true, zoom: true, hover: true, select: true, contextMenu: true, keyboard: true, channelDraft: true, channelMenu: true },
+		features: { pan: true, zoom: true, hover: true, select: true, contextMenu: true, keyboard: true, channelDraft: true },
 		// 下面五条是同一条路：每个回调先报一句判读，再交给页面自己那一条（日志、草稿读数都还在）
 		onPointerDown: (payload, event) => {
 			report(describeAction(payload, '按下'))

package/docs//346/216/245/345/217/243/345/215/217/350/256/256.md

@@ -325,7 +325,7 @@ HTTP `409 Conflict` 示例：
   "channelId": "channel-a",
   "action": { "type": "splitGroups", "groupIds": ["channel-a", "channel-a::2"] },
   "groups": [
-    { "id": "channel-a", "lineIds": ["line-0", "line-1"], "path": [[18.0, 10.2], [20.5, 11.1]] },
+    { "id": "channel-a", "lineIds": ["line-0", "line-1"], "path": [[18.0, 10.2], [20.5, 11.1]], "waypointOffsets": { "1": [1.2, -0.8] } },
     { "id": "channel-a::2", "lineIds": ["line-2"], "path": [] }
   ],
   "baseVersion": 12,
@@ -337,10 +337,11 @@ HTTP `409 Conflict` 示例：
 | --- | --- | --- |
 | `channelId` | `string \| number` | 通道 id，必须与路径参数一致 |
 | `action` | `object` | 审计用动作：`splitGroups` / `mergeGroups` / `moveLine` / `addGroup` / `setGroups`；服务端不应依赖它恢复数据 |
-| `groups` | `Array<{ id, lineIds, path }>` | **整份**分组声明；顺序就是后续回线排布顺序 |
+| `groups` | `Array<{ id, lineIds, path, waypointOffsets? }>` | **整份**分组声明；顺序就是后续回线排布顺序 |
 | `groups[].id` | `string \| number` | 分组稳定 id |
 | `groups[].lineIds` | `Array<string \| number>` | 这一组包含的回线 id；同一条回线在整份声明里只能出现一次 |
 | `groups[].path` | `[number, number][]` | 分组公共骨架的中间拐点；`[]` 是合法的「直连」，不能当成没提交 |
+| `groups[].waypointOffsets` | `Record<string, [number, number] \| { x, y }>` | `vertex` 拖动的分组刚性偏移：键是含首尾端点的骨架顶点序号（只认中间拐点），值是组内所有回线共用的世界坐标增量；省略或空对象表示不带偏移 |
 
 `groups` 至少保留一组。若业务允许空通道，建议另走 `DELETE /gis/channels/{channelId}`，不要把空分组声明当作删除通道的隐式约定。
 
@@ -350,7 +351,7 @@ HTTP `409 Conflict` 示例：
 {
   "channelId": "channel-a",
   "groups": [
-    { "id": "channel-a", "lineIds": ["line-0", "line-1"], "path": [[18.0, 10.2], [20.5, 11.1]] },
+    { "id": "channel-a", "lineIds": ["line-0", "line-1"], "path": [[18.0, 10.2], [20.5, 11.1]], "waypointOffsets": { "1": [1.2, -0.8] } },
     { "id": "channel-a::2", "lineIds": ["line-2"], "path": [] }
   ],
   "groupCount": 2,
@@ -358,11 +359,11 @@ HTTP `409 Conflict` 示例：
 }
 ```
 
-服务端应校验 channel 存在、`lineIds` 全部属于这条通道且不重复、每个 `path` 点都是有限数值；返回落库后的整份快照，前端用 `groups` 覆盖本地对应通道。
+服务端应校验 channel 存在、`lineIds` 全部属于这条通道且不重复、每个 `path` 点都是有限数值，以及 `waypointOffsets` 的键都落在中间拐点、值都是有限增量；返回落库后的整份快照，前端用 `groups` 覆盖本地对应通道。
 
 ### 5.2 `PATCH /gis/channels/{channelId}/groups/waypoints`
 
-覆盖一条通道里某一组的**公共骨架**。`path` 只包含中间拐点，两端由通道绑定的节点补齐。拖动过程中 `phase: 'start' / 'move'` 不发请求，只在 `add` / `remove` / `end` 发一条。
+覆盖一条通道里某一组的**公共骨架与分组刚性偏移**。`path` 只包含中间拐点，两端由通道绑定的节点补齐；`waypointOffsets` 是 `channelWaypointDragMode: 'vertex'` 拖出来的按骨架序号偏移。拖动过程中 `phase: 'start' / 'move'` 不发请求，只在 `add` / `remove` / `end` 发一条。
 
 请求体：
 
@@ -372,6 +373,7 @@ HTTP `409 Conflict` 示例：
   "channelId": "channel-a",
   "groupId": "channel-a::2",
   "path": [[18.0, 10.2], [20.5, 11.1]],
+  "waypointOffsets": { "1": [1.2, -0.8] },
   "phase": "end",
   "scope": "group",
   "baseVersion": 12,
@@ -384,8 +386,9 @@ HTTP `409 Conflict` 示例：
 | `channelId` | `string \| number` | 通道 id |
 | `groupId` | `string \| number` | 分组 id |
 | `path` | `[number, number][]` | 整份公共骨架的中间拐点；空数组表示直连 |
+| `waypointOffsets` | `Record<string, [number, number] \| { x, y }>` | 分组刚性偏移：键按含首尾端点的骨架序号算，只接受中间拐点；省略或空对象表示普通平行骨架 |
 | `phase` | `'add' \| 'remove' \| 'end'` | 实际落地阶段；`select` / `start` / `move` 不应发请求 |
-| `scope` | `'group'` | 公共骨架的存储范围；组内每条回线的偏移拐点是由它派生的，不单独落库 |
+| `scope` | `'group'` | 公共骨架与分组刚性偏移的存储范围；组内每条回线的车道偏移是由它派生的，不单独落库 |
 
 响应 `data.result`：
 
@@ -393,10 +396,13 @@ HTTP `409 Conflict` 示例：
 {
   "target": { "type": "channelGroup", "channelId": "channel-a", "groupId": "channel-a::2", "scope": "group" },
   "path": [[18.0, 10.2], [20.5, 11.1]],
+  "waypointOffsets": { "1": [1.2, -0.8] },
   "pointCount": 2
 }
 ```
 
+服务端必须把 `path` 与 `waypointOffsets` 一起落库并一起返回：只收 `path` 会丢掉非平行拖动结果，刷新后分组又回到旧骨架。
+
 ### 5.3 `PATCH /gis/lines/{lineId}/path`
 
 覆盖独立线路的整条折线。与通道分组不同，这里 `path` **包含首尾端点**，因为独立线路不依赖通道节点补端点。
@@ -446,9 +452,9 @@ HTTP `409 Conflict` 示例：
 ### 6.3 通道分组 / 拐点
 
 1. 只在真实落地的 `add` / `remove` / `end` 发请求；`start` / `move` 的中间态不发。
-2. 请求体永远是操作完成后的**整份** `groups` 或 `path`，从 `view.getChannelGroups()` / `view.getChannelGroupWaypoints()` 重新读。
+2. 请求体永远是操作完成后的**整份** `groups`，或成对的 `path` + `waypointOffsets`，从 `view.getChannelGroups()` / `view.getChannelGroupWaypoints()` 重新读。
 3. 同一条通道的写请求串行发送；拖动期间只保留最后一个 `end`。
-4. 成功用响应里的 `groups` / `path` 覆盖本地快照；如果服务端做了归一化，以服务端为准。
+4. 成功用响应里的 `groups` / `path` / `waypointOffsets` 覆盖本地快照；如果服务端做了归一化，以服务端为准。
 5. 409 优先使用错误包里的 `data.current` 做局部恢复；没有 `current` 时先拉最新文档。
 
 ### 6.4 前端落地映射：拿到 `data.result` 之后
@@ -582,7 +588,7 @@ else {
 
 const opId = crypto.randomUUID()              // rebase 是一次新提交，不能复用旧 opId
 const nextBody = {
-  ...rebuildRequestFromCurrentView(),          // 从恢复后的视图重新读整份 groups / path
+  ...rebuildRequestFromCurrentView(),          // 从恢复后的视图重新读整份 groups / path + waypointOffsets
   baseVersion: failure.currentVersion,
   opId
 }
@@ -611,7 +617,7 @@ const nextBody = {
 - **事务边界**：成功应用与幂等记录、版本推进在同一个数据库事务里提交；否则会出现「数据已写但幂等表没写」的重复应用风险。
 - **稳定 id**：所有分组、线路、通道都优先按 id 对账，不要用数组下标当业务主键。客户端生成 id 时，后端要校验唯一性。
 - **空 `path`**：是合法值，表示直连。校验时只检查「是否是数组 + 坐标是否有限」，不要用 truthy 判断吞掉空数组。
-- **响应快照**：分组 / 拐点接口返回落库后的最新 `groups` / `path`；复制返回 `idMap`；合并返回事务实际涉及的 id 集合。
+- **响应快照**：分组 / 拐点接口返回落库后的最新 `groups` / `path` / `waypointOffsets`；复制返回 `idMap`；合并返回事务实际涉及的 id 集合。
 - **审计**：记录 `requestId` / `traceId` / `opId` / `transactionId` / `actor` / 资源 id，日志里不要只记一个 URL。
 - **顺序**：同文档的写请求按版本串行；客户端也应对同一条通道 / 同一份文档做串行化，避免多个成功响应相互覆盖。
 
@@ -622,7 +628,7 @@ const nextBody = {
 | 批量复制与合并 | 框选后复制 | `POST /gis/copies/batch` | `transactionId`、`created`、`counts`、`idMap` |
 | 批量复制与合并 | 拖拽 / 选中后合并 | `POST /gis/merges` | `retainedPointIds`、`removedPointIds`、删线 / 删通道 id |
 | 通道与数据 | 拆 / 并 / 挪回线 / 新建组 | `PATCH /gis/channels/{id}/groups` | `groups` 最新快照、`groupCount`、`lineCount` |
-| 通道与数据 | 通道分组加 / 删 / 拖拐点 | `PATCH /gis/channels/{id}/groups/waypoints` | `target`、`path`、`pointCount` |
+| 通道与数据 | 通道分组加 / 删 / 拖拐点 | `PATCH /gis/channels/{id}/groups/waypoints` | `target`、`path`、`waypointOffsets`、`pointCount` |
 | 通道与数据 | 独立线路拐点 | `PATCH /gis/lines/{id}/path` | `target`、`path`、`pointCount` |
 
 两个演示的面板都提供：正常 200、网络失败、服务端 500、版本冲突 409；“重试最近失败请求”保留原 `opId`，「重放最近成功请求」用于验证幂等回放不推进版本。请求预览区会同时打印请求头、body、HTTP 状态与完整响应包。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gis-view-webgl2",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "WebGL2 矢量视图：点、线与 GeoJSON / 图片背景层，无内置界面，点击 / 双击 / 拖拽可配置",
   "type": "module",
   "scripts": {
@@ -40,4 +40,4 @@
     "vite-plugin-lib-inject-css": "^2.2.2",
     "vue": "^3.5.32"
   }
-}
+}