Rust科学绘图库kuva完全指南：60种图表类型、从SVG到终端，一站式可视化解决方案

kuva 是一款用 Rust 编写的科学绘图库（scientific plotting library），内置 60 种图表类型，覆盖散点图、曼哈顿图、系统发育树、桑基图等，输出 SVG，可选 PNG/PDF 后端，还能通过 --terminal 参数把图表直接渲染到终端。无论是生物信息学分析、统计可视化还是命令行场景，kuva 都是一站式解决方案。

🎯 一、kuva 是什么？为什么值得尝试？

kuva 定位为面向科学计算与生物信息学的高性能 Rust 绘图库，核心卖点一句话概括：

特性	说明
60 种图表	从基础散点/折线/柱状图到 Manhattan、UpSet、Synteny、3D 曲面
多种输出	SVG（默认）、PNG、PDF，外加终端 Braille 渲染
双入口	Rust API（builder 模式）+ kuva 命令行工具，无需写代码出图
自动布局	边距、刻度、坐标范围全部由数据自动推导，无需手摆位置
性能优秀	100 万点散点约 0.4 秒，100 万 SNP 的 GWAS 曼哈顿图约 0.5 秒

其渲染流水线为：plot struct → Plot enum → Layout → SVG / PNG / PDF / 终端，架构细节见 ARCHITECTURE.md。对新手来说最关键的一点：所有绘图共享同一套布局与主题系统，你学一次 API，60 种图都会画。

🚀 二、三步上手：安装与第一张图

1. 安装 Rust 工具链

如果还没有 cargo，先安装 rustup：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

2. 安装 kuva

# 从 crates.io 安装 CLI（SVG 输出）
cargo install kuva --features cli

# 附带 PNG + PDF 输出
cargo install kuva --features cli,full

也支持从源码安装：

git clone https://gitcode.com/gh_mirrors/ku/kuva && cd kuva
cargo install --path . --features cli,full

3. 一行命令出图

输入文件支持 TSV/CSV 自动检测，列可按名字或 0 起始索引选择：

# 散点图输出 SVG
kuva scatter data.tsv --x x --y y -o plot.svg

# 火山图，标注前 20 个基因
kuva volcano gene_stats.tsv --name-col gene --x-col log2fc --y-col pvalue --top-n 20

# 箱线图直接画在终端里！
kuva box samples.tsv --group-col group --value-col expression --terminal

仓库里现成的示例数据都在 examples/data/ 下，比如 examples/data/scatter.tsv、examples/data/volcano.tsv，可直接拿来练手。

📊 三、60 种图表类型速览：覆盖从统计到生物信息学

kuva 的图表可按场景分为四大类，每一类都有独立文档（位于 docs/src/plots/）：

基础统计与分布

• Scatter / Line / Bar：散点、折线、柱状（分组、堆叠）
• Histogram / Histogram2D / Hexbin：一维、二维直方图与六边形分箱
• Density / Ridgeline / ECDF：KDE 密度曲线、山脊图、经验累积分布
• Box / Violin / Strip / Raincloud / Jointplot：分布对比全家桶，支持 swarm 叠加

生物信息学专精

这是 kuva 最鲜明的特色，几乎是为生信场景量身打造：

• Volcano：差异表达火山图，带阈值线与 Top-N 基因标注
• Manhattan：GWAS 曼哈顿图，支持 22 条染色体预分桶优化
• Phylogenetic Tree：系统发育树，支持 Newick、矩形/斜角/圆形布局
• Synteny：基因组共线性条带图，含反向块
• UpSet：集合交集分析图
• Brick / Dot / Clustermap：测序 reads 砖块图、单细胞点阵图、层次聚类热图
• Forest / ROC / PR / Survival：荟萃分析森林图、分类模型曲线、Kaplan-Meier 生存曲线

流程、网络与层级

• Sankey：多阶段流量桑基图（Bézier 渐窄链接）
• Chord：弦图，成对流量弧带
• Network：力导向或环形布局的节点边图
• Treemap / Sunburst / Venn / Mosaic：层级与占比可视化
• Streamgraph / StackedArea / Bump：随时间变化的构成图

商业、金融与特殊坐标

• Waterfall / Funnel / Gantt / Waffle / Pyramid：瀑布、漏斗、甘特、华夫饼、人口金字塔
• Candlestick：K 线图，可挂成交量面板
• Polar / Rose / Radar / Ternary：极坐标、夜莺玫瑰、雷达、三元图
• Scatter3D / Surface3D / Contour / Quiver：三维散点、三维曲面、等高线、向量场

完整清单与每张图的说明见 docs/src/gallery.md，目录索引见 docs/src/SUMMARY.md。

🖥️ 四、从 SVG 到终端：四种输出后端

输出格式选择

方式	命令/特性	说明
SVG	-o out.svg（默认输出到 stdout）	无损矢量，可加 --interactive 嵌入交互
PNG	-o out.png（feature png）	自带光栅化器，无需系统依赖
PDF	-o out.pdf（feature pdf）	面向论文排版
终端	--terminal	Unicode Braille + ANSI 24 位色，零依赖

终端渲染：HPC 与远程服务器的神器

--terminal 参数把任意图表用 Unicode 盲文点阵（U+2800–U+28FF）+ 方块字符 + ANSI 24 位色画在当前终端里，无需显示器、无需文件。在 HPC 集群、远程 SSH、CI 日志中看数据分布再方便不过：

# 自动检测终端尺寸
kuva scatter data.tsv --x x --y y --terminal

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

每个字符格映射为 2×4 的盲文点阵，支持贝塞尔曲线与填充多边形，因此 Sankey 缎带、弦图弧、饼图扇区都能正确渲染。除 upset 外所有子命令都支持，详见 docs/src/cli/terminal.md。

SVG 交互：一个文件 = 一个可交互应用

加上 --interactive，SVG 内会嵌入自包含脚本（无外部依赖）：悬停提示、点击固定、搜索高亮、图例开关、坐标读出。当前已完整支持 scatter、line、bar、strip、volcano，参考 docs/src/reference/interactive.md。

🛠️ 五、常用参数与主题定制（一分钟掌握）

参数	作用
--title / --x-label / --y-label	标题与坐标轴标签
--theme light/dark/solarized/minimal	内置主题，一键切换配色风格
--palette category10	多序列配色板
--cvd-palette deuteranopia	色觉障碍友好配色
--embed-font	把 DejaVu Sans 以 base64 嵌入 SVG，无字体环境也能正确显示
--log-x / --log-y	对数坐标轴
--width / --height	画布尺寸（默认 800×500）

主题机制详见 docs/src/reference/themes.md，配色板见 docs/src/reference/palettes.md。

📦 六、作为 Rust 库使用：Builder 模式极简 API

作为库引入只需在 Cargo.toml 中添加 kuva = "0.3"，然后：

use kuva::prelude::*;

let plot = ScatterPlot::new()
    .with_data(vec![(1.0_f64, 2.0), (3.0, 5.0), (5.0, 4.0)])
    .with_color("steelblue")
    .with_legend("samples");

let plots: Vec<Plot> = vec![plot.into()];
let layout = Layout::auto_from_plots(&plots)
    .with_title("My Plot")
    .with_x_label("X")
    .with_y_label("Y");

let svg = render_to_svg(plots, layout);
std::fs::write("my_plot.svg", svg).unwrap();

一行 use kuva::prelude::* 即可导入全部 60 个绘图结构体、Layout、Figure、Theme 等常用类型，定义在 src/prelude.rs。多子图网格布局（跨格合并、共享坐标轴、共享图例）见 docs/src/reference/figure.md；日期时间轴见 docs/src/reference/datetime.md。

每种图都有对应的可运行示例，如 examples/scatter.rs、examples/manhattan.rs，文档内所有插图由 scripts/gen_docs.sh 批量再生成。

⚡ 七、性能基准：千万级数据也能秒开

kuva 使用 Criterion 做微基准测试，关键数字（release 构建、AMD64 Linux）：

场景	规模	耗时
散点图（场景构建+SVG 输出）	100 万点	414 ms
曼哈顿图（22 染色体，预分桶 O(n)）	100 万 SNP	501 ms
KDE 密度估计	10 万样本	28 ms
SVG 原始字符串生成	100 万圆	~200 ns/元素，完美线性

亮点优化包括：截断式 KDE 内核（排序+二分查找，万级数据约 8 倍加速）、Manhattan 预分桶（O(22n)→O(n)）、自研光栅化后端（Wu 线段 + SDF 圆，散点比 resvg 方案快 12 倍）。完整数据见 docs/src/benchmarks.md 与 benches/render.rs。

📚 八、项目结构导航：快速找到你要的资料

路径	内容
docs/src/SUMMARY.md	文档总目录：60 种图 + CLI + 参考手册
docs/src/gallery.md	全部图表画廊，一图一类
docs/src/cli/index.md	CLI 完整参数手册（安装/输入/输出/共享参数）
docs/src/benchmarks.md	性能基准与优化记录
ARCHITECTURE.md	渲染流水线架构图
src/plot/	60 种图表类型实现源码
src/render/	布局、主题、调色板、数学标签等渲染基础设施
src/backend/	SVG/PNG/PDF/终端四个输出后端
examples/	每种图一个可运行示例 + 示例数据
tests/	SVG 快照与行为测试（如 tests/terminal_basic.rs）
man/kuva.1	man 手册页
scripts/gen_docs.sh	一键再生成全部文档插图

🎬 九、彩蛋与总结

• 彩蛋：cargo build --bin kuva --features cli,doom 后运行 kuva doom，会生成一个约 15 MB、完全离线可玩的 DOOM SVG——是的，这个科学绘图库能输出可玩的《毁灭战士》，见 docs/src/doom.md。
• 选型建议：
  • 生信日常（DESeq2 结果、GWAS、reads 比对）→ 火山图/曼哈顿图/Brick 图直接 CLI 出图
  • 论文投稿 → --features full 输出 PDF，或用 --theme minimal
  • 服务器无图形环境 → --terminal 盲文渲染
  • 嵌入自己的 Rust 项目 → builder API + Figure 网格布局

kuva 把"科学绘图"这件事做到了 Rust 生态里的完整度标杆：60 种图表、四种输出、CLI 与 API 双入口、生信场景专精，且性能经得起百万级数据检验。如果你的项目需要把数据变成图，不妨从一条 kuva scatter 命令开始体验。