VTK入门：vtkLabeledDataMapper——数据集点的“文本标签生成器”

原创于 2025-11-05 17:15:57 发布 · 387 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#VTK #3d

VTK 专栏收录该内容

51 篇文章

订阅专栏

VTK入门：vtkLabeledDataMapper——数据集点的“文本标签生成器”

在VTK可视化中，你是否遇到过这样的需求：在3D模型的关键点上标注“点ID”“温度值”或“坐标”，让观众能直观理解每个点的含义？比如在医学影像中标记病灶点的CT值，在机械模型中标注螺栓孔的坐标，在地形点云中标注海拔高度——而vtkLabeledDataMapper就是专门解决这个问题的工具。它像一个“智能标签机”，能自动在数据集的点位置绘制文本标签，支持多种数据类型标注，还能自定义标签的格式和外观，是VTK可视化中“信息标注”的核心类。

一、先搞懂：vtkLabeledDataMapper是什么？

用一句话总结：vtkLabeledDataMapper是VTK中的“点标签渲染器”，继承自vtkMapper2D，能在数据集（如点云、多边形模型）的每个点位置绘制文本标签，支持标注点ID、标量、向量、法向量等多种数据，最终通过vtkActor2D在渲染窗口中显示。

它的“身份卡”必须先明确，避免新手误用：

继承关系：vtkObjectBase → vtkObject → vtkAlgorithm → vtkAbstractMapper → vtkMapper2D → vtkLabeledDataMapper
关键继承点：
1. 继承vtkMapper2D：意味着它处理的是2D文本渲染，但标签位置关联的是3D数据集的点坐标（需通过渲染管线转换为屏幕坐标）；
2. 依赖vtkActor2D：Mapper仅负责“生成标签数据”，必须通过vtkActor2D关联到渲染窗口，否则标签无法显示；
核心逻辑：遍历输入数据集的每个点，根据配置的“标注模式”提取点的对应数据（如ID、标量值），按指定格式生成文本，再将文本渲染到点的屏幕投影位置；
输入输出：
- 输入：任意vtkDataSet（如vtkPolyData点云、vtkUnstructuredGrid），需包含要标注的数据（如点ID、标量数组）；
- 输出：2D文本标签（通过vtkActor2D渲染到屏幕），可获取标签的文本内容和位置。

二、核心特性：5大能力，覆盖所有标签需求

vtkLabeledDataMapper的核心价值在于“灵活支持多种标注场景”，新手需重点掌握以下5个核心特性：

1. 多类型数据标注（LabelMode）

这是最核心的功能——支持标注数据集的多种内置数据类型，通过SetLabelMode或便捷方法（如SetLabelModeToLabelScalars）切换，覆盖90%的标注场景：

标注模式	便捷方法	标注内容	适用场景
LabelIds	SetLabelModeToLabelIds()	点的唯一ID（从0开始递增）	标记点的索引，如“关键点1”“关键点2”
LabelScalars	SetLabelModeToLabelScalars()	点的标量值（如温度、高度、CT值）	医学影像（CT值标注）、地形（海拔标注）
LabelVectors	SetLabelModeToLabelVectors()	点的向量值（如速度、力的x/y/z分量）	流体模拟（速度向量标注）、力学分析（力向量）
LabelNormals	SetLabelModeToLabelNormals()	点的法向量（表面朝向的x/y/z分量）	模型表面分析（法向量方向标注）
LabelTCoords	SetLabelModeToLabelTCoords()	点的纹理坐标（u/v）	纹理映射调试（纹理坐标标注）
LabelTensors	SetLabelModeToLabelTensors()	点的张量值（如应力张量）	结构力学（应力分布标注）
LabelFieldData	SetLabelModeToLabelFieldData()	点的字段数据（用户自定义数据）	自定义附加信息（如“零件编号”“检测结果”）

注意：默认标注模式是LabelIds（点ID），若需标注其他数据，必须确保数据集包含对应数据（如标注标量需先给点添加标量数组）。

2. 自定义标签格式（LabelFormat）

支持std::format风格的格式字符串，可灵活控制标签的显示形式，比如保留小数位数、添加单位、前缀后缀等，解决“标签显示不直观”的问题。

格式示例	效果	适用场景
“{:.2f}”	将标量值保留2位小数（如10.23）	温度、高度等连续值
“{:.0f}℃”	整数温度加单位（如25℃）	带单位的物理量
“Point {}”	点ID加前缀（如Point 5）	点ID的友好显示
“应力: {:.3e}”	科学计数法显示（如1.234e+05）	极大/极小的张量、应力值

代码示例：

// 标注温度，保留1位小数并添加单位
labelMapper->SetLabelFormat("{:.1f}℃");

3. 多分量数据的精细控制

对于向量、法向量等多分量数据（如向量有x、y、z 3个分量），提供两个关键参数控制标注内容：

LabeledComponent：指定标注某一个分量（默认-1，标注所有分量）。例如向量数据中，SetLabeledComponent(1)仅标注y分量；
ComponentSeparator：多分量标注时的分隔符（默认空格）。例如设置为“,”，向量(x,y,z)会显示为“1.0,2.0,3.0”。

代码示例：

// 标注向量的y分量
labelMapper->SetLabelModeToLabelVectors();
labelMapper->SetLabeledComponent(1); // 0=x,1=y,2=z
// 多分量分隔符设为逗号（若标注所有分量）
labelMapper->SetComponentSeparator(',');

4. 标签外观自定义（LabelTextProperty）

通过vtkTextProperty控制标签的字体、大小、颜色、样式等，让标签更符合可视化需求（如重要标签用红色加粗，普通标签用黑色常规字体）。

支持的外观配置包括：

字体（FontFamily）：宋体、黑体、Times New Roman等；
字号（FontSize）：12、14、16等（单位为像素）；
颜色（Color）：RGB三色值（如红色(1,0,0)）；
样式（Bold/Italic/ShadowOn）：加粗、斜体、阴影；
对齐方式（Justification）：左对齐、居中、右对齐。

代码示例：

// 创建文本属性对象
vtkSmartPointer<vtkTextProperty> textProp = vtkSmartPointer<vtkTextProperty>::New();
textProp->SetFontFamilyToArial(); // 字体设为Arial
textProp->SetFontSize(12);       // 字号12
textProp->SetColor(1.0, 0.0, 0.0); // 红色
textProp->BoldOn();              // 加粗
textProp->ShadowOn();            // 显示阴影

// 关联到LabeledDataMapper
labelMapper->SetLabelTextProperty(textProp);

5. 坐标系统切换（CoordinateSystem）

支持两种坐标系统来定义标签的位置，适配不同交互场景：

WORLD（世界坐标）：标签位置是3D数据集的点坐标，当相机旋转时，标签会随点的3D位置变化（适合观察标签与点的空间关联）；
DISPLAY（显示坐标）：标签位置是2D屏幕坐标（x/y有效，z忽略），标签固定在屏幕某个位置（适合静态标注，如“图例说明”）。

代码示例：

// 设置为显示坐标（标签固定在屏幕上）
labelMapper->CoordinateSystemDisplay();
// 设置为世界坐标（标签随3D点移动）
// labelMapper->CoordinateSystemWorld();

三、使用流程：6步实现点云标签渲染

vtkLabeledDataMapper的使用需遵循VTK的“数据源→Mapper→Actor→Renderer→RenderWindow”管线，步骤清晰，新手可按以下流程操作：

步骤1：准备带标注数据的数据集

首先创建或读取数据集，并确保包含要标注的数据（如点ID默认存在，标量需手动添加）。示例中创建球体点云，并添加“Z坐标”作为标量（用于标注海拔）：

// 1. 创建球体数据源（中心(0,0,0)，半径5）
vtkSmartPointer<vtkSphereSource> sphereSource = vtkSmartPointer<vtkSphereSource>::New();
sphereSource->SetCenter(0, 0, 0);
sphereSource->SetRadius(5);
sphereSource->SetPhiResolution(20); // 纬度方向点数
sphereSource->SetThetaResolution(20); // 经度方向点数
sphereSource->Update();
vtkPolyData* sphereData = sphereSource->GetOutput();

// 2. 给球体点添加“Z坐标”作为标量（用于标注海拔）
vtkSmartPointer<vtkDoubleArray> zCoords = vtkSmartPointer<vtkDoubleArray>::New();
zCoords->SetName("Altitude"); // 标量数组名称
zCoords->SetNumberOfComponents(1);

for (vtkIdType i = 0; i < sphereData->GetNumberOfPoints(); i++) {
    double point[3];
    sphereData->GetPoint(i, point); // 获取点的(x,y,z)
    zCoords->InsertNextTuple1(point[2]); // 插入Z坐标作为标量
}
sphereData->GetPointData()->AddArray(zCoords);
sphereData->GetPointData()->SetActiveScalars("Altitude"); // 激活标量数组

步骤2：创建vtkLabeledDataMapper并设置输入

vtkSmartPointer<vtkLabeledDataMapper> labelMapper = vtkSmartPointer<vtkLabeledDataMapper>::New();
labelMapper->SetInputData(sphereData); // 关联数据集

步骤3：配置标注模式和格式

这里选择标注“标量（Z坐标，即海拔）”，格式保留1位小数并添加“m”单位：

// 设置标注模式为“标量”
labelMapper->SetLabelModeToLabelScalars();
// 设置标签格式：保留1位小数+单位“m”
labelMapper->SetLabelFormat("{:.1f}m");

步骤4：配置标签外观（TextProperty）

vtkSmartPointer<vtkTextProperty> textProp = vtkSmartPointer<vtkTextProperty>::New();
textProp->SetFontFamilyToArial();
textProp->SetFontSize(10);
textProp->SetColor(0.0, 1.0, 0.0); // 绿色标签
textProp->ShadowOn(); // 显示阴影（避免与模型重叠）
labelMapper->SetLabelTextProperty(textProp);

步骤5：创建vtkActor2D并关联Mapper

vtkLabeledDataMapper是2D Mapper，必须通过vtkActor2D才能渲染：

vtkSmartPointer<vtkActor2D> labelActor = vtkSmartPointer<vtkActor2D>::New();
labelActor->SetMapper(labelMapper); // 关联LabeledDataMapper

步骤6：构建渲染管线并显示

// 创建渲染器、渲染窗口、交互器
vtkSmartPointer<vtkRenderer> renderer = vtkSmartPointer<vtkRenderer>::New();
vtkSmartPointer<vtkRenderWindow> renderWindow = vtkSmartPointer<vtkRenderWindow>::New();
vtkSmartPointer<vtkRenderWindowInteractor> interactor = vtkSmartPointer<vtkRenderWindowInteractor>::New();

// 配置渲染管线
renderWindow->AddRenderer(renderer);
interactor->SetRenderWindow(renderWindow);
renderer->AddActor2D(labelActor); // 添加标签Actor
renderer->SetBackground(0.1, 0.1, 0.1); // 背景色（深灰）

// 显示并启动交互
renderWindow->Render();
interactor->Start();

四、新手避坑指南：5个常见错误及解决方法

标签不显示：忘记关联vtkActor2D
- 错误原因：vtkLabeledDataMapper是Mapper，需通过vtkActor2D添加到Renderer，直接加Mapper会导致无显示；
- 解决：必须创建vtkActor2D，调用SetMapper(labelMapper)，再将Actor添加到Renderer。
标注模式与数据不匹配（如标注标量却无标量数据）
- 错误表现：标签显示空值或乱码，控制台可能报“no scalars available”；
- 原因：选择LabelScalars模式，但数据集未添加标量数组；
- 解决：先给数据集添加标量数组（如步骤1中的Z坐标），并通过SetActiveScalars激活。
多分量数据标注混乱（如向量显示3个分量却只需1个）
- 错误原因：默认LabeledComponent=-1（标注所有分量），未指定单个分量；
- 解决：通过SetLabeledComponent(n)指定分量索引（如向量的y分量设为1）。
标签外观不生效：TextProperty未正确关联
- 错误原因：创建了vtkTextProperty但未调用SetLabelTextProperty；
- 解决：确保labelMapper->SetLabelTextProperty(textProp)，且TextProperty的参数（如颜色、字号）已正确设置。
相机旋转时标签位置异常：坐标系统选择错误
- 错误表现：旋转相机时，标签固定在屏幕上（或随相机旋转过度）；
- 原因：误选DISPLAY坐标（静态）或WORLD坐标；
- 解决：需要标签随3D点移动选WORLD，需要标签固定在屏幕选DISPLAY。