gis-view-webgl2 0.1.11 → 0.1.13

package/docs/steps/selftest-perf.html

@@ -663,7 +663,7 @@
 				for (let index = 0; index < anchorLines.length; index += 1) {
 					anchorLines[index] = { id: `ax${index}`, start: [anchorRandom() * 4000, anchorRandom() * 2500], end: [anchorRandom() * 4000, anchorRandom() * 2500], name: `长线 ${index}` }
 				}
-				const anchorView = createGisView(anchorHost, { points: anchorPoints, lines: anchorLines, width: 900, height: 560, label: { content: '{name}', maxCount: 200 }, lineLabel: { maxCount: 60 } })
+				const anchorView = createGisView(anchorHost, { points: anchorPoints, lines: anchorLines, width: 900, height: 560, progressiveInit: false, labelOptimize: true, label: { content: '{name}', maxCount: 200 }, lineLabel: { maxCount: 60 } })
 				await sleep(200)
 				for (let step = 0; step < 6; step += 1) {
 					anchorView.setCamera({ center: [1000 + step * 120, 700 + step * 60], scale: 1.4 })
@@ -673,15 +673,28 @@
 				// 程序化相机运动还有 160ms 的轻量画法窗口，停稳后会补一张全质量帧并再收一次候选。
 				// 先让这一帧落地，再开始计量，后面测到的才是稳态重排，而不是收尾那一帧的噪声。
 				await sleep(800)
+				// 四万点 + 四万线的发散渲染可能比上面那一段更慢：没铺完时 refreshLabels 会主动等下一帧，
+				// 这时六轮 updateOptions 的读数都是 0，随后 updatePoint 正好撞上第一次真实排版，
+				// 会把整屏标签都算成「第一次出现」。先等到 isLayoutReady 再做稳态断言。
+				const anchorReadyDeadline = now() + 8000
+				while (!anchorView.isLayoutReady() && now() < anchorReadyDeadline) {
+					await sleep(16)
+				}
+				await new Promise(resolve => requestAnimationFrame(() => resolve()))
+				// 字体加载完成会推进 labelFontEpoch，让所有标签尺寸缓存按新字体重量一次。
+				// 这是真实且必要的一次失效，不能算进「稳态重排」；先等字体集合稳定，避免冷启动把
+				// 最后一轮定向更新的读数抬成整屏标签数。
+				await document.fonts?.ready
+				await sleep(50)
 				const anchorStats = { reads: 0, duplicates: 0 }
-				const anchorSeen = new Set()
-				const anchorReads = []
-				const anchorDuplicates = []
-				const nativeAnchorRect = Element.prototype.getBoundingClientRect
-				Element.prototype.getBoundingClientRect = function (...args) {
-					if (this.classList?.contains('gis-view__label')) {
-						anchorStats.reads += 1
-						// 按标签身份（类型 + 行号 + 标签名）去重：标签节点是循环复用的，按节点去重会把「同一格换了条标签」误判成重复量
+				const anchorSeen = new Set()
+				const anchorReads = []
+				const anchorDuplicates = []
+				const nativeAnchorRect = Element.prototype.getBoundingClientRect
+				Element.prototype.getBoundingClientRect = function (...args) {
+					if (this.classList?.contains('gis-view__label')) {
+						anchorStats.reads += 1
+						// 按标签身份（类型 + 行号 + 标签名）去重：标签节点是循环复用的，按节点去重会把「同一格换了条标签」误判成重复量
 						const anchorKey = `${this.dataset.labelKind}#${this.dataset.labelIndex}#${this.dataset.labelLabel}`
 						if (anchorSeen.has(anchorKey)) {
 							anchorStats.duplicates += 1
@@ -690,11 +703,11 @@
 					}
 					return nativeAnchorRect.apply(this, args)
 				}
-				const anchorRound = () => {
-					anchorStats.reads = 0
-					anchorStats.duplicates = 0
-					anchorSeen.clear()
-				}
+				const anchorRound = () => {
+					anchorStats.reads = 0
+					anchorStats.duplicates = 0
+					anchorSeen.clear()
+				}
 				try {
 					// 跑 6 轮：换锚点（anchorFallback）/ 沿线滑动（slideFallback）会让某一轮补画几十条
 					// 从没出现过的标签 —— 第一次出现必须量一次尺寸，这一笔有限、下一轮起回零；
@@ -702,8 +715,8 @@
 					for (let round = 0; round < 6; round += 1) {
 						anchorRound()
 						anchorView.updateOptions({ label: { content: '{name}', maxCount: 200 }, lineLabel: { maxCount: 60 } })
-						anchorReads.push(anchorStats.reads)
-						anchorDuplicates.push(anchorStats.duplicates)
+						anchorReads.push(anchorStats.reads)
+						anchorDuplicates.push(anchorStats.duplicates)
 					}
 					// 改一条视口里的标签（下标 = 76 行 × 400 列 + 150 → 世界坐标 1500, 760）：这一轮同样不该整层重量
 					anchorRound()
@@ -714,13 +727,13 @@
 				finally {
 					Element.prototype.getBoundingClientRect = nativeAnchorRect
 				}
- diag('放大后连续整层重排 · 标签量测读数', `逐轮 ${anchorReads.join(' / ')} 次 · 同一轮里重复量 ${anchorDuplicates.join(' / ')} 条（按标签身份去重；旧写法第 1 轮 2662 次里有 1235 次是把同一条标签又量了一遍）`)
+ diag('放大后连续整层重排 · 标签量测读数', `逐轮 ${anchorReads.join(' / ')} 次 · 同一轮里重复量 ${anchorDuplicates.join(' / ')} 条（按标签身份去重；旧写法第 1 轮 2662 次里有 1235 次是把同一条标签又量了一遍）`)
 				check('稳态重排（后 3 轮）一次布局都不读（避让盒全走算术）', anchorReads.slice(3, 6).every(value => value === 0), `第 4~6 轮 ${anchorReads.slice(3, 6).join(' / ')} 次`)
 				// 换落点那条路补画的新标签都是「第一次出现」，各量一次尺寸就进缓存；整段合计要有限，
 				// 真退回「每轮把所有标签都真量一遍」的老写法时这里会立刻爆掉（旧写法一轮 1299 ~ 2662 次）
 				check('稳态重排里补画的新标签只量第一次出现的那一次（合计有限、之后回零）', anchorReads.slice(1, 6).reduce((sum, value) => sum + value, 0) <= 400, `第 2~6 轮合计 ${anchorReads.slice(1, 6).reduce((sum, value) => sum + value, 0)} 次（逐轮 ${anchorReads.slice(1, 6).join(' / ')}）`)
  check('整层重排里没有哪条标签（按身份）被量第二次（避让盒不再退回真量一次）', anchorDuplicates.every(value => value === 0), `逐轮重复 ${anchorDuplicates.join(' / ')} 条`)
- check('改一条可见标签之后的定向重排也不读布局、不重复量', anchorDuplicates[6] === 0 && anchorReads[6] === 0, `读数 ${anchorReads[6]} 次 · 重复 ${anchorDuplicates[6]} 条`)
+ check('改一条可见标签之后的定向重排也不读布局、不重复量', anchorDuplicates[6] === 0 && anchorReads[6] === 0, `读数 ${anchorReads[6]} 次 · 重复 ${anchorDuplicates[6]} 条`)
 				anchorView.destroy()
 				anchorHost.remove()
 				labelView.destroy()
@@ -1447,10 +1460,225 @@
 				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()
+				diag('热力图密度场更新', `纯透明度 ${opacityUpdateMs.toFixed(2)} ms / 换色带 ${colorUpdateMs.toFixed(2)} ms；烘焙 ${densityAfterColor.ms.toFixed(1)} ms`)
+				densityView.destroy()
+				densityHost.remove()
+
+				/* 密度场不能复用背景图片的四边形：图片之外的要素也必须按自己的世界范围铺场 */
+				const densityBackgroundHost = document.createElement('div')
+				densityBackgroundHost.style.cssText = 'width:640px;height:380px'
+				document.body.append(densityBackgroundHost)
+				const densityBackgroundSvg = `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="8" height="8"><rect width="8" height="8" fill="#ffffff"/></svg>')}`
+				const densityBackgroundView = createGisView(densityBackgroundHost, {
+					points: [
+						{ id: 'dbg-a', x: 400, y: 200, value: 100 },
+						{ id: 'dbg-b', x: 460, y: 200, value: 100 }
+					],
+					lines: [],
+					pointStyle: { opacity: 0 },
+					heatmap: {
+						enabled: true,
+						target: 'point',
+						field: 'value',
+						domain: [0, 100],
+						colors: ['#ff0000', '#ff0000'],
+						opacity: 1,
+						glow: false,
+						density: { style: 'smooth', resolution: 96, radiusRatio: 0.12, threshold: 0, opacity: 1 }
+					},
+					background: { color: '#000000', image: { src: densityBackgroundSvg, bounds: [0, 0, 80, 80] } },
+					width: 640,
+					height: 380,
+					quality: 'high',
+					showGrid: false
+				})
+				densityBackgroundView.setCamera({ center: [430, 200], scale: 1 })
+				await densityBackgroundView.whenRendered()
+				// 等背景图片解码完成后再显式补一帧；静止画面不会自己继续画，不能先 sleep 再等 whenRendered
+				await sleep(300)
+				densityBackgroundView.refresh()
+				await densityBackgroundView.whenRendered()
+				const densityBackgroundCanvas = densityBackgroundHost.querySelector('canvas')
+				const densityBackgroundGl = densityBackgroundCanvas.getContext('webgl2')
+				const densityBackgroundPixels = new Uint8Array(densityBackgroundCanvas.width * densityBackgroundCanvas.height * 4)
+				densityBackgroundGl.readPixels(0, 0, densityBackgroundCanvas.width, densityBackgroundCanvas.height, densityBackgroundGl.RGBA, densityBackgroundGl.UNSIGNED_BYTE, densityBackgroundPixels)
+				let densityBackgroundWarm = 0
+				for (let index = 0; index < densityBackgroundPixels.length; index += 4) {
+					const red = densityBackgroundPixels[index]
+					if (red > 20 && red > Math.max(densityBackgroundPixels[index + 1], densityBackgroundPixels[index + 2]) + 5) {
+						densityBackgroundWarm += 1
+					}
+				}
+				check('热力图密度场：有图片背景时仍按数据范围铺场，图片范围外不漏画',
+					Boolean(densityBackgroundView.snapshotScene().backgroundImage) && densityBackgroundWarm > 20 && densityBackgroundView.getStats().heatDensity?.samples > 0,
+					JSON.stringify({ warm: densityBackgroundWarm, density: densityBackgroundView.getStats().heatDensity, image: Boolean(densityBackgroundView.snapshotScene().backgroundImage) }))
+				densityBackgroundView.destroy()
+				densityBackgroundHost.remove()
+
+				/* 热力交互帧：线路光晕不消失，且合并成一笔绘制（不再退回「无光晕 + 细线」） */
+				const heatMotionHost = document.createElement('div')
+				heatMotionHost.style.cssText = 'width:640px;height:380px'
+				document.body.append(heatMotionHost)
+				heatMotionHost.scrollIntoView({ block: 'center', inline: 'nearest' })
+				const heatMotionPoints = Array.from({ length: 12 }, (unused, index) => ({
+					id: `hm-p${index}`,
+					x: (index % 4) * 80,
+					y: Math.floor(index / 4) * 90
+				}))
+				const heatMotionLines = Array.from({ length: 18 }, (unused, index) => ({
+					id: `hm-l${index}`,
+					from: heatMotionPoints[index % heatMotionPoints.length].id,
+					to: heatMotionPoints[(index * 5 + 3) % heatMotionPoints.length].id,
+					value: 30 + (index % 5) * 15
+				}))
+				const heatMotionGlow = { strength: 1, size: [20, 3], blend: 'normal' }
+				const heatMotionHeatmap = {
+					enabled: true,
+					target: 'line',
+					field: 'value',
+					domain: [0, 100],
+					colors: ['#ff2d2d', '#ff2d2d'],
+					opacity: 1,
+					density: false,
+					glow: heatMotionGlow
+				}
+				const heatMotionView = createGisView(heatMotionHost, {
+					points: heatMotionPoints,
+					lines: heatMotionLines,
+					lineStyle: { width: 1, opacity: 1 },
+					heatmap: heatMotionHeatmap,
+					background: '#05070b',
+					width: 640,
+					height: 380,
+					quality: 'high',
+					interactionNoMsaa: false,
+					showGrid: false
+				})
+				await heatMotionView.whenRendered()
+				await sleep(80)
+				const heatMotionCanvas = heatMotionHost.querySelector('canvas')
+				const heatMotionGl = heatMotionCanvas.getContext('webgl2')
+				const readHeatMotionPixels = () => {
+					const pixels = new Uint8Array(heatMotionCanvas.width * heatMotionCanvas.height * 4)
+					heatMotionGl.readPixels(0, 0, heatMotionCanvas.width, heatMotionCanvas.height, heatMotionGl.RGBA, heatMotionGl.UNSIGNED_BYTE, pixels)
+					return pixels
+				}
+				const summarizeHeatMotionPixels = (pixels) => {
+					let warm = 0
+					let intensity = 0
+					for (let index = 0; index < pixels.length; index += 4) {
+						const red = pixels[index]
+						const green = pixels[index + 1]
+						const blue = pixels[index + 2]
+						const redness = Math.max(0, red - Math.max(green, blue))
+						intensity += redness
+						if (red > 10 && redness > 3) {
+							warm += 1
+						}
+					}
+					return { warm, intensity }
+				}
+				const readHeatMotionWarmPixels = () => summarizeHeatMotionPixels(readHeatMotionPixels())
+				const heatMotionPointById = new Map(heatMotionPoints.map(point => [point.id, point]))
+				const heatMotionMidpoints = heatMotionLines.map((line) => {
+					const from = heatMotionPointById.get(line.from)
+					const to = heatMotionPointById.get(line.to)
+					return [(from.x + to.x) / 2, (from.y + to.y) / 2]
+				})
+				const heatMotionWarmAt = (pixels, screen) => {
+					if (!screen) {
+						return false
+					}
+					const scaleX = heatMotionCanvas.width / Math.max(heatMotionHost.clientWidth, 1)
+					const scaleY = heatMotionCanvas.height / Math.max(heatMotionHost.clientHeight, 1)
+					const centerX = Math.round(screen[0] * scaleX)
+					const centerY = Math.round((heatMotionHost.clientHeight - screen[1]) * scaleY)
+					for (let offsetY = -5; offsetY <= 5; offsetY += 1) {
+						const y = centerY + offsetY
+						if (y < 0 || y >= heatMotionCanvas.height) {
+							continue
+						}
+						for (let offsetX = -5; offsetX <= 5; offsetX += 1) {
+							const x = centerX + offsetX
+							if (x < 0 || x >= heatMotionCanvas.width) {
+								continue
+							}
+							const index = (y * heatMotionCanvas.width + x) * 4
+							const red = pixels[index]
+							if (red > 8 && red > Math.max(pixels[index + 1], pixels[index + 2]) + 2) {
+								return true
+							}
+						}
+					}
+					return false
+				}
+				const heatMotionMissingLines = pixels => heatMotionMidpoints
+					.map((midpoint, index) => (heatMotionWarmAt(pixels, heatMotionView.project(midpoint[0], midpoint[1])) ? null : index))
+					.filter(index => index !== null)
+				const heatMotionStart = heatMotionView.getCamera()
+				heatMotionView.setCamera({ center: [heatMotionStart.center[0] + 2, heatMotionStart.center[1] + 1], scale: heatMotionStart.scale * 1.15 })
+				await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+				heatMotionView.refresh({ reflow: false })
+				const heatMotionMovingPixels = readHeatMotionPixels()
+				const heatMotionMovingWarm = summarizeHeatMotionPixels(heatMotionMovingPixels)
+				const heatMotionMovingStats = heatMotionView.getStats()
+				const heatMotionMovingMissing = heatMotionMissingLines(heatMotionMovingPixels)
+				await sleep(360)
+				heatMotionView.refresh({ reflow: false })
+				const heatMotionStaticPixels = readHeatMotionPixels()
+				const heatMotionStaticWarm = summarizeHeatMotionPixels(heatMotionStaticPixels)
+				const heatMotionStaticStats = heatMotionView.getStats()
+				const heatMotionStaticMissing = heatMotionMissingLines(heatMotionStaticPixels)
+				check('热力图交互帧：逐条线路在相机运动与停稳帧都有热力（不是只统计整屏暖色）',
+					heatMotionMovingMissing.length === 0 && heatMotionStaticMissing.length === 0,
+					`运动缺失 ${heatMotionMovingMissing.join(',') || '无'} / 停稳缺失 ${heatMotionStaticMissing.join(',') || '无'}`)
+				check('热力图交互帧：相机运动时线路光晕仍在（暖色像素与停稳帧相当）',
+					heatMotionStaticWarm.warm > 0 && heatMotionMovingWarm.warm > 0 && heatMotionMovingWarm.warm / heatMotionStaticWarm.warm > 0.55 && heatMotionMovingWarm.warm / heatMotionStaticWarm.warm < 1.8 && heatMotionMovingWarm.intensity / heatMotionStaticWarm.intensity > 0.65 && heatMotionMovingWarm.intensity / heatMotionStaticWarm.intensity < 1.5,
+					`停稳 ${heatMotionStaticWarm.warm} 像素 / 强度 ${heatMotionStaticWarm.intensity}；运动 ${heatMotionMovingWarm.warm} 像素 / 强度 ${heatMotionMovingWarm.intensity}`)
+				check('热力图交互帧：合并管线接管线路绘制，不再走会丢光晕的细线快路径，也不多出绘制批次',
+					heatMotionMovingStats.thinLines === false && heatMotionMovingStats.drawCalls <= heatMotionStaticStats.drawCalls,
+					`thinLines=${heatMotionMovingStats.thinLines} drawCalls ${heatMotionStaticStats.drawCalls} -> ${heatMotionMovingStats.drawCalls}`)
+				heatMotionView.updateOptions({ heatmap: { ...heatMotionHeatmap, glow: false } })
+				await sleep(40)
+				heatMotionView.refresh({ reflow: false })
+				const heatMotionNoGlowWarm = readHeatMotionWarmPixels()
+				check('热力图交互帧：关掉光晕后暖色覆盖明显收窄（像素断言确实量到光晕）',
+					heatMotionNoGlowWarm.warm > 0 && heatMotionNoGlowWarm.warm < heatMotionStaticWarm.warm * 0.8 && heatMotionNoGlowWarm.intensity < heatMotionStaticWarm.intensity * 0.8,
+					`有光晕 ${heatMotionStaticWarm.warm} 像素 / 强度 ${heatMotionStaticWarm.intensity}；无光晕 ${heatMotionNoGlowWarm.warm} 像素 / 强度 ${heatMotionNoGlowWarm.intensity}`)
+				const heatMotionNoGlowStart = heatMotionView.getCamera()
+				heatMotionView.setCamera({ center: [heatMotionNoGlowStart.center[0] + 2, heatMotionNoGlowStart.center[1] - 1], scale: heatMotionNoGlowStart.scale * 1.02 })
+				await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+				heatMotionView.refresh({ reflow: false })
+				const heatMotionNoGlowMovingWarm = readHeatMotionWarmPixels()
+				const heatMotionNoGlowMovingStats = heatMotionView.getStats()
+				check('热力图交互帧：关光晕时细线快路径照常生效（说明上面确实走的是合并分支）',
+					heatMotionNoGlowMovingStats.thinLines === true,
+					`thinLines=${heatMotionNoGlowMovingStats.thinLines}`)
+				// 深底色最常用的加法混合也走合并管线：glow.blend 一变，混合状态与预乘输出要同时切过去
+				heatMotionView.updateOptions({ heatmap: { ...heatMotionHeatmap, glow: { ...heatMotionGlow, blend: 'add' } } })
+				await sleep(360)
+				heatMotionView.refresh({ reflow: false })
+				const heatMotionAddStaticPixels = readHeatMotionPixels()
+				const heatMotionAddStaticWarm = summarizeHeatMotionPixels(heatMotionAddStaticPixels)
+				const heatMotionAddStart = heatMotionView.getCamera()
+				heatMotionView.setCamera({ center: [heatMotionAddStart.center[0] - 2, heatMotionAddStart.center[1] + 1], scale: heatMotionAddStart.scale * 1.02 })
+				await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))
+				heatMotionView.refresh({ reflow: false })
+				const heatMotionAddMovingPixels = readHeatMotionPixels()
+				const heatMotionAddMovingWarm = summarizeHeatMotionPixels(heatMotionAddMovingPixels)
+				const heatMotionAddMovingStats = heatMotionView.getStats()
+				const heatMotionAddStaticMissing = heatMotionMissingLines(heatMotionAddStaticPixels)
+				const heatMotionAddMovingMissing = heatMotionMissingLines(heatMotionAddMovingPixels)
+				check('热力图交互帧：配置加法混合时仍走两遍光晕管线，逐条线路在停稳与运动帧都不缺失',
+					heatMotionAddStaticWarm.warm > 0 && heatMotionAddMovingWarm.warm > 0 &&
+					heatMotionAddStaticMissing.length === 0 && heatMotionAddMovingMissing.length === 0 &&
+					heatMotionAddMovingStats.thinLines === false,
+					`停稳缺失 ${heatMotionAddStaticMissing.join(',') || '无'} / 运动缺失 ${heatMotionAddMovingMissing.join(',') || '无'}；停稳 ${heatMotionAddStaticWarm.warm} 像素，运动 ${heatMotionAddMovingWarm.warm} 像素；thinLines=${heatMotionAddMovingStats.thinLines}`)
+				await sleep(360)
+				heatMotionView.destroy()
+				heatMotionHost.remove()
+
+				heatFreshView.destroy()
 				heatFreshHost.remove()
 				heatView.destroy()
 				heatHost.remove()
@@ -2448,9 +2676,52 @@
 				check('同一批点线回灌：换通道骨架时线路那一半不能沿用旧几何',
 					JSON.stringify(guardChanged?.lines?.map(line => line.waypoints)) !== JSON.stringify(guardAfter?.lines?.map(line => line.waypoints)),
 					JSON.stringify({ before: guardAfter?.lines?.map(line => line.waypoints), after: guardChanged?.lines?.map(line => line.waypoints) }))
-				big.updateOptions({ channels: [] })
-
-				thinView.destroy()
+				big.updateOptions({ channels: [] })
+
+				/* ---------------- visualMap：图例更新快路径 / 同签名零 DOM 写入 / 自动值域 ---------------- */
+				const visualPerfPointCount = 12000
+				const visualPerfPoints = new Array(visualPerfPointCount)
+				for (let index = 0; index < visualPerfPointCount; index += 1) {
+					visualPerfPoints[index] = { id: `vp${index}`, x: (index % 120) * 12, y: Math.floor(index / 120) * 12, value: index % 1000 }
+				}
+				const visualPerfHost = document.createElement('div')
+				visualPerfHost.style.cssText = 'width:640px;height:380px'
+				document.querySelector('#map').append(visualPerfHost)
+				const visualPerfView = createGisView(visualPerfHost, {
+					points: visualPerfPoints,
+					heatmap: { field: 'value', target: 'point', density: false, glow: false, opacity: 1 },
+					visualMap: { target: 'point', title: '性能图例', unit: 'kW', tickCount: 5 },
+					width: 640,
+					height: 380,
+					quality: 'high',
+					showGrid: false
+				})
+				await visualPerfView.whenRendered()
+				await sleep(40)
+				const visualPerfDomain = visualPerfView.getVisualMap()?.domain
+				check('visualMap：一万二千点按当前数据自动取值域', visualPerfDomain?.[0] === 0 && visualPerfDomain?.[1] === 999, JSON.stringify(visualPerfDomain))
+				const visualPerfElement = visualPerfView.getVisualMapElement()
+				let visualPerfMutations = 0
+				const visualPerfObserver = new MutationObserver(records => { visualPerfMutations += records.length })
+				visualPerfObserver.observe(visualPerfElement, { subtree: true, childList: true, attributes: true, characterData: true })
+				const visualPerfPatch = { target: 'point', title: '性能图例', unit: 'kW', tickCount: 5 }
+				const visualPerfStarted = now()
+				for (let round = 0; round < 50; round += 1) {
+					visualPerfView.updateOptions({ visualMap: { ...visualPerfPatch } })
+				}
+				const visualPerfSyncMs = (now() - visualPerfStarted) / 50
+				await sleep(80)
+				visualPerfObserver.disconnect()
+				check('visualMap：50 次同签名更新只合帧一次，DOM 写入为 0', visualPerfMutations === 0, `${visualPerfMutations} 条 mutation`)
+				diag('visualMap：只改图例的同步开销（1.2 万点热力图）', `${visualPerfSyncMs.toFixed(4)} ms / 次（50 次）`)
+				visualPerfView.updatePoint('vp9999', { value: 5000 })
+				const visualPerfUpdatedDomain = visualPerfView.getVisualMap()?.domain
+				check('visualMap：定向改数据后自动值域跟着当前数据走', visualPerfUpdatedDomain?.[1] === 5000, JSON.stringify(visualPerfUpdatedDomain))
+				visualPerfView.updateOptions({ visualMap: null })
+				visualPerfView.destroy()
+				visualPerfHost.remove()
+
+				thinView.destroy()
 				thinHost.remove()
 				big.destroy()
 				bigHost.remove()

package/docs/steps/selftest-scale.html

@@ -907,16 +907,60 @@
 				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))
+				const exactSpacingView = createGisView(host(640, 320), {
+					points: [{ id: 'e0', x: 0, y: 0, size: 10 }, { id: 'e1', x: 60, y: 0, size: 10 }],
+					fitSpacing: { minDistance: 24, maxZoom: 0 },
+					showGrid: false
+				})
+				await settle(100)
+				const exactGap = (() => {
+					const first = exactSpacingView.project(0, 0)
+					const second = exactSpacingView.project(60, 0)
+					return Math.hypot(second[0] - first[0], second[1] - first[1])
+				})()
+				check('适应节点间距：普通适应得到的间距更大时也会缩到指定 minDistance', Math.abs(exactGap - 24) < 0.1, JSON.stringify({ scale: exactSpacingView.getScale(), gap: exactGap }))
+				exactSpacingView.updateOptions({ fitSpacing: { minDistance: 12, maxZoom: 2 } })
+				exactSpacingView.fitView()
+				await settle(40)
+				const exactSmallGap = (() => {
+					const first = exactSpacingView.project(0, 0)
+					const second = exactSpacingView.project(60, 0)
+					return Math.hypot(second[0] - first[0], second[1] - first[1])
+				})()
+				check('适应节点间距：改小 minDistance 会实际缩小比例，maxZoom 不再截断', Math.abs(exactSmallGap - 12) < 0.1, JSON.stringify({ scale: exactSpacingView.getScale(), gap: exactSmallGap }))
+				exactSpacingView.destroy()
 				spacingView.updateOptions({ fitSpacing: { minDistance: 24, maxZoom: 2 } })
 				spacingView.fitView()
 				await settle(60)
-				const spacingCapped = spacingView.getCamera().scale
-				check('适应节点间距：maxZoom 限制相对普通适应比例的上限', Math.abs(spacingCapped - plainFit * 2) < 1e-6, `${plainFit} → ${spacingCapped}`)
+				const spacingMaxZoomIgnored = spacingView.getCamera().scale
+				check('适应节点间距：maxZoom 兼容保留，不截断精确的 minDistance', Math.abs(spacingMaxZoomIgnored - spacingFit) < 1e-9, `${spacingFit} → ${spacingMaxZoomIgnored}`)
 				spacingView.updateOptions({ fitSpacing: false })
 				spacingView.fitView()
 				await settle(60)
 				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)}`)
+				check('适应节点间距：关闭后恢复普通适应比例与包围盒中心', Math.abs(spacingOff.scale - plainFit) < 1e-9 && Math.abs(spacingOff.center[0] - 5000) < 0.5, `${spacingMaxZoomIgnored} → ${spacingOff.scale} / ${JSON.stringify(spacingOff.center)}`)
+				const selectedSpacing = fitSpacingBaseView.getPointsSpacing(['f1', { index: 3 }, 'f1'])
+				const selectedSpacingPx = 140 * spacingScale
+				check('getPointsSpacing：只算指定节点，引用去重并按当前比例返回 CSS 像素',
+					selectedSpacing.count === 2 && Math.abs(selectedSpacing.minDistance - selectedSpacingPx) < 1e-6 && Math.abs(selectedSpacing.maxDistance - selectedSpacingPx) < 1e-6 && selectedSpacing.nearest?.from.id === 'f1' && selectedSpacing.nearest?.to.id === 'f2',
+					JSON.stringify(selectedSpacing))
+				const emptySpacing = fitSpacingBaseView.getPointsSpacing([])
+				const singleSpacing = fitSpacingBaseView.getPointsSpacing('f1')
+				check('getPointsSpacing：空引用与单节点返回稳定空读数', emptySpacing.count === 0 && emptySpacing.minDistance === null && emptySpacing.maxDistance === null && singleSpacing.count === 1 && singleSpacing.minDistance === null && singleSpacing.maxDistance === null,
+					JSON.stringify({ emptySpacing, singleSpacing }))
+				const hiddenGroupSpacingView = createGisView(host(640, 320), {
+					points: [{ id: 'h0', x: 0, y: 0, size: 10 }, { id: 'h1', x: 40, y: 0, size: 10 }],
+					showGrid: false
+				})
+				await settle(100)
+				hiddenGroupSpacingView.hideFeatures('point', 'h1')
+				await settle(40)
+				const hiddenVisibleSpacing = hiddenGroupSpacingView.getPointSpacing()
+				const hiddenGroupSpacing = hiddenGroupSpacingView.getPointsSpacing(['h0', 'h1'])
+				check('getPointsSpacing：显式传入的隐藏节点仍参与统计（与 getPointSpacing 的可见集合分开）',
+					hiddenVisibleSpacing.count === 1 && hiddenGroupSpacing.count === 2 && Math.abs(hiddenGroupSpacing.minDistance - 40 * hiddenGroupSpacingView.getScale()) < 1e-6,
+					JSON.stringify({ visible: hiddenVisibleSpacing.count, group: hiddenGroupSpacing }))
+				hiddenGroupSpacingView.destroy()
 				/* maxDistance 反过来压住稀疏数据：最远节点在屏幕上不超过给定像素，避免少量场站回显时整幅放大 */
 				const sparseSpacingView = createGisView(host(640, 320), {
 					points: [{ id: 's0', x: 0, y: 0, size: 10 }, { id: 's1', x: 100, y: 0, size: 10 }, { id: 's2', x: 0, y: 80, size: 10 }],
@@ -958,6 +1002,20 @@
 					Math.abs(gridCenter[0] - 5000) <= 0.5 && Math.abs(gridCenter[1] - 5000) <= 0.5,
 					JSON.stringify(gridCenter))
 				gridSpacingView.destroy()
+				/* 默认 maxScale 不能提前截断 minDistance：经纬度这类小量纲数据需要的比例会超过旧缺省 20000 */
+				const fineSpacingView = createGisView(host(640, 320), {
+					points: [{ id: 'fine0', x: 0, y: 0, size: 10 }, { id: 'fine1', x: 0.01, y: 0, size: 10 }],
+					fitSpacing: { minDistance: 1000 },
+					showGrid: false
+				})
+				await settle(140)
+				const fineScreen0 = fineSpacingView.project(0, 0)
+				const fineScreen1 = fineSpacingView.project(0.01, 0)
+				const fineGap = Math.hypot(fineScreen1[0] - fineScreen0[0], fineScreen1[1] - fineScreen0[1])
+				check('适应节点间距：默认 maxScale 不再把 minDistance 截在旧上限，目标 1000px 能落到位',
+					fineSpacingView.getScale() > 20000 && Math.abs(fineGap - 1000) < 0.2,
+					JSON.stringify({ scale: fineSpacingView.getScale(), gap: fineGap }))
+				fineSpacingView.destroy()
 				fitSpacingBaseView.destroy()
 				spacingView.destroy()
 			}