如何在终端里直接看到图表？Rust绘图库kuva的Braille终端可视化完整指南

kuva 是一款用 Rust 编写的科学绘图库，支持 60 种图表类型。它最有意思的隐藏技能之一，是直接在终端里渲染彩色图表：用 Unicode Braille 盲文点阵画点、画线、画曲线，配合 ANSI 24-bit 真彩色，无需打开浏览器、无需 GUI 环境，SSH 到服务器上敲一条命令，散点图、火山图、热图就直接打印在字符界面里。本文带你从零上手这套 Braille 终端可视化功能。

为什么要在终端里看图表？

大多数绘图工具的输出是 SVG / PNG 文件，你得把文件传回本地再打开。但在这些场景里，这会非常别扭：

• HPC 集群 / 计算节点：登录节点不允许图形界面，数据又不方便下载；
• SSH 远程调试：手头只有终端，想快速看一眼数据分布；
• CI 日志、tmux 分屏：输出直接进日志流，可搜索、可滚动。

kuva 的 --terminal 模式就是为这些场景设计的：不生成文件、不依赖显示系统，只需要一个 UTF-8 终端。

快速上手：一条命令在终端画柱状图

第一步，安装 CLI（已安装可跳过）：

cargo install kuva --features cli

第二步，加 --terminal 参数渲染。以柱状图为例：

kuva bar counts.tsv --label-col gene --value-col count --terminal

执行后，终端里会直接打印出一张带坐标轴、刻度标签和图例的彩色柱状图：

其他常用写法：

# 散点图，按组着色
kuva scatter data.tsv --x x --y y --color-by group --terminal

# 从 stdin 管道读入
cat gwas.tsv | kuva manhattan --chr-col chr --pvalue-col pvalue --terminal

注意 --terminal 与 -o（输出到文件）互斥；两者都不加时默认输出 SVG 到 stdout。

Braille 点阵绘图原理：字符里怎么藏下一个像素点？

每个字符格子内部被划分为 2×4 的盲文点阵，因此终端的有效分辨率是 (列数×2) × (行数×4)。100 列 × 30 行的终端，相当于一个 200×120 的"像素"画布——画散点、折线、等高线绰绰有余。

渲染时分三层叠加，文本优先于点阵：

层	字符	用途
Braille 点阵	U+2800–U+28FF	散点、折线、曲线、等高线
实心方块	█	柱状图/直方图填充、图例色块
文本	ASCII / UTF-8	刻度标签、轴标题、图例文字

坐标轴和刻度则用 Unicode 制表符（─ │ └ ┬ 等）绘制，交叉口通过位掩码自动拼出正确的 T 形、十字形字符。颜色通过 ANSI 24-bit 转义码输出，SVG 里的贝塞尔曲线会先细分为 20 段折线再落笔，填充区域用扫描线奇偶规则填充——所以 Sankey 丝带、弦图圆弧、饼图扇形在终端里也能正确渲染。

这套逻辑的完整实现可以见 src/backend/terminal.rs，CLI 侧的输出分发在 src/bin/kuva/output.rs。

终端渲染参数速查表

参数	默认值	说明
--terminal	关闭	在终端渲染而非输出文件
--term-width N	自动（$COLUMNS，否则 80）	终端宽度（字符列数）
--term-height N	自动（$LINES，否则 24）	终端高度（行数）
--term-bg dark|light	dark	终端背景色，用于自动选择可读的主题配色

几个实用细节：

• 尺寸自动探测：终端尺寸通过 ioctl(TIOCGWINSZ) 探测，失败时回退到 100×30。在 tmux 分屏、CI 日志、管道输出等探测不准的场景，用 --term-width / --term-height 手动指定即可，例如：

  kuva bar counts.tsv --label-col gene --value-col count \
      --terminal --term-width 120 --term-height 40
  

• 主题自动适配：启用 --terminal 时，若未显式指定 --theme，kuva 会按终端背景自动选深色主题，浅色终端可加 --term-bg light。

• 数学标签自动降级：$...$ 包裹的公式（如 $\sigma^2$）会转写成 Unicode（σ²、√、∑）后直接画在字符格上。

8 种常用图表的终端效果一览

除了 upset 子命令外，其余所有图表类型都支持 --terminal。下面挑几个生物/数据科学里最常用的：

火山图——差异表达分析一眼定位显著基因：

热图——█ 色块 + 真彩色让基因表达矩阵在终端依然清晰可读：

曼哈顿图——GWAS 结果按染色体分色，峰值基因一眼可见：

直方图——数据分布的快速体检：

其余已支持的子命令还包括：scatter、line、bar、box、violin、strip、pie、waterfall、stacked-area、candlestick、sankey、chord、dot、hist2d、contour、phylo、synteny、network、polar、ternary、quiver 等（完整清单见 docs/src/cli/terminal.md）。

以 K 线图为例，金融时序数据也能直接进终端：

进阶技巧：批量预览与脚本化

仓库自带了一个演示脚本，把所有 CLI 图表类型逐一渲染到终端，适合上手体验：

bash scripts/terminal_plots.sh                 # 开发构建，自动探测尺寸
bash scripts/terminal_plots.sh - 120 40        # 固定 120×40

脚本内容见 scripts/terminal_plots.sh，示例数据都在 examples/data/ 目录下（TSV/CSV 自动识别，列名或 0 基索引均可指定）。

日常调试时的推荐组合：

# 先管道快速看一眼，满意后再导出 SVG
cat samples.tsv | kuva box --group-col group --value-col expression --terminal

# 需要留档时切换回文件输出（去掉 --terminal 即可）
kuva box samples.tsv --group-col group --value-col expression -o box.svg

终端模式 vs 文件输出：怎么选？

场景	推荐方式	原因
远程调试、HPC 登录节点	--terminal	零文件传输，秒级反馈
论文/报告配图	-o figure.svg	矢量输出，可无损缩放
CI 日志归档	--terminal --term-width 120	纯文本可检索、可 diff
本地精调样式	-o figure.png	像素级检查配色与布局

两种模式共用同一套场景（Scene）渲染管线，图表布局、配色、主题完全一致，只是最后一步的"打印机"不同——这也是为什么终端里的图和导出的 SVG 长得很像。

总结

• 一个 --terminal 参数，即可让 Rust 绘图库 kuva 的 60 种图表直接在终端里"现形"；
• 底层用 2×4 Braille 盲文点阵 + █ 色块 + ANSI 24-bit 彩色，分辨率、配色远超传统 ASCII 图表；
• 用 --term-width / --term-height 适配 tmux 与 CI，用 --term-bg 适配浅色终端；
• 除了 SVG/PNG/PDF 文件输出，终端模式是查看数据最轻量的"第三条路"。

更多终端模式细节参见官方文档 docs/src/cli/terminal.md。