VTK 2D图像中文显示全攻略：从豆腐块到SetFontFile的字体渲染实战

做图像可视化的人，百分之百会遇到同一个尴尬：打开一张 CT 影像或者无人机航拍图，想在上面加一行中文标注"病灶区域""跑道中线""温度异常分布"，结果屏幕上出现一排整整齐齐的小方框。对，就是那种一个汉字一个豆腐块的经典画面。第一次碰到时我也以为是编码或者 API 用错了，翻遍国内外技术社区和邮件列表才知道，问题出在 VTK 的字体系统根本不认识中文字形，而不是字符串传递出了偏差。这篇文章就把"VTK 在2D图像上显示中文文本"这件事彻底讲透：从字体管线的底层原理，到三条能落地的实现路线，再到字体文件选择、编码坑、离屏渲染输出 PNG 的完整步骤。适合所有用 VTK 做医学图像标注、遥感影像批注、实验结果出图的同学，不管你是 C++ 工程还是 Python 绑定，看完基本可以直接照抄。

1. 为什么 VTK 渲染中文会变成"豆腐块"：字体管线的底层原因

1.1 FreeType 不生产字形，它只是搬运工

VTK 里所有文本的渲染，不管是 vtkTextActor、vtkCornerAnnotation 还是标尺上的刻度，最终都汇入同一条管线：VTK 把字符串和 vtkTextProperty 交给 vtkTextRenderer，后者调用 FreeType 去读取字体文件，把每个字符对应的字形光栅化成像素，再交给渲染器画到屏幕上。

这里有一个关键认知：FreeType 本身不包含任何字形。它本质上是一台"打印机"，字形是"字模"，字模存放在字体文件里。VTK 在发布时为了跨平台表现一致，自带了几套基础字体度量数据，只覆盖 Arial、Courier、Times 这几个家族对应的拉丁字符和少量符号。CJK 统一表意文字区块，也就是我们日常用到的汉字，在默认字体文件里一个字形都没有。

所以当 FreeType 拿着中文字符去查内置字体时，查不到字形，只能回退到 .notdef 缺字字形。这就是你看到的小方框，专业说法叫 tofu，中文圈习惯叫豆腐块。很多初学者以为是 API 用错了，或者是编码问题，其实往源头想一下就清楚：缺失的是字形数据，你传什么编码的字符串来都一样。

1.2 SetFontFamily 为什么救不了中文

网上最常被转发的错误建议是设置字体家族：textProperty->SetFontFamilyToTimes()，或者SetFontFamilyToArial()。这句话只会在 VTK 内置的那几套西文字体里做选择，跟中文字形一点关系都没有。换多少次家族，内置字体里依然没有汉字。

真正有效的唯一思路是：让 FreeType 去读取一个包含中文字形的字体文件，也就是给你的文本属性挂上外部字体。VTK 6.2 以后，vtkTextProperty 提供了SetFontFile()接口，配套的字体家族枚举是VTK_FONT_FILE。可以这么说，90% 的"VTK 中文乱码或方块"问题，都是因为没人告诉你这两个 API 的存在。

1.3 三条主流技术路线怎么选

围绕"把中文字显示在2D图像上"这个需求，我按实际工程场景整理了三条路，先看表格再展开：

路线 A 是日常开发最常用的，稳定性最高；路线 B 适合做交付物，把标注"焊死"在图片里；路线 C 适合后台批量脚本，整个流程不依赖窗口和显卡。下面按这个顺序把细节和坑都过一遍。

2. 路线A：vtkTextActor 叠加中文标注，交互查看的标准做法

2.1 C++ 最小可运行示例

直接上代码，这是我在一个模拟项目X里验证过的最小版本：读入一张 2D 图片，左上角叠加一行中文说明。

#include <vtkSmartPointer.h> #include <vtkImageReader2Factory.h> #include <vtkImageReader2.h> #include <vtkImageViewer2.h> #include <vtkTextActor.h> #include <vtkTextProperty.h> #include <vtkRenderWindowInteractor.h> int main(int argc, char* argv[]) { // 读入一张 2D 图像 auto reader = vtkSmartPointer<vtkImageReader2>::Take( vtkImageReader2Factory::CreateImageReader2(argv[1])); reader->SetFileName(argv[1]); reader->Update(); // 图像查看器 auto viewer = vtkSmartPointer<vtkImageViewer2>::New(); viewer->SetInputConnection(reader->GetOutputPort()); // 中文文本 Actor auto textActor = vtkSmartPointer<vtkTextActor>::New(); textActor->SetInput("病灶区域，建议随访"); vtkTextProperty* prop = textActor->GetTextProperty(); prop->SetFontFamily(vtkTextProperty::VTK_FONT_FILE); // 关键点1 prop->SetFontFile("C:/Windows/Fonts/simhei.ttf"); // 关键点2 prop->SetFontSize(32); // 单位是point prop->SetColor(1.0, 0.84, 0.0); // 金黄色 textActor->SetDisplayPosition(80, 100); // 相对窗口左下角 // 注意是 AddActor2D，不是 AddActor viewer->GetRenderer()->AddActor2D(textActor); viewer->Render(); auto interactor = vtkSmartPointer<vtkRenderWindowInteractor>::New(); viewer->SetupInteractor(interactor); interactor->Start(); return 0; }

这段代码里有两个"只可意会"的细节。第一个是属性设置顺序：先SetFontFamily(vtkTextProperty::VTK_FONT_FILE)再SetFontFile(...)。虽然只调 SetFontFile 在多数版本里也能工作，但显式声明字体家族来源是"字体文件"，能避免部分版本内部状态没有正确切换到文件字体模式。第二个是AddActor2D而不是AddActor：vtkTextActor 属于 2D actor 集合，它的定位方式基于窗口像素的显示坐标，不受相机缩放影响。如果不小心把 2D actor 当普通 actor 加进渲染器，某些情况下它也能显示，但坐标解读会完全错乱，原因排查起来非常头疼。

2.2 Python 绑定版本，适合快速验证字体

如果你只是想知道某个字体文件在 VTK 里能不能正确渲染中文，建议先写一个十几行的 Python 脚本跑通，再回 C++ 工程里使用，能省下大量编译时间：

import vtk reader = vtk.vtkPNGReader() reader.SetFileName("demo.png") reader.Update() viewer = vtk.vtkImageViewer2() viewer.SetInputData(reader.GetOutput()) actor = vtk.vtkTextActor() actor.SetInput("跑道中线 / 海拔 1200m") prop = actor.GetTextProperty() prop.SetFontFamily(vtk.VTK_FONT_FILE) prop.SetFontFile("/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc") prop.SetFontSize(36) prop.SetColor(1.0, 0.0, 0.2) actor.SetDisplayPosition(150, 50) viewer.GetRenderer().AddActor2D(actor) viewer.Render() interactor = vtk.vtkRenderWindowInteractor() viewer.SetupInteractor(interactor) interactor.Start()

Python 3 源码默认就是 UTF-8，字符串这层比 C++ 省心。Linux 下路径里的文泉驿正黑是开箱即用的免费中文字体之一，第5节我会专门整理一份跨平台字体路径清单。

2.3 多行文本、对齐方式与字号换算

中文标注经常需要两行，比如第一行写标题、第二行写说明。直接在 SetInput 里加\n换行即可，VTK 会按照当前文本属性自动排版。如果要相对窗口居中、或者底部对齐而不是固定左下角，需要额外设置对齐属性：

textActor->GetTextProperty()->SetJustificationToCentered(); textActor->GetTextProperty()->SetVerticalJustificationToBottom(); textActor->SetDisplayPosition(winW / 2, 20);

这里有一个容易想当然的坑：SetFontSize 的单位是 point，也就是 1/72 英寸，最终像素大小跟渲染时使用的 DPI 相关。vtkImageViewer2 交互窗口里 32 point 大约对应 32 像素，但如果图像分辨率很大、窗口发生了整体缩放，文字像素尺寸也会跟着变。所以"标注必须固定在某个图像坐标"的需求，不能简单用 SetDisplayPosition 硬写，需要在 Resize 事件或相机交互回调里根据缩放比例重新换算坐标和字号。简单项目里我一般接受文字跟随窗口缩放的行为，只有出图需求时才用第3节的离屏方案。

3. 路线B：把中文标注烧进图像，离屏渲染输出带文字的PNG

3.1 什么时候需要"烧"进去

交互式查看器满足不了所有需求。我遇到最多的情况是给报告配图、给遥感解译结果批量出图，对方要的是一张打开就能看的 PNG，不能依赖接收方电脑上的 VTK 环境。这时必须把中文文字栅格化进图像像素，而不是停留在窗口叠加层。

3.2 vtkWindowToImageFilter 离屏捕获完整流程

思路是先把图像和文字渲染到一个看不见的窗口里，再用 vtkWindowToImageFilter 把帧缓冲取出来写成 PNG。窗口尺寸设成和图像一致后，文字叠加在图像上的像素坐标就是精确的，不会出现缩放偏差：

#include <vtkRenderWindow.h> #include <vtkRenderer.h> #include <vtkImageActor.h> #include <vtkTextActor.h> #include <vtkWindowToImageFilter.h> #include <vtkPNGWriter.h> // 假设 reader 已经读入图像并 Update() auto imgData = reader->GetOutput(); int w = imgData->GetDimensions()[0]; int h = imgData->GetDimensions()[1]; auto renderer = vtkSmartPointer<vtkRenderer>::New(); renderer->SetBackground(0.0, 0.0, 0.0); auto imageActor = vtkSmartPointer<vtkImageActor>::New(); imageActor->SetInputData(imgData); renderer->AddActor(imageActor); // 复用第2节的中文 actor 配置，这里省略 // auto textActor = ...; renderer->AddActor2D(textActor); auto renderWindow = vtkSmartPointer<vtkRenderWindow>::New(); renderWindow->AddRenderer(renderer); renderWindow->SetSize(w, h); renderWindow->OffScreenRenderingOn(); auto w2i = vtkSmartPointer<vtkWindowToImageFilter>::New(); w2i->SetInput(renderWindow); w2i->SetInputBufferTypeToRGBA(); w2i->ReadFrontBufferOff(); renderWindow->Render(); w2i->Update(); auto writer = vtkSmartPointer<vtkPNGWriter>::New(); writer->SetFileName("annotated.png"); writer->SetInputConnection(w2i->GetOutputPort()); writer->Write();

3.3 离屏输出最容易翻车的三个细节

第一个是SetSize必须写在Render()之前，而且必须写。忘记设置的话窗口默认是 300x300，吐出来的图基本没法用。第二个是ReadFrontBufferOff()。默认情况下 WindowToImageFilter 读取前缓冲，而离屏渲染通常只更新后缓冲，不关掉前缓冲读取就会得到一张黑图。第三个是SetInputBufferTypeToRGBA()。如果只想导出图像本身，RGB 就够；但要包含文本叠加层，并且希望文字边缘的半透明像素正确保留，必须用 RGBA。

再说一个出图场景里很实际的问题：透明背景文字。如果业务方要的是"只有一行中文、背景全透明"的 PNG，用来贴到别的图上，那 WindowToImageFilter 这条路不方便，因为窗口背景色会跟着进入帧缓冲。更干净的替代方案是直接用 vtkFreeTypeStringToImage 拿文字 RGBA 位图，再用 vtkImageBlend 与底图合成。无头环境下这才是正统做法，具体用法我在第6节末尾补充。

4. 扩展战场：角注、标尺、三维标注的中文化

实际工程里不止主画面文本需要中文。图像四周的角注、彩色标尺的标题刻度、三维渲染场景里的标签，全都躲不开中文化。

4.1 vtkCornerAnnotation：角落信息栏也要中文

vtkCornerAnnotation 常用来在图像角落显示采集时间、序列位置、对象编号。它的文本属性同样支持 SetFontFile，但要注意角编号的含义：

auto corner = vtkSmartPointer<vtkCornerAnnotation>::New(); corner->SetLinearFontScaleFactor(2); corner->SetNonlinearFontScaleFactor(1); corner->SetMaximumFontSize(18); corner->SetText(2, "左上角：采集时间 10:32:05"); corner->SetText(3, "右上角：序列第 12 帧"); corner->GetTextProperty()->SetFontFamily(vtkTextProperty::VTK_FONT_FILE); corner->GetTextProperty()->SetFontFile("C:/Windows/Fonts/simhei.ttf"); viewer->GetRenderer()->AddActor2D(corner);

角编号对应关系是：0 左下、1 右下、2 左上、3 右上。这里有两个经验值：第一，SetMaximumFontSize必须设置，否则 VTK 会按场景自动计算字号，可能把字撑到看不清，或者反过来缩到看不见；第二，中文场景建议把SetLinearFontScaleFactor调大一些，因为汉字笔画密度高，字号太小会糊成一团。

4.2 vtkScalarBarActor：色标标题和刻度标签

医学图像和热力图里色标几乎是标配，刻度标签经常要写"温度 (℃)"或者"灰度值 (HU)"。vtkScalarBarActor 有两个完全独立的文本属性，标题归标题，刻度归刻度，两个都要设置字体文件，漏掉任何一个都会出现一半中文一半豆腐块的"阴阳脸"：

auto scalarBar = vtkSmartPointer<vtkScalarBarActor>::New(); scalarBar->SetTitle("温度 (℃) 分布"); scalarBar->SetNumberOfLabels(5); scalarBar->GetTitleTextProperty()->SetFontFamily(vtkTextProperty::VTK_FONT_FILE); scalarBar->GetTitleTextProperty()->SetFontFile(fontPath); scalarBar->GetLabelTextProperty()->SetFontFamily(vtkTextProperty::VTK_FONT_FILE); scalarBar->GetLabelTextProperty()->SetFontFile(fontPath); viewer->GetRenderer()->AddActor2D(scalarBar);

顺带提醒一个细节：℃ 这个符号不属于 CJK 字形，它在标点和数学符号区，simhei、wqy-zenhei 这些字体一般都有覆盖。但有些生僻的中日韩统一表意文字扩展B区字符，常见字体的覆盖就不好说了。验证字体时一定用你真实业务里要显示的那一批字符串来测，只测"测试中文"四个字是远远不够的。

4.3 三维场景的中文标签：用 vtkTextActor3D

如果是三维渲染里的标注，很多人的第一反应是 vtkVectorText。这里直接给结论：不要用 vtkVectorText 显示中文。它的字形来源是 VTK 内置的轮廓字体，走的是和 FreeType 无关的矢量轮廓路径，根本不接受字体文件参数，汉字没有地方找字形。

正确选择是 vtkTextActor3D，它在 VTK 8.1 之后的版本里支持把文本按字体文件渲染并贴在空间位置：

auto actor3D = vtkSmartPointer<vtkTextActor3D>::New(); actor3D->SetInput("右心室"); actor3D->GetTextProperty()->SetFontFamily(vtkTextProperty::VTK_FONT_FILE); actor3D->GetTextProperty()->SetFontFile("C:/Windows/Fonts/msyh.ttc"); actor3D->GetTextProperty()->SetFontSize(18); actor3D->SetPosition(12.5, 30.0, 8.0); // 世界坐标 renderer->AddActor(actor3D);

注意 SetPosition 用的是世界坐标，文字会随相机视角自然缩放和朝向变化，这是它和 2D 文本的本质区别。同样的字体文件设置也适用，说明"SetFontFile + VTK_FONT_FILE"这套机制在整个 VTK 文本体系里是统一的，学会一次就能到处用。

5. 字体文件选型：跨平台路径、TTF与TTC、以及静默失败

5.1 一份可以直接抄的字体路径清单

不同平台放置中文字体的位置差别很大，我第一次在 Linux 服务器上部署时就找了半小时字体。下面这份清单是我长期攒下来的，可以直接抄：

选择原则是：优先用"单一字面"的 TTF 文件。为什么？因为 TTC 是字体集合，一个文件里打包了多个字体 face。FreeType 打开 TTC 时默认取第一个 face，而有些 TTC 的第一个 face 恰好是西文或者某个特殊字重，中文字形缺失，表现就是"明明设置了字体文件，依然豆腐块"。simhei.ttf 是单面 TTF，拿过来就能用，所以我的默认项目字体路径长期指向它。

5.2 字体文件不生效的排查套路

SetFontFile 最大的坑是：它不返回错误码。文件不存在、路径写错、字体本身损坏，VTK 都会静默回退到默认字体，而且多数情况下不打印任何日志。所以一旦看到豆腐块，我建议按固定顺序排查：

1. 用ls -l或资源管理器确认字体文件存在，且大小不为 0。
2. 确认路径斜杠方向。Windows 下也建议统一写成正斜杠C:/Windows/Fonts/simhei.ttf，避免 C++ 字符串里反斜杠转义出幺蛾子。
3. 用第2节的 Python 小脚本单独渲染一行"中 Test 中"。如果只有"中"变豆腐，说明字体文件本身不含中文字形，换字体；如果整段都不显示，说明加载失败或字体家族枚举没设置。
4. 用系统工具确认字体确实覆盖目标字符。Linux 下可以先跑fc-list :lang=zh看系统可用中文字体，再用真实业务字符串逐条验证。

提示：SetFontFile 静默失败是 VTK 中文问题里最浪费生命的一种。建议把第2节的 Python 脚本保存成check_font.py，每次换字体或者换机器环境时先跑一遍，五秒钟就能确认字体链路通不通。

5.3 字体版权和体积的务实提醒

嵌入式设备或者打包发布时，中文字体动辄十几 MB，很多人想裁字体。从合规和工程两个角度看，建议优先用开源字体：文泉驿、Noto CJK、思源黑体都是开源授权，可以随程序分发。Windows 自带的 simhei 有版权限制，一般只适合受控内部环境，别随便打包对外发布。

裁剪字体也确实可行，国内常用的两个工具是 fonttools 和 pyftsubset。我做过一个医学标注工具，把用户最常用到的几百个字裁进一个子集字体，文件从十几 MB 压到几百 KB，程序启动快了不少。裁完记得再用那个 check_font.py 把真实业务字符串全部验一遍，防止漏字。

6. 编码、编译选项与DPI：这些坑比字体本身更容易让人崩溃

6.1 UTF-8 编码：C++ 用户的隐形地雷

VTK 内部要求文本字符串是 UTF-8 编码。这个问题在 Python 里根本不是事，但在 C++ 里能掀翻整个项目。旧的 MSVC 在编译不带/utf-8选项的源文件时，会把源码里的"中文"字面量按本地代码页转成字节，中文 Windows 下就是 GBK，然后这些 GBK 字节被 VTK 当成 UTF-8 去解析，最终显示出来的是乱码或者一串问号。注意，乱码和缺字形的豆腐块是两种完全不同的症状，排错路径也不一样。

解决办法按推荐度排序：

1. Visual Studio 工程属性里给 C/C++ 增加/utf-8编译选项，一劳永逸。
2. CMake 里对目标加target_compile_options(${PROJECT_NAME} PRIVATE /utf-8)，这样换 IDE 或者命令行构建都不受影响。
3. 把源码文件保存为带 BOM 的 UTF-8，MSVC 能识别 BOM 从而自动正确解码。但这招在 Linux 交叉编译场景下并不通用，还是推荐前两种。

6.2 字号、DPI和图像分辨率的一致性问题

前面提过 SetFontSize 单位是 point，最终像素数等于 point × DPI / 72。vtkImageViewer2 默认情况接近 72 DPI，所以 36 point 大约等于 36 像素。但高分辨率医学图像，比如 2048x2048，交互窗口为了适应屏幕会整体缩小，文字跟着变小，标注就可能挤成一团。

我的实践方案是这样的：交互查看器场景下接受"文字相对屏幕固定大小"，因为用户要的是可读性；批量出图场景下，把目标 DPI 固定为 96，先算显示缩放比scale = windowWidth / imageWidth，再根据 scale 反推标注字号。写成辅助函数后，出图的文字比例和交互窗口的观感完全一致，核心就一行：

prop->SetFontSize(static_cast<int>(basePointSize / scale + 0.5));

6.3 FreeType 模块未启用与字形缓存

VTK 构建时，Module_VTK_RenderingFreeType必须开启，新版本默认就是开的，但自定义裁剪构建或一些老版本发行包里可能没启用。一旦没启用，文本渲染会退回系统字体路径，中文基本全凉。检查方法是在 cmake 配置阶段看组件清单，或者直接搜安装目录里有没有vtkFreeTypeStringToImage.h头文件。

字形缓存是另一个隐蔽坑。在一次长时间运行的查看程序里，我先后用 Arial 渲染了几百个英文标签，然后给同一个 vtkTextProperty 换成了中文字体文件，结果第一次渲染中文时仍然是旧字形。这是 FreeType 模块内部 MRU 缓存的经典表现。稳妥做法是一个文本属性对象只管一种字体，不跨字体复用；如果实在要复用，换字体后调用prop->Modified()强制无效化缓存。

6.4 服务器环境没有显示器怎么办

后台批量出图时，即使开了OffScreenRenderingOn()，在没有任何显示设备的 Linux 环境里依然可能初始化失败。这时候可以给任务挂xvfb-run，或者直接在 Windows 上保证有图形会话。更硬核的做法是放弃渲染管线，用vtkFreeTypeStringToImage在纯 CPU 环境生成文字 RGBA 位图，再用 vtkImageBlend 与底图合成。这条路完全不依赖窗口和 GPU，是真正适合海量批量处理的方案。我做过一个模拟项目X，就是在无头容器里每天合成上万张带中文标注的遥感切片，走的正是这条纯 CPU 路线。VTK 9 里调用方式大致长这样：

vtkNew<vtkFreeTypeStringToImage> toImage; vtkNew<vtkImageData> textImage; toImage->Render(textProp, "切片编号 001", 300, textImage);

不同小版本里这个方法的前后参数顺序略有差别，写代码前去对应版本的头文件里瞄一眼签名最稳妥，别想当然地照抄老帖子。

项目做久了你会发现，VTK 在2D图像上显示中文文本这件事，核心就一个认知：VTK 的文本渲染器只听"字体文件"的话，而汉字字形只存在于字体文件里。把SetFontFile + VTK_FONT_FILE这套固定组合记住，再配好 UTF-8 编码和一份靠谱的字体路径清单，剩下都是组合拳。我个人最喜欢的搭配是 Windows 上默认 simhei.ttf，Linux 上默认 wqy-zenhei，字体路径集中到一个配置项里，方便跨平台切换；必要时用 fonttools 裁剪出一个轻量专用字体，把加载速度再提升一个档位。最后再分享一个容易被忽略的小技巧：验证字体覆盖时，一定用你自己真实业务里要显示的那几个字符串，而不是"中文测试"这种样例。生僻字、单位符号、全角括号的覆盖范围在字体之间差别很大，等项目上线才发现某个地名显示成豆腐块，比开发阶段多花三分钟验证要惨得多。