5分钟美化你的科研图表：Rust绘图库kuva主题、调色板与图例定制全解

kuva 是一款 Rust 科学绘图库（A scientific plotting library in Rust），内置 60 种图表类型，只需一个命令行参数即可切换主题、调色板与图例，5 分钟就能让你的科研图表从"能看"变"好看"。本文带你快速掌握 tema 之外的三大美化利器：主题（Theme）、调色板（Palette）与图例（Legend）。

为什么科研图表需要"颜值"管理？

默认出图往往存在三个问题：

• 🌑 背景刺眼：白底黑字在深色演示文稿中很突兀；
• 🔴 颜色撞车：红绿搭配对约 8% 的男性色觉障碍者不友好；
• 📦 图例碍事：图例盖住数据，或者干脆不知道去哪找。

kuva 把这三件事都封装成了"一个参数"级别的操作，无需手绘样式。

一、4 个内置主题，一行命令换装

主题控制图表的"外壳"：背景、坐标轴、网格线、文字与图例框的颜色（数据点颜色不受主题影响）。kuva 内置 4 套主题，默认 light。

主题	风格	适合场景
light	白底、黑字、浅灰网格	通用默认
dark	深炭底（#1e1e1e）、浅灰文字	深色 PPT、大屏演示
minimal	白底、无网格、衬线字体	期刊投稿
solarized	暖米色底（Solarized 风格）	长时间阅读的网页

在 CLI 中只需加一个参数：

kuva scatter data.tsv --x x --y y --theme dark
kuva bar data.tsv --label-col gene --value-col count --theme minimal

在 Rust 代码中同样简单：Layout 上调用 .with_theme(Theme::dark()) 即可。完整的主题属性对照表见 docs/src/reference/themes.md。

进阶：自定义主题

想要"GitHub 暗色风"？直接构造 Theme 结构体，指定背景、轴线、网格、图例框等任意组合：

let theme = Theme {
    background: "#0d1117".into(),
    text_color:  "#c9d1d9".into(),
    legend_bg:   "#161b22".into(),
    // …其余字段
};
let layout = Layout::auto_from_plots(&plots).with_theme(theme);

实现位于 src/render/theme.rs，字段一目了然。

二、9 套调色板，色觉障碍友好

Palette 是一个有序的命名色表，会自动按顺序为多个系列配色，不用逐个手写颜色。

色盲安全系（推荐）

调色板	色数	特点
wong / okabe_ito	8	通用首选，色觉障碍安全
tol_bright	7	适合蓝色盲（tritanopia），演示效果好
tol_muted	10	大色组数据首选，全类型 CVD 安全
tol_light	9	明亮浅色系
ibm	5	IBM 设计语言，5 色紧凑套装

通用系

• category10（默认）：Tableau/D3 经典 10 色
• pastel：柔和粉彩 10 色
• bold：高饱和 10 色

使用方式，CLI 或代码二选一：

kuva scatter data.tsv --x x --y y --palette wong

let layout = Layout::auto_from_plots(&plots)
    .with_palette(Palette::wong());

💡 贴心功能：支持按色觉障碍类型直接选色——--cvd-palette deuteranopia（红绿色盲）、protanopia（红色盲）、tritanopia（蓝色盲），它会自动覆盖 --palette 并返回合适的色表。

自定义调色板

期刊有官方配色？几行代码搞定：

let pal = Palette::custom("my_palette",
    vec!["#264653".into(), "#2a9d8f".into(), "#e9c46a".into()]);

全部色值与构造器定义在 src/render/palette.rs，详细说明见 docs/src/reference/palettes.md。

三、图例定制：从"自动收集"到"像素级定位"

kuva 的图例默认自动收集：只要在绘图对象上写了 .with_legend("Cluster A")，Layout::auto_from_plots() 会统一汇总并在右侧渲染——画布还会自动加宽，无需手动留白。

位置：12+ 种预设 + 2 种自由放置

需求	方法
右侧/左侧/上下边距	with_legend_position(LegendPosition::Outside*) 系列
叠在数据区空白角	InsideTopRight、InsideBottomLeft 等 6 种
像素级坐标	with_legend_at(x, y)
跟随数据坐标	with_legend_at_data(x, y)，坐标轴缩放时图例自动跟随

外观与内容控制

• .with_legend_box(false)：去掉背景框，适合叠在数据区上；
• .with_legend_title("Variant type")：加粗标题行；
• .with_legend_group("Controls", entries)：图例分组，组标题加粗；
• .with_legend_entries(...)：手动指定图例项，支持 Rect、Circle、Line、Marker 等多种图例标记形状。

多面板图还能用 Figure 的 .with_shared_legend() 把各面板图例合并成整图共享图例，或用 LegendPlot 单独画一个图例格（下方横排 / 右侧竖排均可），实现见 src/plot/legend.rs，完整 API 速查表见 docs/src/reference/legends.md 与 docs/src/plots/legend.md。

四、加分项：字体嵌入，跨平台不失真

SVG 默认按名称引用字体，在没装字体的容器/CI 环境里可能显示异常。加一个参数即可让 SVG 自带字体：

kuva scatter data.tsv --x x --y y --embed-font -o plot.svg

它会把内置的 DejaVu Sans 以 base64 @font-face 形式注入 SVG，文件自包含（体积约 +1 MB）。PNG/PDF 后端不受影响——字体始终随库打包（见 assets/fonts/ 中自带的字体文件）。

快速上手：3 步美化你的第一张图

1️⃣ 安装 CLI（cargo install kuva --features cli），或用 Cargo.toml 引入 kuva = "0.3" 作为库使用。

2️⃣ 一键换风格：

kuva line data.tsv --x-col time --y-col value --color-by group \
    --theme dark --palette wong --legend --title "Expression over time"

3️⃣ 按需微调：图例挡数据 → InsideBottomLeft；投稿期刊 → minimal 主题 + --embed-font。

🎯 至此，kuva 的主题、调色板、图例三件套就讲完了。更多图表类型与参数可参考 docs/src/SUMMARY.md 的完整文档目录，祝出图愉快！