使用 LaTeX 渲染文本#

Matplotlib 可以使用 LaTeX 来渲染文本。通过在 rcParams 中设置 text.usetex : True,或者在单独的 Text 对象上将 usetex 属性设置为 True 来激活此功能。通过 LaTeX 处理文本比 Matplotlib 非常强大的 mathtext 慢,但由于可以使用不同的 LaTeX 包(字体包、数学包等),它更灵活。效果可能非常显著,尤其是当您注意在图形中使用与主文档相同的字体时。

Matplotlib 的 LaTeX 支持需要一个可用的 LaTeX 安装。对于 *Agg 后端,还需要 dvipng;对于 PS 后端,还需要 PSfragdvipsGhostscript。对于 PDF 和 SVG 后端,如果存在 LuaTeX,它将用于加速一些后处理步骤,但请注意它不用于解析 TeX 字符串本身(仅支持 LaTeX)。这些外部依赖项的可执行文件都必须位于您的 PATH 中。

仅支持少量字体系列(由 PSNFSS 方案定义)。它们在此列出,并附有相应的 LaTeX 字体选择命令和 LaTeX 包,这些包是自动使用的。

通用字体系列

字体

衬线字体 (\rmfamily)

Computer Modern Roman, Palatino (mathpazo), Times (mathptmx), Bookman (bookman), New Century Schoolbook (newcent), Charter (charter)

无衬线字体 (\sffamily)

Computer Modern Serif, Helvetica (helvet), Avant Garde (avant)

草书 (\rmfamily)

Zapf Chancery (chancery)

等宽字体 (\ttfamily)

Computer Modern Typewriter, Courier (courier)

默认字体系列(无需加载任何 LaTeX 包)是 Computer Modern。所有其他系列都是 Adobe 字体。Times 和 Palatino 各自拥有自己的配套数学字体,而其他 Adobe 衬线字体则使用 Computer Modern 数学字体。

要启用 LaTeX 并选择字体,例如使用:

plt.rcParams.update({
    "text.usetex": True,
    "font.family": "Helvetica"
})

或等效地,将您的 matplotlibrc 设置为

text.usetex : true
font.family : Helvetica

也可以将 font.family 设置为其中一个通用系列名称,然后配置相应的通用系列;例如:

plt.rcParams.update({
    "text.usetex": True,
    "font.family": "sans-serif",
    "font.sans-serif": "Helvetica",
})

(这是 Matplotlib 3.5 之前所需的做法)。

这是一个标准示例,使用 TeX 渲染数学方程

../../../_images/sphx_glr_tex_demo_001.png

请注意,不支持显示数学模式 ($$ e=mc^2 $$),但如上述演示中所示,添加命令 \displaystyle 将产生相同的结果。

非 ASCII 字符(例如上面 y 标签中的度数符号)受 inputenc 支持的程度支持。

注意

为了与非 usetex 情况保持一致,Matplotlib 对换行符进行了特殊处理,因此单个换行符会产生换行(而不是像标准 LaTeX 那样被解释为空格)。

Matplotlib 使用 underscore 包,以便下划线 (_) 在文本模式下“原样”打印(而不是像标准 LaTeX 那样导致错误)。下划线在数学模式下仍会引入下标。

注意

某些字符在 TeX 中需要特殊转义,例如

# $ % & ~ ^ \ { } \( \) \[ \]

因此,这些字符的行为会因 rcParams["text.usetex"](默认值:False)而异。如上所述,下划线 (_) 在数学模式之外不需要转义。

注意

LaTeX 总是默认使用衬线字体进行数学排版(即使 rcParams["font.family"] = "sans-serif")。如果需要,将 \usepackage{sfmath} 添加到 rcParams["text.latex.preamble"] 可以让 LaTeX 输出无衬线数学字体。

PostScript 选项#

为了生成可嵌入新 LaTeX 文档的封装 PostScript (EPS) 文件,Matplotlib 的默认行为是提炼输出,这会删除 LaTeX 使用的一些在 EPS 文件中非法的 PostScript 操作符。此步骤产生的结果可能令一些用户无法接受,因为文本被粗略地栅格化并转换为位图,这些位图不像标准 PostScript 那样可缩放,并且文本不可搜索。一种解决方法是在您的 rc 设置中将 rcParams["ps.distiller.res"](默认值:6000)设置为更高的值(例如 6000),这会生成更大的文件,但可能看起来更好并合理缩放。一个更好的解决方法需要 PopplerXpdf,可以通过将 rcParams["ps.usedistiller"](默认值:None)更改为 xpdf 来激活。此替代方案生成不带栅格化文本的 PostScript,因此它可以正确缩放,可以在 Adobe Illustrator 中编辑,并且可以在 pdf 文档中搜索文本。

可能出现的问题#

  • 在 Windows 上,可能需要修改 PATH 环境变量,以包含 latex、dvipng 和 ghostscript 可执行文件所在的目录。有关详细信息,请参阅 环境变量在 Windows 中设置环境变量

  • 将 MiKTeX 与 Computer Modern 字体一起使用时,如果出现异常的 *Agg 和 PNG 结果,请转到 MiKTeX/Options 并更新您的格式文件。

  • 在 Ubuntu 和 Gentoo 上,基本的 texlive 安装不包含 type1cm 包。您可能需要安装一些额外的包,才能获得其他 LaTeX 发行版附带的所有好东西。

故障排除#

  • 尝试删除您的 .matplotlib/tex.cache 目录。如果您不知道在哪里找到 .matplotlib,请参阅 matplotlib 配置和缓存目录位置

  • 确保 LaTeX、dvipng 和 Ghostscript 都能正常工作并位于您的 PATH 中。

  • 确保您尝试在 LaTeX 文档中执行的操作是可能的,您的 LaTeX 语法是有效的,并且在必要时使用了原始字符串以避免意外的转义序列。

  • rcParams["text.latex.preamble"](默认值:'')不被官方支持。此选项提供了很大的灵活性,也可能导致许多问题。在报告问题之前,请禁用此选项。

  • 如果您仍然需要帮助,请参阅 获取帮助

由 Sphinx-Gallery 生成的画廊