一行代码让 matplotlib 输出符合学术论文规范的图表，原生支持中文。
📖 English README · 📥 安装指南 · 🖼️ 样图画廊
academic-plot 是为科研、工程师量身打造的 matplotlib 风格统一库。无论你用 Python 处理振动数据、传感器输出、FFT 频谱还是控制系统频响，都能用一两行代码画出符合 IEEE / Elsevier 工程类期刊以及国内核心期刊（仪器仪表学报、机械工程学报等）规范的图表。
最大特色是 一流的中文支持：跨平台中文字体自动检测，提供 4 个专门的中文 profile，让中文坐标轴、图例、标题和英文数学符号无缝混排。
- 🎯 学术规范开箱即用 — Helvetica 8 pt / 内向刻度 / 四边框 / Wong 色盲友好 8 色，与 IEEE 期刊投稿要求一致
- 🇨🇳 原生中文支持 — 跨平台自动检测中文字体（macOS / Windows / Linux），提供
single_cn/double_cn/slide_cn/poster_cn四种中文 profile - 📐 8 种 profile 覆盖全场景 — 单栏论文、双栏论文、PPT 汇报、海报，中英文各 4 种
- 🧰 7 个常用绘图模板 — 时域、FFT 频谱、多曲线、双 Y 轴、误差棒、Bode、热图
- 📤 同时输出 PDF + PNG — 矢量 PDF 给论文，600 dpi PNG 给汇报，一次调用搞定
- 🤖 多 Agent 适配 — Claude Code / Cursor / Codex CLI / Google Antigravity 均有集成模板
- 🎨 零配置可用 — 一行
ap.apply_style()一切搞定，不用手撸rcParams
import academic_plot as ap
import numpy as np
ap.apply_style("single") # 单栏论文
t = np.linspace(0, 0.1, 1000)
vib = np.sin(2 * np.pi * 50 * t) + 0.3 * np.random.randn(len(t))
fig, ax = ap.plot_time_series(
t * 1000, vib,
xlabel="Time (ms)",
ylabel=r"Acceleration (m/s$^2$)",
)
ap.save_figure(fig, "vibration.png")
# → 同时输出 vibration.png + vibration.pdfap.apply_style("single_cn") # 中文单栏
fig, ax = ap.plot_time_series(
t * 1000, vib,
xlabel="时间 (ms)",
ylabel=r"加速度 (m/s$^2$)",
)
ax.set_title("振动信号 · 时域")
ap.save_figure(fig, "振动信号.png")中文标签、英文单位、数学符号
m/s²同图共存，无须额外配置。
这是 academic-plot 与其他通用 matplotlib 样式库的最大差异。
apply_style() 启动时会自动扫描系统已安装的中文字体，按以下顺序加载：
| 操作系统 | 优先级（从高到低） |
|---|---|
| macOS | PingFang SC → STHeiti → Songti SC → Hiragino Sans GB |
| Windows | Microsoft YaHei（微软雅黑）→ SimHei（黑体）→ SimSun（宋体） |
| Linux | Source Han Sans SC（思源黑体）→ Noto Sans CJK → WenQuanYi |
加载结果可通过 API 查询：
import academic_plot as ap
ap.has_cjk_font() # → True / False
ap.list_cjk_fonts() # → ['Heiti TC', 'Songti SC', 'PingFang SC', ...]
ap.CJK_FONT.get_name() # → 'PingFang SC'| profile | 用途 | 字号 | 尺寸 |
|---|---|---|---|
single_cn |
中文单栏论文 | 8 pt | 3.5 × 2.6 in |
double_cn |
中文双栏 / 多子图 | 8 pt | 7.16 × 3.0 in |
slide_cn |
中文 PPT 汇报 | 14 pt | 8.0 × 5.0 in |
poster_cn |
中文海报 | 18 pt | 10.0 × 7.0 in |
_cn profile 把中文字体放在 fallback 链首位，英文 / 数学符号会自动降级到 Helvetica / Arial，渲染效果与纯英文 profile 视觉一致：
ap.apply_style("double_cn")
fig, axes = ap.new_figure("double_cn", n_rows=2, n_cols=2)
# 中文标签 + 英文单位 + 数学符号同图
axes[0, 0].set_xlabel("时间 (ms)")
axes[0, 0].set_ylabel(r"加速度 (m/s$^2$)")
axes[0, 1].set_xlabel("频率 (Hz)")
# 子图内部嵌入中文标注
ap.cjk_text(axes[0, 0], 0.97, 0.97, "时域", ha="right", va="top")
# 标题用 CJK 字体强制渲染
fig.suptitle("某传感器测试综合性能", fontproperties=ap.CJK_FONT)Linux 默认不带中文字体，一行命令补齐：
sudo apt install fonts-noto-cjk fonts-wqy-microhei或在 Dockerfile 中：
RUN apt-get update && apt-get install -y fonts-noto-cjk之后再 import academic_plot 即可自动识别。
完整样图见 docs/gallery/ 目录。每张图同时提供 PNG 和 PDF 两种格式。
| 时域 | FFT 频谱 |
|---|---|
 |
 |
| 多曲线 | 双 Y 轴 |
|---|---|
 |
 |
| 误差棒 | Bode |
|---|---|
 |
 |
| 热图 | 2×2 多子图组合 |
|---|---|
 |
 |
| 时域 | FFT 频谱 |
|---|---|
 |
 |
| 多曲线 | 双 Y 轴 |
|---|---|
 |
 |
| Bode | 2×2 中文综合 |
|---|---|
 |
 |
详细多 Agent 集成方式见 INSTALL.md。这里只给最常用三种：
git clone https://github.com/mintandkiwi/academic-plot.git ~/.claude/skills/academic-plot
pip install matplotlib numpyClaude Code 启动后会自动识别此 Skill，对"画图"类任务自动调用。
pip install git+https://github.com/mintandkiwi/academic-plot.git适用于 Jupyter、脚本、其他 Agent 工具。
pip install git+https://github.com/mintandkiwi/academic-plot.git
# 然后按 INSTALL.md 把对应 integration 配置复制到 IDE / Agent| Agent / 工具 | 自动触发 | 集成方式 |
|---|---|---|
| Claude Code | ✅ | clone 到 ~/.claude/skills/ |
| Cursor | ✅ | .cursorrules |
| Codex CLI | ✅ | ~/.codex/AGENTS.md |
| Google Antigravity | ✅ | 系统提示词 |
| Jupyter / 脚本 | 手动 | import academic_plot as ap |
| Windsurf / Aider | ✅ | 同 Cursor 套路 |
各 Agent 的具体配置文件在 integrations/ 目录。
import academic_plot as ap
# 风格
ap.apply_style(profile) # 8 种：single/double/slide/poster + _cn 版本
ap.new_figure(profile, n_rows, n_cols)
# 配色（Wong 色盲友好 8 色）
ap.COLORS # 颜色列表
ap.get_colors(n) # 取前 n 个
# 绘图模板
ap.plot_time_series(t, y, ...) # 时域曲线
ap.plot_spectrum(signal, fs, ...) # FFT 频谱
ap.plot_multi_curves(x, ys, labels) # 多曲线对比
ap.plot_dual_axis(x, y1, y2, ...) # 双 Y 轴
ap.plot_errorbar(x, y, yerr, ...) # 误差棒
ap.plot_bode(freq, mag_db, phase) # Bode 图
ap.plot_heatmap(data, ...) # 热图
# 工具
ap.add_subplot_label(ax, "(a)") # 子图标号
ap.save_figure(fig, "name.png") # 同时输出 PNG + PDF
ap.cjk_text(ax, x, y, "中文") # 嵌入中文文本
# 中文字体
ap.has_cjk_font() # bool
ap.list_cjk_fonts() # 已安装的 CJK 字体列表
ap.CJK_FONT # FontProperties 实例完整参数说明见 docs/reference.md。
为什么不用 seaborn.set_style("paper") 或 SciencePlots？
- 它们的默认风格偏 Nature/Science 自然科学类（仅左下两边框、外向刻度），不符合 IEEE 工程类标准
- 都不解决中文渲染问题，需要用户自己 hack
rcParams["font.sans-serif"] - 没有针对实验数据的高层绘图模板（时域 / FFT / 双 Y 轴 / Bode 等）
academic-plot 的取舍：
- IEEE 工程风 作为默认（内向刻度、四边框、次刻度）
- 中文一等公民 —— 不是"也能用中文"，而是为中文场景专门设计 4 个 profile
- 薄包装，不锁定 —— 模板函数返回
(fig, ax)，你随时可以接着用原生 matplotlib API 自定义
欢迎 PR / Issue。
- Issue：https://github.com/mintandkiwi/academic-plot/issues
- 想法：开 Discussion 聊
MIT © 2026 Yancy Chan