做机器人抓取项目的时候我发现一个很基础但又特别容易忽略的需求在三维场景里给物体、路径或者关键点加文字说明。用常规的屏幕贴图文字比如用vtkCornerAnnotation在角落显示信息倒是简单可一旦视点转动、相机拉近拉远文字要么被物体挡住要么和三维坐标对不上总觉得缺了点“空间感”。后来我把目光转向VTK里的3D Text方案用vtkVectorText把字符串变成真正的三维几何体才算解决了问题。这篇记录的就是VTK学习系列的第15篇专门讲3D Text在VTK里的实现思路、代码细节和避坑经验适合做三维标注、机器人仿真、医学可视化、数字孪生项目的朋友参考。开门见山说一句VTK里说的3D Text核心类是vtkVectorText。它和平时用的屏幕文字完全是两回事——屏幕文字是画在渲染窗口上的位图跟场景无关而vtkVectorText生成的是一组有真实坐标、真实朝向、可以被光照照亮、可以被鼠标拾取的三维网格。你可以把它当成一个普通的vtkActor来摆放、旋转、缩放甚至和机械设备、模型一起做碰撞检测。这对很多工程场景来说是一个“看着不起眼关键时刻真救场”的功能。1. 3D Text在VTK中的定位与核心思路1.1 vtkVectorText到底在底层做了什么先理解vtkVectorText的本质。它接收一个字符串然后按字符逐个把每个字母的矢量轮廓数据提取出来再通过三角剖分生成一片片多边形网格。这里的“矢量轮廓”不是位图字体那种像素点阵而是字体文件里每条笔画的控制点曲线。VTK把这些曲线闭合、填充最终输出一个vtkPolyData里面包含三件事顶点坐标、构成面的三角形索引、以及面法向量。这套机制带来的直接好处是文字不再是贴在屏幕上的贴纸而是可旋转、可缩放、可做剖面、可参与布尔运算的三维几何体。我拿它做过一个给汽车底盘传感器打标签的小工具文字标签挂在传感器正上方当工装夹具转动时标签跟着一起转操作员一眼就能看清传感器编号而不需要凑近屏幕。这一点如果用屏幕文字实现会非常困难因为屏幕文字和场景是分离的需要不断手动计算屏幕坐标来更新位置而3D Text天然就在同一个三维坐标系里。vtkVectorText还有一个隐藏特性它输出的几何体是真正的“字面几何”这意味着它可以用任意vtkPolyData的后处理滤波器。比如给它加一个厚度、拉一个斜角、或者做倒角挤出就能得到类似立体雕刻字的效果。这在做产品三维预览、虚拟展厅字幕时特别好用。1.2 为什么在三维世界里需要专门的文字对象很多新手会困惑我一个字符串直接用vtkTextActor放在屏幕角落不就完了为什么要大费周章把它变成网格这里就要分清两种“文字”的使用场景。屏幕文字vtkTextActor适合做固定信息的展示比如操作提示、帧率、坐标读数它在任何视角下都保持正对相机清晰度最高。但它有两个致命缺陷第一它没有深度信息永远浮在所有三维物体之上遮挡关系是假的第二它不能随物体一起变换。比如你要在机械臂末端画一个“TCP”标签机械臂一旋转屏幕文字不会跟着转标签就失去意义了。vtkVectorText则相反。它是三维世界里的实体对象放到哪个坐标就是哪个坐标跟它旁边的模型共享同一个空间。它的代价是需要你手动管理朝向不能默认“始终面向相机”。所以VTK里另外提供了vtkFollower这样的适配器让3D文字既能钉在三维坐标上又能自动转向读者。这个结合非常实用下文会专门讲。1.3 四条可行路线对比VectorText、TextActor3D、Caption、BillboardVTK里能显示文字的方式远不止一种。我整理了一张表方便你根据场景快速选择方案文字形态是否贴场景是否可拾取典型用途vtkVectorText三维网格是是需要真实深度、需要交互选中的场景vtkTextActor3D三维空间中的平面文字是但无厚度是轻量标签不需要挤出厚度vtkCaptionActor2D屏幕文字三维引线是引线贴场景否带引线标注如“这里是夹爪”vtkBillboardTextActor3D三维定位屏幕朝向部分位置贴场景否远处标签始终正对相机经过多个项目对比我的个人结论是如果追求真实几何感、需要光照立体感选vtkVectorText如果只是想要“文字在空间某个位置出现”不管它是平面还是立体选vtkTextActor3D更快如果只是做引线说明、不关心遮挡关系vtkCaptionActor2D最省事。后两者优势是API简单缺点是做不出“带厚度的实心雕刻字”效果。2. 核心细节解析与实操要点2.1 认识vtkVectorText的核心接口与隐藏设定vtkVectorText的接口其实不多熟悉三四个就足够日常用了。SetText是传入需要显示的字符串这个没什么好说的。SetBold控制是否加粗SetItalic控制是否斜体这两个内部是通过修改矢量轮廓的控制点比重来实现的。SetDepth控制文字的挤出厚度默认值是1.0单位是VTK内部的长度单位不是像素。所以如果你在机器人仿真里以毫米为单位1.0厚度其实已经相当薄了。还有一个关键隐藏设定vtkVectorText生成的文字默认是平躺在XY平面上并且文字的“前方”朝Z轴正方向。这和大多数人的直觉不一样——很多新手以为文字应该是立着垂直于桌面的“牌子”结果跑起来发现是一摊“印在纸上的字”平放赶紧去找旋转方法。所以你在代码里通常会看到我给文字加了一个旋转让它在XZ平面或YZ平面立起来具体转多少取决于你的应用场景。另外需要注意vtkVectorText的输出几何体法向量是根据字面正反面生成的如果文字模型被缩成负比例或者经过某些矩阵变换法线方向会反掉出现“看不见但能选中”的诡异现象。遇到这种情况可以在Mapper里设置BackfaceCullingOff必要时给Actor单独设置BackfaceProperty。2.2 显示管线从字符串到屏幕上的一整个链路要把3D文字显示出来本质上就是走VTK里最经典的一条渲染管线vtkVectorText数据源→ vtkPolyDataMapper映射器→ vtkActor三维对象→ vtkRenderer渲染器→ vtkRenderWindow窗口其中容易忽略的是vtkVectorText本身只负责“造几何体”它不负责颜色、材质、光照。颜色和材质要设置在vtkActor上比如给Actor设置一个DiffuseColor为淡蓝色然后打开场景里的光照文字才会有立体感。如果场景里没有打开光照或者灯是从正前方打的文字看起来会是一块颜色均匀的平板看不出挤出效果的层次。给文字加厚度之后别忘了处理法线和光照的配合。vtkVectorText生成的挤出侧边就是文字笔画厚度那一圈法线是自动计算的但默认的阴影效果可能偏暗尤其是文字侧边朝下时会出现一片死黑。我的习惯是给Actor设置两个光源一个主光在右上方一个补光在左前方补光强度0.3左右这样无论文字怎么旋转笔画凹槽和侧边都能看清。2.3 变换技巧位置、朝向、缩放的叠加顺序3D Text毕竟是几何体直接调用vtkActor的SetPosition、SetOrientation、SetScale就能摆放。但在很多项目中文字标签不是固定在原点的而是要跟着某个设备的局部坐标系走。这时候就不要直接设置Actor的变换了因为Actor的变换是相对于世界坐标系的。规范做法是用vtkTransform先搭一个“偏移旋转缩放”的变换矩阵再交给vtkTransformPolyDataFilter处理vtkVectorText的输出最后把这个滤波器当作Mapper的输入。这样文字就相当于被烘焙进了目标坐标系可以整体跟着设备运动。我自己常用的组合是Transform先做一次绕Z轴旋转让文字竖起来再做一次沿X轴的平移把文字中心挪到标签位置最后用SetScale调整字号大小因为vtkString生成的文字默认大小取决于字体轮廓的尺寸通常是设计字体时的点阵尺寸直接跑出来往往会过大或过小。这个“先旋转再平移最后缩放”的顺序不要搞反否则旋转中心会跟着平移跑掉文字会跑到一个意想不到的位置上。2.4 和场景中其他物体共存时的渲染状态设置3D Text和普通模型最大的不同是它经常会在很小的区域里密集出现多段文字。比如一个手术导航界面里器官旁边同时挂三个标签静脉、动脉、肿瘤边界。文字之间密度高锯齿也明显。这种情况下我强烈建议开启多重采样抗锯齿。在多采样抗锯齿模式下3D Text轮廓线的锯齿感会大幅下降。如果没有开三个标签挤在一起时笔画细的地方会有严重的闪烁感尤其当相机慢慢推进时细笔画会像碎掉一样抖动。另外3D Text的PolyData网格通常比较碎如果场景里同时有大量其他高精度模型整体渲染性能会受影响。我的做法是把静态文字一次性生成好后直接缓存为VTU或VTP文件下次启动不再生成直接读取能省掉每次启动时几十毫秒的字符串转网格时间。别看这点时间短在需要频繁调试的场景里积累起来非常难受。3. 实操过程与核心环节实现3.1 一个最小可用的C版本从空项目到3D文字显示下面这个示例来自我给某跨平台仿真工具加“坐标轴标签”功能时抽出的最小复现代码。它能完成的事情是在三维坐标原点附近生成一个写着“Origin”的3D文字并让它立起来正对相机背景深色交互旋转。#include vtkSmartPointer.h #include vtkVectorText.h #include vtkPolyDataMapper.h #include vtkActor.h #include vtkRenderer.h #include vtkRenderWindow.h #include vtkRenderWindowInteractor.h #include vtkCamera.h #include vtkTransform.h #include vtkTransformPolyDataFilter.h int main() { // 1. 创建文字几何体 vtkSmartPointervtkVectorText textSource vtkSmartPointervtkVectorText::New(); textSource-SetText(Origin); textSource-SetDepth(0.5); // 2. 用变换把文字立起来并缩放到合适大小 vtkSmartPointervtkTransform transform vtkSmartPointervtkTransform::New(); transform-RotateX(-90.0); // 让文字从平躺变成竖直 transform-Scale(0.5, 0.5, 0.5); // 调整整体大小 vtkSmartPointervtkTransformPolyDataFilter transformFilter vtkSmartPointervtkTransformPolyDataFilter::New(); transformFilter-SetInputConnection(textSource-GetOutputPort()); transformFilter-SetTransform(transform); transformFilter-Update(); // 3. 走标准渲染管线 vtkSmartPointervtkPolyDataMapper mapper vtkSmartPointervtkPolyDataMapper::New(); mapper-SetInputConnection(transformFilter-GetOutputPort()); vtkSmartPointervtkActor actor vtkSmartPointervtkActor::New(); actor-SetMapper(mapper); actor-GetProperty()-SetColor(0.2, 0.7, 1.0); // 4. 渲染窗口 vtkSmartPointervtkRenderer renderer vtkSmartPointervtkRenderer::New(); renderer-AddActor(actor); renderer-SetBackground(0.1, 0.1, 0.15); vtkSmartPointervtkRenderWindow window vtkSmartPointervtkRenderWindow::New(); window-AddRenderer(renderer); window-SetSize(800, 600); window-Render(); vtkSmartPointervtkRenderWindowInteractor interactor vtkSmartPointervtkRenderWindowInteractor::New(); interactor-SetRenderWindow(window); interactor-Start(); return 0; }这段代码看着简单但有几个细节值得拆开说。第一SetDepth(0.5)不是随便拍的。如果文字在场景里显得“像纸片”就是深度值太小如果笔画之间粘到一起就是深度值太大。调这个值的时候要结合文字的总尺寸判断。我通常的做法是先把Scale定下来再看文字的实际包围盒大小把深度设置为包围盒宽度的1/20到1/10之间。比如一个宽100单位的文字深度给5到10单位立体感最自然。第二RotateX(-90.0)这个角度决定了文字朝向。vtkVectorText默认生成的文字平面是XY平面朝Z方向。我想让它在屏幕前竖直于是绕X轴转负90度这个变换把原来平放的字面立起来。如果要在机械臂上挂标签就不转这么一下而是根据标签法线方向去对齐。第三很多新手会漏掉SetInputConnection而不是SetInputData。如果直接拿vtkVectorText的输出传递给Mapper不经过transformFilter那文字就是平躺的。所以从代码结构上变换滤波器是必不可少的。3.2 进阶需求让3D Text始终保持“面向相机”在上面的例子里文字立起来了但当你旋转视角时会发现一个尴尬文字立是立着可转几圈之后你只能看到它的侧面变成一条线。这在很多标注场景下不可接受——我想让标签无论怎么转视角都保持在读者眼前但同时仍然钉在三维场景中的固定坐标上。这时就要用到vtkFollower它的名字听起来像“跟随者”职责正是“位置跟随Actor但朝向始终正向相机”。使用方式很简单不再添加vtkActor而是创建vtkFollower把之前建好的Mapper塞给它然后调用SetPosition设置坐标再添加到Renderer里。vtkSmartPointervtkFollower follower vtkSmartPointervtkFollower::New(); follower-SetMapper(mapper); follower-SetPosition(10.0, 0.0, 0.0); follower-GetProperty()-SetColor(1.0, 0.8, 0.2); renderer-AddActor(follower);这里有一个经验如果使用vtkFollower那么前面vtkTransform里的旋转部分就可以省略了因为Follower会强制把文字的正面向相机你再手动旋转反而会得到一个歪斜的标签。只需要保留Scale变换再把位置用SetPosition设定就行。vtkFollower还有一个好处是它内部会自动更新法线矩阵确保光照方向正确。当你在交互器里按住鼠标旋转场景时Follower的朝向更新是每帧同步的实测在中等规模场景中不会引入明显的性能开销。不过要注意Follower不能和普通Actor一样混用RenderPass有些特殊后期处理管线里Follower的朝向更新逻辑会失效我遇到过一次在SSAO效果下标签发黑的问题排查半天发现是深度缓冲和法向缓冲不匹配换成普通Actor后解决。如果你只需要“文字在固定三维位置显示但以屏幕文字形式呈现”还有一个更轻量的选择vtkBillboardTextActor3D。它的定位是“无论相机怎么转都像广告牌一样正对读者”但显示的是位图渲染出来的文字不是三维网格。它适合做远处的设备编号牌离近了有字离远了还是一行清晰的字不追求立体感。三个方案的取舍表我在前面已经列了这里补充一句三者在鼠标拾取方面也有差异vtkVectorText可以拾取到面片IDvtkFollower也能拾取但显示的文字内容需要自己建立“Actor到字符串”的映射。3.3 用3D Text做坐标轴标签的完整场景坐标轴标签是最能体现3D Text价值的场景之一。比如你在做一款机械臂仿真软件需要在基座坐标系原点显示X、Y、Z三个方向标签同时显示当前末端坐标值。用vtkVectorText生成“X”“Y”“Z”三个字分别挂到三个轴的末端用vtkFollower让“X”始终面向相机这样用户哪怕转到机械臂背后也能知道哪个方向是X。我这里给出一个坐标轴标签的定位思路不贴完整代码但把关键的计算逻辑画出来假设X轴方向是(1,0,0)轴长为200毫米那么标签坐标就是X (210,0,0)参照这个逻辑往下算Y (0,210,0)Z (0,0,210)。偏移量比轴长多出10毫米是为了不让标签和轴尖端的网格重叠造成视觉遮挡。多少个标签需要多少个Actor这个没法投机取巧。但可以把它们统一装进一个vtkPropAssembly这样一个集合体就能整体做显示/隐藏切换配合交互式界面的“显示标签”开关非常方便。这也是我在工程里经常用的组织方式同类文字标签装进一个PropAssembly和模型本体分开管理显示状态。3.4 Python环境下的快速验证如果你只是做算法验证或者快速原型不必要起一个C工程直接在Python里用VTK包装器几行代码就能跑起来。Python和C的类名、方法名基本一致只是创建方式略有区别。import vtk text_source vtk.vtkVectorText() text_source.SetText(Coordinate Origin) text_source.SetDepth(0.3) transform vtk.vtkTransform() transform.RotateX(-90.0) transform.Scale(0.02, 0.02, 0.02) transform_filter vtk.vtkTransformPolyDataFilter() transform_filter.SetInputConnection(text_source.GetOutputPort()) transform_filter.SetTransform(transform) mapper vtk.vtkPolyDataMapper() mapper.SetInputConnection(transform_filter.GetOutputPort()) actor vtk.vtkActor() actor.SetMapper(mapper) actor.GetProperty().SetColor(0.8, 0.9, 0.2) renderer vtk.vtkRenderer() renderer.AddActor(actor) renderer.SetBackground(0.05, 0.05, 0.1) window vtk.vtkRenderWindow() window.AddRenderer(renderer) window.SetSize(800, 600) interactor vtk.vtkRenderWindowInteractor() interactor.SetRenderWindow(window) interactor.Initialize() window.Render() interactor.Start()Python版的要点是坐标系缩放要小心。很多仿真环境里世界坐标是毫米级比如机器人工作空间用0.02这种缩放值正好能把默认尺寸很大的文字缩到合适比例如果是在医学图像场景里世界坐标是豪米且模型尺寸本身就是几十毫米那Scale甚至可以设为1.0不缩放。这个数值没有通用解只能看你的数据单位所以千万别直接照抄一个缩放系数就完事。4. 常见问题与排查技巧实录4.1 文字不显示但程序正常运行这种问题最迷惑因为控制台什么都没有窗口黑漆漆一片但代码逻辑看着也没毛病。根据我的经验按顺序检查三件事先检查Actor是不是被添加到了Renderer里。听起来很傻但真的发生过——代码里加了Actor到某个不用的Renderer然后渲染的是另一个空Renderer折腾一下午才发现AddActor加错了对象。再检查背景色和文字颜色是否对比度太低。我遇到过把背景设成纯白、文字也设成默认白色的情况文字其实是显示了的只是看不见。把文字颜色改成鲜艳的亮色背景用深灰是排错最快的方法。最后检查汉字支持问题。vtkVectorText默认使用的字体机制对中文字符支持并不好遇到中文可能直接生成空几何体。我的处理方式是要么改用西文字符要么换用支持中文的FreeType字体管线用vtkVectorText做中文字体需要额外加载字体文件到VTK的字体缓存里接口相对麻烦如果只是做标签直接用vtkTextActor3D更省心。4.2 文字太小、被场景淹没vtkVectorText生成的文字尺寸由矢量字体文件本身的单位决定跟你的场景尺寸可能完全对不上。如果你在机器人仿真环境中机器人本体是毫米级800毫米而文字默认可能只有1到2毫米结果就是文字缩成一个点看不清。解决办法是在Transform里设置Scale或者用vtkActor里的SetScale直接放大。但要提醒一个问题把文字放大太多会导致笔画之间互相穿插很丑。我建议在做完Scale后在场景里把相机拉近到文字附近正面观察一下确认笔画的镂空部分没有被堵死。4.3 文字方向不对、有些面“透视”能看见内部3D Text生成的是封闭网格正常渲染时只显示外表面但当你把文字旋转到某个角度会看到某些笔画内部透出背景色像透明了一样。这通常是法线方向反了或者渲染管线的背面剔除设置不对。解决思路分两步。第一在Mapper里关闭背面剔除第二给Actor加一个BackfaceProperty把双面的颜色调成稍微加深的颜色这样即使从背面看也能看出文字的轮廓不会出现“透明空洞”。我之前在给一个模拟项目做“侧着看的文字”标签时就靠这一步解决了半透明空洞的问题。4.4 文字和模型的遮挡关系不对有些场景里文字应该被模型的一部分挡住比如文字在机械臂底座内部但实际渲染出来文字永远在最前面。这种情况几乎可以确定不是3D Text本身的问题而是你没有开启深度测试或者用了透明渲染管线把文字放进了透明队列。我的经验是3D Text默认走Opaque队列只要你的场景里没有“把半透明物体全部塞到透明队列里去做排序”这种特殊操作遮挡关系通常是正确的。如果发现文字被错误地提前渲染可以检查Renderer是否调用了SetUseDepthPeeling以及文字Actor是否误设了Opacity小于1.0。只要把透明度改回1.0文字立刻回到正确的深度关系上。4.5 常用问题速查表现象最常见原因排查优先级文字完全不可见未AddActor / 颜色与背景相同 / 中文未支持高文字在但极小场景尺度与字体尺度不匹配未做缩放高文字出现在奇怪位置变换顺序错误 / 未区分世界坐标和局部坐标中文字有一条线或“纸片”状SetDepth过小 / 光照角度过平中旋转视角后文字消失法线方向翻转 / 背面剔除开启中文字重叠闪烁多个标签坐标重叠 / 多重采样未开启低中文字符无法显示默认字体不支持中文高5. 应用场景扩展3D Text能用在哪些真实项目里5.1 机器人仿真与数字孪生中的坐标标注机器人运动规划时我们通常需要一眼看到末端执行器的当前坐标甚至要在三维世界里的每个关节处标注角度值。这些标注如果放在屏幕角落总要不停在“看屏幕”和“看模型”之间切换注意力。把坐标标签用3D Text直接显示在末端执行器旁边视觉上就像“那个点旁边悬浮着一行字”配合跟随相机视角的朝向处理操作体验会好很多。我见过一个仿真平台把整个机器人工作空间划分成网格每个路径点旁边显示时间和坐标文字用户拖动时间轴时标签跟着路径点移动。这个功能如果用vtkVectorText实现每个路径点就是一个Actor几百个Actor对渲染压力不大实测下来可以在中端独立显卡上流畅运行。这类场景里我强烈推荐把标签装进PropAssembly避免上百个Actor直接堆进Renderer里管理混乱。5.2 医学可视化里的结构标引医学三维重建模型比如血管、器官通常都在一个狭小的空间里密集排列用屏幕文字做标注很难准确指示“这一块是谁”。3D Text的优势是可以在模型表面附近悬浮一行字医生转视角时文字和模型的空间关系始终明确不会有屏幕文字那种“浮在玻璃上”的错位感。而且医学领域经常用到“切面”操作文字网格可以跟着切面一起裁切从而显示不同层面的标注这是屏幕文字做不到的。5.3 科学可视化与实验数据展示做流体仿真、电磁场显示时等值面旁边加一行“Value2.5”的标签比看颜色条省力得多。这些标签如果放在固定位置会遮挡数据如果用vtkFollower让它始终面向读者又保持距离不变效果最好。我印象最深的是一次给某图像处理Demo加等值面标签用的就是vtkFollower挂3D Text转视角时标签始终在数据旁边但永远朝向读者交互体验非常自然。5.4 虚拟展厅、三维字幕和产品预览如果你在做轻量级的产品预览工具3D Text还能承担类似“雕刻字”的职责。把文字挤出一定厚度配上金属材质贴图、打上反射光就能做出一行有真实体积感的铭牌字。很多三维展厅里的标题字就是这么做的。这种场景不需要特别复杂的字体效果只要在vtkVectorText的SetDepth后配合vtkTexture和光照参数就能输出不错的视觉结果成本很低。5.5 3D Text与其他VTK功能的联动3D Text本质上是一份vtkPolyData所以它可以和VTK里几乎所有几何处理功能联动。比如用vtkAppendPolyData把文字和某个模型合并用vtkClipPolyData沿着文字笔画做切割用vtkTransformPolyDataFilter把文字随机械臂整体变换甚至在文字上做碰撞检测拿鼠标拾取整个文字网格。这个“文字即几何”的模型让它成为VTK生态里灵活性极高的一类对象。如果你想基于文字模型做更丰富的效果可以尝试给文字表面贴纹理、加描边、加发光材质。VTK里没有直接提供“文字描边”的API但可以用vtkOutlineFilter提取文字包围盒或者用vtkFeatureEdges提取笔画轮廓再做偏移渲染效果接近。写在最后的一个小经验如果让我从这么多“3D Text”实操里只提炼出一句话我会说永远不要急着写代码先想清楚你的文字到底要“贴在屏幕”还是“贴在世界里”。很多项目里需求描述是“显示一个标签”但实际使用场景是在三维空间里定位只能继续回头改造绕了很大的弯。vtkVectorText的出现让“在世界里立起一行字”变成了一条非常顺手的路径。根据自己的项目类型在提案阶段就选对文字方案后面会省掉大量返工时间。最后再分享一个小技巧如果文字标签位置和模型重叠出现“花了眼”的视觉干扰可以给标签加一个半透明的底板用vtkCubeSource生成一个薄片放在文字后面透明度设为0.6左右。这样在复杂场景里标签既不会被背景吞掉又能从视觉上和模型区分开。这个底板属于场景物体而不是文字的一部分所以它的朝向、位置需要跟着文字一起更新两个对象一起变换即可。这个小设计我在不少项目里用过观众普遍反馈比裸标签清楚很多算是一个零成本高收益的小改进。