code-map-visualization

代码地图可视化最佳实践

如何渲染投影并经过地理哈希处理的代码库，并在 2D 地图上直观浏览——让地图真实、快速、清晰、可交互、带动画且易于访问。这是建立在空间结构之上的渲染与感知技艺：它借鉴了数十年来信息可视化、制图学、计算机图形学以及受自然和生物启发的布局知识，让代码地图易于正确解读，并能以交互速率运行。包含 9 个类别中的 47 条规则，按影响力排序。

何时应用

在以下情况下，请参考这些指南：

• 决定将哪种代码属性映射到哪个视觉通道（位置、大小、颜色），以及哪种颜色比例尺能准确表达数据
• 使用 Canvas2D、WebGL 或 deck.gl 在网页上绘制数万至数百万个单元格，并确保渲染循环在帧预算内完成
• 放置并疏理区域和文件标签，并在繁杂的地图上渲染清晰易读的文字
• 实现交互功能——悬停、拾取、选择、相机/视图状态模型、深层链接、键盘控制
• 为相机移动、细节层级转换和数据更新添加动画，同时避免让查看者感到迷失
• 让画布对色觉缺陷者、对动态效果敏感者、仅使用键盘的用户和屏幕阅读器用户都易于访问

范围说明

这项技能属于渲染与感知层。配套技能 geohash-spatial-code-maps 负责空间数学——地理哈希编码、代码到平面的投影、包围盒/覆盖集查询、分块，以及精度与缩放之间的导航模型。此处的规则会交叉引用该技能（例如 map-deterministic-projection、nav-level-of-detail-aggregation），而不是重新推导相关内容。示例以使用 Canvas2D、WebGL/deck.gl 和 d3-scale/d3-color 的 TypeScript 为目标；其中的感知原理可推广到任何渲染技术栈。

按优先级划分的规则类别

优先级	类别	影响	前缀	规则数
1	视觉编码与感知通道	严重	encode-	6
2	颜色与感知型颜色比例尺	严重	color-	5
3	GPU 渲染管线（Canvas2D + WebGL）	高	gpu-	6
4	渲染性能与帧预算	高	perf-	5
5	标签与文本渲染	中高	text-	5
6	交互、拾取与相机	中高	interact-	5
7	动画与过渡	中	anim-	4
8	无障碍与包容性渲染	中	access-	4
9	受自然和细胞启发的布局与渲染	中	bio-	7

快速参考

1. 视觉编码与感知通道（严重）

• encode-rank-channels-by-perceptual-accuracy — 将决策指标映射到位置/长度，而非色相
• encode-let-projection-own-position — 让地理哈希投影决定 x/y；不要重新布局
• encode-size-by-area-not-radius — 将数值映射到面积；半径取其平方根
• encode-separate-categorical-from-quantitative — 用色相表示类别，用有序通道表示大小
• encode-redundant-encoding-for-key-signals — 对少数绝不能遗漏的信号使用双重编码
• encode-maximize-data-ink-drop-chartjunk — 去掉与数据争抢注意力的阴影、斜面和粗重网格

2. 色彩与感知均匀的色阶（关键）

• color-perceptually-uniform-sequential-ramp — 使用 Viridis/OKLCH，绝不使用彩虹色/jet
• color-match-scale-type-to-data — 根据数据选择顺序色阶、发散色阶或分类色阶
• color-design-for-color-vision-deficiency — 使用对色觉缺陷安全的调色板，并通过模拟验证
• color-limit-categorical-hues — 将色相数量限制在约 8–12 种；将长尾类别归为一组
• color-control-contrast-against-basemap — 确保单元格在浅色或深色背景上都清晰可读

3. GPU 渲染管线 — Canvas2D + WebGL（高）

• gpu-layer-canvas2d-over-webgl — 在 GL 中批量绘制单元格，在 Canvas2D 中清晰绘制标签和叠加层
• gpu-instance-cells-not-per-quad-draw — 使用一次实例化绘制调用，而非每个单元格调用一次
• gpu-batch-to-cut-draw-calls-and-state-changes — 按程序/纹理分组，避免管线刷新
• gpu-pack-attributes-into-typed-arrays — 使用可复用的 Float32Array，避免每帧分配内存
• gpu-atlas-tiles-and-glyphs — 只绑定一次图集，通过 UV 偏移寻址
• gpu-size-canvas-to-devicepixelratio — 根据 DPR 设置画布后备缓冲区大小，以获得清晰且无过度绘制的输出

4. 渲染性能与帧预算（高）

• perf-render-in-a-single-raf-loop — 将输入合并为每帧一次重绘
• perf-redraw-only-dirty-regions — 只重绘叠加层，不重绘静态单元格图层
• perf-debounce-viewport-recompute — 限制覆盖集合的重新计算频率；每帧都绘制
• perf-offload-to-worker-and-offscreencanvas — 将繁重的投影和打包操作移出主线程
• perf-bound-the-tile-cache — 使用 LRU 限制瓦片缓存；淘汰时释放 GPU 缓冲区

5. 标签与文本渲染（中高）

• text-place-and-declutter-labels-greedily — 按优先级贪心放置标签，避免碰撞
• text-show-labels-by-level-of-detail — 低缩放级别显示领域标签，仅在文件足够大时显示文件标签
• text-render-glyphs-on-canvas2d-not-per-glyph-textures — 使用原生 fillText，而不是上传 GL 字形纹理
• text-add-halo-for-legibility — 光晕让标签在任何填充背景上都清晰可读
• text-anchor-region-labels-at-centroid — 使用最大内切圆中心，而非边界框中心

6. 交互、拾取与相机（中高）

• interact-pick-with-gpu-color-id-or-spatial-index — 使用 O(1)/O(log n) 拾取，而非线性扫描
• interact-keep-hover-feedback-under-one-frame — 即时高亮叠加层，异步加载详情
• interact-model-the-camera-not-the-dom — 使用单一视图状态对象作为事实来源
• interact-sync-view-state-to-the-url — 支持深层链接和视图分享
• interact-support-keyboard-pan-zoom-and-focus — 使用方向键和 +/- 键控制相机

7. 动画与过渡（中）

• anim-ease-camera-transitions-not-jumps — 平滑移动中心点和缩放，让用户能跟上视图变化
• anim-crossfade-between-lod-levels — 将聚合渐变为点，不要突然切换
• anim-preserve-object-constancy-on-data-update — 按 geohash 标识；只为实际变化添加动画
• anim-keep-transitions-interruptible-and-budgeted — 取消并重新定位正在进行的补间动画

8. 无障碍与包容性渲染（中）

• access-encode-redundantly-never-color-alone — 将颜色与形状或标签搭配使用（WCAG 1.4.1）
• access-honor-prefers-reduced-motion — 为对动态效果敏感的用户简化动画
• access-make-the-map-keyboard-operable — 支持聚焦、显示焦点，且不设键盘陷阱
• access-provide-a-text-alternative-for-the-canvas — 为屏幕阅读器提供同步的 DOM/ARIA 大纲

9. 自然与细胞启发式布局和渲染（中）

用于以自然方式渲染地图的情境化工具箱；其中两种方法是为软件可视化而设计的。

• bio-voronoi-regions-for-space-filling-tessellation — 以投影点为种子的无缝 Voronoi 单元
• bio-relax-weights-for-even-cell-areas — 对权重应用 Lloyd/CVT；保持种子位置不变
• bio-circle-packing-for-nested-counts — 用打包圆表示层级和计数
• bio-phyllotaxis-packing-for-even-point-spread — 用黄金角螺旋实现密集、均匀的填充
• bio-metaball-hulls-for-region-membranes — 用行进正方形算法绘制自然的区域轮廓
• bio-edge-bundling-for-dependency-overlays — 对比 Holten 边捆绑与杂乱的直线连线
• bio-flow-fields-for-animated-dependency-load — 在动态效果表示负载时使用 Physarum/boids 流场

使用方法

阅读各个参考文件，了解详细说明、代码示例以及“何时不应应用”的指导：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

规则通过 [[other-rule-slug]] 相互链接；引用相关模式时，请沿链接阅读。指向 enc-、prec-、dec-、qry-、nbr-、idx-、map- 和 nav- 规则的交叉链接属于配套的 geohash-spatial-code-maps 技能 — 请前往该处阅读空间数学内容。

要端到端构建渲染器，主要步骤是：确定编码方式（类别 1）→ 选择颜色（类别 2）→ 搭建 GPU 管线（类别 3）→ 控制帧预算（类别 4）→ 添加标签、交互、动画和无障碍支持（类别 5–8）；当地图适用时，可采用自然风格的细胞渲染方式 — Voronoi 区域、打包、膜结构、边捆绑（类别 9）。上游投影和分块由 geohash-spatial-code-maps 提供。

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息
AGENTS.md	自动生成的目录导航

相关技能

• geohash-spatial-code-maps — 本工具渲染的空间层：geohash 编码、代码→平面投影、平铺，以及精度↔缩放级别导航模型
• computer-science-algorithms — 支撑快速拾取、避让和渲染循环的空间索引、排序及复杂度基础算法